@sixtyninecommerce/admin 0.9.0 → 0.10.0

package/dist/pricing/vouchers.d.ts

@@ -0,0 +1,103 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Personal vouchers (incentives sprint 9): a voucher TEMPLATE under a promotion, codes issued one
+ * by one to a customer of the store, single use, with an optional expiry and the issuing journey
+ * recorded as an opaque `source`. Applied like any coupon (`pricing.coupons.apply`, the till's
+ * `pos.sale.applyCouponCode`), which refuse `VOUCHER_NOT_FOR_CUSTOMER`, `VOUCHER_EXPIRED` and
+ * `VOUCHER_ALREADY_REDEEMED`. Issuing needs `CreatePromotion`.
+ */
+/** A customer of this store: exactly one of its id or a master system's key (PR #1176). */
+export type VoucherCustomer = {
+    id: string;
+} | {
+    externalRef: {
+        system: string;
+        ref: string;
+    };
+};
+export interface IssueVoucherInput {
+    templateId: string;
+    customer: VoucherCustomer;
+    /** Usable through the end of the store's local day this many days after today (1 to 3650). */
+    validityDays?: number;
+    /** Or an explicit instant, ISO-8601. Neither: the template's default, else the promotion's window. */
+    expiresAt?: string;
+    /** The issuing journey; with a `ref`, an issue is exactly-once per template, customer and source. */
+    source: {
+        system: string;
+        ref?: string;
+    };
+}
+export interface IssueVouchersInput {
+    templateId: string;
+    sourceSystem: string;
+    /** At most 1,000. */
+    items: Array<{
+        customer: VoucherCustomer;
+        validityDays?: number;
+        expiresAt?: string;
+        sourceRef?: string;
+    }>;
+}
+export interface IssuedVoucher {
+    id: string;
+    code: string;
+    customerId: string;
+    /** The earlier of its own expiry and its promotion's end; null when neither ends. */
+    expiresAt: string | null;
+    /** False when this template, customer and source had issued it already: the same code. */
+    created: boolean;
+}
+export interface IssueVouchersItem {
+    index: number;
+    voucher: IssuedVoucher | null;
+    /** A `VOUCHER_*` code or `ENTITY_NOT_FOUND` for a refused item; the others were issued. */
+    errorCode: string | null;
+    message: string | null;
+}
+export type VoucherStatus = 'OPEN' | 'REDEEMED' | 'EXPIRED' | 'REVOKED';
+export interface Voucher {
+    id: string;
+    code: string;
+    templateId: string;
+    promotionId: string;
+    customerId: string | null;
+    status: VoucherStatus;
+    issuedAt: string;
+    expiresAt: string | null;
+    sourceSystem: string | null;
+    sourceRef: string | null;
+    /** The order that redeemed it. */
+    orderId: string | null;
+}
+export interface VoucherTemplate {
+    id: string;
+    promotionId: string;
+    prefix: string;
+    codeLength: number;
+    defaultValidityDays: number | null;
+}
+export interface PricingVouchersModule {
+    /** A voucher template under a promotion of this store (codes of 12 to 32 random characters). */
+    createTemplate(input: {
+        promotionId: string;
+        prefix: string;
+        codeLength?: number;
+        defaultValidityDays?: number;
+    }, options?: Call): Promise<VoucherTemplate>;
+    /**
+     * Issue one voucher. `options.idempotencyKey` replays the first answer; the same template,
+     * customer and `source.ref` answers the voucher already issued (`created: false`) under any key.
+     */
+    issue(input: IssueVoucherInput, options?: Call): Promise<IssuedVoucher>;
+    /** Issue up to 1,000 vouchers of one template; a refused item answers in its place. */
+    issueMany(input: IssueVouchersInput, options?: Call): Promise<IssueVouchersItem[]>;
+    /** A customer's vouchers in this store, newest first; every status when `status` is omitted. */
+    forCustomer(customer: VoucherCustomer, status?: VoucherStatus, options?: Call): Promise<Voucher[]>;
+}
+export declare const CREATE_VOUCHER_TEMPLATE_MUTATION = "\n  mutation CreateVoucherTemplate($input: CreateVoucherTemplateInput!) {\n    createVoucherTemplate(input: $input) {\n      id\n      promotionId\n      prefix\n      codeLength\n      defaultValidityDays\n    }\n  }\n";
+export declare const ISSUE_VOUCHER_MUTATION = "\n  mutation IssueVoucher($input: IssueVoucherInput!, $idempotencyKey: String) {\n    issueVoucher(input: $input, idempotencyKey: $idempotencyKey) { id code customerId expiresAt created }\n  }\n";
+export declare const ISSUE_VOUCHERS_MUTATION = "\n  mutation IssueVouchers($input: IssueVouchersInput!, $idempotencyKey: String) {\n    issueVouchers(input: $input, idempotencyKey: $idempotencyKey) {\n      items { index errorCode message voucher { id code customerId expiresAt created } }\n    }\n  }\n";
+export declare const VOUCHERS_FOR_CUSTOMER_QUERY = "\n  query VouchersForCustomer($customer: VoucherCustomerInput!, $status: VoucherStatus) {\n    vouchersForCustomer(customer: $customer, status: $status) {\n      id\n      code\n      templateId\n      promotionId\n      customerId\n      status\n      issuedAt\n      expiresAt\n      sourceSystem\n      sourceRef\n      orderId\n    }\n  }\n";
+export declare function createPricingVouchersModule(transport: Transport): PricingVouchersModule;

