@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/pos/exchanges.d.ts

@@ -0,0 +1,103 @@
+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: 0. Complete it with `sale.complete`. */
+    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,
+            };
+        },
+    };
+}