@sixtyninecommerce/admin 0.10.0 → 0.12.0

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

package/dist/pos/quick-keys.d.ts

@@ -0,0 +1,103 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * A store's quick keys (POS sprint 13): the till's favourite-product buttons, on named, coloured
+ * pages, one layout per store, shown on every till of the store. The limits and the palette are
+ * the engine's (`vendure-plugin-pos` `services/quick-key-layout.ts`), pinned by
+ * `pos-quick-keys.spec.ts`.
+ */
+/** The quick key palette; anything else is refused `POS_QUICK_KEYS_INVALID`. */
+export declare const POS_QUICK_KEY_COLORS: readonly ["slate", "red", "orange", "amber", "green", "teal", "sky", "blue", "violet", "pink"];
+export type PosQuickKeyColor = (typeof POS_QUICK_KEY_COLORS)[number];
+/** At most 10 pages of at most 40 keys; a page name of 1-20 and a label of up to 30 characters. */
+export declare const POS_QUICK_KEY_LIMITS: {
+    readonly pages: 10;
+    readonly keysPerPage: 40;
+    readonly pageNameLength: 20;
+    readonly labelLength: 30;
+};
+/** Whether the till shows a key; only `available` keys are on the till. More may come. */
+export type PosQuickKeyState = 'available' | 'product_disabled' | 'product_gone' | 'variant_disabled' | 'variant_gone' | 'no_sellable_variant' | (string & {});
+export interface PosQuickKey {
+    /** Send it back to keep the key, also when it moves to another page. */
+    id: string;
+    productId: string;
+    /** The one variant the key adds; null for a product key (one variant adds, several open the picker). */
+    variantId: string | null;
+    /** The store's button text; null shows the product's (or the variant's) own name. */
+    label: string | null;
+    /** A palette colour, or a newer engine's; null for none. */
+    color: string | null;
+    state: PosQuickKeyState;
+    /** The catalogue's name now (the variant's for a variant key); null when it is gone. */
+    name: string | null;
+    /** The variant's SKU for a variant key; null otherwise. */
+    sku: string | null;
+    featuredAsset: {
+        id: string;
+        preview: string;
+    } | null;
+}
+export interface PosQuickKeyPage {
+    /** Send it back to keep the page. */
+    id: string;
+    name: string;
+    color: string | null;
+    keys: PosQuickKey[];
+}
+export interface PosQuickKeyLayout {
+    /** Raised by every save that changes the layout; 0 before the first. Send it as `expectedVersion`. */
+    version: number;
+    /** When a save last changed the layout (ISO-8601); null before the first. */
+    updatedAt: string | null;
+    pages: PosQuickKeyPage[];
+}
+export interface PosQuickKeyInput {
+    /** A stored key's id keeps the key; omit it for a new key. */
+    id?: string;
+    productId: string;
+    /** Pin the key to one variant of the product; omit for the product. */
+    variantId?: string | null;
+    /** Blank shows the product's (or the variant's) own name. */
+    label?: string | null;
+    /**
+     * A palette colour, or null for none. A colour this SDK does not list is sent as read (sprint
+     * 27: a back office keeps an engine colour it does not know); the engine refuses one IT does not
+     * know (`POS_QUICK_KEYS_INVALID`, `color_unknown`).
+     */
+    color?: PosQuickKeyColor | (string & {}) | null;
+}
+export interface PosQuickKeyPageInput {
+    /** A stored page's id keeps the page; omit it for a new page. */
+    id?: string;
+    name: string;
+    /**
+     * A palette colour, or null for none. A colour this SDK does not list is sent as read (sprint
+     * 27: a back office keeps an engine colour it does not know); the engine refuses one IT does not
+     * know (`POS_QUICK_KEYS_INVALID`, `color_unknown`).
+     */
+    color?: PosQuickKeyColor | (string & {}) | null;
+    keys: PosQuickKeyInput[];
+}
+export interface SetPosQuickKeyLayoutInput {
+    /** The `version` the editor read. */
+    expectedVersion: number;
+    pages: PosQuickKeyPageInput[];
+}
+/** Read needs UpdateSettings or ManagePosDevices; set needs UpdateSettings. */
+export interface PosQuickKeysModule {
+    /** The store's quick keys, every page and key in order, each key's `state` saying whether the till shows it. */
+    get(options?: Call): Promise<PosQuickKeyLayout>;
+    /**
+     * Replace them (the whole layout). Refusals: `POS_QUICK_KEYS_CONFLICT` (`ConflictError`, 409:
+     * changed since `expectedVersion`; read again), `POS_QUICK_KEYS_INVALID` (`ValidationError`, 400;
+     * `error.details[0].field` is a JSON Pointer into the input), `POS_QUICK_KEYS_PRODUCT_NOT_FOUND`
+     * (`NotFoundError`, 404), `POS_QUICK_KEYS_FORMAT_UNSUPPORTED` (`BusinessRuleError`, 422),
+     * `ORGANIZATION_WORKSPACE_NOT_A_STORE`. Sending what is stored again is never refused, whatever
+     * `expectedVersion` says.
+     */
+    set(input: SetPosQuickKeyLayoutInput, options?: Call): Promise<PosQuickKeyLayout>;
+}
+export declare const POS_QUICK_KEY_LAYOUT_QUERY = "query PosQuickKeyLayout { posQuickKeyLayout { version updatedAt pages { id name color keys { id productId variantId label color state name sku featuredAsset { id preview } } } } }";
+export declare const SET_POS_QUICK_KEY_LAYOUT_MUTATION = "mutation SetPosQuickKeyLayout($input: SetPosQuickKeyLayoutInput!) { setPosQuickKeyLayout(input: $input) { version updatedAt pages { id name color keys { id productId variantId label color state name sku featuredAsset { id preview } } } } }";
+export declare function createPosQuickKeysModule(transport: Transport): PosQuickKeysModule;

