# entity

This document is auto-generated from the JSDoc comments in `src/store` by running `npm run api-doc`.

## `entity.create`

*Source: `src/store/entity/create.js`*

Creates a new entity (customer) in a customer group, recording history. Optional `number`; if omitted, allocates via `numbers.nextNumber` (`type` `entity`).

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `input` | `object` | The entity creation input. |
| `input.customergroupId` | `number` | The id of the customer group. |
| `input.name` | `string` | The entity name. |
| `[input.firstName]` | `string` | The entity first name. |
| `[input.number]` | `string` | Optional explicit customer number. |
| `[tx]` | `object` | Optional transaction to run within. |

**Returns**

`Promise<{id: number, customergroupId: number, firstName: string|null, name: string, number: string, createdAt: string, updatedAt: string}>` — The created entity.

**Throws**

`Error` — If the name is empty.

**Example**

```js
const entity = await store.entity.create(42, { customergroupId: 5, name: 'Doe', firstName: 'John' });
// => { id, customergroupId, firstName, name, number, createdAt, updatedAt }
```

## `entity.delete`

*Source: `src/store/entity/delete.js`*

Deletes an entity by its id within the user's selected company.

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `id` | `number` | The id of the entity to delete. |
| `[tx]` | `object` | Optional transaction to run within. |

**Returns**

`Promise<void>`

**Throws**

`Error` — If the entity is not found or is in use.

**Example**

```js
await store.entity.delete(42, 5);
```

## `entity.getById`

*Source: `src/store/entity/getById.js`*

Returns a single entity by its id within the user's selected company.

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `id` | `number` | The id of the entity. |
| `[tx]` | `object` | Optional transaction to run within. |

**Returns**

`Promise<{id: number, customergroupId: number, firstName: string|null, name: string, number: string, createdAt: string, updatedAt: string}>` — The entity.

**Throws**

`Error` — If the entity is not found.

**Example**

```js
const entity = await store.entity.getById(42, 5);
// => { id, customergroupId, firstName, name, number, createdAt, updatedAt }
```

## `entity.isNumberFree`

*Source: `src/store/entity/isNumberFree.js`*

Returns whether a customer number is free within the user's selected company. Pass `excludeEntityId` when editing so the entity's own number counts as free.

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `number` | `string` | The customer number to check. |
| `[options]` | `object` | Optional options. |
| `[options.excludeEntityId]` | `number` | An entity id to exclude from the check. |
| `[tx]` | `object` | Optional transaction to run within. |

**Returns**

`Promise<boolean>` — Whether the number is free.

**Throws**

`Error` — If the number is empty.

**Example**

```js
const free = await store.entity.isNumberFree(42, 'C-100');
// => true
const freeOnEdit = await store.entity.isNumberFree(42, 'C-100', { excludeEntityId: 5 });
// => true
```

## `entity.list`

*Source: `src/store/entity/list.js`*

Lists the entities (customers) of the user's selected company, optionally filtered by customer group or restricted to the 'customer' role.

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `[options]` | `object` | Optional options. |
| `[options.customergroupId]` | `number` | Filter by customer group id. |
| `[options.role]` | `string` | Restrict to `'customer'` role if set. |
| `[tx]` | `object` | Optional transaction to run within. |

**Returns**

`Promise<Array<{id: number, customergroupId: number, firstName: string|null, name: string, number: string, createdAt: string, updatedAt: string}>>` — The entities.

**Throws**

`Error` — If the role is invalid.

**Example**

```js
const entities = await store.entity.list(42, { customergroupId: 5 });
// => [{ id, customergroupId, firstName, name, number, createdAt, updatedAt }]
```

## `entity.peekNextNumber`

*Source: `src/store/entity/peekNextNumber.js`*

Returns the next customer number that would be allocated for the user's selected company (`numbers` type `entity`) without consuming it.

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `[tx]` | `object` | Optional transaction to run within. |

**Returns**

`Promise<string>` — The next entity number.

**Example**

```js
const number = await store.entity.peekNextNumber(42);
// => '1'
```

## `entity.update`

*Source: `src/store/entity/update.js`*

Updates name, first name, and/or customer number of an entity, recording history. Optional `number` sets the customer number explicitly (does not auto-allocate).

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `googleAuthId` | `number` | The id of the Google auth user. |
| `id` | `number` | The id of the entity to update. |
| `patch` | `object` | The update patch. |
| `[patch.name]` | `string` | The new entity name. |
| `[patch.firstName]` | `string` | The new first name. |
| `[patch.number]` | `string` | The new customer number. |
| `[tx]` | `object` | Optional transaction to run within. |

**Returns**

`Promise<{id: number, customergroupId: number, firstName: string|null, name: string, number: string, createdAt: string, updatedAt: string}>` — The updated entity.

**Throws**

`Error` — If no valid field is provided or the entity is not found.

**Example**

```js
const entity = await store.entity.update(42, 5, { name: 'Doe', firstName: 'Jane', number: 'C-42' });
// => { id, customergroupId, firstName, name, number, createdAt, updatedAt }
```