@sixtyninecommerce/admin 0.9.0 → 0.11.0

package/dist/pos/no-receipt.d.ts

@@ -0,0 +1,94 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Returns without a receipt (POS engine sprint 21): goods come back with no sale to return them
+ * against, as a document of their own (`NR-000001`, never an order). Each line at its current
+ * catalogue price incl. tax (or a lower typed price), its tax reversed per line; the money goes to
+ * a named customer's store credit or, where the store allows it, out of a till's open drawer with a
+ * manager. Money is integer minor units of the store's currency.
+ *
+ * - `policy.get` / `policy.set`: the store's rules (off, cash off, no limits until saved). `set`
+ *   needs UpdateSettings; an omitted field keeps its value, null clears a limit. Refused
+ *   `POS_NO_RECEIPT_POLICY_INVALID` (`extensions.field`).
+ * - `quote`: what a return would do now (lines, tax, total, what today's cap still allows, the
+ *   cash to hand out). A read; why it cannot be done now is `blockedBy`, never thrown.
+ *
+ * The return itself (`posNoReceiptReturn`) is taken at a PAIRED TILL: it pays out of, and is
+ * counted in, that till's open drawer, so a headless till (a machine principal) is refused
+ * `POS_PRINCIPAL_REQUIRED` and this module offers no `create` yet.
+ */
+export type PosNoReceiptPayout = 'STORE_CREDIT' | 'CASH';
+export interface PosNoReceiptReturnPolicy {
+    enabled: boolean;
+    /** Cash may be paid out (always with a manager and a reason). */
+    cashAllowed: boolean;
+    /** Highest total of one return; null: none. */
+    maxPerReturn: number | null;
+    /** Highest total per day (the till location's zone), both payouts; null: none. */
+    dailyCap: number | null;
+    currencyCode: string;
+    /** The store can credit a customer's store credit (a stored-value method and the entitlement). */
+    storeCreditAvailable: boolean;
+}
+/** What `policy.set` changes: an omitted field keeps its value; null clears a limit. */
+export interface PosNoReceiptReturnPolicyInput {
+    enabled?: boolean;
+    cashAllowed?: boolean;
+    maxPerReturn?: number | null;
+    dailyCap?: number | null;
+}
+export interface PosNoReceiptQuoteInput {
+    lines?: Array<{
+        variantId: string;
+        quantity: number;
+        unitPriceWithTax?: number;
+    }>;
+    customerId?: string;
+    /** Omitted: STORE_CREDIT. */
+    payout?: PosNoReceiptPayout;
+}
+export interface PosNoReceiptLine {
+    variantId: string;
+    name: string;
+    sku: string;
+    quantity: number;
+    catalogueUnitPriceWithTax: number;
+    unitPriceWithTax: number;
+    lineTotal: number;
+    /** Percent. */
+    taxRate: number;
+    lineTax: number;
+    restockable: boolean;
+    reasonCode: string | null;
+    restock: boolean | null;
+}
+export interface PosNoReceiptQuote {
+    currencyCode: string;
+    lines: PosNoReceiptLine[];
+    total: number;
+    tax: number;
+    taxSummary: Array<{
+        taxRate: number;
+        base: number;
+        tax: number;
+    }>;
+    policy: PosNoReceiptReturnPolicy;
+    remainingToday: number | null;
+    cashPaidOut: number;
+    restockLocationName: string | null;
+    /** A POS_NO_RECEIPT_* code (or POS_SESSION_REQUIRED), or null. More may come. */
+    blockedBy: string | null;
+    blockedReason: string | null;
+}
+export interface PosNoReceiptModule {
+    policy: {
+        get(options?: Call): Promise<PosNoReceiptReturnPolicy>;
+        set(input: PosNoReceiptReturnPolicyInput, options?: Call): Promise<PosNoReceiptReturnPolicy>;
+    };
+    /** What a return without a receipt would do now. Writes nothing. */
+    quote(input: PosNoReceiptQuoteInput, options?: Call): Promise<PosNoReceiptQuote>;
+}
+export declare const POS_NO_RECEIPT_RETURN_POLICY_QUERY = "query PosNoReceiptReturnPolicy { posNoReceiptReturnPolicy { enabled cashAllowed maxPerReturn dailyCap currencyCode storeCreditAvailable } }";
+export declare const SET_POS_NO_RECEIPT_RETURN_POLICY_MUTATION = "mutation SetPosNoReceiptReturnPolicy($input: PosNoReceiptReturnPolicyInput!) { setPosNoReceiptReturnPolicy(input: $input) { enabled cashAllowed maxPerReturn dailyCap currencyCode storeCreditAvailable } }";
+export declare const POS_NO_RECEIPT_RETURN_QUOTE_QUERY = "query PosNoReceiptReturnQuote($input: PosNoReceiptQuoteInput!) { posNoReceiptReturnQuote(input: $input) { currencyCode lines { variantId name sku quantity catalogueUnitPriceWithTax unitPriceWithTax lineTotal taxRate lineTax restockable reasonCode restock } total tax taxSummary { taxRate base tax } policy { enabled cashAllowed maxPerReturn dailyCap currencyCode storeCreditAvailable } remainingToday cashPaidOut restockLocationName blockedBy blockedReason } }";
+export declare function createPosNoReceiptModule(transport: Transport): PosNoReceiptModule;