package/dist/pos/quick-keys.js

@@ -0,0 +1,45 @@
+/**
+ * A store's quick keys (POS sprint 13): the till's favourite-product buttons, on named, coloured
+ * pages, one layout per store, shown on every till of the store. The limits and the palette are
+ * the engine's (`vendure-plugin-pos` `services/quick-key-layout.ts`), pinned by
+ * `pos-quick-keys.spec.ts`.
+ */
+/** The quick key palette; anything else is refused `POS_QUICK_KEYS_INVALID`. */
+export const POS_QUICK_KEY_COLORS = [
+    'slate',
+    'red',
+    'orange',
+    'amber',
+    'green',
+    'teal',
+    'sky',
+    'blue',
+    'violet',
+    'pink',
+];
+/** At most 10 pages of at most 40 keys; a page name of 1-20 and a label of up to 30 characters. */
+export const POS_QUICK_KEY_LIMITS = {
+    pages: 10,
+    keysPerPage: 40,
+    pageNameLength: 20,
+    labelLength: 30,
+};
+const LAYOUT_FIELDS = 'version updatedAt pages { id name color keys { id productId variantId label color state name sku featuredAsset { id preview } } }';
+export const POS_QUICK_KEY_LAYOUT_QUERY = `query PosQuickKeyLayout { posQuickKeyLayout { ${LAYOUT_FIELDS} } }`;
+export const SET_POS_QUICK_KEY_LAYOUT_MUTATION = `mutation SetPosQuickKeyLayout($input: SetPosQuickKeyLayoutInput!) { setPosQuickKeyLayout(input: $input) { ${LAYOUT_FIELDS} } }`;
+export function createPosQuickKeysModule(transport) {
+    const gql = async (query, variables, options) => transport.graphql({ api: 'admin', query, variables }, options);
+    return {
+        async get(options) {
+            const data = await gql(POS_QUICK_KEY_LAYOUT_QUERY, {}, options);
+            return data.posQuickKeyLayout;
+        },
+        async set(input, options) {
+            if (!Number.isInteger(input.expectedVersion) || input.expectedVersion < 0) {
+                throw new TypeError('quickKeys.set needs expectedVersion: the whole-number version the layout was read at (0 before the first save).');
+            }
+            const data = await gql(SET_POS_QUICK_KEY_LAYOUT_MUTATION, { input }, options);
+            return data.setPosQuickKeyLayout;
+        },
+    };
+}