@sixtyninecommerce/admin 0.11.0 → 0.13.0

package/dist/pos/index.d.ts

@@ -113,6 +113,12 @@ import { type PosReturnsModule } from './returns.js';
  * till makes while offline (off by default) and its limits; `offlineSales` is the manager's queue
  * of the ones the engine could not record as rung (engine sprint 45). The till's replay is its
  * own door: no method here sends one.
+ *
+ * ## Idle lock
+ *
+ * `settings.idleLock` / `setIdleLock` are after how many minutes without a cashier's touch,
+ * keystroke or scan the store's tills sign their cashier out (1 to 60; the tills' default of 5
+ * until the store chooses).
  */
 export interface PosModule {
     registers: PosRegistersModule;
@@ -388,12 +394,23 @@ export interface PosSessionApproval {
  * is no variance yet: count it with `sessions.count` (never approved as it is).
  */
 export type PosVarianceApproval = 'not_required' | 'approved' | 'pending' | 'uncounted';
+/** The X report's totals: the drawer so far, with the gift cards its sales issued (engine C6). */
+export interface PosXReportTotals extends PosSessionTotals {
+    /**
+     * Of which gift cards sold (engine C6): the face value of the cards the session's completed sales
+     * issued, a memo already inside the tenders (a liability, not sales; never subtract it from
+     * `net`). Absent when an engine before C6 answered: leave it out, never show it as 0.
+     */
+    giftCardsSold?: number;
+    /** How many gift cards those sales issued; absent like {@link giftCardsSold}. */
+    giftCardsSoldCount?: number;
+}
 /** A mid-shift snapshot. Reading it changes nothing. */
 export interface PosXReport {
     sessionId: string;
     openingFloat: number;
     expectedCash: number;
-    totals: PosSessionTotals;
+    totals: PosXReportTotals;
     movementCount: number;
 }
 export interface OpenPosSessionInput {
@@ -428,7 +445,14 @@ export interface PosSessionsModule {
         countedCash: number;
         closingCounts?: Record<string, number>;
     }, options?: PosCall): Promise<PosRegisterSession>;
-    /** The X report: the drawer so far, read-only. */
+    /**
+     * The X report: the drawer so far, read-only, with the gift cards its sales issued
+     * (`totals.giftCardsSold`, engine C6). On a closed session the figures are its stored Z's. An
+     * engine before C6 refuses the memo at validation; the report is then read without it (the two
+     * memo fields absent). An id that is no session of the store is `POS_SESSION_NOT_FOUND`.
+     *
+     * @effect read
+     */
     xReport(sessionId: string, options?: Call): Promise<PosXReport>;
     /**
      * One session with its close's details (engine sprint 25b): who closed it, whether the store
@@ -1726,6 +1750,14 @@ export interface PosPairingCode {
     code: string;
     expiresAt: string;
 }
+/**
+ * How long a pairing code works before a tablet claims it (`devices.pair`, engine
+ * `emre/pos-reviewer-pairing`): `STANDARD` 10 minutes, `APP_REVIEW` 30 days for a store reviewer's
+ * device. Either way the code is claimed once.
+ */
+export type PosPairingCodeValidity = 'STANDARD' | 'APP_REVIEW';
+/** The validities a pairing code is issued with, in the engine's order. */
+export declare const POS_PAIRING_CODE_VALIDITIES: readonly PosPairingCodeValidity[];
 /** A new device (`devices.create`). */
 export interface PosDeviceCreateInput {
     label: string;
@@ -1852,6 +1884,14 @@ export interface PosDevicesModule {
      * 400 the transport reports as `BAD_REQUEST`); without it the document is the one every engine
      * serves.
      *
+     * From engine `pos-device-move-refuses-open-drawer`, a move that changes the device's location
+     * or register is refused `POS_DEVICE_SESSION_OPEN` (`BusinessRuleError`, the engine's sentence
+     * naming the drawer's register) while the device has an open drawer: the drawer stays on the
+     * register it opened on, so close it first (at the till, or `sessions.close` /
+     * `sessions.closeUncounted` in the back office; {@link PosSessionsModule.openForDevice} reads
+     * it). A move to where the device already stands, with its own register, still answers the
+     * device. An older engine moves the device and leaves the drawer behind.
+     *
      * @effect write
      */
     assignLocation(deviceId: string, stockLocationId: string, options?: {
@@ -1868,7 +1908,10 @@ export interface PosDevicesModule {
      * `pos-device-writes-validate` the device is judged first, as
      * {@link PosDevicesModule.assignLocation} judges it (`POS_DEVICE_NOT_FOUND`,
      * `LOCATION_NOT_ALLOWED` for a device at a location outside a restricted credential's,
-     * `POS_DEVICE_REVOKED`).
+     * `POS_DEVICE_REVOKED`). From engine `pos-device-move-refuses-open-drawer`, another register
+     * is refused `POS_DEVICE_SESSION_OPEN` (`BusinessRuleError`) while the device has an open
+     * drawer, as {@link PosDevicesModule.assignLocation} says; the register it holds still answers
+     * the device.
      *
      * @effect write
      */
@@ -1952,9 +1995,23 @@ export interface PosDevicesModule {
      * a restricted credential's, and `POS_DEVICE_CEILING_NOT_ALLOWED` to a caller that does not
      * hold every permission the till will carry.
      *
+     * `validity` sets how long the code works unclaimed: `STANDARD` (10 minutes, what a call without
+     * it gets) or `APP_REVIEW` (30 days), for a store reviewer who installs the app days after it
+     * was submitted. Either way the code is claimed once, by one tablet, and a new code of either
+     * validity replaces the device's unclaimed one. Only a platform SuperAdmin may ask for
+     * `APP_REVIEW` (the demo store's tool): anyone else is refused
+     * `POS_PAIRING_REVIEW_CODE_NOT_ALLOWED` (`PermissionDeniedError`) before the device is read. Without `validity` the call works against any
+     * engine; with one it needs an engine with `emre/pos-reviewer-pairing`. An older engine refuses
+     * the document (it does not know the argument), and the SDK raises a 400 `ValidationError`
+     * (`BAD_REQUEST`). A value outside
+     * `POS_PAIRING_CODE_VALIDITIES` is refused before anything is sent (`ValidationError`, code
+     * `POS_PAIRING_CODE_VALIDITY_INVALID`). Show `expiresAt` in the store's time zone.
+     *
      * @effect write
      */
-    pair(deviceId: string, options?: Call): Promise<PosPairingCode>;
+    pair(deviceId: string, options?: {
+        validity?: PosPairingCodeValidity;
+    } & Call): Promise<PosPairingCode>;
     /**
      * Retire the device for good: its token stops working at once, its tablet's sessions end, and
      * it can never be paired again (add a new device to use that tablet). There is no undo.
@@ -1985,7 +2042,21 @@ export interface PosReceiptNumbering {
 }
 /** Needs `ManagePosDevices` (or `UpdateSettings`). */
 export interface PosReceiptNumberingModule {
+    /**
+     * The format the store's receipts are numbered in: its organization's while it inherits
+     * `settings.numbering_formats`, else its own.
+     *
+     * @effect read
+     */
     get(options?: Call): Promise<PosReceiptNumbering>;
+    /**
+     * Change the store's own receipt number format; an omitted field keeps its value, `digits` is
+     * held to 3..8. Answers the store's own row, not the inherited format `get` reads: read again
+     * after saving. A store that inherits the format is refused `ORGANIZATION_SETTINGS_INHERITED`
+     * until it overrides the group, and one whose organization locks it `MANAGED_BY_ORGANIZATION`.
+     *
+     * @effect write
+     */
     set(input: Partial<PosReceiptNumbering>, options?: Call): Promise<PosReceiptNumbering>;
 }
 /** A store's POS settings as the setup surfaces read them. The Mollie key itself is never returned. */
@@ -1997,6 +2068,11 @@ export interface PosSettings {
     /** The till's card (terminal) payment method; null = the engine's default `pos-mollie-terminal`. */
     cardPaymentMethodCode: string | null;
     inStoreShippingMethodId: string | null;
+    /**
+     * The fulfillment profile a till sale prefers when it sits at the till's location; null = the
+     * location's own POS profile (`pos-<locationId>`), else its first enabled one.
+     */
+    fulfillmentProfileId: string | null;
     /** Pre-fills a new device's location; the engine never reads it otherwise. */
     defaultStockLocationId: string | null;
     /** `none`, `nearest_05` or `nearest_10`; a till treats any other stored value as `none`. */
@@ -2011,6 +2087,29 @@ export interface PosSettings {
      */
     maskedMollieApiKey: string | null;
 }
+/**
+ * What `settings.update` changes: an omitted field keeps its value, `null` clears a reference
+ * (the till then charges through the engine's default method, `pos-cash` / `pos-mollie-terminal`).
+ * Every reference names one of the store's own records. The Mollie key and the cash rounding have
+ * methods of their own (`setMollieApiKey`, `setCashRoundingMode`), and so do the receipt
+ * (`setReceipt`) and the idle lock (`setIdleLock`).
+ */
+export interface PosSettingsInput {
+    /** Whether the store's tills may open sessions and take payments. */
+    enabled?: boolean;
+    /** A payment method CODE of the store, the one cash sales are recorded on. */
+    cashPaymentMethodCode?: string | null;
+    /** A payment method CODE of the store, the one card (terminal) sales are recorded on. */
+    cardPaymentMethodCode?: string | null;
+    /** A live shipping method of the store: the zero-cost "collect in store" method till sales carry. */
+    inStoreShippingMethodId?: string | null;
+    /** A fulfillment profile of the store a till sale prefers. */
+    fulfillmentProfileId?: string | null;
+    /** A stock location of the store that a new device is pre-filled with. */
+    defaultStockLocationId?: string | null;
+}
+/** The fields `settings.update` sends; anything else is refused before a request is made. */
+export declare const POS_SETTINGS_INPUT_FIELDS: readonly ["enabled", "cashPaymentMethodCode", "cardPaymentMethodCode", "inStoreShippingMethodId", "fulfillmentProfileId", "defaultStockLocationId"];
 /** A Mollie terminal the store's till key reaches, as Mollie reports it now. */
 export interface PosMollieTerminal {
     /** `term_…`: what a device is assigned. */
@@ -2024,6 +2123,22 @@ export interface PosMollieTerminal {
     serialNumber: string | null;
     currency: string | null;
 }
+/**
+ * A Mollie terminal pairing code for the store's till key (engine `pos-mollie-terminal-pairing`):
+ * a Mollie Tap terminal (the Tap app on a phone, or a Mollie Tap device) scans `qrCodeSvg` or has
+ * `code` typed in to join the key's Mollie profile. Usable more than once until it expires or is
+ * revoked: `code` is a secret, never store or log it.
+ */
+export interface PosMollieTerminalPairingCode {
+    /** Mollie's id for the code (`termpc_…`): what {@link PosTerminalsModule.revokePairingCode} takes. */
+    pairingCodeId: string;
+    /** The code a person types on the terminal. */
+    code: string;
+    /** Mollie's QR for the code, a `data:image/svg+xml;base64,` URI to show as an image; null when Mollie sent none. */
+    qrCodeSvg: string | null;
+    /** ISO 8601: when Mollie stops accepting it; null when Mollie did not say. */
+    expiresAt: string | null;
+}
 /** One thing the store's tills need before they take cash and card payments. */
 export interface PosSetupCheck {
     /** `pos_enabled`, `cash_method`, `card_method`, `mollie_key`, `card_device`, `in_store_shipping`, `default_location`, `staff`, `fulfillment_profile`; more may come. */
@@ -2079,8 +2194,35 @@ export interface PosCustomItemPolicyInput {
 }
 /** Needs `UpdateSettings` to write; `get` needs any session of the store. */
 export interface PosSettingsModule {
-    /** The store's POS settings, or null when POS was never set up. */
+    /**
+     * The store's POS settings, or null when POS was never set up.
+     *
+     * @effect read
+     */
     get(options?: Call): Promise<PosSettings | null>;
+    /**
+     * Change what the store's tills sell through: POS on or off, the cash and card payment methods,
+     * the in-store shipping method, the fulfillment profile and the default stock location
+     * ({@link PosSettingsInput}); an omitted field keeps its value. Needs `UpdateSettings` alone: it
+     * names the methods the till charges through, so `ManagePosDevices` (the till estate) is not
+     * enough. A store with no POS settings yet gets them, POS off unless `enabled` says otherwise.
+     *
+     * Refusals: `POS_CONFIG_REFERENCE_INVALID` (400) when a reference the call CHANGES is not one of
+     * the store's own records: a payment method code the store does not have, a shipping method,
+     * fulfillment profile or stock location of another store or of none; `details[]` names each
+     * such field as `/<field>`, and nothing is written. Another store's record and a missing one are
+     * refused alike. A value sent back unchanged always passes, even one stored before the check
+     * that no longer resolves. `LOCATION_NOT_ALLOWED` when a location-restricted credential names a
+     * default location outside its own. `ORGANIZATION_WORKSPACE_NOT_A_STORE` when switching POS on in
+     * an organization's workspace (switching it off is never refused). A field this method does not
+     * know (the Mollie key, the cash rounding) is refused with a `TypeError` before anything is sent.
+     *
+     * Whether a method is enabled, or works with the till's cash or terminal handler, is not judged
+     * here: `readiness()` reports it.
+     *
+     * @effect write
+     */
+    update(input: PosSettingsInput, options?: Call): Promise<PosSettings>;
     /**
      * Store the till's Mollie API key (encrypted at rest; never readable again). The key is trimmed;
      * an empty one is refused here (`TypeError`) — remove it with `removeMollieApiKey`. Sending the
@@ -2218,7 +2360,35 @@ export interface PosSettingsModule {
      * `UpdateSettings`. An engine before 45 refuses the document at validation.
      */
     setOfflineCashSales(input: PosOfflineCashSalesInput, options?: Call): Promise<PosOfflineCashSales>;
-}
+    /**
+     * The store's idle lock at its tills: after how many minutes without a cashier's touch,
+     * keystroke or scan a till signs its cashier out. `minutes` is the store's choice, 1 to 60, or
+     * null until it chooses (its tills then lock after `POS_IDLE_LOCK_LIMITS.defaultMinutes`, 5).
+     * Null when POS was never set up. Any staff session of the store reads it. Its own document: an
+     * engine without the setting refuses it at validation, and every other settings read keeps
+     * working.
+     */
+    idleLock(options?: Call): Promise<PosIdleLock | null>;
+    /**
+     * Set the store's idle lock: a whole number of minutes, which the engine holds to
+     * `POS_IDLE_LOCK_LIMITS` (never refused: 0 is stored as 1, 90 as 60), or `null` back to the
+     * tills' default. A value that is not a whole number is refused here (`TypeError`), before
+     * anything is sent. It applies at each till's next sign-in. Needs `UpdateSettings`. An engine
+     * without the setting refuses the document at validation.
+     */
+    setIdleLock(minutes: number | null, options?: Call): Promise<PosIdleLock>;
+}
+/** A store's idle lock at its tills. */
+export interface PosIdleLock {
+    /** The store's choice, 1 to 60 minutes; null for the tills' default. */
+    minutes: number | null;
+}
+/** The bounds the engine holds a store's idle lock to, and the tills' default. */
+export declare const POS_IDLE_LOCK_LIMITS: {
+    readonly minMinutes: 1;
+    readonly maxMinutes: 60;
+    readonly defaultMinutes: 5;
+};
 /** How tax shows on a receipt (engine sprint 22). */
 export type PosReceiptTaxDisplay = 'INCLUSIVE' | 'EXCLUSIVE';
 /** The store's details as the platform holds them (what a receipt's header may print). */
@@ -2415,6 +2585,33 @@ export interface PosTerminalsModule {
      * operator must configure it; a non-retryable 500, Mollie not asked). Branch on the code.
      */
     list(options?: Call): Promise<Page<PosMollieTerminal>>;
+    /**
+     * A new Mollie pairing code, with Mollie's QR, for the profile of the store's till key (engine
+     * `pos-mollie-terminal-pairing`): show it, and a Mollie Tap terminal that scans it (or has the
+     * code typed in) joins the profile and appears in {@link list}, pending at first. PAX terminals
+     * take no code: Mollie ships them set up. Every call makes a new code; revoke it with
+     * {@link revokePairingCode} once the terminal shows up. Refusals, each carrying `.code`:
+     * POS_MOLLIE_PAIRING_TEST_MODE (a `test_` key: Mollie pairs nothing in test mode, its test
+     * terminal is in {@link list} already), POS_MOLLIE_PAIRING_NOT_ELIGIBLE (Mollie does not let the
+     * account pair terminals yet: finish onboarding at Mollie), and the key refusals of
+     * {@link list}. A person's session only: an API token is refused `TOKEN_CREDENTIAL_NOT_ALLOWED`
+     * and an app installation `APP_CREDENTIAL_NOT_ALLOWED` (each a `PermissionDeniedError`), since the
+     * code joins a card reader to the store's Mollie account. An engine before it fails the
+     * document's validation (`GRAPHQL_VALIDATION_FAILED`, or a 400 the transport reports as
+     * `BAD_REQUEST`).
+     *
+     * @effect write
+     */
+    createPairingCode(options?: Call): Promise<PosMollieTerminalPairingCode>;
+    /**
+     * Revoke a pairing code of the store's till key: no terminal pairs with it again, and terminals it
+     * already paired keep working. A code Mollie no longer knows answers `true`. Refused
+     * POS_MOLLIE_PAIRING_CODE_ID_INVALID (`ValidationError`: not a `termpc_` id) and the key
+     * refusals of {@link list}.
+     *
+     * @effect write
+     */
+    revokePairingCode(pairingCodeId: string, options?: Call): Promise<boolean>;
 }
 /**
  * The languages a staff member's own till language may be (`en`, `nl`, `de`, `fr`); the engine's
@@ -2463,8 +2660,14 @@ export interface PosStaffUpdateInput {
  * manager may do all of them, whatever is stored. Closing a drawer above the store's variance
  * threshold is not one: it stays a manager's.
  */
-export declare const POS_STAFF_GRANTS: readonly ["manual_price", "discount", "custom_item_over_limit", "refund", "discard_held_sale", "paid_out", "no_sale", "safe_drop", "float_adjust", "return_items", "void_sale", "no_receipt_return", "online_return"];
+export declare const POS_STAFF_GRANTS: readonly ["manual_price", "discount", "custom_item_over_limit", "refund", "discard_held_sale", "paid_out", "no_sale", "safe_drop", "float_adjust", "return_items", "void_sale", "no_receipt_return", "online_return", "manage_card_terminal", "discount_over_limit", "view_reports"];
 export type PosStaffGrant = (typeof POS_STAFF_GRANTS)[number];
+/**
+ * The grants a staff member holds only when stored on their record, whatever their role: a manager
+ * does not hold these by being one. `discount_over_limit` lets a till discount they authorise
+ * (their own, or one they approve as a manager) go past the store's discount limit.
+ */
+export declare const POS_EXPLICIT_STAFF_GRANTS: readonly ["discount_over_limit"];
 /** What one staff member may do at a till without a manager, as the store stored it. */
 export interface PosStaffGrants {
     id: string;
@@ -2555,6 +2758,14 @@ export interface PosStaffModule {
      * @effect write
      */
     setGrants(id: string, grants: readonly PosStaffGrant[], options?: Call): Promise<PosStaffGrants>;
+    /**
+     * The grants the engine this client talks to knows (its `PosStaffGrant` enum), so a caller
+     * deployed ahead of the engine offers only those: `setGrants` naming one the engine lacks fails
+     * GraphQL validation for the whole document. Empty for an engine with no grants at all.
+     *
+     * @effect read
+     */
+    knownGrants(options?: Call): Promise<string[]>;
 }
 export declare const POS_REGISTERS_QUERY = "query PosRegisters { posRegisters { id stockLocationId name status createdAt updatedAt } }";
 export declare const POS_REGISTER_QUERY = "query PosRegister($id: ID!) { posRegister(id: $id) { id stockLocationId name status createdAt updatedAt } }";
@@ -2562,7 +2773,9 @@ export declare const CREATE_POS_REGISTER_MUTATION = "mutation CreatePosRegister(
 export declare const UPDATE_POS_REGISTER_MUTATION = "mutation UpdatePosRegister($id: ID!, $input: UpdatePosRegisterInput!) { updatePosRegister(id: $id, input: $input) { id stockLocationId name status createdAt updatedAt } }";
 export declare const OPEN_POS_SESSION_MUTATION = "mutation OpenPosRegisterSession($input: OpenPosRegisterSessionInput!, $staffToken: String) { openPosRegisterSession(input: $input, staffToken: $staffToken) { id registerId deviceId openedByStaffId openingFloat status expectedCash countedCash cashOverShort totals openedAt closedAt } }";
 export declare const CLOSE_POS_SESSION_MUTATION = "mutation ClosePosRegisterSession($input: ClosePosRegisterSessionInput!, $staffToken: String) { closePosRegisterSession(input: $input, staffToken: $staffToken) { id registerId deviceId openedByStaffId openingFloat status expectedCash countedCash cashOverShort totals openedAt closedAt } }";
-export declare const POS_X_REPORT_QUERY = "query PosXReport($sessionId: ID!) { posXReport(sessionId: $sessionId) { sessionId openingFloat expectedCash movementCount totals { cash card other refunds net saleCount } } }";
+export declare const POS_X_REPORT_QUERY = "query PosXReport($sessionId: ID!) { posXReport(sessionId: $sessionId) { sessionId openingFloat expectedCash movementCount totals { cash card other refunds net saleCount giftCardsSold giftCardsSoldCount } } }";
+/** {@link POS_X_REPORT_QUERY} for an engine before C6 (no gift-card memo), which refuses it. */
+export declare const POS_X_REPORT_QUERY_BEFORE_GIFT_CARDS = "query PosXReport($sessionId: ID!) { posXReport(sessionId: $sessionId) { sessionId openingFloat expectedCash movementCount totals { cash card other refunds net saleCount } } }";
 export declare const POS_SESSION_QUERY = "query PosRegisterSession($id: ID!) { posRegisterSession(id: $id) { id registerId deviceId openedByStaffId openingFloat status expectedCash countedCash cashOverShort totals openedAt closedAt } }";
 export declare const POS_SESSION_DETAIL_QUERY = "query PosRegisterSessionDetail($id: ID!) { posRegisterSession(id: $id) { id registerId deviceId openedByStaffId openingFloat status expectedCash countedCash cashOverShort totals openedAt closedAt closedByStaffId blindCount varianceThreshold varianceApproval varianceApprovedByStaffId varianceApprovedAt } }";
 export declare const POS_SESSION_APPROVAL_QUERY = "query PosRegisterSessionApproval($id: ID!) { posRegisterSession(id: $id) { id varianceApproval varianceThreshold varianceApprovedByStaffId varianceApprovedAt varianceApprovedByUserId varianceApprovedByUserName varianceApprovedByCredential varianceApprovalNote } }";
@@ -2612,6 +2825,7 @@ export declare const POS_REFUND_MUTATION = "mutation PosRefund($input: PosRefund
 export declare const POS_DEVICES_QUERY = "query PosDevices { posDevices { id stockLocationId registerId label status paired lastSeenAt mollieTerminalId createdAt updatedAt } }";
 export declare const POS_DEVICE_QUERY = "query PosDevice($id: ID!) { posDevice(id: $id) { lastSeenAt } }";
 export declare const POS_PAIRING_CODE_MUTATION = "mutation GeneratePosPairingCode($deviceId: ID!) { generatePosPairingCode(deviceId: $deviceId) { code expiresAt } }";
+export declare const POS_PAIRING_CODE_WITH_VALIDITY_MUTATION = "mutation GeneratePosPairingCodeWithValidity($deviceId: ID!, $validity: PosPairingCodeValidity!) { generatePosPairingCode(deviceId: $deviceId, validity: $validity) { code expiresAt } }";
 export declare const REVOKE_POS_DEVICE_MUTATION = "mutation RevokePosDevice($deviceId: ID!) { revokePosDevice(deviceId: $deviceId) { id stockLocationId registerId label status paired lastSeenAt mollieTerminalId createdAt updatedAt } }";
 export declare const POS_DEVICE_DETAIL_QUERY = "query PosDeviceDetail($id: ID!) { posDevice(id: $id) { id stockLocationId registerId label status paired lastSeenAt mollieTerminalId createdAt updatedAt } }";
 export declare const ASSIGN_POS_DEVICE_LOCATION_MUTATION = "mutation AssignPosDeviceLocation($deviceId: ID!, $stockLocationId: ID!) { assignPosDeviceLocation(deviceId: $deviceId, stockLocationId: $stockLocationId) { id stockLocationId registerId label status paired lastSeenAt mollieTerminalId createdAt updatedAt } }";
@@ -2627,11 +2841,15 @@ export declare const LOCK_POS_DEVICE_MUTATION = "mutation LockPosDevice($deviceI
 export declare const UNLOCK_POS_DEVICE_MUTATION = "mutation UnlockPosDevice($deviceId: ID!) { unlockPosDevice(deviceId: $deviceId) { id stockLocationId registerId label status paired lastSeenAt mollieTerminalId createdAt updatedAt heartbeatAt lockedAt silentSince kind } }";
 export declare const POS_RECEIPT_NUMBERING_QUERY = "query PosReceiptNumberingConfig { posReceiptNumberingConfig { prefix suffix digits } }";
 export declare const UPDATE_POS_RECEIPT_NUMBERING_MUTATION = "mutation UpdatePosReceiptNumberingConfig($input: UpdatePosReceiptNumberingConfigInput!) { updatePosReceiptNumberingConfig(input: $input) { prefix suffix digits } }";
-export declare const POS_SETTINGS_QUERY = "query PosSettings { getPosConfig { enabled cashPaymentMethodCode cardPaymentMethodCode inStoreShippingMethodId defaultStockLocationId cashRoundingMode hasMollieKey maskedMollieApiKey } }";
-export declare const UPDATE_POS_SETTINGS_MUTATION = "mutation UpdatePosSettings($input: UpdatePosConfigInput!) { updatePosConfig(input: $input) { enabled cashPaymentMethodCode cardPaymentMethodCode inStoreShippingMethodId defaultStockLocationId cashRoundingMode hasMollieKey maskedMollieApiKey } }";
+export declare const POS_SETTINGS_QUERY = "query PosSettings { getPosConfig { enabled cashPaymentMethodCode cardPaymentMethodCode inStoreShippingMethodId fulfillmentProfileId defaultStockLocationId cashRoundingMode hasMollieKey maskedMollieApiKey } }";
+export declare const UPDATE_POS_SETTINGS_MUTATION = "mutation UpdatePosSettings($input: UpdatePosConfigInput!) { updatePosConfig(input: $input) { enabled cashPaymentMethodCode cardPaymentMethodCode inStoreShippingMethodId fulfillmentProfileId defaultStockLocationId cashRoundingMode hasMollieKey maskedMollieApiKey } }";
 export declare const POS_MOLLIE_TERMINALS_QUERY = "query PosMollieTerminals { posMollieTerminals { terminalId description status brand model serialNumber currency } }";
+export declare const CREATE_POS_MOLLIE_PAIRING_CODE_MUTATION = "mutation CreatePosMollieTerminalPairingCode { createPosMollieTerminalPairingCode { pairingCodeId code qrCodeSvg expiresAt } }";
+export declare const REVOKE_POS_MOLLIE_PAIRING_CODE_MUTATION = "mutation RevokePosMollieTerminalPairingCode($pairingCodeId: String!) { revokePosMollieTerminalPairingCode(pairingCodeId: $pairingCodeId) }";
 export declare const POS_CASH_CONTROLS_QUERY = "query PosCashControls { getPosConfig { cashControls { blindCount varianceThreshold } } }";
 export declare const SET_POS_CASH_CONTROLS_MUTATION = "mutation SetPosCashControls($input: PosCashControlsInput!) { setPosCashControls(input: $input) { blindCount varianceThreshold } }";
+export declare const POS_IDLE_LOCK_QUERY = "query PosIdleLock { getPosConfig { idleLockMinutes } }";
+export declare const SET_POS_IDLE_LOCK_MUTATION = "mutation SetPosIdleLock($input: UpdatePosConfigInput!) { updatePosConfig(input: $input) { idleLockMinutes } }";
 export declare const POS_RECEIPT_SETTINGS_QUERY = "query PosReceiptSettings { getPosConfig { receipt { configured showStoreName showAddress showPhone showVatNumber headerLines footerLines taxDisplay identity { storeName addressLines phone vatNumber registrationNumber } } } }";
 export declare const SET_POS_RECEIPT_SETTINGS_MUTATION = "mutation SetPosReceiptSettings($input: PosReceiptSettingsInput!) { setPosReceiptSettings(input: $input) { configured showStoreName showAddress showPhone showVatNumber headerLines footerLines taxDisplay identity { storeName addressLines phone vatNumber registrationNumber } } }";
 export declare const POS_RECEIPT_PREVIEW_QUERY = "query PosReceiptPreview($input: PosReceiptSettingsInput) { posReceiptPreview(input: $input) { kind orderId orderCode receiptNumber issuedAt language locale timeZone currencyCode taxDisplay header { storeName addressLines phone vatNumber registrationNumber extraLines } cashierName registerName lines { orderLineId name sku quantity unitPrice amount taxRate discounts { kind description amount } note ships } subtotal adjustments { kind description amount } taxes { description rate base amount } total tenders { kind exchange methodName amount tendered cashRounding change } changeDue refunds { kind exchange methodName amount refundedAt } orderNote delivery { name addressLines methodName } footerLines thankYou scanCode } }";
@@ -2657,4 +2875,5 @@ export declare const SET_POS_STAFF_PIN_MUTATION = "mutation SetPosStaffPin($id:
 export declare const POS_STAFF_GRANTS_QUERY = "query PosStaffGrants($id: ID!) { posStaff(id: $id) { id role grants } }";
 export declare const POS_STAFF_GRANTS_LIST_QUERY = "query PosStaffGrantsList { posStaffList { id role grants } }";
 export declare const SET_POS_STAFF_GRANTS_MUTATION = "mutation SetPosStaffGrants($id: ID!, $grants: [PosStaffGrant!]!) { setPosStaffGrants(id: $id, grants: $grants) { id role grants } }";
+export declare const POS_STAFF_GRANT_VALUES_QUERY = "query PosStaffGrantValues { __type(name: \"PosStaffGrant\") { enumValues { name } } }";
 export declare function createPosModule(transport: Transport): PosModule;

package/dist/pos/index.js

@@ -12,6 +12,22 @@ import { createPosReportsModule } from './reports.js';
 import { createPosReturnsModule } from './returns.js';
 /** The kinds a device is created as (engine sprint 39), in the engine's order. */
 export const POS_DEVICE_KINDS = ['till', 'display'];
+/** The validities a pairing code is issued with, in the engine's order. */
+export const POS_PAIRING_CODE_VALIDITIES = [
+    'STANDARD',
+    'APP_REVIEW',
+];
+/** The fields `settings.update` sends; anything else is refused before a request is made. */
+export const POS_SETTINGS_INPUT_FIELDS = [
+    'enabled',
+    'cashPaymentMethodCode',
+    'cardPaymentMethodCode',
+    'inStoreShippingMethodId',
+    'fulfillmentProfileId',
+    'defaultStockLocationId',
+];
+/** The bounds the engine holds a store's idle lock to, and the tills' default. */
+export const POS_IDLE_LOCK_LIMITS = { minMinutes: 1, maxMinutes: 60, defaultMinutes: 5 };
 /**
  * The languages a staff member's own till language may be (`en`, `nl`, `de`, `fr`); the engine's
  * list, which a value outside it is refused against. The till speaks a language only once its
@@ -40,6 +56,23 @@ export const POS_STAFF_GRANTS = [
     'no_receipt_return',
     // Engine C3/34: a webshop order returned at the till, refunded to its online payment.
     'online_return',
+    // Engine pos-mollie-terminal-pairing: the till's own card terminal (assign, clear, pair a new
+    // Mollie Tap terminal from the till).
+    'manage_card_terminal',
+    // Engine pos-cart-integrity: a till discount past the store limit. EXPLICIT: a manager holds it
+    // only when stored, like a cashier (see POS_EXPLICIT_STAFF_GRANTS).
+    'discount_over_limit',
+    // Engine POS programme PR 15: the money figures of the till day report (its Reports tab);
+    // without it a cashier sees the counts of the day only. A manager holds it by role.
+    'view_reports',
+];
+/**
+ * The grants a staff member holds only when stored on their record, whatever their role: a manager
+ * does not hold these by being one. `discount_over_limit` lets a till discount they authorise
+ * (their own, or one they approve as a manager) go past the store's discount limit.
+ */
+export const POS_EXPLICIT_STAFF_GRANTS = [
+    'discount_over_limit',
 ];
 const REGISTER_FIELDS = 'id stockLocationId name status createdAt updatedAt';
 // The X report selects only fields every engine answers; per-tender refunds come with the stored Z.
@@ -61,7 +94,9 @@ export const CREATE_POS_REGISTER_MUTATION = `mutation CreatePosRegister($input:
 export const UPDATE_POS_REGISTER_MUTATION = `mutation UpdatePosRegister($id: ID!, $input: UpdatePosRegisterInput!) { updatePosRegister(id: $id, input: $input) { ${REGISTER_FIELDS} } }`;
 export const OPEN_POS_SESSION_MUTATION = `mutation OpenPosRegisterSession($input: OpenPosRegisterSessionInput!, $staffToken: String) { openPosRegisterSession(input: $input, staffToken: $staffToken) { ${SESSION_FIELDS} } }`;
 export const CLOSE_POS_SESSION_MUTATION = `mutation ClosePosRegisterSession($input: ClosePosRegisterSessionInput!, $staffToken: String) { closePosRegisterSession(input: $input, staffToken: $staffToken) { ${SESSION_FIELDS} } }`;
-export const POS_X_REPORT_QUERY = `query PosXReport($sessionId: ID!) { posXReport(sessionId: $sessionId) { sessionId openingFloat expectedCash movementCount totals { ${TOTALS} } } }`;
+export const POS_X_REPORT_QUERY = `query PosXReport($sessionId: ID!) { posXReport(sessionId: $sessionId) { sessionId openingFloat expectedCash movementCount totals { ${TOTALS} giftCardsSold giftCardsSoldCount } } }`;
+/** {@link POS_X_REPORT_QUERY} for an engine before C6 (no gift-card memo), which refuses it. */
+export const POS_X_REPORT_QUERY_BEFORE_GIFT_CARDS = `query PosXReport($sessionId: ID!) { posXReport(sessionId: $sessionId) { sessionId openingFloat expectedCash movementCount totals { ${TOTALS} } } }`;
 export const POS_SESSION_QUERY = `query PosRegisterSession($id: ID!) { posRegisterSession(id: $id) { ${SESSION_FIELDS} } }`;
 // Engine sprint 25b; an older engine refuses the document at validation.
 export const POS_SESSION_DETAIL_QUERY = `query PosRegisterSessionDetail($id: ID!) { posRegisterSession(id: $id) { ${SESSION_FIELDS} ${SESSION_CLOSE_FIELDS} } }`;
@@ -139,6 +174,9 @@ export const POS_REFUND_MUTATION = `mutation PosRefund($input: PosRefundInput!,
 export const POS_DEVICES_QUERY = `query PosDevices { posDevices { ${DEVICE_FIELDS} } }`;
 export const POS_DEVICE_QUERY = `query PosDevice($id: ID!) { posDevice(id: $id) { lastSeenAt } }`;
 export const POS_PAIRING_CODE_MUTATION = `mutation GeneratePosPairingCode($deviceId: ID!) { generatePosPairingCode(deviceId: $deviceId) { code expiresAt } }`;
+// Engine `emre/pos-reviewer-pairing`: a code that names its validity. Only this document names the
+// argument, so an older engine refuses it alone and `pair` without a validity keeps working there.
+export const POS_PAIRING_CODE_WITH_VALIDITY_MUTATION = `mutation GeneratePosPairingCodeWithValidity($deviceId: ID!, $validity: PosPairingCodeValidity!) { generatePosPairingCode(deviceId: $deviceId, validity: $validity) { code expiresAt } }`;
 export const REVOKE_POS_DEVICE_MUTATION = `mutation RevokePosDevice($deviceId: ID!) { revokePosDevice(deviceId: $deviceId) { ${DEVICE_FIELDS} } }`;
 // The device's own read and its three assignments: Admin API doors every deployed engine serves.
 // Like `list` and `revoke`, they select no kind or health column (`fleet` reads those).
@@ -166,13 +204,19 @@ export const LOCK_POS_DEVICE_MUTATION = `mutation LockPosDevice($deviceId: ID!)
 export const UNLOCK_POS_DEVICE_MUTATION = `mutation UnlockPosDevice($deviceId: ID!) { unlockPosDevice(deviceId: $deviceId) { ${DEVICE_FIELDS} ${DEVICE_HEALTH_FIELDS} } }`;
 export const POS_RECEIPT_NUMBERING_QUERY = `query PosReceiptNumberingConfig { posReceiptNumberingConfig { prefix suffix digits } }`;
 export const UPDATE_POS_RECEIPT_NUMBERING_MUTATION = `mutation UpdatePosReceiptNumberingConfig($input: UpdatePosReceiptNumberingConfigInput!) { updatePosReceiptNumberingConfig(input: $input) { prefix suffix digits } }`;
-const SETTINGS_FIELDS = 'enabled cashPaymentMethodCode cardPaymentMethodCode inStoreShippingMethodId defaultStockLocationId cashRoundingMode hasMollieKey maskedMollieApiKey';
+const SETTINGS_FIELDS = 'enabled cashPaymentMethodCode cardPaymentMethodCode inStoreShippingMethodId fulfillmentProfileId defaultStockLocationId cashRoundingMode hasMollieKey maskedMollieApiKey';
 export const POS_SETTINGS_QUERY = `query PosSettings { getPosConfig { ${SETTINGS_FIELDS} } }`;
 export const UPDATE_POS_SETTINGS_MUTATION = `mutation UpdatePosSettings($input: UpdatePosConfigInput!) { updatePosConfig(input: $input) { ${SETTINGS_FIELDS} } }`;
 export const POS_MOLLIE_TERMINALS_QUERY = `query PosMollieTerminals { posMollieTerminals { terminalId description status brand model serialNumber currency } }`;
+// Engine `pos-mollie-terminal-pairing`; an older engine refuses both documents at validation.
+export const CREATE_POS_MOLLIE_PAIRING_CODE_MUTATION = `mutation CreatePosMollieTerminalPairingCode { createPosMollieTerminalPairingCode { pairingCodeId code qrCodeSvg expiresAt } }`;
+export const REVOKE_POS_MOLLIE_PAIRING_CODE_MUTATION = `mutation RevokePosMollieTerminalPairingCode($pairingCodeId: String!) { revokePosMollieTerminalPairingCode(pairingCodeId: $pairingCodeId) }`;
 // Engine sprint 25b; an older engine refuses both documents at validation.
 export const POS_CASH_CONTROLS_QUERY = `query PosCashControls { getPosConfig { cashControls { blindCount varianceThreshold } } }`;
 export const SET_POS_CASH_CONTROLS_MUTATION = `mutation SetPosCashControls($input: PosCashControlsInput!) { setPosCashControls(input: $input) { blindCount varianceThreshold } }`;
+// The store's idle lock (POS polish programme PR 2); an older engine refuses both at validation.
+export const POS_IDLE_LOCK_QUERY = `query PosIdleLock { getPosConfig { idleLockMinutes } }`;
+export const SET_POS_IDLE_LOCK_MUTATION = `mutation SetPosIdleLock($input: UpdatePosConfigInput!) { updatePosConfig(input: $input) { idleLockMinutes } }`;
 // Engine sprint 22 (the receipt's tender and refund `exchange`, its lines' `ships` and its `delivery`:
 // engine C3); an older engine refuses each document at validation.
 const RECEIPT_SETTINGS_FIELDS = 'configured showStoreName showAddress showPhone showVatNumber headerLines footerLines taxDisplay identity { storeName addressLines phone vatNumber registrationNumber }';
@@ -217,6 +261,8 @@ const STAFF_GRANTS_FIELDS = 'id role grants';
 export const POS_STAFF_GRANTS_QUERY = `query PosStaffGrants($id: ID!) { posStaff(id: $id) { ${STAFF_GRANTS_FIELDS} } }`;
 export const POS_STAFF_GRANTS_LIST_QUERY = `query PosStaffGrantsList { posStaffList { ${STAFF_GRANTS_FIELDS} } }`;
 export const SET_POS_STAFF_GRANTS_MUTATION = `mutation SetPosStaffGrants($id: ID!, $grants: [PosStaffGrant!]!) { setPosStaffGrants(id: $id, grants: $grants) { ${STAFF_GRANTS_FIELDS} } }`;
+// The engine's own list of grants, read by introspection: any engine answers it (null type, none).
+export const POS_STAFF_GRANT_VALUES_QUERY = `query PosStaffGrantValues { __type(name: "PosStaffGrant") { enumValues { name } } }`;
 const DEVICE_KIND_INVALID = 'POS_DEVICE_KIND_INVALID';
 /** A kind outside {@link POS_DEVICE_KINDS}, refused before sending, as the engine refuses it. */
 function deviceKindRefusal(kind) {
@@ -229,6 +275,18 @@ function deviceKindRefusal(kind) {
         details: [{ field: 'kind', code: DEVICE_KIND_INVALID, message }],
     });
 }
+const PAIRING_CODE_VALIDITY_INVALID = 'POS_PAIRING_CODE_VALIDITY_INVALID';
+/** A validity outside {@link POS_PAIRING_CODE_VALIDITIES}, refused before sending. */
+function pairingValidityRefusal(validity) {
+    const message = `A pairing code is ${POS_PAIRING_CODE_VALIDITIES.join(' or ')}, not "${String(validity).slice(0, 40)}".`;
+    return new ValidationError({
+        code: PAIRING_CODE_VALIDITY_INVALID,
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field: 'validity', code: PAIRING_CODE_VALIDITY_INVALID, message }],
+    });
+}
 const LOCALE_UNSUPPORTED = 'POS_LOCALE_UNSUPPORTED';
 const LOCALE_UNSUPPORTED_MESSAGE = `A staff language must be one of ${POS_STAFF_LOCALES.join(', ')}, or null to follow the store.`;
 function localeRefusal(message) {
@@ -424,7 +482,17 @@ export function createPosModule(transport) {
                 return toSession(data.closePosRegisterSession);
             },
             async xReport(sessionId, options) {
-                const data = await gql(POS_X_REPORT_QUERY, { sessionId }, options);
+                try {
+                    const data = await gql(POS_X_REPORT_QUERY, { sessionId }, options);
+                    return data.posXReport;
+                }
+                catch (error) {
+                    // An engine before C6 knows no gift-card memo: the report without it. Anything else
+                    // (a missing session, a refusal, a transient failure) is the read's own.
+                    if (!isUnknownFieldRejection(error))
+                        throw error;
+                }
+                const data = await gql(POS_X_REPORT_QUERY_BEFORE_GIFT_CARDS, { sessionId }, options);
                 return data.posXReport;
             },
             async get(sessionId, options) {
@@ -748,7 +816,15 @@ export function createPosModule(transport) {
                 return data.createPosDevice;
             },
             async pair(deviceId, options) {
-                const data = await gql(POS_PAIRING_CODE_MUTATION, { deviceId }, options);
+                const validity = options?.validity;
+                if (validity === undefined || validity === null) {
+                    const data = await gql(POS_PAIRING_CODE_MUTATION, { deviceId }, options);
+                    return data.generatePosPairingCode;
+                }
+                if (!POS_PAIRING_CODE_VALIDITIES.includes(validity)) {
+                    throw pairingValidityRefusal(validity);
+                }
+                const data = await gql(POS_PAIRING_CODE_WITH_VALIDITY_MUTATION, { deviceId, validity }, options);
                 return data.generatePosPairingCode;
             },
             async revoke(deviceId, options) {
@@ -790,6 +866,16 @@ export function createPosModule(transport) {
                 const data = await gql(POS_SETTINGS_QUERY, {}, options);
                 return data.getPosConfig;
             },
+            async update(input, options) {
+                const known = POS_SETTINGS_INPUT_FIELDS;
+                // Names the field, never its value: a Mollie key sent here must not reach a log.
+                const unknown = Object.keys(input).filter((field) => !known.includes(field));
+                if (unknown.length > 0) {
+                    throw new TypeError(`settings.update does not change ${unknown.join(', ')}: use setMollieApiKey, setCashRoundingMode, setReceipt or setIdleLock.`);
+                }
+                const data = await gql(UPDATE_POS_SETTINGS_MUTATION, { input: { ...input } }, options);
+                return data.updatePosConfig;
+            },
             async setMollieApiKey(apiKey, options) {
                 const key = apiKey.trim();
                 if (key === '') {
@@ -877,12 +963,31 @@ export function createPosModule(transport) {
             async setOfflineCashSales(input, options) {
                 return writeOfflineCashSales(transport, input, options);
             },
+            async idleLock(options) {
+                const data = await gql(POS_IDLE_LOCK_QUERY, {}, options);
+                return data.getPosConfig ? { minutes: data.getPosConfig.idleLockMinutes ?? null } : null;
+            },
+            async setIdleLock(minutes, options) {
+                if (minutes !== null && !Number.isInteger(minutes)) {
+                    throw new TypeError('setIdleLock needs a whole number of minutes, or null.');
+                }
+                const data = await gql(SET_POS_IDLE_LOCK_MUTATION, { input: { idleLockMinutes: minutes } }, options);
+                return { minutes: data.updatePosConfig.idleLockMinutes ?? null };
+            },
         },
         terminals: {
             async list(options) {
                 const data = await gql(POS_MOLLIE_TERMINALS_QUERY, {}, options);
                 return wholeList(data.posMollieTerminals);
             },
+            async createPairingCode(options) {
+                const data = await gql(CREATE_POS_MOLLIE_PAIRING_CODE_MUTATION, {}, options);
+                return data.createPosMollieTerminalPairingCode;
+            },
+            async revokePairingCode(pairingCodeId, options) {
+                const data = await gql(REVOKE_POS_MOLLIE_PAIRING_CODE_MUTATION, { pairingCodeId }, options);
+                return data.revokePosMollieTerminalPairingCode;
+            },
         },
         staff: {
             async list(options) {
@@ -928,6 +1033,10 @@ export function createPosModule(transport) {
                 const data = await gql(SET_POS_STAFF_GRANTS_MUTATION, { id, grants: [...grants] }, options);
                 return data.setPosStaffGrants;
             },
+            async knownGrants(options) {
+                const data = await gql(POS_STAFF_GRANT_VALUES_QUERY, {}, options);
+                return (data.__type?.enumValues ?? []).map((value) => value.name);
+            },
         },
         quickKeys: createPosQuickKeysModule(transport),
         returns: createPosReturnsModule(transport),