package/dist/pos/no-receipt.js

@@ -0,0 +1,25 @@
+const POLICY_FIELDS = 'enabled cashAllowed maxPerReturn dailyCap currencyCode storeCreditAvailable';
+const LINE_FIELDS = 'variantId name sku quantity catalogueUnitPriceWithTax unitPriceWithTax lineTotal taxRate lineTax restockable reasonCode restock';
+export const POS_NO_RECEIPT_RETURN_POLICY_QUERY = `query PosNoReceiptReturnPolicy { posNoReceiptReturnPolicy { ${POLICY_FIELDS} } }`;
+export const SET_POS_NO_RECEIPT_RETURN_POLICY_MUTATION = `mutation SetPosNoReceiptReturnPolicy($input: PosNoReceiptReturnPolicyInput!) { setPosNoReceiptReturnPolicy(input: $input) { ${POLICY_FIELDS} } }`;
+export const POS_NO_RECEIPT_RETURN_QUOTE_QUERY = `query PosNoReceiptReturnQuote($input: PosNoReceiptQuoteInput!) { posNoReceiptReturnQuote(input: $input) { currencyCode lines { ${LINE_FIELDS} } total tax taxSummary { taxRate base tax } policy { ${POLICY_FIELDS} } remainingToday cashPaidOut restockLocationName blockedBy blockedReason } }`;
+export function createPosNoReceiptModule(transport) {
+    const gql = async (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+    return {
+        policy: {
+            async get(options) {
+                const data = await gql(POS_NO_RECEIPT_RETURN_POLICY_QUERY, {}, options);
+                return data.posNoReceiptReturnPolicy;
+            },
+            async set(input, options) {
+                // Sent as given: an omitted field keeps its value, an explicit null clears a limit.
+                const data = await gql(SET_POS_NO_RECEIPT_RETURN_POLICY_MUTATION, { input: { ...input } }, options);
+                return data.setPosNoReceiptReturnPolicy;
+            },
+        },
+        async quote(input, options) {
+            const data = await gql(POS_NO_RECEIPT_RETURN_QUOTE_QUERY, { input }, options);
+            return data.posNoReceiptReturnQuote;
+        },
+    };
+}

package/dist/pos/offline-sales.d.ts

@@ -0,0 +1,187 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * Offline cash sales (engine sprint 45, shipped dark): a till that loses its connection may keep
+ * selling for cash, within the store's limits, and sends each sale when it is back. The engine
+ * records each sale once, at the prices the till charged, into the drawer it was rung in; a sale
+ * it cannot record as rung waits for a manager.
+ *
+ * - `admin.pos.settings.offlineCashSales()` / `setOfflineCashSales(input)`: the store's switch
+ *   (off by default) and its three limits, with whether the store can sell offline now.
+ * - `admin.pos.offlineSales.list` / `resolve`: the manager's queue. `needs_review` (recorded, a
+ *   reason to look at) and `refused` (nothing recorded but the row) wait until a manager marks
+ *   them handled with a note; `recorded` needs nobody.
+ * - `admin.pos.devices.offlineSalesToReview()`: how many of each device's offline sales wait.
+ *
+ * The replay itself (`posRecordOfflineSale`) is a paired till's door alone: a machine principal
+ * is online by nature, so this SDK offers no method for it. An engine before 45 answers every
+ * call here `GRAPHQL_VALIDATION_FAILED` (or a 400 the transport reports as `BAD_REQUEST`); each
+ * is a document of its own, so every other call keeps working there.
+ */
+/**
+ * The bounds of each limit, both inclusive, and the engine's default for a store that never saved
+ * them. Money in minor units of the store's default currency; minutes count from the server's
+ * last answer to the till. Outside the bounds the save is refused `POS_OFFLINE_POLICY_INVALID`.
+ */
+export declare const POS_OFFLINE_CASH_SALES_LIMITS: {
+    readonly maxSaleAmount: {
+        readonly min: 100;
+        readonly max: 500000;
+        readonly default: 10000;
+    };
+    readonly maxSalesPerOutage: {
+        readonly min: 1;
+        readonly max: 200;
+        readonly default: 25;
+    };
+    readonly maxOfflineMinutes: {
+        readonly min: 15;
+        readonly max: 720;
+        readonly default: 240;
+    };
+};
+/** What a manager writes when marking an offline sale handled: 1 to this many characters, trimmed. */
+export declare const POS_OFFLINE_SALE_NOTE_MAX_LENGTH = 500;
+/** Why a store cannot sell offline now, in the order the engine lists them. More may come. */
+export declare const POS_OFFLINE_NOT_READY_REASONS: readonly ["prices_exclude_tax", "automatic_promotions", "no_cash_method", "pos_disabled"];
+export type PosOfflineNotReadyReason = (typeof POS_OFFLINE_NOT_READY_REASONS)[number];
+/**
+ * Why the engine refused or flagged an offline sale, in the order an answer lists them: the
+ * refusals first (`item_gone` to `rounding_mismatch`: nothing was recorded but the row), then the
+ * reviews (`price_changed` to `sold_at_suspect`: the sale is recorded). More may come.
+ */
+export declare const POS_OFFLINE_SALE_REASONS: readonly ["item_gone", "drawer_closed", "currency_changed", "prices_exclude_tax", "out_of_stock", "gift_card", "total_mismatch", "rounding_mismatch", "price_changed", "not_fulfilled", "cashier_changed", "policy_off", "over_cap", "sold_at_suspect"];
+export type PosOfflineSaleReason = (typeof POS_OFFLINE_SALE_REASONS)[number];
+/**
+ * `recorded` (the order, the cash and the receipt number exist, as the till rang it),
+ * `needs_review` (recorded, with a reason to look at) or `refused` (nothing but this row). More
+ * may come: show an unknown status as it is.
+ */
+export type PosOfflineSaleStatus = 'recorded' | 'needs_review' | 'refused';
+/** A store's offline cash sales (engine sprint 45): the switch, its limits, and its readiness. */
+export interface PosOfflineCashSales {
+    /** Off until a manager turns it on. */
+    enabled: boolean;
+    /** The largest offline sale, minor units of the store's default currency. */
+    maxSaleAmount: number;
+    /** Offline sales a till makes in one outage. */
+    maxSalesPerOutage: number;
+    /** Minutes after the server last answered that a till still sells offline. */
+    maxOfflineMinutes: number;
+    /** Whether this store can sell offline now: switched on is not enough. */
+    ready: boolean;
+    /** Why not; empty when ready. Strings, so a reason a newer engine adds never fails a read. */
+    notReadyReasons: Array<PosOfflineNotReadyReason | (string & {})>;
+}
+/** What `setOfflineCashSales` stores: every field, each within {@link POS_OFFLINE_CASH_SALES_LIMITS}. */
+export interface PosOfflineCashSalesInput {
+    enabled: boolean;
+    maxSaleAmount: number;
+    maxSalesPerOutage: number;
+    maxOfflineMinutes: number;
+}
+/** One line of an offline sale: what the till charged, and the server's price beside it. */
+export interface PosOfflineSaleLine {
+    variantId: string;
+    quantity: number;
+    /** The unit price with tax the till charged, minor units. */
+    unitPriceWithTax: number;
+    /**
+     * The server's unit price with tax when the sale was recorded; null when the variant was gone or
+     * the sale was refused before it was built.
+     */
+    serverUnitPriceWithTax: number | null;
+}
+/** An offline sale as the engine recorded or refused it (engine sprint 45). Money in minor units. */
+export interface PosOfflineSale {
+    id: string;
+    deviceId: string;
+    /** The till's name as the store names it now; null when it is gone. */
+    deviceLabel: string | null;
+    /** The drawer the till had open when it sold. */
+    registerSessionId: string;
+    /** The till's own id for the sale (a uuid). */
+    offlineSaleId: string;
+    /** The number printed on the provisional receipt the customer took. */
+    provisionalReceiptNumber: string;
+    /** When the till completed it, by the till's clock. */
+    soldAt: string;
+    /** When the engine received it. */
+    recordedAt: string;
+    status: PosOfflineSaleStatus | (string & {});
+    /** {@link PosOfflineSaleReason}s; strings, so one a newer engine adds never fails a read. */
+    reasons: Array<PosOfflineSaleReason | (string & {})>;
+    /** The order it became; null when refused. */
+    orderId: string | null;
+    orderCode: string | null;
+    /** The final receipt number; null when refused. */
+    receiptNumber: string | null;
+    currencyCode: string;
+    totalWithTax: number;
+    cashTendered: number;
+    changeGiven: number;
+    /** The cash rounding the till applied, signed. */
+    cashRounding: number;
+    lines: PosOfflineSaleLine[];
+    /** The cashier signed in when the till sent it (verified), as the store names them now. */
+    staffName: string | null;
+    /** The cashier the till says rang it up: its claim. */
+    claimedStaffName: string | null;
+    /** When a manager marked it handled; null while it waits (or for a `recorded` sale). */
+    resolvedAt: string | null;
+    resolvedByUserName: string | null;
+    /** What the manager wrote they did about it. Staff text. */
+    resolutionNote: string | null;
+}
+/** `open` (the default): the sales a manager must still handle; `all`: every offline sale. */
+export type PosOfflineSaleFilter = 'open' | 'all';
+export interface PosOfflineSaleListOptions extends ListOptions {
+    filter?: PosOfflineSaleFilter;
+    /** One device's sales. */
+    deviceId?: string;
+}
+/** How many of a device's offline sales wait for a manager (the fleet's `offlineSalesToReview`). */
+export interface PosDeviceOfflineSalesToReview {
+    deviceId: string;
+    /** `needs_review` or `refused`, not yet handled. */
+    offlineSalesToReview: number;
+}
+export interface PosOfflineSalesModule {
+    /**
+     * The store's offline sales, newest first (`posOfflineSales`). `filter: 'open'` (the default)
+     * keeps the ones a manager must still handle (`needs_review` or `refused`, not yet handled);
+     * `'all'` every one. `deviceId` keeps one device's. `limit` is at most 100 (50 when omitted);
+     * `after` is the previous page's cursor; `total` counts the whole filter. A location-restricted
+     * caller sees the tills at its locations only. Refused `POS_LIST_RANGE_INVALID`
+     * (`extensions.field`, `reason`). Needs `UpdateSettings` or `ManagePosDevices`.
+     */
+    list(options?: PosOfflineSaleListOptions): Promise<Page<PosOfflineSale>>;
+    /**
+     * Mark an offline sale handled, with what was done about it (`note`: 1 to 500 characters once
+     * trimmed, no control character but a line break or a tab). Nothing is recorded again: fix the
+     * order, the stock or the drawer first, then say so here. Idempotent by state: the same note
+     * again answers the sale unchanged. Refused `POS_OFFLINE_NOTE_INVALID` (`ValidationError`,
+     * `details[0].field` `note`), `POS_OFFLINE_SALE_NOT_FOUND` (`NotFoundError`: another store's, a
+     * till the caller may not see, an unknown id, or a `recorded` sale, which needs nobody) and
+     * `POS_OFFLINE_SALE_RESOLVED` (`BusinessRuleError`, `extensions.resolvedAt`: already handled
+     * with another note). Needs `UpdateSettings` or `ManagePosDevices`.
+     */
+    resolve(input: {
+        id: string;
+        note: string;
+    }, options?: Call): Promise<PosOfflineSale>;
+}
+export declare const POS_OFFLINE_CASH_SALES_QUERY = "query PosOfflineCashSales { getPosConfig { offlineCashSales { enabled maxSaleAmount maxSalesPerOutage maxOfflineMinutes ready notReadyReasons } } }";
+export declare const SET_POS_OFFLINE_CASH_SALES_MUTATION = "mutation SetPosOfflineCashSales($input: PosOfflineCashSalesInput!) { setPosOfflineCashSales(input: $input) { enabled maxSaleAmount maxSalesPerOutage maxOfflineMinutes ready notReadyReasons } }";
+export declare const POS_OFFLINE_SALES_QUERY = "query PosOfflineSales($input: PosOfflineSaleListInput) { posOfflineSales(input: $input) { items { id deviceId deviceLabel registerSessionId offlineSaleId provisionalReceiptNumber soldAt recordedAt status reasons orderId orderCode receiptNumber currencyCode totalWithTax cashTendered changeGiven cashRounding lines { variantId quantity unitPriceWithTax serverUnitPriceWithTax } staffName claimedStaffName resolvedAt resolvedByUserName resolutionNote } totalItems } }";
+export declare const RESOLVE_POS_OFFLINE_SALE_MUTATION = "mutation ResolvePosOfflineSale($input: ResolvePosOfflineSaleInput!) { resolvePosOfflineSale(input: $input) { id deviceId deviceLabel registerSessionId offlineSaleId provisionalReceiptNumber soldAt recordedAt status reasons orderId orderCode receiptNumber currencyCode totalWithTax cashTendered changeGiven cashRounding lines { variantId quantity unitPriceWithTax serverUnitPriceWithTax } staffName claimedStaffName resolvedAt resolvedByUserName resolutionNote } }";
+export declare const POS_DEVICE_OFFLINE_SALES_TO_REVIEW_QUERY = "query PosDeviceOfflineSalesToReview($stockLocationId: ID) { posDeviceFleet(stockLocationId: $stockLocationId) { device { id } offlineSalesToReview } }";
+/** `admin.pos.settings.offlineCashSales()`: null when POS was never set up. */
+export declare function readOfflineCashSales(transport: Transport, options?: Call): Promise<PosOfflineCashSales | null>;
+/** `admin.pos.settings.setOfflineCashSales(input)`: the four fields, as given. */
+export declare function writeOfflineCashSales(transport: Transport, input: PosOfflineCashSalesInput, options?: Call): Promise<PosOfflineCashSales>;
+/** `admin.pos.devices.offlineSalesToReview()`: one row per device the fleet lists, whole. */
+export declare function readOfflineSalesToReview(transport: Transport, options?: {
+    stockLocationId?: string;
+} & Call): Promise<PosDeviceOfflineSalesToReview[]>;
+export declare function createPosOfflineSalesModule(transport: Transport): PosOfflineSalesModule;