package/dist/pricing/vouchers.js

@@ -0,0 +1,69 @@
+const ISSUED_VOUCHER_FIELDS = `id code customerId expiresAt created`;
+export const CREATE_VOUCHER_TEMPLATE_MUTATION = /* GraphQL */ `
+  mutation CreateVoucherTemplate($input: CreateVoucherTemplateInput!) {
+    createVoucherTemplate(input: $input) {
+      id
+      promotionId
+      prefix
+      codeLength
+      defaultValidityDays
+    }
+  }
+`;
+export const ISSUE_VOUCHER_MUTATION = /* GraphQL */ `
+  mutation IssueVoucher($input: IssueVoucherInput!, $idempotencyKey: String) {
+    issueVoucher(input: $input, idempotencyKey: $idempotencyKey) { ${ISSUED_VOUCHER_FIELDS} }
+  }
+`;
+export const ISSUE_VOUCHERS_MUTATION = /* GraphQL */ `
+  mutation IssueVouchers($input: IssueVouchersInput!, $idempotencyKey: String) {
+    issueVouchers(input: $input, idempotencyKey: $idempotencyKey) {
+      items { index errorCode message voucher { ${ISSUED_VOUCHER_FIELDS} } }
+    }
+  }
+`;
+export const VOUCHERS_FOR_CUSTOMER_QUERY = /* GraphQL */ `
+  query VouchersForCustomer($customer: VoucherCustomerInput!, $status: VoucherStatus) {
+    vouchersForCustomer(customer: $customer, status: $status) {
+      id
+      code
+      templateId
+      promotionId
+      customerId
+      status
+      issuedAt
+      expiresAt
+      sourceSystem
+      sourceRef
+      orderId
+    }
+  }
+`;
+export function createPricingVouchersModule(transport) {
+    return {
+        async createTemplate(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: CREATE_VOUCHER_TEMPLATE_MUTATION, variables: { input } }, options);
+            return data.createVoucherTemplate;
+        },
+        async issue(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ISSUE_VOUCHER_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.issueVoucher;
+        },
+        async issueMany(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ISSUE_VOUCHERS_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.issueVouchers.items;
+        },
+        async forCustomer(customer, status, options) {
+            const data = await transport.graphql({ api: 'admin', query: VOUCHERS_FOR_CUSTOMER_QUERY, variables: { customer, status } }, options);
+            return data.vouchersForCustomer;
+        },
+    };
+}

package/dist/returns/index.d.ts

