@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/fulfillments/create.d.ts

@@ -0,0 +1,167 @@
+/**
+ * `admin.fulfillments.create` and `admin.fulfillments.profileChargePreview`: the shared create
+ * flow's write and its office-only delivery-charge preview (headless W10-38; spec
+ * `decoupling-fulfillments` §13, §15.4).
+ *
+ * The create answers the warehouse API's union: a refusal of the WHOLE call is thrown through
+ * `warehouseRefusalError`, so a code reaches a caller as the same class from `create` as from
+ * `fulfillments.warehouse.append` and the warehouse reads (`INVALID_INPUT` a `ValidationError`
+ * 400, never a 422). Each group's own refusal is data in `results[].error`.
+ */
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import { type KeyedWarehouseCall, type WarehouseFulfillment, type WarehouseFulfillmentLineInput, type WarehouseHandlerArg, type WarehouseRefusal } from './warehouse.js';
+/** One fulfilment to create: the lines it ships and its carrier. */
+export interface CreateFulfillmentGroupInput {
+    /** 1–500 lines, each a whole quantity of 1 or more, at most what is left to ship. */
+    lines: WarehouseFulfillmentLineInput[];
+    /** The carrier (fulfilment handler) code; `fulfillments.warehouse.handlers()` lists them. */
+    handlerCode: string;
+    /**
+     * The carrier's own arguments, as text. Send every name in the carrier's
+     * `argsRequiredForCreate`; the warehouse, profile and pick override are set by the engine.
+     */
+    handlerArgs?: WarehouseHandlerArg[];
+    /** Office staff only (`OFFICE_ONLY` otherwise): the profile whose minimum and delivery charge apply. */
+    fulfillmentProfileId?: string;
+}
+/** What `create` sends: one fulfilment per group, all shipping from one warehouse. */
+export interface CreateFulfillmentsInput {
+    /** The warehouse every group ships from; it must be in the caller's scope. */
+    stockLocationId: string;
+    /** 1–50 groups. */
+    groups: CreateFulfillmentGroupInput[];
+    /**
+     * Claim each created in-house fulfilment for the caller (`Picking`). Only on a store with the
+     * warehouse workspace (`WAREHOUSE_NOT_ENABLED` otherwise).
+     */
+    startPicking?: boolean;
+    /**
+     * Office staff with no location restriction only: ship lines whose order picked another
+     * warehouse from this one (`OFFICE_ONLY` / `LOCATION_OUT_OF_SCOPE` otherwise).
+     */
+    overridePreferredLocation?: boolean;
+}
+/** What became of one group, by its position in the input. */
+export interface CreateFulfillmentGroupResult {
+    index: number;
+    /** The fulfilment as it now is; null when the group was refused. */
+    fulfillment: WarehouseFulfillment | null;
+    /** Why the group was refused; nothing of it was written. */
+    error: WarehouseRefusal | null;
+    /** Set when the fulfilment WAS created but `startPicking` could not claim it. */
+    claimError: WarehouseRefusal | null;
+}
+/** Every group of a `create`, each on its own. */
+export interface CreateFulfillmentsResult {
+    results: CreateFulfillmentGroupResult[];
+    created: number;
+    failed: number;
+}
+/** What `profileChargePreview` prices: a profile and the lines one fulfilment would ship. */
+export interface FulfillmentProfileChargePreviewInput {
+    fulfillmentProfileId: string;
+    /** 1–500 lines, each a whole quantity of 1 or more. */
+    lines: Array<{
+        orderLineId: string;
+        quantity: number;
+    }>;
+}
+/**
+ * A fulfilment profile's minimum and delivery charge for a selection. Nothing was written. Money
+ * is integer MINOR UNITS of `currencyCode`.
+ */
+export interface FulfillmentProfileChargePreview {
+    profileName: string;
+    currencyCode: string;
+    /** The profile's minimum order value, NET. */
+    minOrder: number;
+    /**
+     * The net value the minimum is judged on: the selected lines' combined net, or, for a whole
+     * order that met the minimum when it was placed, its lines that count toward minimums.
+     */
+    selectedNet: number;
+    /** How far the selection is below the minimum; 0 when it is met. */
+    shortfall: number;
+    /** What the profile's shipping method charges for these lines; null when none would be added. */
+    deliveryCharge: number | null;
+    /** Whether `deliveryCharge` includes tax; null with no charge. */
+    deliveryChargeIncludesTax: boolean | null;
+    /**
+     * Every order the delivery is for already paid delivery at checkout, so no charge is added.
+     * When nothing is delivered (`handedOver`), whether every order is fully paid.
+     */
+    settled: boolean;
+    /**
+     * Nothing in the selection is delivered (collected, sold at a till, nothing to ship): the
+     * minimum and the delivery charge do not apply (`minOrder` and `shortfall` 0, no charge); the
+     * profile still picks the warehouse.
+     */
+    handedOver: boolean;
+}
+export interface FulfillmentCreateMethods {
+    /**
+     * Create fulfilments at one warehouse: one per group, each in its own transaction, through the
+     * same create path as the order page. A group that is refused is reported in its
+     * `results[].error` and the rest go on, so the answer can mix created and refused groups.
+     * Needs `UpdateFulfillment` (warehouse staff, on a store with the warehouse workspace, at a
+     * warehouse assigned to them) or `UpdateOrder` (office staff, on any store, at any of its
+     * warehouses).
+     *
+     * MONEY and outside effects, per created fulfilment: a fulfilment profile (office only) can
+     * add a delivery charge to its orders, shared across a consolidation; on a store without the
+     * warehouse workspace the carrier is booked at create (a label bought, or a 3PL handed the
+     * order; with the workspace it is booked later, at Packed); the customer gets the
+     * `fulfillment_created` e-mail.
+     *
+     * A line nobody picked a warehouse for, whose stock is reserved at another warehouse, has its
+     * reservation moved here: released there and taken from this warehouse, as it is for
+     * warehouse staff assigned here (a line whose order picked another warehouse is refused
+     * `LINE_PREFERS_OTHER_LOCATION`, unless the office sets `overridePreferredLocation`).
+     *
+     * One key per attempt (`options.idempotencyKey`): a repeat under the same key answers the
+     * first call's result (each fulfilment as it is now) and creates nothing, however few of a
+     * line's units it asked for. Another request under that key is `IDEMPOTENCY_CONFLICT`
+     * (`ConflictError`, 409). The groups commit one by one, so the engine spends the key before the
+     * first: a repeat while the first is still running, or after it stopped without answering, is
+     * `IDEMPOTENCY_OUTCOME_UNKNOWN` (`outcomeUnknown`): read the orders' fulfilments, never create
+     * again under a new key blind; once the first has answered, the key replays its answer. A
+     * refusal of the whole call does not spend the key. Left out, a key is made up (a UUIDv7) and
+     * returned as `idempotencyKey` on the result, and on a thrown error as an untyped own property
+     * of the error.
+     *
+     * Refusals. Of the whole call, THROWN, with the classes of every warehouse refusal:
+     * `INVALID_INPUT` (a `ValidationError`, 400; also before any request for a missing warehouse,
+     * no groups, a group without a carrier or a line without an id or a whole quantity),
+     * `LOCATION_OUT_OF_SCOPE`, `OFFICE_ONLY`, `WAREHOUSE_NOT_ENABLED` (`BusinessRuleError`, 422).
+     * Of one group, as DATA: `COMBINE_RULE_VIOLATED` (the part of the rule that broke in
+     * `field`), `LINE_OVER_FULFILLED`, `INSUFFICIENT_STOCK_AT_LOCATION`, `ORDER_NOT_COVERED`,
+     * `PROFILE_MINIMUM_NOT_MET` (a consolidation short of the profile minimum; one order short of it
+     * is `INVALID_INPUT`, its sentence naming the minimum), `SOURCE_FULFILLED_BLOCKED`, a carrier's
+     * own refusal, … A missing
+     * permission is `FORBIDDEN` and a carrier of a plugin the store does not have
+     * `PLUGIN_ACCESS_DENIED` (both `PermissionDeniedError`, 403).
+     *
+     * @effect money
+     */
+    create(input: CreateFulfillmentsInput, options?: KeyedWarehouseCall): Promise<CreateFulfillmentsResult & {
+        idempotencyKey: string;
+    }>;
+    /**
+     * What a fulfilment profile would ask of a selection before it is created: its minimum, how
+     * far the selection is below it, and the delivery charge it would add. Office staff only
+     * (`UpdateOrder`). Who pays which share of a consolidated charge is decided at create. Money in
+     * integer minor units.
+     *
+     * A malformed or unknown profile or line, no lines or more than 500, a bad quantity, or orders
+     * in different currencies are `FULFILLMENT_PROFILE_PREVIEW_INVALID` (a `ValidationError`,
+     * 400); a selection the create would refuse answers that code (`LOCATION_OUT_OF_SCOPE`,
+     * `COMBINE_RULE_VIOLATED`, `PROFILE_CURRENCY_MISMATCH`, `BusinessRuleError`).
+     *
+     * @effect read
+     */
+    profileChargePreview(input: FulfillmentProfileChargePreviewInput, options?: Call): Promise<FulfillmentProfileChargePreview>;
+}
+export declare const CREATE_WAREHOUSE_FULFILLMENTS_MUTATION = "\n  mutation CreateWarehouseFulfillments(\n    $input: CreateWarehouseFulfillmentsInput!\n    $idempotencyKey: String\n  ) {\n    createWarehouseFulfillments(input: $input, idempotencyKey: $idempotencyKey) {\n      __typename\n      ... on WarehouseCreateResult {\n        created\n        failed\n        results {\n          index\n          fulfillment {\n            \n  id\n  state\n  handlerCode\n  method\n  mode\n  trackingCode\n  stockLocationId\n  stockLocationName\n  createdAt\n  stateChangedAt\n  overdue\n  claimedBy {\n    id\n    name\n  }\n  claimedAt\n  packedAt\n  bookingStatus\n  bookingError\n  parcels {\n    weightGrams\n    lengthMm\n    widthMm\n    heightMm\n  }\n  orders {\n    id\n    code\n    poNumber\n    orderNotes\n    requestedDeliveryDate\n    deliveryDue\n    paymentBadge\n    hold {\n      reason\n      note\n    }\n  }\n  customer {\n    id\n    name\n    phone\n  }\n  shippingAddress {\n    \n  fullName\n  company\n  streetLine1\n  streetLine2\n  city\n  province\n  postalCode\n  countryCode\n\n  }\n  lineCount\n  unitCount\n\n          }\n          error {\n            code\n            message\n            field\n          }\n          claimError {\n            code\n            message\n            field\n          }\n        }\n      }\n      ... on WarehouseError {\n        errorCode\n        code\n        message\n        field\n      }\n    }\n  }\n";
+export declare const FULFILLMENT_PROFILE_CHARGE_PREVIEW_QUERY = "\n  query FulfillmentProfileChargePreview($input: FulfillmentProfileChargePreviewInput!) {\n    fulfillmentProfileChargePreview(input: $input) {\n      profileName\n      currencyCode\n      minOrder\n      selectedNet\n      shortfall\n      deliveryCharge\n      deliveryChargeIncludesTax\n      settled\n      handedOver\n    }\n  }\n";
+export declare function createFulfillmentCreateMethods(transport: Transport): FulfillmentCreateMethods;