package/dist/pos/offline-sales.js

@@ -0,0 +1,116 @@
+import { pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+/**
+ * Offline cash sales (engine sprint 45, shipped dark): a till that loses its connection may keep
+ * selling for cash, within the store's limits, and sends each sale when it is back. The engine
+ * records each sale once, at the prices the till charged, into the drawer it was rung in; a sale
+ * it cannot record as rung waits for a manager.
+ *
+ * - `admin.pos.settings.offlineCashSales()` / `setOfflineCashSales(input)`: the store's switch
+ *   (off by default) and its three limits, with whether the store can sell offline now.
+ * - `admin.pos.offlineSales.list` / `resolve`: the manager's queue. `needs_review` (recorded, a
+ *   reason to look at) and `refused` (nothing recorded but the row) wait until a manager marks
+ *   them handled with a note; `recorded` needs nobody.
+ * - `admin.pos.devices.offlineSalesToReview()`: how many of each device's offline sales wait.
+ *
+ * The replay itself (`posRecordOfflineSale`) is a paired till's door alone: a machine principal
+ * is online by nature, so this SDK offers no method for it. An engine before 45 answers every
+ * call here `GRAPHQL_VALIDATION_FAILED` (or a 400 the transport reports as `BAD_REQUEST`); each
+ * is a document of its own, so every other call keeps working there.
+ */
+/**
+ * The bounds of each limit, both inclusive, and the engine's default for a store that never saved
+ * them. Money in minor units of the store's default currency; minutes count from the server's
+ * last answer to the till. Outside the bounds the save is refused `POS_OFFLINE_POLICY_INVALID`.
+ */
+export const POS_OFFLINE_CASH_SALES_LIMITS = {
+    maxSaleAmount: { min: 100, max: 500_000, default: 10_000 },
+    maxSalesPerOutage: { min: 1, max: 200, default: 25 },
+    maxOfflineMinutes: { min: 15, max: 720, default: 240 },
+};
+/** What a manager writes when marking an offline sale handled: 1 to this many characters, trimmed. */
+export const POS_OFFLINE_SALE_NOTE_MAX_LENGTH = 500;
+/** Why a store cannot sell offline now, in the order the engine lists them. More may come. */
+export const POS_OFFLINE_NOT_READY_REASONS = [
+    'prices_exclude_tax',
+    'automatic_promotions',
+    'no_cash_method',
+    'pos_disabled',
+];
+/**
+ * Why the engine refused or flagged an offline sale, in the order an answer lists them: the
+ * refusals first (`item_gone` to `rounding_mismatch`: nothing was recorded but the row), then the
+ * reviews (`price_changed` to `sold_at_suspect`: the sale is recorded). More may come.
+ */
+export const POS_OFFLINE_SALE_REASONS = [
+    'item_gone',
+    'drawer_closed',
+    'currency_changed',
+    'prices_exclude_tax',
+    'out_of_stock',
+    'gift_card',
+    'total_mismatch',
+    'rounding_mismatch',
+    'price_changed',
+    'not_fulfilled',
+    'cashier_changed',
+    'policy_off',
+    'over_cap',
+    'sold_at_suspect',
+];
+const DEFAULT_PAGE = 50;
+const MAX_PAGE = 100;
+const POLICY_FIELDS = 'enabled maxSaleAmount maxSalesPerOutage maxOfflineMinutes ready notReadyReasons';
+const SALE_FIELDS = 'id deviceId deviceLabel registerSessionId offlineSaleId provisionalReceiptNumber soldAt recordedAt status reasons orderId orderCode receiptNumber currencyCode totalWithTax cashTendered changeGiven cashRounding lines { variantId quantity unitPriceWithTax serverUnitPriceWithTax } staffName claimedStaffName resolvedAt resolvedByUserName resolutionNote';
+export const POS_OFFLINE_CASH_SALES_QUERY = `query PosOfflineCashSales { getPosConfig { offlineCashSales { ${POLICY_FIELDS} } } }`;
+export const SET_POS_OFFLINE_CASH_SALES_MUTATION = `mutation SetPosOfflineCashSales($input: PosOfflineCashSalesInput!) { setPosOfflineCashSales(input: $input) { ${POLICY_FIELDS} } }`;
+export const POS_OFFLINE_SALES_QUERY = `query PosOfflineSales($input: PosOfflineSaleListInput) { posOfflineSales(input: $input) { items { ${SALE_FIELDS} } totalItems } }`;
+export const RESOLVE_POS_OFFLINE_SALE_MUTATION = `mutation ResolvePosOfflineSale($input: ResolvePosOfflineSaleInput!) { resolvePosOfflineSale(input: $input) { ${SALE_FIELDS} } }`;
+// The fleet's count beside the device's id alone, its own document: the fleet read
+// (`POS_DEVICE_FLEET_QUERY`) never names it, so an engine before 45 keeps answering the fleet.
+export const POS_DEVICE_OFFLINE_SALES_TO_REVIEW_QUERY = 'query PosDeviceOfflineSalesToReview($stockLocationId: ID) { posDeviceFleet(stockLocationId: $stockLocationId) { device { id } offlineSalesToReview } }';
+function gqlOf(transport) {
+    return async (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+}
+/** `admin.pos.settings.offlineCashSales()`: null when POS was never set up. */
+export async function readOfflineCashSales(transport, options) {
+    const data = await gqlOf(transport)(POS_OFFLINE_CASH_SALES_QUERY, {}, options);
+    return data.getPosConfig?.offlineCashSales ?? null;
+}
+/** `admin.pos.settings.setOfflineCashSales(input)`: the four fields, as given. */
+export async function writeOfflineCashSales(transport, input, options) {
+    const { enabled, maxSaleAmount, maxSalesPerOutage, maxOfflineMinutes } = input;
+    const data = await gqlOf(transport)(SET_POS_OFFLINE_CASH_SALES_MUTATION, { input: { enabled, maxSaleAmount, maxSalesPerOutage, maxOfflineMinutes } }, options);
+    return data.setPosOfflineCashSales;
+}
+/** `admin.pos.devices.offlineSalesToReview()`: one row per device the fleet lists, whole. */
+export async function readOfflineSalesToReview(transport, options) {
+    const data = await gqlOf(transport)(POS_DEVICE_OFFLINE_SALES_TO_REVIEW_QUERY, { stockLocationId: options?.stockLocationId ?? null }, options);
+    return data.posDeviceFleet.map((row) => ({
+        deviceId: row.device.id,
+        offlineSalesToReview: row.offlineSalesToReview,
+    }));
+}
+export function createPosOfflineSalesModule(transport) {
+    const gql = gqlOf(transport);
+    async function salePage(skip, take, options) {
+        const input = { skip, take };
+        if (options?.filter !== undefined)
+            input.filter = options.filter;
+        if (options?.deviceId !== undefined)
+            input.deviceId = options.deviceId;
+        const data = await gql(POS_OFFLINE_SALES_QUERY, { input }, options);
+        return pageFromVendureList(data.posOfflineSales, skip, take, (cursor) => salePage(readOffsetCursor(cursor), take, options));
+    }
+    return {
+        async list(options) {
+            const take = Math.min(Math.max(Math.trunc(options?.limit ?? DEFAULT_PAGE), 1), MAX_PAGE);
+            const skip = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+            return salePage(skip, take, options);
+        },
+        async resolve(input, options) {
+            // Sent as given: the engine trims and judges the note (POS_OFFLINE_NOTE_INVALID).
+            const data = await gql(RESOLVE_POS_OFFLINE_SALE_MUTATION, { input: { id: input.id, note: input.note } }, options);
+            return data.resolvePosOfflineSale;
+        },
+    };
+}

package/dist/pos/pay-by-link.d.ts

@@ -0,0 +1,143 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Pay by link at the till (engine C5, row 41): the till asks the customer to pay part or all of an
+ * open till sale through a link (shown as a QR code), which opens the store's online checkout on
+ * the customer's phone. The payment provider's webhook records the money on the sale; none of
+ * these calls does. While a link is open its amount is held back from every other tender
+ * (`outstanding` leaves it out) and the sale's money cannot change. Off until the store switches
+ * it on and picks the hosted payment method customers pay with.
+ *
+ * A headless till is a supported caller of every till money door: the link create is keyed like a
+ * tender (`idempotencyKey`), its check and cancel take no key (they read the state and are safe to
+ * repeat). An engine before C5 answers every call `GRAPHQL_VALIDATION_FAILED`.
+ */
+/** A link's life in minutes (the store's policy). */
+export declare const POS_PAY_BY_LINK_EXPIRY_MINUTES: {
+    readonly min: 5;
+    readonly max: 120;
+    readonly default: 30;
+};
+export interface PosPayByLinkPolicy {
+    enabled: boolean;
+    /** The code of the store's hosted payment method a link opens; null until chosen. */
+    methodCode: string | null;
+    /** 5-120; 30 by default. */
+    expiryMinutes: number;
+}
+export interface PosPayByLinkPolicyInput {
+    /** Omitted keeps the stored value. Switching on needs a method. */
+    enabled?: boolean;
+    methodCode?: string;
+    expiryMinutes?: number;
+}
+/** Whether the till may offer pay by link for a sale. */
+export interface PosPayByLinkOptions {
+    available: boolean;
+    /**
+     * Why not: `OFF`, `NO_METHOD`, `METHOD_UNUSABLE`, `NO_RETURN_PAGE`, `NOT_ENTITLED`,
+     * `NOT_CONFIGURED`; more may come. Null when available.
+     */
+    reason: string | null;
+    methodName: string | null;
+    expiryMinutes: number;
+}
+export interface PosPaymentRequest {
+    id: string;
+    amount: number;
+    currencyCode: string;
+    /** `OPEN`, `PAID`, `EXPIRED` or `CANCELLED`; more may come. */
+    status: string;
+    closeReason: string | null;
+    /** The link to show as a QR code; null once it is closed. A bearer link: never log it. */
+    url: string | null;
+    expiresAt: string;
+    createdAt: string;
+    /** How many checkouts the customer opened with it. */
+    attemptCount: number;
+    paymentId: string | null;
+}
+/** The sale's money with its links (`PosTenderState`), integer minor units. */
+export interface PosLinkTenderState {
+    orderId: string;
+    total: number;
+    settled: number;
+    pending: number;
+    /** What the OPEN links ask for, already left out of `outstanding`. */
+    requested: number;
+    /** What a new tender may take: total − settled − pending − requested, at least 0. */
+    outstanding: number;
+    covered: boolean;
+    paymentRequests: PosPaymentRequest[];
+}
+export interface PosPaymentRequestResult {
+    request: PosPaymentRequest;
+    tenderState: PosLinkTenderState;
+}
+export interface PosPaymentRequestOutcomeResult {
+    requestId: string;
+    /** `paid`, `pending`, `cancelled` or `unknown`; treat one you do not know as `unknown`. */
+    outcome: string;
+    /**
+     * Why, when pending, unknown or forced: `POS_PAYMENT_REQUEST_WAITING`, `…_CHECKOUT_OPEN`,
+     * `…_PAID_LANDING`, `…_PROVIDER_UNREACHABLE`, `…_FORCED`. Null otherwise.
+     */
+    reasonCode: string | null;
+    tenderState: PosLinkTenderState;
+}
+/** A till call's cashier: a paired DEVICE's PIN session; a machine principal omits it. */
+type TillCall = Call & {
+    staffToken?: string;
+};
+export interface PosPayByLinkModule {
+    /** The store's policy. Needs `UpdateSettings` or `ManagePosDevices`. */
+    policy(options?: Call): Promise<PosPayByLinkPolicy>;
+    /**
+     * Set it (omitted fields keep their value). Needs `UpdateSettings`. Refusals:
+     * `POS_PAY_BY_LINK_POLICY_INVALID` (`field`: `expiryMinutes` outside 5-120, a blank `methodCode`,
+     * or switched on with no method), `POS_PAY_BY_LINK_METHOD_UNUSABLE` (`reason`: switched on with a
+     * method that cannot open an online checkout here), `ORGANIZATION_WORKSPACE_NOT_A_STORE`.
+     */
+    setPolicy(input: PosPayByLinkPolicyInput, options?: Call): Promise<PosPayByLinkPolicy>;
+    /** Whether a link may be offered for this sale, and why not. Read only. */
+    options(orderId: string, options?: Call): Promise<PosPayByLinkOptions>;
+    /**
+     * Open a link for `amount` (at most what the sale still owes) on an open till sale; readies it
+     * for payment. Keyed: a repeat with the same `idempotencyKey` answers the same link. Refusals:
+     * `POS_PAY_BY_LINK_UNAVAILABLE` (`reason`), `POS_PAY_BY_LINK_TILL_CART_ONLY` (an order no till
+     * opened: send a link from the back office), `POS_PAYMENT_REQUEST_OPEN` (one open link per sale),
+     * `POS_TENDER_EXCEEDS_OUTSTANDING` (`requested`).
+     */
+    request(input: {
+        orderId: string;
+        amount: number;
+    }, options: TillCall & {
+        idempotencyKey: string;
+    }): Promise<PosPaymentRequestResult>;
+    /** How a link is doing; never records money. Refused `POS_PAYMENT_REQUEST_NOT_FOUND`. */
+    check(input: {
+        orderId: string;
+        requestId: string;
+    }, options?: TillCall): Promise<PosPaymentRequestOutcomeResult>;
+    /**
+     * Close a link: only when no checkout of the customer's can still pay, else it answers pending or
+     * unknown and stays open. `force` closes it anyway and needs a manager: a manager's own
+     * `staffToken` or a manager's `approvalToken` (`POS_MANAGER_REQUIRED` otherwise); a payment that
+     * lands afterwards is recorded on the sale and refunded like any other.
+     */
+    cancel(input: {
+        orderId: string;
+        requestId: string;
+        force?: boolean;
+    }, options?: TillCall & {
+        approvalToken?: string;
+    }): Promise<PosPaymentRequestOutcomeResult>;
+}
+export declare const POS_PAY_BY_LINK_POLICY_QUERY = "query PosPayByLinkPolicy { posPayByLinkPolicy { enabled methodCode expiryMinutes } }";
+export declare const SET_POS_PAY_BY_LINK_POLICY_MUTATION = "mutation SetPosPayByLinkPolicy($input: PosPayByLinkPolicyInput!) { setPosPayByLinkPolicy(input: $input) { enabled methodCode expiryMinutes } }";
+export declare const POS_PAY_BY_LINK_OPTIONS_QUERY = "query PosPayByLinkOptions($orderId: ID!) { posPayByLinkOptions(orderId: $orderId) { available reason methodName expiryMinutes } }";
+export declare const POS_REQUEST_PAYMENT_MUTATION = "mutation PosRequestPayment($input: PosRequestPaymentInput!, $staffToken: String) { posRequestPayment(input: $input, staffToken: $staffToken) { request { id amount currencyCode status closeReason url expiresAt createdAt attemptCount paymentId } tenderState { orderId total settled pending requested outstanding covered paymentRequests { id amount currencyCode status closeReason url expiresAt createdAt attemptCount paymentId } } } }";
+export declare const POS_CHECK_PAYMENT_REQUEST_MUTATION = "mutation PosCheckPaymentRequest($input: PosPaymentRequestInput!, $staffToken: String) { posCheckPaymentRequest(input: $input, staffToken: $staffToken) { requestId outcome reasonCode tenderState { orderId total settled pending requested outstanding covered paymentRequests { id amount currencyCode status closeReason url expiresAt createdAt attemptCount paymentId } } } }";
+export declare const POS_CANCEL_PAYMENT_REQUEST_MUTATION = "mutation PosCancelPaymentRequest($input: PosCancelPaymentRequestInput!, $staffToken: String, $approvalToken: String) { posCancelPaymentRequest(input: $input, staffToken: $staffToken, approvalToken: $approvalToken) { requestId outcome reasonCode tenderState { orderId total settled pending requested outstanding covered paymentRequests { id amount currencyCode status closeReason url expiresAt createdAt attemptCount paymentId } } } }";
+export declare function createPosPayByLinkModule(transport: Transport): PosPayByLinkModule;
+export {};

package/dist/pos/pay-by-link.js

@@ -0,0 +1,57 @@
+/**
+ * Pay by link at the till (engine C5, row 41): the till asks the customer to pay part or all of an
+ * open till sale through a link (shown as a QR code), which opens the store's online checkout on
+ * the customer's phone. The payment provider's webhook records the money on the sale; none of
+ * these calls does. While a link is open its amount is held back from every other tender
+ * (`outstanding` leaves it out) and the sale's money cannot change. Off until the store switches
+ * it on and picks the hosted payment method customers pay with.
+ *
+ * A headless till is a supported caller of every till money door: the link create is keyed like a
+ * tender (`idempotencyKey`), its check and cancel take no key (they read the state and are safe to
+ * repeat). An engine before C5 answers every call `GRAPHQL_VALIDATION_FAILED`.
+ */
+/** A link's life in minutes (the store's policy). */
+export const POS_PAY_BY_LINK_EXPIRY_MINUTES = { min: 5, max: 120, default: 30 };
+const POLICY_FIELDS = 'enabled methodCode expiryMinutes';
+const REQUEST_FIELDS = 'id amount currencyCode status closeReason url expiresAt createdAt attemptCount paymentId';
+const STATE_FIELDS = `orderId total settled pending requested outstanding covered paymentRequests { ${REQUEST_FIELDS} }`;
+const OUTCOME_FIELDS = `requestId outcome reasonCode tenderState { ${STATE_FIELDS} }`;
+export const POS_PAY_BY_LINK_POLICY_QUERY = `query PosPayByLinkPolicy { posPayByLinkPolicy { ${POLICY_FIELDS} } }`;
+export const SET_POS_PAY_BY_LINK_POLICY_MUTATION = `mutation SetPosPayByLinkPolicy($input: PosPayByLinkPolicyInput!) { setPosPayByLinkPolicy(input: $input) { ${POLICY_FIELDS} } }`;
+export const POS_PAY_BY_LINK_OPTIONS_QUERY = 'query PosPayByLinkOptions($orderId: ID!) { posPayByLinkOptions(orderId: $orderId) { available reason methodName expiryMinutes } }';
+export const POS_REQUEST_PAYMENT_MUTATION = `mutation PosRequestPayment($input: PosRequestPaymentInput!, $staffToken: String) { posRequestPayment(input: $input, staffToken: $staffToken) { request { ${REQUEST_FIELDS} } tenderState { ${STATE_FIELDS} } } }`;
+export const POS_CHECK_PAYMENT_REQUEST_MUTATION = `mutation PosCheckPaymentRequest($input: PosPaymentRequestInput!, $staffToken: String) { posCheckPaymentRequest(input: $input, staffToken: $staffToken) { ${OUTCOME_FIELDS} } }`;
+export const POS_CANCEL_PAYMENT_REQUEST_MUTATION = `mutation PosCancelPaymentRequest($input: PosCancelPaymentRequestInput!, $staffToken: String, $approvalToken: String) { posCancelPaymentRequest(input: $input, staffToken: $staffToken, approvalToken: $approvalToken) { ${OUTCOME_FIELDS} } }`;
+export function createPosPayByLinkModule(transport) {
+    const gql = async (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+    return {
+        async policy(options) {
+            const data = await gql(POS_PAY_BY_LINK_POLICY_QUERY, {}, options);
+            return data.posPayByLinkPolicy;
+        },
+        async setPolicy(input, options) {
+            const data = await gql(SET_POS_PAY_BY_LINK_POLICY_MUTATION, { input }, options);
+            return data.setPosPayByLinkPolicy;
+        },
+        async options(orderId, options) {
+            const data = await gql(POS_PAY_BY_LINK_OPTIONS_QUERY, { orderId }, options);
+            return data.posPayByLinkOptions;
+        },
+        async request(input, options) {
+            const key = options?.idempotencyKey;
+            if (typeof key !== 'string' || key.trim() === '') {
+                throw new TypeError('payByLink.request needs options.idempotencyKey (a fresh UUIDv7 per link; resend it only to retry the same link).');
+            }
+            const data = await gql(POS_REQUEST_PAYMENT_MUTATION, { input: { ...input, idempotencyKey: key }, staffToken: options.staffToken }, options);
+            return data.posRequestPayment;
+        },
+        async check(input, options) {
+            const data = await gql(POS_CHECK_PAYMENT_REQUEST_MUTATION, { input, staffToken: options?.staffToken }, options);
+            return data.posCheckPaymentRequest;
+        },
+        async cancel(input, options) {
+            const data = await gql(POS_CANCEL_PAYMENT_REQUEST_MUTATION, { input, staffToken: options?.staffToken, approvalToken: options?.approvalToken }, options);
+            return data.posCancelPaymentRequest;
+        },
+    };
+}