215 lines
6.0 KiB
Markdown
215 lines
6.0 KiB
Markdown
# 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 }
|
|
```
|