package/dist/fulfillments/create.js

@@ -0,0 +1,216 @@
+/**
+ * `admin.fulfillments.create` and `admin.fulfillments.profileChargePreview`: the shared create
+ * flow's write and its office-only delivery-charge preview (headless W10-38; spec
+ * `decoupling-fulfillments` §13, §15.4).
+ *
+ * The create answers the warehouse API's union: a refusal of the WHOLE call is thrown through
+ * `warehouseRefusalError`, so a code reaches a caller as the same class from `create` as from
+ * `fulfillments.warehouse.append` and the warehouse reads (`INVALID_INPUT` a `ValidationError`
+ * 400, never a 422). Each group's own refusal is data in `results[].error`.
+ */
+import { idempotencyKey as mintIdempotencyKey, ValidationError, } from '@sixtyninecommerce/core';
+import { assertId, FULFILLMENT_FIELDS, invalid, isWarehouseErrorMember, toFulfillment, toRefusal, warehouseRefusalError, withAttemptKey, } from './warehouse.js';
+export const CREATE_WAREHOUSE_FULFILLMENTS_MUTATION = /* GraphQL */ `
+  mutation CreateWarehouseFulfillments(
+    $input: CreateWarehouseFulfillmentsInput!
+    $idempotencyKey: String
+  ) {
+    createWarehouseFulfillments(input: $input, idempotencyKey: $idempotencyKey) {
+      __typename
+      ... on WarehouseCreateResult {
+        created
+        failed
+        results {
+          index
+          fulfillment {
+            ${FULFILLMENT_FIELDS}
+          }
+          error {
+            code
+            message
+            field
+          }
+          claimError {
+            code
+            message
+            field
+          }
+        }
+      }
+      ... on WarehouseError {
+        errorCode
+        code
+        message
+        field
+      }
+    }
+  }
+`;
+export const FULFILLMENT_PROFILE_CHARGE_PREVIEW_QUERY = /* GraphQL */ `
+  query FulfillmentProfileChargePreview($input: FulfillmentProfileChargePreviewInput!) {
+    fulfillmentProfileChargePreview(input: $input) {
+      profileName
+      currencyCode
+      minOrder
+      selectedNet
+      shortfall
+      deliveryCharge
+      deliveryChargeIncludesTax
+      settled
+      handedOver
+    }
+  }
+`;
+const isObject = (value) => typeof value === 'object' && value !== null;
+/**
+ * Refused before any request: each of these would otherwise fail GraphQL validation with no code.
+ * Bounds the engine checks (group and line counts, quantities, ids that are not uuids) are left
+ * to it.
+ */
+function assertCreateInput(input) {
+    if (!isObject(input))
+        throw invalid('input', 'Name the warehouse and the groups to create.');
+    assertId(input.stockLocationId, 'stockLocationId');
+    const groups = input.groups;
+    if (!Array.isArray(groups) || groups.length === 0) {
+        throw invalid('groups', 'Add at least one group of lines to fulfill.');
+    }
+    for (const [index, group] of groups.entries()) {
+        const at = `groups[${String(index)}]`;
+        if (!isObject(group))
+            throw invalid(at, `Group ${String(index + 1)} is not a group of lines.`);
+        if (typeof group.handlerCode !== 'string' || group.handlerCode.trim() === '') {
+            throw invalid(`${at}.handlerCode`, `Group ${String(index + 1)}: choose a carrier (fulfillment handler).`);
+        }
+        if (!Array.isArray(group.lines)) {
+            throw invalid(`${at}.lines`, `Group ${String(index + 1)}: list the lines it ships.`);
+        }
+        for (const [lineIndex, line] of group.lines.entries()) {
+            const lineAt = `${at}.lines[${String(lineIndex)}]`;
+            assertId(isObject(line) ? line.orderLineId : undefined, `${lineAt}.orderLineId`);
+            if (!Number.isInteger(line.quantity)) {
+                throw invalid(`${lineAt}.quantity`, 'A quantity is a whole number.');
+            }
+        }
+        if (group.handlerArgs !== undefined && !Array.isArray(group.handlerArgs)) {
+            throw invalid(`${at}.handlerArgs`, 'The carrier arguments are a list of names and values.');
+        }
+        for (const [argIndex, arg] of (group.handlerArgs ?? []).entries()) {
+            if (!isObject(arg) || typeof arg.name !== 'string' || typeof arg.value !== 'string') {
+                throw invalid(`${at}.handlerArgs[${String(argIndex)}]`, 'Each carrier argument has a name and a value, both text.');
+            }
+        }
+    }
+}
+function invalidPreview(field, message) {
+    return new ValidationError({
+        code: 'FULFILLMENT_PROFILE_PREVIEW_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field, code: 'FULFILLMENT_PROFILE_PREVIEW_INVALID', message }],
+    });
+}
+/** Refused before any request, with the engine's own code: each would fail GraphQL validation. */
+function assertPreviewInput(input) {
+    if (!isObject(input))
+        throw invalidPreview('input', 'Name a profile and the lines to preview.');
+    const profileId = input.fulfillmentProfileId;
+    if (typeof profileId !== 'string' || profileId.trim() === '') {
+        throw invalidPreview('fulfillmentProfileId', 'A fulfillment profile id is required.');
+    }
+    if (!Array.isArray(input.lines)) {
+        throw invalidPreview('lines', 'List the lines the fulfillment would ship.');
+    }
+    for (const [index, line] of input.lines.entries()) {
+        const at = `lines[${String(index)}]`;
+        const id = isObject(line) ? line.orderLineId : undefined;
+        if (typeof id !== 'string' || id.trim() === '') {
+            throw invalidPreview(`${at}.orderLineId`, 'Each line names its order line.');
+        }
+        if (!Number.isInteger(line.quantity)) {
+            throw invalidPreview(`${at}.quantity`, 'A quantity is a whole number.');
+        }
+    }
+}
+export function createFulfillmentCreateMethods(transport) {
+    return {
+        async create(input, options) {
+            assertCreateInput(input);
+            const key = options?.idempotencyKey ?? mintIdempotencyKey();
+            try {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: CREATE_WAREHOUSE_FULFILLMENTS_MUTATION,
+                    variables: {
+                        input: {
+                            stockLocationId: input.stockLocationId,
+                            groups: input.groups.map((group) => ({
+                                lines: group.lines.map(({ orderLineId, quantity }) => ({
+                                    orderLineId,
+                                    quantity,
+                                })),
+                                handlerCode: group.handlerCode,
+                                ...(group.handlerArgs
+                                    ? { handlerArgs: group.handlerArgs.map(({ name, value }) => ({ name, value })) }
+                                    : {}),
+                                ...(group.fulfillmentProfileId
+                                    ? { fulfillmentProfileId: group.fulfillmentProfileId }
+                                    : {}),
+                            })),
+                            ...(input.startPicking === undefined ? {} : { startPicking: input.startPicking }),
+                            ...(input.overridePreferredLocation === undefined
+                                ? {}
+                                : { overridePreferredLocation: input.overridePreferredLocation }),
+                        },
+                        idempotencyKey: key,
+                    },
+                }, { ...options, idempotencyKey: key });
+                const result = data.createWarehouseFulfillments;
+                // The whole call refused: classified like every other warehouse refusal (W10-37 F-4).
+                if (isWarehouseErrorMember(result))
+                    throw warehouseRefusalError(result);
+                const outcome = result;
+                return {
+                    created: outcome.created,
+                    failed: outcome.failed,
+                    results: outcome.results.map((item) => ({
+                        index: item.index,
+                        fulfillment: item.fulfillment ? toFulfillment(item.fulfillment) : null,
+                        error: toRefusal(item.error),
+                        claimError: toRefusal(item.claimError),
+                    })),
+                    idempotencyKey: key,
+                };
+            }
+            catch (error) {
+                throw withAttemptKey(error, key);
+            }
+        },
+        async profileChargePreview(input, options) {
+            assertPreviewInput(input);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: FULFILLMENT_PROFILE_CHARGE_PREVIEW_QUERY,
+                variables: {
+                    input: {
+                        fulfillmentProfileId: input.fulfillmentProfileId,
+                        lines: input.lines.map(({ orderLineId, quantity }) => ({ orderLineId, quantity })),
+                    },
+                },
+            }, options);
+            const preview = data.fulfillmentProfileChargePreview;
+            return {
+                profileName: preview.profileName,
+                currencyCode: preview.currencyCode,
+                minOrder: preview.minOrder,
+                selectedNet: preview.selectedNet,
+                shortfall: preview.shortfall,
+                deliveryCharge: preview.deliveryCharge ?? null,
+                deliveryChargeIncludesTax: preview.deliveryChargeIncludesTax ?? null,
+                settled: preview.settled,
+                handedOver: preview.handedOver,
+            };
+        },
+    };
+}