@@ -0,0 +1,225 @@
+/**
+ * `admin.returns`: the single-return reads of the returns (RMA) plugin, and the
+ * plan for settling one (headless plan W9-47).
+ *
+ * A first, minimal module: the reads the order and return pages need. The list
+ * (`orderReturns`) and the writes (create, approve, reject, cancel, receipt,
+ * settle, notes, numbering) are phase 7. Money is in MINOR UNITS throughout,
+ * as everywhere in this SDK.
+ *
+ * Every value set below is the engine's own and grows over time, so each field
+ * that carries one also accepts a string this version does not name: treat an
+ * unknown value as "not available".
+ */
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** A return's state: the latest row of its status log. */
+export declare const RETURN_STATES: readonly ["requested", "approved", "rejected", "cancelled", "items_received", "settlement_pending", "settlement_failed", "settled"];
+export type ReturnState = (typeof RETURN_STATES)[number];
+/**
+ * How a return is settled. `refund` gives money back to an original payment.
+ * `store_credit` issues a credit note: on a store with an accounts-receivable
+ * ledger it credits the customer's account, elsewhere it credits the order's
+ * invoice and moves no money.
+ */
+export declare const RETURN_SETTLEMENT_METHODS: readonly ["refund", "store_credit"];
+export type ReturnSettlementMethod = (typeof RETURN_SETTLEMENT_METHODS)[number];
+export interface OrderReturnLine {
+    id: string;
+    returnId: string;
+    orderLineId: string;
+    productVariantId: string;
+    productVariantName: string;
+    productVariantSku: string;
+    requestedQty: number;
+    /** Null until approval; 0 means the line was declined. */
+    approvedQty: number | null;
+    /** Units received back, across every receipt. */
+    receivedQty: number;
+    restockQty: number;
+    writeOffQty: number;
+    restockLocationId: string | null;
+    /** `damaged`, `defective`, `wrong_item`, `not_as_described`, `arrived_late`, `no_longer_needed`, `order_error`, `other`. */
+    reasonCode: string;
+    reasonNote: string | null;
+    /** The order line's prorated unit price incl. tax, rounded per unit. Display only. */
+    unitPriceWithTax: number;
+    /**
+     * The same price before per-unit rounding; null for returns requested before
+     * it was recorded. Multiply by a quantity and round ONCE to estimate a line.
+     */
+    unitPriceWithTaxUnrounded: number | null;
+    /** What the line refunds; null until approved. */
+    refundAmount: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One row of a return's status log. */
+export interface OrderReturnStatusLogEntry {
+    state: ReturnState | (string & {});
+    /** `customer`, `admin` or `system`. */
+    actor: string;
+    actorUserId: string | null;
+    reason: string | null;
+    createdAt: string;
+}
+export interface OrderReturn {
+    id: string;
+    /** The human-facing RMA code, e.g. `RMA-000042`. */
+    code: string;
+    channelId: string;
+    orderId: string;
+    orderCode: string;
+    customerId: string;
+    currencyCode: string;
+    state: ReturnState | (string & {});
+    /** `customer` or `admin`. */
+    initiator: string;
+    customerNote: string | null;
+    adminNote: string | null;
+    preferredSettlementMethod: ReturnSettlementMethod | (string & {}) | null;
+    /** The method it was settled with; null until settled. */
+    settlementMethod: ReturnSettlementMethod | (string & {}) | null;
+    /** Shipping refunded on top of the lines. */
+    shippingRefundAmount: number;
+    /** What was settled; null until settled. */
+    settledAmount: number | null;
+    refundId: string | null;
+    creditNoteId: string | null;
+    creditNoteNumber: string | null;
+    requestedAt: string;
+    resolvedAt: string | null;
+    lines: OrderReturnLine[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** {@link OrderReturn} with its status log, newest first: what `get` answers. */
+export interface OrderReturnDetail extends OrderReturn {
+    history: OrderReturnStatusLogEntry[];
+}
+/** One order line and what of it can still be returned. */
+export interface ReturnableOrderLine {
+    orderLineId: string;
+    productVariantId: string;
+    productVariantName: string;
+    productVariantSku: string;
+    /** Units shipped or delivered. */
+    fulfilledQty: number;
+    /** `fulfilledQty` less the units other open returns already claim. */
+    returnableQty: number;
+    unitPriceWithTax: number;
+    unitPriceWithTaxUnrounded: number;
+}
+export interface ReturnEligibility {
+    orderId: string;
+    /** False only when nothing is returnable: an admin may return outside the window. */
+    eligible: boolean;
+    /** Why not, when not eligible. */
+    reason: string | null;
+    /** ISO-8601 with offset; null when the store sets no window. */
+    returnWindowEndsAt: string | null;
+    /** Lines with a fulfilled quantity only. */
+    lines: ReturnableOrderLine[];
+}
+/** Why a return cannot be settled now, in the order the engine checks them. */
+export declare const RETURN_SETTLEMENT_BLOCKERS: readonly ["OUTCOME_UNKNOWN", "ALREADY_SETTLED", "IN_PROGRESS", "RECEIPT_REQUIRED", "STATE"];
+/**
+ * - `OUTCOME_UNKNOWN`: the refund it waits on reached the provider and was never
+ *   confirmed. Record the provider's answer first (`reconcileRefundOutcome`):
+ *   made completes the return, not made lets it be settled again.
+ * - `ALREADY_SETTLED`: settled, or settled by a credit note.
+ * - `IN_PROGRESS`: a refund is on its way and settles the return when the
+ *   provider confirms it.
+ * - `RECEIPT_REQUIRED`: approved, and the store requires the goods received first.
+ * - `STATE`: requested, rejected or cancelled.
+ */
+export type ReturnSettlementBlocker = (typeof RETURN_SETTLEMENT_BLOCKERS)[number];
+/**
+ * - `NO_REFUNDABLE_PAYMENT`: no settled payment can still give money back (net
+ *   terms, everything refunded, reserved by a refund of unknown outcome, or
+ *   moved to the customer's account).
+ * - `REFUND_ORPHAN_EXISTS`: a refund of the invoiced order stands that no credit
+ *   note names; another refund could pay the same money back twice.
+ */
+export type ReturnRefundUnavailableReason = 'NO_REFUNDABLE_PAYMENT' | 'REFUND_ORPHAN_EXISTS';
+/**
+ * - `AR`: the store keeps an accounts-receivable ledger; the credit note credits
+ *   the customer's account, which is money.
+ * - `RETAIL`: the credit note credits the order's invoice and moves no money.
+ */
+export type ReturnCreditNoteLedger = 'AR' | 'RETAIL';
+/**
+ * - `ISSUER_UNAVAILABLE`: the server runs without the plugin that issues it.
+ * - `CURRENCY_MISMATCH` (`AR`): the order is not in the store's default currency.
+ * - `NO_CREDITABLE_INVOICE` (`RETAIL`): the order has no live invoice to credit.
+ * - `REFUND_ORPHAN_EXISTS` (`AR`): as for the refund.
+ */
+export type ReturnCreditNoteUnavailableReason = 'ISSUER_UNAVAILABLE' | 'CURRENCY_MISMATCH' | 'NO_CREDITABLE_INVOICE' | 'REFUND_ORPHAN_EXISTS';
+/** A settled payment a refund may name, with what it can still give back. */
+export interface ReturnSettlementPayment {
+    paymentId: string;
+    method: string;
+    /** As the platform's refund position counts it. */
+    refundable: number;
+}
+export interface ReturnSettlementOptions {
+    returnId: string;
+    currencyCode: string;
+    settleable: boolean;
+    /** Null exactly when `settleable`. */
+    blockedBy: ReturnSettlementBlocker | (string & {}) | null;
+    refund: {
+        available: boolean;
+        /** Null exactly when `available`. */
+        reasonCode: ReturnRefundUnavailableReason | (string & {}) | null;
+        /** Empty when not available. */
+        payments: ReturnSettlementPayment[];
+    };
+    creditNote: {
+        available: boolean;
+        ledger: ReturnCreditNoteLedger | (string & {});
+        /** Null exactly when `available`. */
+        reasonCode: ReturnCreditNoteUnavailableReason | (string & {}) | null;
+        /** `RETAIL` only: the invoice it would credit, when known. */
+        invoiceNumber: string | null;
+    };
+    /** The credit note when asked for or when no refund is possible, and it is available; else `refund`. */
+    initialMethod: ReturnSettlementMethod | (string & {});
+    /** The approved line total: what a settlement without an override settles, before shipping. */
+    defaultAmount: number;
+}
+export declare const RETURN_QUERY = "\n  query SdkOrderReturn($id: ID!) {\n    orderReturn(id: $id) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n      history {\n        state\n        actor\n        actorUserId\n        reason\n        createdAt\n      }\n    }\n  }\n";
+export declare const RETURNS_FOR_ORDER_QUERY = "\n  query SdkReturnsForOrder($orderId: ID!) {\n    returnsForOrder(orderId: $orderId) {\n      \n    id\n    code\n    channelId\n    orderId\n    orderCode\n    customerId\n    currencyCode\n    state\n    initiator\n    customerNote\n    adminNote\n    preferredSettlementMethod\n    settlementMethod\n    shippingRefundAmount\n    settledAmount\n    refundId\n    creditNoteId\n    creditNoteNumber\n    requestedAt\n    resolvedAt\n    createdAt\n    updatedAt\n    lines {\n      id\n      returnId\n      orderLineId\n      productVariantId\n      productVariantName\n      productVariantSku\n      requestedQty\n      approvedQty\n      receivedQty\n      restockQty\n      writeOffQty\n      restockLocationId\n      reasonCode\n      reasonNote\n      unitPriceWithTax\n      unitPriceWithTaxUnrounded\n      refundAmount\n      createdAt\n      updatedAt\n    }\n\n    }\n  }\n";
+export declare const RETURN_ELIGIBILITY_QUERY = "\n  query SdkReturnEligibility($orderId: ID!) {\n    returnEligibilityForOrder(orderId: $orderId) {\n      orderId\n      eligible\n      reason\n      returnWindowEndsAt\n      lines {\n        orderLineId\n        productVariantId\n        productVariantName\n        productVariantSku\n        fulfilledQty\n        returnableQty\n        unitPriceWithTax\n        unitPriceWithTaxUnrounded\n      }\n    }\n  }\n";
+export declare const RETURN_SETTLEMENT_OPTIONS_QUERY = "\n  query SdkReturnSettlementOptions($returnId: ID!) {\n    returnSettlementOptions(returnId: $returnId) {\n      returnId\n      currencyCode\n      settleable\n      blockedBy\n      refund {\n        available\n        reasonCode\n        payments {\n          paymentId\n          method\n          refundable\n        }\n      }\n      creditNote {\n        available\n        ledger\n        reasonCode\n        invoiceNumber\n      }\n      initialMethod\n      defaultAmount\n    }\n  }\n";
+export interface ReturnsModule {
+    /**
+     * One return with its lines and its status log (newest first), or `null`
+     * when this store holds no return with that id. Needs `ReadOrderReturn`.
+     */
+    get(id: string, options?: Call): Promise<OrderReturnDetail | null>;
+    /** Every return of one order, newest first. Needs `ReadOrderReturn`. */
+    forOrder(orderId: string, options?: Call): Promise<OrderReturn[]>;
+    /**
+     * What of an order can still be returned, line by line, and the return
+     * window. The window is reported, never enforced here: an admin may return
+     * outside it. Needs `ReadOrderReturn`.
+     */
+    eligibility(orderId: string, options?: Call): Promise<ReturnEligibility>;
+    /**
+     * How a return can be settled now: whether it is settleable (and why not),
+     * which methods are open (with the payments a refund may name and what each
+     * can still give back), and which method to preselect. Needs
+     * `ReadOrderReturn` AND `ReadOrder`: it names the order's payments.
+     *
+     * This is the PLAN. The write (`settleReturn`) loads its own facts and judges
+     * again, so settling can still be refused when something changed in between,
+     * and an `amountOverride` above a payment's headroom is refused there. A
+     * return this store does not hold is a `NotFoundError` (`ENTITY_NOT_FOUND`).
+     *
+     * Needs an engine that serves `returnSettlementOptions`; against an older one
+     * this call fails validation and nothing else does.
+     */
+    settlementOptions(returnId: string, options?: Call): Promise<ReturnSettlementOptions>;
+}
+export declare function createReturnsModule(transport: Transport): ReturnsModule;

package/dist/returns/index.js

@@ -0,0 +1,160 @@
+/** A return's state: the latest row of its status log. */
+export const RETURN_STATES = [
+    'requested',
+    'approved',
+    'rejected',
+    'cancelled',
+    'items_received',
+    'settlement_pending',
+    'settlement_failed',
+    'settled',
+];
+/**
+ * How a return is settled. `refund` gives money back to an original payment.
+ * `store_credit` issues a credit note: on a store with an accounts-receivable
+ * ledger it credits the customer's account, elsewhere it credits the order's
+ * invoice and moves no money.
+ */
+export const RETURN_SETTLEMENT_METHODS = ['refund', 'store_credit'];
+/** Why a return cannot be settled now, in the order the engine checks them. */
+export const RETURN_SETTLEMENT_BLOCKERS = [
+    'OUTCOME_UNKNOWN',
+    'ALREADY_SETTLED',
+    'IN_PROGRESS',
+    'RECEIPT_REQUIRED',
+    'STATE',
+];
+/** The fields of an `OrderReturn` every read selects (a selection, spliced into each document). */
+const RETURN_FIELDS = /* GraphQL */ `
+    id
+    code
+    channelId
+    orderId
+    orderCode
+    customerId
+    currencyCode
+    state
+    initiator
+    customerNote
+    adminNote
+    preferredSettlementMethod
+    settlementMethod
+    shippingRefundAmount
+    settledAmount
+    refundId
+    creditNoteId
+    creditNoteNumber
+    requestedAt
+    resolvedAt
+    createdAt
+    updatedAt
+    lines {
+      id
+      returnId
+      orderLineId
+      productVariantId
+      productVariantName
+      productVariantSku
+      requestedQty
+      approvedQty
+      receivedQty
+      restockQty
+      writeOffQty
+      restockLocationId
+      reasonCode
+      reasonNote
+      unitPriceWithTax
+      unitPriceWithTaxUnrounded
+      refundAmount
+      createdAt
+      updatedAt
+    }
+`;
+export const RETURN_QUERY = /* GraphQL */ `
+  query SdkOrderReturn($id: ID!) {
+    orderReturn(id: $id) {
+      ${RETURN_FIELDS}
+      history {
+        state
+        actor
+        actorUserId
+        reason
+        createdAt
+      }
+    }
+  }
+`;
+export const RETURNS_FOR_ORDER_QUERY = /* GraphQL */ `
+  query SdkReturnsForOrder($orderId: ID!) {
+    returnsForOrder(orderId: $orderId) {
+      ${RETURN_FIELDS}
+    }
+  }
+`;
+export const RETURN_ELIGIBILITY_QUERY = /* GraphQL */ `
+  query SdkReturnEligibility($orderId: ID!) {
+    returnEligibilityForOrder(orderId: $orderId) {
+      orderId
+      eligible
+      reason
+      returnWindowEndsAt
+      lines {
+        orderLineId
+        productVariantId
+        productVariantName
+        productVariantSku
+        fulfilledQty
+        returnableQty
+        unitPriceWithTax
+        unitPriceWithTaxUnrounded
+      }
+    }
+  }
+`;
+export const RETURN_SETTLEMENT_OPTIONS_QUERY = /* GraphQL */ `
+  query SdkReturnSettlementOptions($returnId: ID!) {
+    returnSettlementOptions(returnId: $returnId) {
+      returnId
+      currencyCode
+      settleable
+      blockedBy
+      refund {
+        available
+        reasonCode
+        payments {
+          paymentId
+          method
+          refundable
+        }
+      }
+      creditNote {
+        available
+        ledger
+        reasonCode
+        invoiceNumber
+      }
+      initialMethod
+      defaultAmount
+    }
+  }
+`;
+export function createReturnsModule(transport) {
+    return {
+        async get(id, options) {
+            const data = await transport.graphql({ api: 'admin', query: RETURN_QUERY, variables: { id } }, options);
+            return data.orderReturn;
+        },
+        async forOrder(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: RETURNS_FOR_ORDER_QUERY, variables: { orderId } }, options);
+            return data.returnsForOrder;
+        },
+        async eligibility(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: RETURN_ELIGIBILITY_QUERY, variables: { orderId } }, options);
+            return data.returnEligibilityForOrder;
+        },
+        async settlementOptions(returnId, options) {
+            const data = await transport.graphql({ api: 'admin', query: RETURN_SETTLEMENT_OPTIONS_QUERY, variables: { returnId } }, options);
+            return data.returnSettlementOptions;
+        },
+    };
+}

