@sixtyninecommerce/admin 0.10.0 → 0.12.0

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;
+        },
+    };
+}

package/dist/pos/exchanges.d.ts

@@ -0,0 +1,108 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import type { PosReturnLeg, PosReturnLineInput, PosReturnQuoteLine, PosReturnRefund } from './returns.js';
+/**
+ * Till exchanges (POS engine sprint 21): a completed till sale's items come back and their value
+ * pays an OPEN till cart as its LAST tender, carried as settled exchange-credit payments (no
+ * provider is asked for what is carried), any excess refunded to the sale's own payments. A
+ * headless till (a machine principal with `x-location`) is a supported caller: its CREDENTIAL is
+ * the manager gate, so no staff or approval token is sent. Money is integer minor units.
+ *
+ * `quote` is a read: the credit, what the cart owes, what would be carried, the excess and its
+ * refunds, and why it cannot be done now (`blockedBy`, never thrown:
+ * `POS_EXCHANGE_BALANCE_DUE` while the cart owes more than the credit — tender the difference
+ * first). `create` re-computes under the sale's money turn and refuses figures other than
+ * `expectedCredit` / `expectedApplied` (`POS_EXCHANGE_AMOUNT_CHANGED`). Then complete the cart
+ * with `sale.complete`. Refusals that mean NOTHING moved: `POS_EXCHANGE_INVALID`
+ * (`extensions.reason`: not_till_cart, same_order, currency, nothing_owed), the `POS_RETURN_*`
+ * refusals of `returns.create`, `POS_CART_HELD`. `IDEMPOTENCY_OUTCOME_UNKNOWN`: an excess card
+ * refund reached the provider and the outcome is unknown; never retry under a new key.
+ */
+export interface PosExchangeQuoteInput {
+    /** The completed till sale the items come back from. */
+    returnOrderId: string;
+    /** The open till cart the credit goes to. */
+    orderId: string;
+    lines?: Array<{
+        orderLineId: string;
+        quantity: number;
+    }>;
+    cashFirst?: boolean;
+}
+export interface PosExchangeCarry {
+    /** The returned sale's payment the credit comes from. */
+    sourcePaymentId: string;
+    /** cash, card or other. More may come. */
+    kind: string;
+    method: string;
+    amount: number;
+    /** The exchange payment on the cart; null in a quote. */
+    paymentId: string | null;
+}
+export interface PosExchangeQuote {
+    returnOrderId: string;
+    orderId: string;
+    currencyCode: string;
+    receiptNumber: string | null;
+    lines: PosReturnQuoteLine[];
+    credit: number;
+    newSaleTotal: number;
+    newSalePaid: number;
+    /** Still to pay before the exchange: tender it first. */
+    due: number;
+    applied: number;
+    excess: number;
+    carries: PosExchangeCarry[];
+    legs: PosReturnLeg[];
+    cashPaidOut: number;
+    returnWindowEndsAt: string | null;
+    outsideWindow: boolean;
+    refundedOutsideReturns: number;
+    restockLocationName: string | null;
+    /** A POS_EXCHANGE_* / POS_RETURN_* code, or null. More may come. */
+    blockedBy: string | null;
+    blockedReason: string | null;
+}
+export interface PosExchangeCreateInput {
+    returnOrderId: string;
+    orderId: string;
+    lines: PosReturnLineInput[];
+    /** `quote(...).credit` as shown. */
+    expectedCredit: number;
+    /** `quote(...).applied` as shown. */
+    expectedApplied: number;
+    overrideWindow?: boolean;
+    cashFirst?: boolean;
+}
+export interface PosExchangeResult {
+    returnOrderId: string;
+    orderId: string;
+    returnId: string;
+    /** The return's RMA code. */
+    returnCode: string;
+    credit: number;
+    applied: number;
+    excess: number;
+    carries: PosExchangeCarry[];
+    refunds: PosReturnRefund[];
+    cashPaidOut: number;
+    /**
+     * What the cart still owes after the credit: 0, unless a card is being charged on it or a
+     * payment link is open, which the exchange holds back (it never carries credit over money in
+     * flight). Complete the sale with `sale.complete` once that money lands; a completion while
+     * money is still owed is refused `POS_SALE_NOT_COVERED`.
+     */
+    remaining: number;
+    complete: boolean;
+}
+export interface PosExchangesModule {
+    /** What an exchange would do now. Writes nothing. */
+    quote(input: PosExchangeQuoteInput, options?: Call): Promise<PosExchangeQuote>;
+    /** Exchange the items: the key is REQUIRED (`options.idempotencyKey`). */
+    create(input: PosExchangeCreateInput, options: Call & {
+        idempotencyKey: string;
+    }): Promise<PosExchangeResult>;
+}
+export declare const POS_EXCHANGE_QUOTE_QUERY = "query PosExchangeQuote($input: PosExchangeQuoteInput!) { posExchangeQuote(input: $input) { returnOrderId orderId currencyCode receiptNumber lines { orderLineId name sku customItem restockable soldQuantity returnedQuantity returnableQuantity quantity refundAmount } credit newSaleTotal newSalePaid due applied excess carries { sourcePaymentId kind method amount paymentId } legs { paymentId kind method amount } cashPaidOut returnWindowEndsAt outsideWindow refundedOutsideReturns restockLocationName blockedBy blockedReason } }";
+export declare const POS_EXCHANGE_MUTATION = "mutation PosExchange($input: PosExchangeInput!) { posExchange(input: $input) { returnOrderId orderId returnId returnCode credit applied excess carries { sourcePaymentId kind method amount paymentId } refunds { paymentId kind method amount refundId outcome } cashPaidOut remaining complete } }";
+export declare function createPosExchangesModule(transport: Transport): PosExchangesModule;

