dashlibstorage/API.entity.md

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

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

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

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

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

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

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

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