package/dist/fulfillments/index.d.ts

@@ -1,6 +1,10 @@
 import { type Transport } from '@sixtyninecommerce/core';
 import type { OrderOverpaymentChoice, OverpaymentOption } from '../orders/surcharges.js';
 import type { Call } from '../types.js';
+import { type FulfillmentCreateMethods } from './create.js';
+import { type FulfillmentPaymentPolicyModule } from './payment-policy.js';
+import { type WarehouseDemandRouting, type WarehouseFulfillmentsModule } from './warehouse.js';
+export type { WarehouseDemandRouting };
 /**
  * A fulfillment's parcels as the order records them: one MyParcel shipment per
  * parcel, and the barcodes the carrier has issued so far.
@@ -40,8 +44,6 @@ export interface FulfillmentParcelTracking {
     parcelCount: number;
 }
 export type FulfillmentLabelFormat = 'A4' | 'A6';
-/** How a warehouse's "To ship" queue routes a line (`WarehouseDemandRouting`). */
-export type WarehouseDemandRouting = 'preferred' | 'allocated' | 'unrouted' | 'no_stock';
 /**
  * Which "To ship" entry of an order to read. The entry, and so whether it
  * holds the whole order, depends on the warehouse and on the routing filters:
@@ -196,6 +198,11 @@ export interface FulfillmentCancelSettlement {
     amount: number;
     currencyCode: string;
     choice: OrderOverpaymentChoice;
+    /**
+     * For `ACCOUNT_CREDIT`: the store's customer-credit book the credit lands in (`AR` or
+     * `STORE_CREDIT`); null for `REFUND` and from an engine before it.
+     */
+    book?: string | null;
 }
 /** A cancelled fulfillment and what its cancel queued. */
 export interface CancelledFulfillment {
@@ -262,8 +269,11 @@ export declare const FULFILLMENT_COVERAGE_REASON_MAX_LENGTH = 500;
  * Fulfillment parcels (multi-parcel shipments). Each method is its own request
  * on purpose: a caller deployed ahead of an engine without these fields sees
  * only that call refused, never the order or fulfillment read beside it.
+ *
+ * `create` and `profileChargePreview` (the shared create flow) are declared in
+ * `fulfillments/create.ts`.
  */
-export interface FulfillmentsModule {
+export interface FulfillmentsModule extends FulfillmentCreateMethods {
     /** Every fulfillment of an order, with its parcels. Needs `ReadOrder`. */
     parcelsOfOrder(orderId: string, options?: Call): Promise<OrderFulfillmentParcels[]>;
     /**
@@ -281,7 +291,11 @@ export interface FulfillmentsModule {
     /**
      * Every parcel's MyParcel label merged by MyParcel into one PDF, fetched live
      * and never cached. Needs `ReadOrder`. Allowed up to 55s: the engine retries
-     * a slow MyParcel within a budget the default timeout does not cover.
+     * a slow MyParcel within a budget the default timeout does not cover. A
+     * credential restricted to stock locations (an API token or app installation
+     * with `locationIds`) prints it only for a fulfillment that ships from one of
+     * them; any other, another store's and a missing one included, is
+     * `LOCATION_OUT_OF_SCOPE` (422).
      */
     myparcelLabel(fulfillmentId: string, format: FulfillmentLabelFormat, options?: Call): Promise<FulfillmentLabel>;
     /**
@@ -303,8 +317,11 @@ export interface FulfillmentsModule {
      * `NotFoundError` (`MYPARCEL_ORDER_NOT_FOUND_ERROR`); a cancelled one, or
      * one holding no shipment, a `BusinessRuleError`
      * (`MYPARCEL_VALIDATION_ERROR`), as is MyParcel switched off for the store
-     * (`MYPARCEL_NOT_CONFIGURED_ERROR`). Only queues work, so the default
-     * timeout applies.
+     * (`MYPARCEL_NOT_CONFIGURED_ERROR`). A credential restricted to stock
+     * locations (an API token or app installation with `locationIds`) is refused
+     * `LOCATION_OUT_OF_SCOPE` (422) first for a fulfillment that does not ship
+     * from one of them, another store's and a missing one included. Only queues
+     * work, so the default timeout applies.
      */
     labelMyparcelParcels(fulfillmentId: string, input?: LabelMyparcelParcelsInput, options?: Call): Promise<MyparcelParcelsLabelRequest>;
     /**
@@ -336,7 +353,10 @@ export interface FulfillmentsModule {
      * What cancelling the fulfillment would owe each order's customer back (a delivery charge
      * they already paid), and which ways of settling it are open. Read now, without a lock; the
      * cancel judges it again. Needs `UpdateOrder`. Another store's fulfillment is a
-     * `NotFoundError` (`ENTITY_NOT_FOUND`).
+     * `NotFoundError` (`ENTITY_NOT_FOUND`). A credential restricted to stock locations (an API
+     * token or app installation with `locationIds`) reads it only for a fulfillment that ships
+     * from one of them; any other, another store's and a missing one included, is
+     * `LOCATION_OUT_OF_SCOPE` (422).
      */
     cancelPreview(fulfillmentId: string, options?: Call): Promise<FulfillmentCancelPreview>;
     /**
@@ -355,7 +375,10 @@ export interface FulfillmentsModule {
      * `AR_ACCOUNT_IN_ERP`, `ORDER_OVERPAYMENT_REFUND_UNRECONCILED`, …);
      * `FULFILLMENT_CANCEL_REFUSED` (→ `BusinessRuleError`) when the fulfillment's process refuses
      * the cancel (already cancelled, a carrier that cannot let go). Another store's fulfillment is
-     * a `NotFoundError`.
+     * a `NotFoundError`. A credential restricted to stock locations (an API token or app
+     * installation with `locationIds`) cancels only a fulfillment that ships from one of them; any
+     * other (one with no recorded warehouse, another store's and a missing one included) is
+     * `LOCATION_OUT_OF_SCOPE` (422), before the key is claimed.
      *
      * `options.idempotencyKey`: a repeat under it answers the first call's result, never a second
      * cancel; the same key with a different choice is `IDEMPOTENCY_CONFLICT`.
@@ -389,14 +412,25 @@ export interface FulfillmentsModule {
     allowUncovered(orderId: string, reason: string, options?: Call & {
         idempotencyKey?: string;
     }): Promise<FulfillmentCoverageOverride>;
+    /**
+     * The store's fulfilment payment policy (`fulfillmentPaymentPolicy`): whether a fulfilment of
+     * an order not paid in full is refused `ORDER_NOT_COVERED`, and which payment methods are
+     * exempt. Read as the engine applies it; written whole (`UpdateChannel`).
+     */
+    paymentPolicy: FulfillmentPaymentPolicyModule;
+    /**
+     * The pick/pack/ship workspace: the warehouse API (price-free, location-scoped), the pick list
+     * and consolidation. See `fulfillments/warehouse.ts`.
+     */
+    warehouse: WarehouseFulfillmentsModule;
 }
 /**
  * Its own document, like every call here: on an engine without the query this call alone fails
  * validation.
  */
-export declare const FULFILLMENT_CANCEL_PREVIEW_QUERY = "\n  query FulfillmentCancelPreview($fulfillmentId: ID!) {\n    fulfillmentCancelPreview(fulfillmentId: $fulfillmentId) {\n      fulfillmentId\n      overpayments {\n        orderId\n        orderCode\n        amount\n        currencyCode\n        refund { \n  available\n  code\n  message\n }\n        accountCredit { \n  available\n  code\n  message\n }\n      }\n    }\n  }\n";
+export declare const FULFILLMENT_CANCEL_PREVIEW_QUERY = "\n  query FulfillmentCancelPreview($fulfillmentId: ID!) {\n    fulfillmentCancelPreview(fulfillmentId: $fulfillmentId) {\n      fulfillmentId\n      overpayments {\n        orderId\n        orderCode\n        amount\n        currencyCode\n        refund { \n  available\n  code\n  message\n  book\n }\n        accountCredit { \n  available\n  code\n  message\n  book\n }\n      }\n    }\n  }\n";
 /** `$overpayment` and `$idempotencyKey` are optional and left out of the variables when not given. */
-export declare const CANCEL_FULFILLMENT_MUTATION = "\n  mutation CancelFulfillment(\n    $fulfillmentId: ID!\n    $overpayment: [FulfillmentCancelOverpaymentInput!]\n    $idempotencyKey: String\n  ) {\n    cancelFulfillment(\n      fulfillmentId: $fulfillmentId\n      overpayment: $overpayment\n      idempotencyKey: $idempotencyKey\n    ) {\n      fulfillment {\n        id\n        state\n      }\n      settlements {\n        orderId\n        orderCode\n        amount\n        currencyCode\n        choice\n      }\n    }\n  }\n";
+export declare const CANCEL_FULFILLMENT_MUTATION = "\n  mutation CancelFulfillment(\n    $fulfillmentId: ID!\n    $overpayment: [FulfillmentCancelOverpaymentInput!]\n    $idempotencyKey: String\n  ) {\n    cancelFulfillment(\n      fulfillmentId: $fulfillmentId\n      overpayment: $overpayment\n      idempotencyKey: $idempotencyKey\n    ) {\n      fulfillment {\n        id\n        state\n      }\n      settlements {\n        orderId\n        orderCode\n        amount\n        currencyCode\n        choice\n        book\n      }\n    }\n  }\n";
 /** Its own document: on an engine without the query this call alone fails validation. */
 export declare const ORDER_FULFILLMENT_COVERAGE_QUERY = "\n  query OrderFulfillmentCoverage($orderId: ID!) {\n    orderFulfillmentCoverage(orderId: $orderId) {\n      orderId\n      orderCode\n      currencyCode\n      policyActive\n      covered\n      outstanding\n      exempt\n      exemptReason\n      allowed\n      override { \n  id\n  orderId\n  reason\n  actorKind\n  actorId\n  outstandingAtGrant\n  currencyCode\n  createdAt\n  active\n }\n    }\n  }\n";
 /** `$idempotencyKey` is optional and left out of the variables when not given. */

package/dist/fulfillments/index.js

@@ -1,4 +1,8 @@
 import { errorFromErrorResult, isErrorResult, NotFoundError, ValidationError, } from '@sixtyninecommerce/core';
+import { storeCreditAware } from '../payments/store-credit-fields.js';
+import { createFulfillmentCreateMethods } from './create.js';
+import { createFulfillmentPaymentPolicyModule, } from './payment-policy.js';
+import { createWarehouseFulfillmentsModule, } from './warehouse.js';
 /** The longest override reason the engine stores. */
 export const FULFILLMENT_COVERAGE_REASON_MAX_LENGTH = 500;
 /** Every field of `OrderOverpaymentOption`. */
@@ -6,6 +10,7 @@ const OVERPAYMENT_OPTION_FIELDS = /* GraphQL */ `
   available
   code
   message
+  book
 `;
 /**
  * Its own document, like every call here: on an engine without the query this call alone fails
@@ -48,6 +53,7 @@ export const CANCEL_FULFILLMENT_MUTATION = /* GraphQL */ `
         amount
         currencyCode
         choice
+        book
       }
     }
   }
@@ -360,6 +366,9 @@ function assertLabelRequest(fulfillmentId, format) {
 }
 export function createFulfillmentsModule(transport) {
     return {
+        ...createFulfillmentCreateMethods(transport),
+        paymentPolicy: createFulfillmentPaymentPolicyModule(transport),
+        warehouse: createWarehouseFulfillmentsModule(transport),
         async parcelsOfOrder(orderId, options) {
             const data = await transport.graphql({ api: 'admin', query: ORDER_FULFILLMENT_PARCELS_QUERY, variables: { id: orderId } }, options);
             if (!data.order)
@@ -442,7 +451,7 @@ export function createFulfillmentsModule(transport) {
             if (typeof fulfillmentId !== 'string' || fulfillmentId.trim() === '') {
                 throw invalidCancel('fulfillmentId', 'A fulfillment id is required.');
             }
-            const data = await transport.graphql({ api: 'admin', query: FULFILLMENT_CANCEL_PREVIEW_QUERY, variables: { fulfillmentId } }, options);
+            const data = await storeCreditAware(transport).graphql({ api: 'admin', query: FULFILLMENT_CANCEL_PREVIEW_QUERY, variables: { fulfillmentId } }, options);
             const preview = data.fulfillmentCancelPreview;
             return {
                 fulfillmentId: preview.fulfillmentId,
@@ -459,7 +468,7 @@ export function createFulfillmentsModule(transport) {
         async cancel(fulfillmentId, input = {}, options) {
             assertCancelRequest(fulfillmentId, input);
             const overpayment = input.overpayment ?? [];
-            const data = await transport.graphql({
+            const data = await storeCreditAware(transport).graphql({
                 api: 'admin',
                 query: CANCEL_FULFILLMENT_MUTATION,
                 // A variable, not a header: the Admin API takes the key as an argument.

package/dist/fulfillments/payment-policy.d.ts

@@ -0,0 +1,64 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** The most payment method codes `exemptMethodCodes` may name. */
+export declare const FULFILLMENT_PAYMENT_POLICY_EXEMPT_METHODS_MAX = 50;
+/** The longest payment method code the list accepts (`PaymentMethod.code` is a varchar(255)). */
+export declare const FULFILLMENT_PAYMENT_POLICY_METHOD_CODE_MAX_LENGTH = 255;
+/**
+ * The store's fulfilment payment policy (`Channel.customFields.fulfillmentPaymentPolicy`):
+ * whether goods are handed over before an order is paid in full. Every field present: this is
+ * what the engine APPLIES, absent and malformed fields read as their defaults (OFF).
+ */
+export interface FulfillmentPaymentPolicy {
+    /**
+     * On: a fulfilment is created, extended or shipped only once the money COLLECTED for the
+     * order (settled, or held by a payment provider) covers what it bills, unless the order is
+     * exempt or an override was recorded (`fulfillments.allowUncovered`). Otherwise refused
+     * `ORDER_NOT_COVERED`.
+     */
+    requireFullPayment: boolean;
+    /**
+     * Payment method CODES whose orders are handed over unpaid as a matter of course (cash on
+     * delivery, a bank transfer the store ships against), judged on the order's latest live
+     * payment. Read as the engine compares them: trimmed, lower-cased, once each.
+     */
+    exemptMethodCodes: string[];
+}
+/** The policy of a store that never set one, and of a column that cannot be read: off. */
+export declare const DEFAULT_FULFILLMENT_PAYMENT_POLICY: Readonly<FulfillmentPaymentPolicy>;
+/**
+ * The ACTIVE store's fulfilment payment policy (`admin.fulfillments.paymentPolicy`), stored as a
+ * Channel custom field and written through core `updateChannel`.
+ *
+ * Reading needs an authenticated administrator on the store; writing needs `UpdateChannel`.
+ */
+export interface FulfillmentPaymentPolicyModule {
+    /**
+     * The policy the engine applies, read as tolerantly as the engine reads it
+     * (`resolveFulfillmentPaymentPolicy`): a store that never set one, a malformed column and a
+     * field of the wrong type all answer OFF ({@link DEFAULT_FULFILLMENT_PAYMENT_POLICY}); the
+     * exempt codes are the non-blank ones, trimmed, lower-cased and once each.
+     */
+    get(options?: Call): Promise<FulfillmentPaymentPolicy>;
+    /**
+     * Replace the whole policy, and answer it as the engine now applies it.
+     *
+     * Both fields are required: read it with {@link get}, change what you mean to, and send it
+     * back. Only the schema's fields are stored, the codes trimmed.
+     *
+     * Refused before any request with `FULFILLMENT_PAYMENT_POLICY_INVALID` ({@link ValidationError},
+     * one `details[]` entry per failing field): a non-boolean switch, an exempt list that is not a
+     * list, holds a blank or over-long code, names one code twice in any case, or more than 50.
+     * The engine's own write validator refuses the same values (a `ValidationError` too, carrying
+     * its sentence), so a value that slips past this check is still never stored.
+     *
+     * Absent and "set to the defaults" mean the same thing to the engine, and a store's column is
+     * never backfilled: write the policy when a merchant changed it.
+     */
+    set(policy: FulfillmentPaymentPolicy, options?: Call): Promise<FulfillmentPaymentPolicy>;
+}
+export declare const FULFILLMENT_PAYMENT_POLICY_QUERY = "\n  query FulfillmentPaymentPolicy {\n    activeChannel { \n  id\n  customFields {\n    fulfillmentPaymentPolicy\n  }\n }\n  }\n";
+export declare const SET_FULFILLMENT_PAYMENT_POLICY_MUTATION = "\n  mutation SetFulfillmentPaymentPolicy($input: UpdateChannelInput!) {\n    updateChannel(input: $input) {\n      ... on Channel { \n  id\n  customFields {\n    fulfillmentPaymentPolicy\n  }\n }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
+/** A payment method code as the engine compares it (`normalizeMethodCode`). */
+export declare function normalizeFulfillmentPolicyMethodCode(code: string): string;
+export declare function createFulfillmentPaymentPolicyModule(transport: Transport): FulfillmentPaymentPolicyModule;