package/dist/pos/exchanges.js

@@ -0,0 +1,22 @@
+const CARRY_FIELDS = 'sourcePaymentId kind method amount paymentId';
+const QUOTE_FIELDS = `returnOrderId orderId currencyCode receiptNumber lines { orderLineId name sku customItem restockable soldQuantity returnedQuantity returnableQuantity quantity refundAmount } credit newSaleTotal newSalePaid due applied excess carries { ${CARRY_FIELDS} } legs { paymentId kind method amount } cashPaidOut returnWindowEndsAt outsideWindow refundedOutsideReturns restockLocationName blockedBy blockedReason`;
+const RESULT_FIELDS = `returnOrderId orderId returnId returnCode credit applied excess carries { ${CARRY_FIELDS} } refunds { paymentId kind method amount refundId outcome } cashPaidOut remaining complete`;
+export const POS_EXCHANGE_QUOTE_QUERY = `query PosExchangeQuote($input: PosExchangeQuoteInput!) { posExchangeQuote(input: $input) { ${QUOTE_FIELDS} } }`;
+export const POS_EXCHANGE_MUTATION = `mutation PosExchange($input: PosExchangeInput!) { posExchange(input: $input) { ${RESULT_FIELDS} } }`;
+export function createPosExchangesModule(transport) {
+    const gql = async (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+    return {
+        async quote(input, options) {
+            const data = await gql(POS_EXCHANGE_QUOTE_QUERY, { input }, options);
+            return data.posExchangeQuote;
+        },
+        async create(input, options) {
+            const key = options?.idempotencyKey;
+            if (typeof key !== 'string' || key.trim() === '') {
+                throw new TypeError('pos.exchanges.create needs options.idempotencyKey (a fresh UUIDv7 per exchange; reuse it only to retry the same one).');
+            }
+            const data = await gql(POS_EXCHANGE_MUTATION, { input: { ...input, idempotencyKey: key } }, options);
+            return data.posExchange;
+        },
+    };
+}

package/dist/pos/gift-cards.d.ts

@@ -0,0 +1,135 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Gift cards at the till (engine C6): a headless till sells a gift card like any item, takes one
+ * as payment by its CODE, checks a card's balance, and hands a sale's codes over itself.
+ *
+ * - **Selling to anyone.** A sale whose buyer has no email address may sell a gift card when the
+ *   till hands the codes over itself: call `setHandover` before the sale's first tender (a
+ *   printer, or any way your till shows the code once). The sale's cards are then issued when it
+ *   completes, and `completeSale` answers their codes in its FIRST answer only.
+ * - **The code is shown once and kept nowhere.** The engine stores no code; a retry of the same
+ *   completion key answers the cards with `code: null`. Hand the codes to your customer (print
+ *   them) straight from that first answer, and never log, cache or persist them: this SDK keeps
+ *   none. A lost first answer loses the codes; a back-office `giftCards.reissueCode` gives the card
+ *   a new one.
+ * - **Paying by code.** `tender` resolves the code on the engine and pays from that card; the
+ *   payment never names the card's account (an account id is not a way to spend a card).
+ *
+ * Every money call is keyed (`idempotencyKey`). Each lookup and each tender spends one of the
+ * caller's gift-card lookups (rate limited per credential and per address). An engine before C6
+ * answers every call `GRAPHQL_VALIDATION_FAILED`.
+ */
+/** A gift card as a till sees it: masked, never its code. */
+export interface PosGiftCardBalance {
+    /** `••••-••••-••••-K2Q7`. */
+    maskedCode: string;
+    /** What it can spend now, minor units of `currencyCode`. */
+    spendable: number;
+    currencyCode: string;
+    /** The last valid day (`YYYY-MM-DD`, store zone); null for no expiry. */
+    expiresOn: string | null;
+    /** `active`, `blocked` or `voided`; more may come (treat an unknown one as not usable). */
+    status: string;
+    /** Whether it can pay the sale named by `orderId` now; false without one. */
+    canPay: boolean;
+    /**
+     * Why not: `NO_SALE`, `EXPIRED`, `BLOCKED`, `CURRENCY`, `EMPTY`, `SALE_SELLS_GIFT_CARD`,
+     * `NOT_ACCEPTED`, `NOTHING_DUE`, `NOT_USABLE`; more may come. Null when it can pay.
+     */
+    cannotPayReason: string | null;
+}
+/** What a till needs to sell a sale's gift cards. */
+export interface PosGiftCardSale {
+    /** Gift-card units on the sale. */
+    units: number;
+    /** The till hands this sale's codes over itself (`setHandover`). */
+    handover: boolean;
+    /** The sale's customer can receive the codes by email (not the walk-in, not a placeholder). */
+    buyerHasEmail: boolean;
+    /** The store can issue gift cards now. */
+    canIssue: boolean;
+}
+/** A gift card a completed sale issued. */
+export interface PosIssuedGiftCard {
+    maskedCode: string;
+    /** `XXXX-XXXX-XXXX-XXXX` in the first answer of a handed-over sale only; null otherwise. */
+    code: string | null;
+    faceValue: number;
+    currencyCode: string;
+    expiresOn: string | null;
+}
+/** A completed sale with its gift cards. */
+export interface PosCompletedSaleWithGiftCards {
+    orderId: string;
+    orderCode: string;
+    receiptNumber: string;
+    state: string;
+    giftCards: PosIssuedGiftCard[];
+    /**
+     * The till hands this sale's codes over itself: they come in the first answer only, so a repeat
+     * answering them null cannot show them again. False for cards that went by email.
+     */
+    giftCardsHandedOver: boolean;
+}
+/** A gift card's payment, as every tender answers. */
+export interface PosGiftCardTenderResult {
+    orderId: string;
+    paymentId: string;
+    covered: boolean;
+    outstanding: number;
+    change: number;
+}
+/** A till call's cashier: a paired DEVICE's PIN session; a machine principal omits it. */
+type TillCall = Call & {
+    staffToken?: string;
+};
+export interface PosGiftCardsModule {
+    /**
+     * This store's card for `code`, masked; null for an unknown, malformed or other store's code.
+     * With `orderId` (the tender screen's who-rule), `canPay` says whether it can pay what that sale
+     * still owes. Spends one gift-card lookup.
+     */
+    byCode(code: string, sale?: {
+        orderId?: string | null;
+    }, options?: Call): Promise<PosGiftCardBalance | null>;
+    /** What the tender screen needs to sell the sale's gift cards. */
+    sale(orderId: string, options?: Call): Promise<PosGiftCardSale>;
+    /**
+     * Pay `amount` (at most what the card can spend and the sale still owes) from the card `code`
+     * names. Keyed: a repeat answers the same payment; the same key with another card is
+     * `IDEMPOTENCY_CONFLICT`. Refusals: `POS_GIFT_CARD_NOT_FOUND` (unknown, malformed or another
+     * store's code), `POS_STORED_VALUE_UNAVAILABLE`, `POS_TENDER_EXCEEDS_OUTSTANDING`, and the
+     * ledger's (`STORED_VALUE_INSUFFICIENT_BALANCE`, `STORED_VALUE_ACCOUNT_EXPIRED`,
+     * `STORED_VALUE_ACCOUNT_BLOCKED`, `STORED_VALUE_GIFT_CARD_PURCHASE_NOT_ALLOWED`, ...). Spends one
+     * gift-card lookup.
+     */
+    tender(input: {
+        orderId: string;
+        code: string;
+        amount: number;
+    }, options: TillCall & {
+        idempotencyKey: string;
+    }): Promise<PosGiftCardTenderResult>;
+    /**
+     * The till hands this sale's codes over itself: before the first tender of an open till sale,
+     * one-way. Refusals: `POS_GIFT_CARD_HANDOVER_TOO_LATE` (money is in),
+     * `STORED_VALUE_GIFT_CARD_NOT_CONFIGURED` (the store cannot issue gift cards now).
+     */
+    setHandover(orderId: string, options?: TillCall): Promise<PosGiftCardSale>;
+    /**
+     * `sale.complete` with the sale's gift cards: a handed-over sale's codes are in this call's
+     * FIRST answer only (a retry of the same key answers `code: null`). Hand them over at once and
+     * keep them nowhere; this SDK stores none.
+     */
+    completeSale(orderId: string, options: TillCall & {
+        idempotencyKey: string;
+    }): Promise<PosCompletedSaleWithGiftCards>;
+}
+export declare const POS_GIFT_CARD_BY_CODE_QUERY = "query PosGiftCardByCode($code: String!, $orderId: ID) { posGiftCardByCode(code: $code, orderId: $orderId) { maskedCode spendable currencyCode expiresOn status canPay cannotPayReason } }";
+export declare const POS_GIFT_CARD_SALE_QUERY = "query PosGiftCardSale($orderId: ID!) { posGiftCardSale(orderId: $orderId) { units handover buyerHasEmail canIssue } }";
+export declare const POS_TENDER_GIFT_CARD_MUTATION = "mutation PosTenderGiftCard($input: PosTenderGiftCardInput!, $staffToken: String) { posTenderGiftCard(input: $input, staffToken: $staffToken) { orderId paymentId covered outstanding change } }";
+export declare const POS_SET_GIFT_CARD_HANDOVER_MUTATION = "mutation PosSetGiftCardHandover($orderId: ID!, $staffToken: String) { posSetGiftCardHandover(orderId: $orderId, staffToken: $staffToken) { units handover buyerHasEmail canIssue } }";
+export declare const POS_COMPLETE_SALE_WITH_GIFT_CARDS_MUTATION = "mutation PosCompleteSaleWithGiftCards($input: PosCompleteSaleInput!, $staffToken: String) { posCompleteSale(input: $input, staffToken: $staffToken) { orderId orderCode receiptNumber state giftCards { maskedCode code faceValue currencyCode expiresOn } giftCardsHandedOver } }";
+export declare function createPosGiftCardsModule(transport: Transport): PosGiftCardsModule;
+export {};

