@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/platform/tax.d.ts

@@ -0,0 +1,154 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { AdminClientConfig } from '../client.js';
+import { type TaxCategory, type TaxRate } from '../tax/index.js';
+import type { Call } from '../types.js';
+/** A new platform-wide tax category, as {@link PlatformTaxCategoriesModule.create} takes it. */
+export interface CreateTaxCategoryInput {
+    name: string;
+    /**
+     * Make it the platform's default category. Only one category is the default: setting it here
+     * takes the mark off the one that had it. Not the default when left out.
+     */
+    isDefault?: boolean;
+}
+/** A change to a tax category. A field left out keeps what the category has. */
+export interface UpdateTaxCategoryInput {
+    name?: string;
+    /** `true` moves the default mark here (off the category that had it). */
+    isDefault?: boolean;
+}
+/** A new platform-wide tax rate, as {@link PlatformTaxRatesModule.create} takes it. */
+export interface CreateTaxRateInput {
+    name: string;
+    /**
+     * A percentage: `21` is 21 %. Not money. The engine keeps two decimals (`5.5`, `20.75`), so
+     * a third one is rounded when it is stored; the answer carries the stored value.
+     */
+    value: number;
+    /** A disabled rate is never applied. Required: a rate is applied from the moment it exists. */
+    enabled: boolean;
+    /** The tax category it prices (`tax.categories.list`). */
+    categoryId: string;
+    /** The zone it prices that category in (`geo.zones.list`). */
+    zoneId: string;
+    /** Only for customers of this group. Left out, the rate applies to every customer. */
+    customerGroupId?: string;
+}
+/**
+ * A change to a tax rate. A field left out keeps what the rate has.
+ *
+ * There is no way to take the customer group OFF a rate: the engine ignores a null group and
+ * keeps the one stored, so `customerGroupId: null` is refused here rather than silently
+ * dropped. To widen a group-limited rate to every customer, create a rate without a group and
+ * delete the old one.
+ */
+export interface UpdateTaxRateInput {
+    name?: string;
+    /** See {@link CreateTaxRateInput.value}. */
+    value?: number;
+    enabled?: boolean;
+    categoryId?: string;
+    zoneId?: string;
+    /** Move the rate to another customer group. */
+    customerGroupId?: string;
+}
+/**
+ * `admin.platform.tax.categories` — the SuperAdmin writes of the platform-wide tax categories
+ * every store shares (spec §9.2 `platform`, ruling G128). Reads are `tax.categories.list()`.
+ *
+ * Every method needs a human SuperAdmin session: an API token or an app credential is refused
+ * with `PLATFORM_REQUIRES_SESSION` (`PermissionDeniedError`, 403) BEFORE anything is sent, and a
+ * store administrator is refused by the engine with `PLATFORM_SETTINGS_NOT_ALLOWED`
+ * (`PermissionDeniedError`, 403) before anything is read or written. No tenant is needed on the
+ * client.
+ */
+export interface PlatformTaxCategoriesModule {
+    /**
+     * Create a tax category, and answer it as `tax.categories.list()` reads it.
+     *
+     * `INVALID_TAX_CATEGORY_INPUT` (`ValidationError`, 400): a missing or blank name, or an
+     * `isDefault` that is not a boolean, refused here before anything is sent.
+     *
+     * @effect write
+     */
+    create(input: CreateTaxCategoryInput, options?: Call): Promise<TaxCategory>;
+    /**
+     * Rename a tax category or move the default mark to it, and answer it as read. Every store
+     * mapping a tax class onto it, and every rate pricing it, keeps pointing at it.
+     *
+     * `ENTITY_NOT_FOUND` (`NotFoundError`, 404): no category has that id.
+     *
+     * @effect write
+     */
+    update(id: string, patch: UpdateTaxCategoryInput, options?: Call): Promise<TaxCategory>;
+    /**
+     * Delete a tax category nothing uses any more.
+     *
+     * - `TAX_CATEGORY_IN_USE` (`ConflictError`, 409): something still prices or carries it. The
+     *   message names what: the tax rates pricing it, each store's tax class mapped to it (by key
+     *   and store code), how many product variants carry it, and whether deleted variants or
+     *   orders were taxed with it. Rates, classes and live variants can be moved to another
+     *   category; deleted variants and orders keep it for good, so such a category can never be
+     *   deleted. Nothing is deleted.
+     * - `TAX_CATEGORY_NOT_DELETED` (`ConflictError`, 409): the engine refused it for a reason it
+     *   answered as a result rather than an error, with that reason.
+     * - `ENTITY_NOT_FOUND` (`NotFoundError`, 404): no category has that id.
+     *
+     * @effect destructive
+     */
+    delete(id: string, options?: Call): Promise<void>;
+}
+/**
+ * `admin.platform.tax.rates` — the SuperAdmin writes of the platform-wide tax rates: what a tax
+ * category costs in a zone. One rate serves every store, so a change reaches every store selling
+ * into that zone. Reads are `tax.rates.list()`.
+ *
+ * Every method needs a human SuperAdmin session (`PLATFORM_REQUIRES_SESSION` before anything is
+ * sent; `PLATFORM_SETTINGS_NOT_ALLOWED` from the engine for a store administrator, both
+ * `PermissionDeniedError`, 403). No tenant is needed on the client.
+ */
+export interface PlatformTaxRatesModule {
+    /**
+     * Create a tax rate, and answer it as `tax.rates.list()` reads it.
+     *
+     * - `INVALID_TAX_RATE_INPUT` (`ValidationError`, 400): a missing name, category, zone or
+     *   `enabled`, or a value that is not a finite number, refused here before anything is sent.
+     * - `ENTITY_NOT_FOUND` (`NotFoundError`, 404): the category, zone or customer group does not
+     *   exist.
+     *
+     * Tagged `money`: a rate decides the tax every store selling into its zone charges from the
+     * moment it exists.
+     *
+     * @effect money
+     */
+    create(input: CreateTaxRateInput, options?: Call): Promise<TaxRate>;
+    /**
+     * Change a tax rate, and answer it as read. Refused as {@link create} is, plus
+     * `INVALID_TAX_RATE_INPUT` for `customerGroupId: null` (see {@link UpdateTaxRateInput}) and
+     * `ENTITY_NOT_FOUND` for an unknown rate.
+     *
+     * @effect money
+     */
+    update(id: string, patch: UpdateTaxRateInput, options?: Call): Promise<TaxRate>;
+    /**
+     * Delete a tax rate, for every store.
+     *
+     * - `TAX_RATE_NOT_DELETED` (`ConflictError`, 409): the engine refused it, with its reason.
+     * - `ENTITY_NOT_FOUND` (`NotFoundError`, 404): no rate has that id.
+     *
+     * @effect destructive
+     */
+    delete(id: string, options?: Call): Promise<void>;
+}
+/** `admin.platform.tax`: SuperAdmin writes of the platform-wide tax tables (G128). */
+export interface PlatformTaxModule {
+    categories: PlatformTaxCategoriesModule;
+    rates: PlatformTaxRatesModule;
+}
+export declare const CREATE_TAX_CATEGORY_MUTATION = "\n  mutation PlatformCreateTaxCategory($input: CreateTaxCategoryInput!) {\n    createTaxCategory(input: $input) { \n  id\n  name\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const UPDATE_TAX_CATEGORY_MUTATION = "\n  mutation PlatformUpdateTaxCategory($input: UpdateTaxCategoryInput!) {\n    updateTaxCategory(input: $input) { \n  id\n  name\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const DELETE_TAX_CATEGORY_MUTATION = "\n  mutation PlatformDeleteTaxCategory($id: ID!) {\n    deleteTaxCategory(id: $id) { \n  result\n  message\n }\n  }\n";
+export declare const CREATE_TAX_RATE_MUTATION = "\n  mutation PlatformCreateTaxRate($input: CreateTaxRateInput!) {\n    createTaxRate(input: $input) { \n  id\n  name\n  value\n  enabled\n  category { id name }\n  zone { id name }\n  customerGroup { id name }\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const UPDATE_TAX_RATE_MUTATION = "\n  mutation PlatformUpdateTaxRate($input: UpdateTaxRateInput!) {\n    updateTaxRate(input: $input) { \n  id\n  name\n  value\n  enabled\n  category { id name }\n  zone { id name }\n  customerGroup { id name }\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const DELETE_TAX_RATE_MUTATION = "\n  mutation PlatformDeleteTaxRate($id: ID!) {\n    deleteTaxRate(id: $id) { \n  result\n  message\n }\n  }\n";
+export declare function createPlatformTaxModule(transport: Transport, config: AdminClientConfig): PlatformTaxModule;

package/dist/platform/tax.js

@@ -0,0 +1,139 @@
+import { ValidationError } from '@sixtyninecommerce/core';
+import { assertDeleted, DELETION_FIELDS, fieldOf, } from '../catalog/types.js';
+import { TAX_CATEGORY_FIELDS, TAX_RATE_FIELDS, } from '../tax/index.js';
+import { requireHumanSession } from './guard.js';
+export const CREATE_TAX_CATEGORY_MUTATION = /* GraphQL */ `
+  mutation PlatformCreateTaxCategory($input: CreateTaxCategoryInput!) {
+    createTaxCategory(input: $input) { ${TAX_CATEGORY_FIELDS} }
+  }
+`;
+export const UPDATE_TAX_CATEGORY_MUTATION = /* GraphQL */ `
+  mutation PlatformUpdateTaxCategory($input: UpdateTaxCategoryInput!) {
+    updateTaxCategory(input: $input) { ${TAX_CATEGORY_FIELDS} }
+  }
+`;
+export const DELETE_TAX_CATEGORY_MUTATION = /* GraphQL */ `
+  mutation PlatformDeleteTaxCategory($id: ID!) {
+    deleteTaxCategory(id: $id) { ${DELETION_FIELDS} }
+  }
+`;
+export const CREATE_TAX_RATE_MUTATION = /* GraphQL */ `
+  mutation PlatformCreateTaxRate($input: CreateTaxRateInput!) {
+    createTaxRate(input: $input) { ${TAX_RATE_FIELDS} }
+  }
+`;
+export const UPDATE_TAX_RATE_MUTATION = /* GraphQL */ `
+  mutation PlatformUpdateTaxRate($input: UpdateTaxRateInput!) {
+    updateTaxRate(input: $input) { ${TAX_RATE_FIELDS} }
+  }
+`;
+export const DELETE_TAX_RATE_MUTATION = /* GraphQL */ `
+  mutation PlatformDeleteTaxRate($id: ID!) {
+    deleteTaxRate(id: $id) { ${DELETION_FIELDS} }
+  }
+`;
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const refusal = (code) => (message) => new ValidationError({ code, message, status: 400, service: 'vendure' });
+const categoryRefusal = refusal('INVALID_TAX_CATEGORY_INPUT');
+const rateRefusal = refusal('INVALID_TAX_RATE_INPUT');
+function requireId(id, what, refuse) {
+    if (typeof id !== 'string' || id.trim() === '')
+        throw refuse(`${what} must be an id.`);
+    return id;
+}
+function categoryInput(input, creating) {
+    if (!isObject(input))
+        throw categoryRefusal('A tax category input must be an object.');
+    const out = {};
+    if (input.name !== undefined || creating) {
+        if (typeof input.name !== 'string' || input.name.trim() === '') {
+            throw categoryRefusal('A tax category needs a name.');
+        }
+        out.name = input.name;
+    }
+    if (input.isDefault !== undefined) {
+        if (typeof input.isDefault !== 'boolean')
+            throw categoryRefusal('isDefault must be a boolean.');
+        out.isDefault = input.isDefault;
+    }
+    return out;
+}
+function rateInput(input, creating) {
+    if (!isObject(input))
+        throw rateRefusal('A tax rate input must be an object.');
+    const out = {};
+    if (input.name !== undefined || creating) {
+        if (typeof input.name !== 'string' || input.name.trim() === '') {
+            throw rateRefusal('A tax rate needs a name.');
+        }
+        out.name = input.name;
+    }
+    if (input.value !== undefined || creating) {
+        if (typeof input.value !== 'number' || !Number.isFinite(input.value)) {
+            throw rateRefusal('value must be a finite number: the percentage, 21 for 21 %.');
+        }
+        out.value = input.value;
+    }
+    if (input.enabled !== undefined || creating) {
+        if (typeof input.enabled !== 'boolean')
+            throw rateRefusal('enabled must be a boolean.');
+        out.enabled = input.enabled;
+    }
+    if (input.categoryId !== undefined || creating) {
+        out.categoryId = requireId(input.categoryId, 'categoryId', rateRefusal);
+    }
+    if (input.zoneId !== undefined || creating) {
+        out.zoneId = requireId(input.zoneId, 'zoneId', rateRefusal);
+    }
+    if (input.customerGroupId === null && !creating) {
+        // The engine reads a null group as "keep the stored one": a request that seems to widen a
+        // group-limited rate to every customer would answer success and change nothing.
+        throw rateRefusal('A tax rate cannot lose its customer group: create a rate without one and delete this one.');
+    }
+    if (input.customerGroupId !== undefined && input.customerGroupId !== null) {
+        out.customerGroupId = requireId(input.customerGroupId, 'customerGroupId', rateRefusal);
+    }
+    return out;
+}
+export function createPlatformTaxModule(transport, config) {
+    // Platform-wide rows: no store is involved, so no tenant is needed. Scoped to a store instead,
+    // the transport would first resolve it through the CMS channel mirror and fail on one missing
+    // there.
+    const unscoped = (call) => ({ ...call, allowUnscoped: true });
+    return {
+        categories: {
+            async create(input, options) {
+                requireHumanSession(config);
+                return fieldOf(transport, CREATE_TAX_CATEGORY_MUTATION, 'createTaxCategory', { input: categoryInput(input, true) }, unscoped(options));
+            },
+            async update(id, patch, options) {
+                requireHumanSession(config);
+                const categoryId = requireId(id, 'id', categoryRefusal);
+                return fieldOf(transport, UPDATE_TAX_CATEGORY_MUTATION, 'updateTaxCategory', { input: { ...categoryInput(patch, false), id: categoryId } }, unscoped(options));
+            },
+            async delete(id, options) {
+                requireHumanSession(config);
+                assertDeleted('TAX_CATEGORY_NOT_DELETED', [
+                    await fieldOf(transport, DELETE_TAX_CATEGORY_MUTATION, 'deleteTaxCategory', { id: requireId(id, 'id', categoryRefusal) }, unscoped(options)),
+                ]);
+            },
+        },
+        rates: {
+            async create(input, options) {
+                requireHumanSession(config);
+                return fieldOf(transport, CREATE_TAX_RATE_MUTATION, 'createTaxRate', { input: rateInput(input, true) }, unscoped(options));
+            },
+            async update(id, patch, options) {
+                requireHumanSession(config);
+                const rateId = requireId(id, 'id', rateRefusal);
+                return fieldOf(transport, UPDATE_TAX_RATE_MUTATION, 'updateTaxRate', { input: { ...rateInput(patch, false), id: rateId } }, unscoped(options));
+            },
+            async delete(id, options) {
+                requireHumanSession(config);
+                assertDeleted('TAX_RATE_NOT_DELETED', [
+                    await fieldOf(transport, DELETE_TAX_RATE_MUTATION, 'deleteTaxRate', { id: requireId(id, 'id', rateRefusal) }, unscoped(options)),
+                ]);
+            },
+        },
+    };
+}

package/dist/pos/anomalies.d.ts

@@ -0,0 +1,158 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * A store's anomaly flags (engine row 43): rules run over each location's ENDED business day flag
+ * unusual refunds, voids, returns without a receipt, outlying or unlogged discounts, cash
+ * variances, uncounted closes, money landed after a Z, a closed drawer whose cash changed, sales
+ * credited to another cashier and many no-sale opens. A flag never acts against anyone: a person
+ * reviews it and acknowledges it with a note.
+ *
+ * OFF until the store turns it on (`setRules({ enabled: true })`): flags name staff, and in the
+ * Netherlands and Germany a system that monitors staff needs the works council's consent first.
+ * Every read and write needs `UpdateSettings` or `ManagePosDevices` (`setRules`: `UpdateSettings`);
+ * a location-restricted caller sees its locations' flags only. Each method is its own document: an
+ * engine before 43 refuses it at validation, nothing else.
+ */
+export interface PosAnomalyThresholds {
+    minCount: number | null;
+    minSales: number | null;
+    multiplier: number | null;
+    floorPercent: number | null;
+    fallbackPercent: number | null;
+    percentile: number | null;
+    /** Minor units of the drawer currency; null = that test off. */
+    amount: number | null;
+}
+export interface PosAnomalyRule {
+    code: string;
+    enabled: boolean;
+    /** False: the store lacks the rule's source (it is skipped). */
+    available: boolean;
+    /** `info`, `warning` or `high`; more may come. */
+    severity: string;
+    /** `staff`, `drawer` or `store_day`; more may come. */
+    subject: string;
+    /** The thresholds this rule takes. */
+    parameters: string[];
+    thresholds: PosAnomalyThresholds;
+    defaults: PosAnomalyThresholds;
+}
+export interface PosAnomalyRules {
+    enabled: boolean;
+    rulesVersion: number;
+    rules: PosAnomalyRule[];
+}
+export interface PosAnomalyRuleInput extends Partial<PosAnomalyThresholds> {
+    code: string;
+    enabled: boolean;
+}
+export interface PosAnomalyRulesInput {
+    enabled: boolean;
+    /** Rules not listed keep their stored settings; a listed one is replaced whole. */
+    rules?: PosAnomalyRuleInput[];
+}
+/** A figure: `count`, `percent`, `basis_points` or `minor` (more may come). */
+export interface PosAnomalyFigure {
+    key: string;
+    value: number;
+    unit: string;
+}
+export interface PosAnomalyFlag {
+    id: string;
+    stockLocationId: string;
+    locationName: string | null;
+    businessDay: string;
+    rule: string;
+    severity: string;
+    subjectKind: string;
+    staffId: string | null;
+    staffName: string | null;
+    sessionId: string | null;
+    registerId: string | null;
+    registerName: string | null;
+    zNumber: number | null;
+    /** `open` or `acknowledged`; more may come. */
+    status: string;
+    measure: PosAnomalyFigure[];
+    thresholds: PosAnomalyFigure[];
+    evidence: {
+        orders: Array<{
+            orderId: string;
+            code: string;
+            receiptNumber: string | null;
+            amount: number | null;
+        }>;
+        sessionIds: string[];
+        truncated: boolean;
+    };
+    detectedAt: string;
+    lastEvaluatedAt: string;
+    acknowledgedAt: string | null;
+    acknowledgedByName: string | null;
+    note: string | null;
+}
+export interface PosAnomalyFlagListOptions extends ListOptions {
+    /** `open` (default), `acknowledged` or `all`. */
+    status?: string;
+    fromDay?: string;
+    toDay?: string;
+    stockLocationId?: string;
+    rule?: string;
+    severity?: string;
+    staffId?: string;
+}
+export interface PosAnomalyOverview {
+    enabled: boolean;
+    open: number;
+    openHigh: number;
+    openWarning: number;
+    openInfo: number;
+    oldestOpenDay: string | null;
+}
+export interface PosAnomalyScanResult {
+    stockLocationId: string;
+    businessDay: string;
+    newFlagCount: number;
+    openFlagCount: number;
+    skippedRules: string[];
+}
+export interface PosAnomaliesModule {
+    rules(options?: Call): Promise<PosAnomalyRules>;
+    /**
+     * Refused `POS_ANOMALY_RULES_INVALID`: `details[0].field` is a JSON Pointer into the input
+     * (`/rules/<index>/<threshold>`, `/enabled`), `details[0].code` the reason.
+     */
+    setRules(input: PosAnomalyRulesInput, options?: Call): Promise<PosAnomalyRules>;
+    /** Newest business day first, then severity; `limit` 1-100 (25), `after` an offset cursor. */
+    list(options?: PosAnomalyFlagListOptions): Promise<Page<PosAnomalyFlag>>;
+    /** One flag, or null (another store's, or another location's for a restricted caller). */
+    get(id: string, options?: Call): Promise<PosAnomalyFlag | null>;
+    overview(options?: Call): Promise<PosAnomalyOverview>;
+    /** Refused `POS_ANOMALY_FLAG_NOT_FOUND`, `POS_ANOMALY_FLAG_NOT_OPEN`, `POS_ANOMALY_NOTE_INVALID`. */
+    acknowledge(input: {
+        flagId: string;
+        note: string;
+    }, options?: Call): Promise<PosAnomalyFlag>;
+    /**
+     * Evaluate one ENDED business day of a location now (a rerun adds nothing). Refused
+     * `POS_ANOMALY_FLAGS_OFF`, `POS_ANOMALY_DAY_NOT_ENDED`, `POS_LIST_RANGE_INVALID`,
+     * `POS_ANOMALY_SCAN_BUSY`, `POS_LOCATION_NOT_FOUND`, `LOCATION_NOT_ALLOWED`.
+     */
+    scanDay(input: {
+        stockLocationId: string;
+        businessDay: string;
+    }, options?: Call): Promise<PosAnomalyScanResult>;
+}
+export declare const POS_ANOMALY_FLAG_FIELDS = "id stockLocationId locationName businessDay rule severity subjectKind staffId staffName sessionId registerId registerName zNumber status measure { key value unit } thresholds { key value unit } evidence { orders { orderId code receiptNumber amount } sessionIds truncated } detectedAt lastEvaluatedAt acknowledgedAt acknowledgedByName note";
+export declare const POS_ANOMALY_RULES_QUERY = "query PosAnomalyRules { posAnomalyRules { enabled rulesVersion rules { code enabled available severity subject parameters thresholds { minCount minSales multiplier floorPercent fallbackPercent percentile amount } defaults { minCount minSales multiplier floorPercent fallbackPercent percentile amount } } } }";
+export declare const SET_POS_ANOMALY_RULES_MUTATION = "mutation SetPosAnomalyRules($input: PosAnomalyRulesInput!) { setPosAnomalyRules(input: $input) { enabled rulesVersion rules { code enabled available severity subject parameters thresholds { minCount minSales multiplier floorPercent fallbackPercent percentile amount } defaults { minCount minSales multiplier floorPercent fallbackPercent percentile amount } } } }";
+export declare const POS_ANOMALY_FLAGS_QUERY = "query PosAnomalyFlags($input: PosAnomalyFlagListInput) { posAnomalyFlags(input: $input) { items { id stockLocationId locationName businessDay rule severity subjectKind staffId staffName sessionId registerId registerName zNumber status measure { key value unit } thresholds { key value unit } evidence { orders { orderId code receiptNumber amount } sessionIds truncated } detectedAt lastEvaluatedAt acknowledgedAt acknowledgedByName note } totalItems } }";
+export declare const POS_ANOMALY_FLAG_QUERY = "query PosAnomalyFlag($id: ID!) { posAnomalyFlag(id: $id) { id stockLocationId locationName businessDay rule severity subjectKind staffId staffName sessionId registerId registerName zNumber status measure { key value unit } thresholds { key value unit } evidence { orders { orderId code receiptNumber amount } sessionIds truncated } detectedAt lastEvaluatedAt acknowledgedAt acknowledgedByName note } }";
+export declare const POS_ANOMALY_OVERVIEW_QUERY = "query PosAnomalyOverview { posAnomalyOverview { enabled open openHigh openWarning openInfo oldestOpenDay } }";
+export declare const ACKNOWLEDGE_POS_ANOMALY_FLAG_MUTATION = "mutation AcknowledgePosAnomalyFlag($input: AcknowledgePosAnomalyFlagInput!) { acknowledgePosAnomalyFlag(input: $input) { id stockLocationId locationName businessDay rule severity subjectKind staffId staffName sessionId registerId registerName zNumber status measure { key value unit } thresholds { key value unit } evidence { orders { orderId code receiptNumber amount } sessionIds truncated } detectedAt lastEvaluatedAt acknowledgedAt acknowledgedByName note } }";
+export declare const RUN_POS_ANOMALY_SCAN_MUTATION = "mutation RunPosAnomalyScan($input: RunPosAnomalyScanInput!) { runPosAnomalyScan(input: $input) { stockLocationId businessDay newFlagCount openFlagCount skippedRules } }";
+/** A flag page: at most this many. */
+export declare const POS_ANOMALY_FLAGS_MAX_PAGE = 100;
+/** ... and this many when `limit` is omitted. */
+export declare const POS_ANOMALY_FLAGS_DEFAULT_PAGE = 25;
+export declare function createPosAnomaliesModule(transport: Transport): PosAnomaliesModule;

package/dist/pos/anomalies.js

@@ -0,0 +1,64 @@
+import { pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+const THRESHOLDS = 'minCount minSales multiplier floorPercent fallbackPercent percentile amount';
+const RULES = `enabled rulesVersion rules { code enabled available severity subject parameters thresholds { ${THRESHOLDS} } defaults { ${THRESHOLDS} } }`;
+const FIGURE = 'key value unit';
+export const POS_ANOMALY_FLAG_FIELDS = `id stockLocationId locationName businessDay rule severity subjectKind staffId staffName sessionId registerId registerName zNumber status measure { ${FIGURE} } thresholds { ${FIGURE} } evidence { orders { orderId code receiptNumber amount } sessionIds truncated } detectedAt lastEvaluatedAt acknowledgedAt acknowledgedByName note`;
+export const POS_ANOMALY_RULES_QUERY = `query PosAnomalyRules { posAnomalyRules { ${RULES} } }`;
+export const SET_POS_ANOMALY_RULES_MUTATION = `mutation SetPosAnomalyRules($input: PosAnomalyRulesInput!) { setPosAnomalyRules(input: $input) { ${RULES} } }`;
+export const POS_ANOMALY_FLAGS_QUERY = `query PosAnomalyFlags($input: PosAnomalyFlagListInput) { posAnomalyFlags(input: $input) { items { ${POS_ANOMALY_FLAG_FIELDS} } totalItems } }`;
+export const POS_ANOMALY_FLAG_QUERY = `query PosAnomalyFlag($id: ID!) { posAnomalyFlag(id: $id) { ${POS_ANOMALY_FLAG_FIELDS} } }`;
+export const POS_ANOMALY_OVERVIEW_QUERY = 'query PosAnomalyOverview { posAnomalyOverview { enabled open openHigh openWarning openInfo oldestOpenDay } }';
+export const ACKNOWLEDGE_POS_ANOMALY_FLAG_MUTATION = `mutation AcknowledgePosAnomalyFlag($input: AcknowledgePosAnomalyFlagInput!) { acknowledgePosAnomalyFlag(input: $input) { ${POS_ANOMALY_FLAG_FIELDS} } }`;
+export const RUN_POS_ANOMALY_SCAN_MUTATION = 'mutation RunPosAnomalyScan($input: RunPosAnomalyScanInput!) { runPosAnomalyScan(input: $input) { stockLocationId businessDay newFlagCount openFlagCount skippedRules } }';
+/** A flag page: at most this many. */
+export const POS_ANOMALY_FLAGS_MAX_PAGE = 100;
+/** ... and this many when `limit` is omitted. */
+export const POS_ANOMALY_FLAGS_DEFAULT_PAGE = 25;
+const FILTERS = [
+    'status',
+    'fromDay',
+    'toDay',
+    'stockLocationId',
+    'rule',
+    'severity',
+    'staffId',
+];
+export function createPosAnomaliesModule(transport) {
+    const gql = (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+    const page = async (skip, take, options) => {
+        const input = { skip, take };
+        for (const key of FILTERS) {
+            const value = options?.[key];
+            if (value !== undefined && value !== '')
+                input[key] = value;
+        }
+        const data = await gql(POS_ANOMALY_FLAGS_QUERY, { input }, options);
+        return pageFromVendureList(data.posAnomalyFlags, skip, take, (cursor) => page(readOffsetCursor(cursor), take, options));
+    };
+    return {
+        async rules(options) {
+            return (await gql(POS_ANOMALY_RULES_QUERY, {}, options))
+                .posAnomalyRules;
+        },
+        async setRules(input, options) {
+            return (await gql(SET_POS_ANOMALY_RULES_MUTATION, { input }, options)).setPosAnomalyRules;
+        },
+        async list(options) {
+            const take = Math.min(Math.max(Math.trunc(options?.limit ?? POS_ANOMALY_FLAGS_DEFAULT_PAGE), 1), POS_ANOMALY_FLAGS_MAX_PAGE);
+            const skip = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+            return page(skip, take, options);
+        },
+        async get(id, options) {
+            return (await gql(POS_ANOMALY_FLAG_QUERY, { id }, options)).posAnomalyFlag;
+        },
+        async overview(options) {
+            return (await gql(POS_ANOMALY_OVERVIEW_QUERY, {}, options)).posAnomalyOverview;
+        },
+        async acknowledge(input, options) {
+            return (await gql(ACKNOWLEDGE_POS_ANOMALY_FLAG_MUTATION, { input }, options)).acknowledgePosAnomalyFlag;
+        },
+        async scanDay(input, options) {
+            return (await gql(RUN_POS_ANOMALY_SCAN_MUTATION, { input }, options)).runPosAnomalyScan;
+        },
+    };
+}

package/dist/pos/assisted-selling.d.ts

@@ -0,0 +1,79 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * A store's assisted selling at the till (engine sprint C4/44): upsell prompts under the till's
+ * cart, from the store's recommendation groups, and assisted search ("Ask": the cashier's words
+ * planned by the platform's AI, then searched in the catalogue). Upsell is on unless the store
+ * turns it off; assisted search is OFF unless the platform has enabled it AND the store turns it
+ * on.
+ */
+/** The most upsell suggestions a store may choose, and the most groups it may name. */
+export declare const POS_ASSISTED_SELLING_LIMITS: {
+    readonly upsellMaxItems: 8;
+    readonly upsellGroups: 10;
+    readonly assistedSearchDailyLimit: 5000;
+    readonly usageDays: 31;
+};
+export interface PosAssistedSelling {
+    /** Upsell prompts under the till's cart. */
+    upsellEnabled: boolean;
+    /** At most this many suggestions (1-8; 4 by default). */
+    upsellMaxItems: number;
+    /** Recommendation group slugs that feed the till, in order; empty = every enabled group. */
+    upsellGroupSlugs: string[];
+    /** AI-planned search at the till; always false while `assistedSearchAvailable` is false. */
+    assistedSearchEnabled: boolean;
+    /** The platform has enabled AI search; until then the store cannot turn it on. */
+    assistedSearchAvailable: boolean;
+    /** AI plans per day in the store's time zone (1-5,000; 300 by default). */
+    assistedSearchDailyLimit: number;
+}
+export interface PosAssistedSellingInput {
+    upsellEnabled: boolean;
+    /** Omitted keeps the stored value. */
+    upsellMaxItems?: number;
+    /** Replaces the list; omitted keeps it. */
+    upsellGroupSlugs?: string[];
+    assistedSearchEnabled: boolean;
+    /** Omitted keeps the stored value. */
+    assistedSearchDailyLimit?: number;
+}
+/** Why a search ran plain, counted per day. More reasons may come. */
+export interface PosAssistedSearchFallbackCount {
+    reason: string;
+    count: number;
+}
+/** One day of a store's assisted search; the words are never kept. */
+export interface PosAssistedSearchUsageDay {
+    /** YYYY-MM-DD in the store's time zone. */
+    day: string;
+    searches: number;
+    /** AI plans asked for (each counts against the daily limit). */
+    planned: number;
+    fallbacks: PosAssistedSearchFallbackCount[];
+    inputTokens: number;
+    outputTokens: number;
+}
+/** `get` needs any staff session of the store; `set` needs `UpdateSettings`; `usage` needs `UpdateSettings` or `ManagePosDevices`. */
+export interface PosAssistedSellingModule {
+    /** The store's assisted selling, defaults applied. */
+    get(options?: Call): Promise<PosAssistedSelling>;
+    /**
+     * Set it. Refusals: `POS_ASSISTED_SELLING_INVALID` (`ValidationError`; `field` and `reason`:
+     * `upsellMaxItems` outside 1-8, `assistedSearchDailyLimit` outside 1-5,000, more than 10
+     * groups, a repeated or blank slug, or a newly picked slug that is not an enabled group of the
+     * store), `POS_ASSISTED_SEARCH_UNAVAILABLE` (turning assisted search on while the platform has
+     * it off), `ORGANIZATION_WORKSPACE_NOT_A_STORE`. An unchanged setting writes nothing.
+     */
+    set(input: PosAssistedSellingInput, options?: Call): Promise<PosAssistedSelling>;
+    /**
+     * The last `days` (1-31, 30 when omitted) of the store's assisted search, newest first; a day
+     * nobody searched has no entry. Refused `POS_ASSISTED_SELLING_INVALID` (`field: 'days'`) out of
+     * range; the SDK refuses a `days` that is not a whole number before sending.
+     */
+    usage(days?: number, options?: Call): Promise<PosAssistedSearchUsageDay[]>;
+}
+export declare const POS_ASSISTED_SELLING_QUERY = "query PosAssistedSelling { posAssistedSelling { upsellEnabled upsellMaxItems upsellGroupSlugs assistedSearchEnabled assistedSearchAvailable assistedSearchDailyLimit } }";
+export declare const SET_POS_ASSISTED_SELLING_MUTATION = "mutation SetPosAssistedSelling($input: PosAssistedSellingInput!) { setPosAssistedSelling(input: $input) { upsellEnabled upsellMaxItems upsellGroupSlugs assistedSearchEnabled assistedSearchAvailable assistedSearchDailyLimit } }";
+export declare const POS_ASSISTED_SEARCH_USAGE_QUERY = "query PosAssistedSearchUsage($days: Int) { posAssistedSearchUsage(days: $days) { day searches planned fallbacks { reason count } inputTokens outputTokens } }";
+export declare function createPosAssistedSellingModule(transport: Transport): PosAssistedSellingModule;

package/dist/pos/assisted-selling.js

@@ -0,0 +1,38 @@
+/**
+ * A store's assisted selling at the till (engine sprint C4/44): upsell prompts under the till's
+ * cart, from the store's recommendation groups, and assisted search ("Ask": the cashier's words
+ * planned by the platform's AI, then searched in the catalogue). Upsell is on unless the store
+ * turns it off; assisted search is OFF unless the platform has enabled it AND the store turns it
+ * on.
+ */
+/** The most upsell suggestions a store may choose, and the most groups it may name. */
+export const POS_ASSISTED_SELLING_LIMITS = {
+    upsellMaxItems: 8,
+    upsellGroups: 10,
+    assistedSearchDailyLimit: 5000,
+    usageDays: 31,
+};
+const SELLING_FIELDS = 'upsellEnabled upsellMaxItems upsellGroupSlugs assistedSearchEnabled assistedSearchAvailable assistedSearchDailyLimit';
+export const POS_ASSISTED_SELLING_QUERY = `query PosAssistedSelling { posAssistedSelling { ${SELLING_FIELDS} } }`;
+export const SET_POS_ASSISTED_SELLING_MUTATION = `mutation SetPosAssistedSelling($input: PosAssistedSellingInput!) { setPosAssistedSelling(input: $input) { ${SELLING_FIELDS} } }`;
+export const POS_ASSISTED_SEARCH_USAGE_QUERY = 'query PosAssistedSearchUsage($days: Int) { posAssistedSearchUsage(days: $days) { day searches planned fallbacks { reason count } inputTokens outputTokens } }';
+export function createPosAssistedSellingModule(transport) {
+    const gql = async (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+    return {
+        async get(options) {
+            const data = await gql(POS_ASSISTED_SELLING_QUERY, {}, options);
+            return data.posAssistedSelling;
+        },
+        async set(input, options) {
+            const data = await gql(SET_POS_ASSISTED_SELLING_MUTATION, { input }, options);
+            return data.setPosAssistedSelling;
+        },
+        async usage(days, options) {
+            if (days !== undefined && !Number.isInteger(days)) {
+                throw new TypeError('assistedSelling.usage(days): days is a whole number from 1 to 31.');
+            }
+            const data = await gql(POS_ASSISTED_SEARCH_USAGE_QUERY, days === undefined ? {} : { days }, options);
+            return data.posAssistedSearchUsage;
+        },
+    };
+}