package/dist/search/index.d.ts

@@ -0,0 +1,99 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** What `admin.search.entities` searches. */
+export type SearchEntityType = 'PRODUCTS' | 'ORDERS' | 'CUSTOMERS' | 'CONTENT';
+/**
+ * Why a type was not searched. A string on the wire: a newer engine may add a reason, so read an
+ * unknown one as "not searched".
+ *
+ * - `PERMISSION`: the credential holds none of the type's read permissions in the store
+ *   (`ReadCatalog` or `ReadProduct` for products, `ReadOrder` for orders, `ReadCustomer` for
+ *   customers).
+ * - `CUSTOMER_DATA_NOT_GRANTED`: the credential reads customer data below `full` (an app installed
+ *   at `none` or `identity`). Orders and customers are matched on customers' names, email
+ *   addresses and companies, so they are not searched for it.
+ * - `UNAVAILABLE`: the search service, or for content the content system, did not answer. Try
+ *   again shortly.
+ */
+export type SearchSkipReason = 'PERMISSION' | 'CUSTOMER_DATA_NOT_GRANTED' | 'UNAVAILABLE' | (string & {});
+export interface SearchProductHit {
+    id: string;
+    name: string;
+    slug: string;
+    /** The featured image's preview URL; null when the product has none. */
+    previewUrl: string | null;
+}
+export interface SearchOrderHit {
+    id: string;
+    code: string;
+    state: string;
+    /** ISO-8601; null for an order not placed yet. */
+    orderPlacedAt: string | null;
+    /** Minor units. */
+    totalWithTax: number;
+    currencyCode: string;
+    /** The order's lifecycle (`open`, `completed`, …); null until the engine sets it. */
+    lifecycleStatus: string | null;
+}
+export interface SearchCustomerHit {
+    id: string;
+    firstName: string;
+    lastName: string;
+    emailAddress: string;
+    /** The company of the default billing address, else the default shipping one, else any. */
+    company: string | null;
+}
+/** A content item of the store's content system. */
+export interface SearchContentHit {
+    id: string;
+    collectionId: string;
+    collectionSlug: string;
+    slug: string | null;
+    /** `draft`, `published` or `archived`. */
+    status: string;
+    title: string | null;
+}
+export interface SearchSkip {
+    type: SearchEntityType | (string & {});
+    reason: SearchSkipReason;
+}
+/** Each list holds the type's best matches, most relevant first. */
+export interface EntitySearchResult {
+    products: SearchProductHit[];
+    orders: SearchOrderHit[];
+    customers: SearchCustomerHit[];
+    content: SearchContentHit[];
+    /** The types that were not searched, and why; their lists are empty. */
+    skipped: SearchSkip[];
+}
+export interface SearchEntitiesOptions extends Call {
+    /** The types to search; all four when omitted. An empty list is refused. */
+    types?: readonly SearchEntityType[];
+    /** Results per type, from 1 to {@link SEARCH_ENTITIES_MAX_TAKE}; 5 when omitted. */
+    take?: number;
+}
+/** The engine's bounds, as `searchAcrossEntities` documents them. */
+export declare const SEARCH_ENTITIES_MIN_TERM_LENGTH = 2;
+export declare const SEARCH_ENTITIES_MAX_TAKE = 10;
+export declare const SEARCH_ACROSS_ENTITIES_QUERY = "\n  query SearchAcrossEntities($input: CommandSearchInput!) {\n    searchAcrossEntities(input: $input) {\n      products {\n        id\n        name\n        slug\n        previewUrl\n      }\n      orders {\n        id\n        code\n        state\n        orderPlacedAt\n        totalWithTax\n        currencyCode\n        lifecycleStatus\n      }\n      customers {\n        id\n        firstName\n        lastName\n        emailAddress\n        company\n      }\n      content {\n        id\n        collectionId\n        collectionSlug\n        slug\n        status\n        title\n      }\n      skipped {\n        type\n        reason\n      }\n    }\n  }\n";
+/**
+ * One search across the store (spec §7 `search.entities`): products, orders, customers and
+ * content items matching a term, in one call.
+ *
+ * - **Relevance order.** Each list is that type's best matches, most relevant first, every one
+ *   already loaded in the store you act on; a match the store no longer holds is left out, so a
+ *   list can be shorter than `take`.
+ * - **A type you may not read is skipped and named**, never a refusal: its list is empty and
+ *   `skipped` says why (see {@link SearchSkipReason}).
+ * - **Content may be missing when the content system is down**: the other types still answer,
+ *   and content is skipped `UNAVAILABLE`.
+ * - **Content** is published items, plus drafts and archived items for a `ReadCmsContent` holder.
+ *
+ * Refused before anything is searched: `SEARCH_INPUT_INVALID` (`ValidationError`, 400) for a term
+ * under {@link SEARCH_ENTITIES_MIN_TERM_LENGTH} or over 500 characters once trimmed, a `take`
+ * outside 1..{@link SEARCH_ENTITIES_MAX_TAKE}, or an empty `types` list.
+ */
+export interface SearchModule {
+    entities(term: string, options?: SearchEntitiesOptions): Promise<EntitySearchResult>;
+}
+export declare function createSearchModule(transport: Transport): SearchModule;