package/dist/pos/gift-cards.js

@@ -0,0 +1,47 @@
+const BALANCE_FIELDS = 'maskedCode spendable currencyCode expiresOn status canPay cannotPayReason';
+const SALE_FIELDS = 'units handover buyerHasEmail canIssue';
+const TENDER_FIELDS = 'orderId paymentId covered outstanding change';
+const ISSUED_FIELDS = 'maskedCode code faceValue currencyCode expiresOn';
+export const POS_GIFT_CARD_BY_CODE_QUERY = `query PosGiftCardByCode($code: String!, $orderId: ID) { posGiftCardByCode(code: $code, orderId: $orderId) { ${BALANCE_FIELDS} } }`;
+export const POS_GIFT_CARD_SALE_QUERY = `query PosGiftCardSale($orderId: ID!) { posGiftCardSale(orderId: $orderId) { ${SALE_FIELDS} } }`;
+export const POS_TENDER_GIFT_CARD_MUTATION = `mutation PosTenderGiftCard($input: PosTenderGiftCardInput!, $staffToken: String) { posTenderGiftCard(input: $input, staffToken: $staffToken) { ${TENDER_FIELDS} } }`;
+export const POS_SET_GIFT_CARD_HANDOVER_MUTATION = `mutation PosSetGiftCardHandover($orderId: ID!, $staffToken: String) { posSetGiftCardHandover(orderId: $orderId, staffToken: $staffToken) { ${SALE_FIELDS} } }`;
+export const POS_COMPLETE_SALE_WITH_GIFT_CARDS_MUTATION = `mutation PosCompleteSaleWithGiftCards($input: PosCompleteSaleInput!, $staffToken: String) { posCompleteSale(input: $input, staffToken: $staffToken) { orderId orderCode receiptNumber state giftCards { ${ISSUED_FIELDS} } giftCardsHandedOver } }`;
+function requireKey(method, options) {
+    const key = options?.idempotencyKey;
+    if (typeof key !== 'string' || key.trim() === '') {
+        throw new TypeError(`giftCards.${method} needs options.idempotencyKey (a fresh UUIDv7 per call; resend it only to retry the same one).`);
+    }
+    return key;
+}
+export function createPosGiftCardsModule(transport) {
+    const gql = async (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+    return {
+        async byCode(code, sale, options) {
+            const data = await gql(POS_GIFT_CARD_BY_CODE_QUERY, { code, orderId: sale?.orderId ?? null }, options);
+            return data.posGiftCardByCode;
+        },
+        async sale(orderId, options) {
+            const data = await gql(POS_GIFT_CARD_SALE_QUERY, { orderId }, options);
+            return data.posGiftCardSale;
+        },
+        async tender(input, options) {
+            const idempotencyKey = requireKey('tender', options);
+            const data = await gql(POS_TENDER_GIFT_CARD_MUTATION, { input: { ...input, idempotencyKey }, staffToken: options.staffToken }, options);
+            return data.posTenderGiftCard;
+        },
+        async setHandover(orderId, options) {
+            const data = await gql(POS_SET_GIFT_CARD_HANDOVER_MUTATION, { orderId, staffToken: options?.staffToken }, options);
+            return data.posSetGiftCardHandover;
+        },
+        async completeSale(orderId, options) {
+            const idempotencyKey = requireKey('completeSale', options);
+            const data = await gql(POS_COMPLETE_SALE_WITH_GIFT_CARDS_MUTATION, { input: { orderId, idempotencyKey }, staffToken: options.staffToken }, options);
+            return {
+                ...data.posCompleteSale,
+                giftCards: data.posCompleteSale.giftCards ?? [],
+                giftCardsHandedOver: data.posCompleteSale.giftCardsHandedOver === true,
+            };
+        },
+    };
+}