@sixtyninecommerce/admin 0.10.0 → 0.12.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 PlatformError, 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:
@@ -180,6 +182,15 @@ export interface FulfillmentCancelPreview {
 export interface FulfillmentCancelChoice {
     orderId: string;
     choice: OrderOverpaymentChoice;
+    /**
+     * With `ACCOUNT_CREDIT` in a store whose book is store credit (`cancelPreview`'s
+     * `accountCredit.book` `STORE_CREDIT`): whether THIS order's customer expressly agreed to store
+     * credit instead of a refund to their payment (EU consumer law, CRD art. 13(1)), as staff
+     * recorded it. The settlement's move records it on its ledger entries
+     * (`StoredValueEntry.customerAgreed`); never a condition, nothing is refused for it. Sent only
+     * when given; an engine before the field (incentives sprint 8 PR 6a) refuses a call that gives it.
+     */
+    customerAgreed?: boolean;
 }
 /** What `cancel` sends besides the fulfillment. */
 export interface CancelFulfillmentInput {
@@ -196,6 +207,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 {
@@ -258,12 +274,44 @@ export interface OrderFulfillmentCoverage {
 }
 /** The longest override reason the engine stores. */
 export declare const FULFILLMENT_COVERAGE_REASON_MAX_LENGTH = 500;
+/** A fulfillment as `transition` leaves it. */
+export interface FulfillmentStateChange {
+    id: string;
+    /** The state it is in now (`Shipped`, `Delivered`, …). */
+    state: string;
+    /** The states it may move to next, as the store's fulfillment process allows. */
+    nextStates: string[];
+}
+/**
+ * The facts a refused `transition` carries on `PlatformError.extensions`, beside its code:
+ * the move that was asked for and the refusing step's own words.
+ */
+export interface FulfillmentTransitionRefusalFacts {
+    /** Core's code for every refused move: `FULFILLMENT_STATE_TRANSITION_ERROR`. */
+    errorCode: string;
+    fromState: string;
+    toState: string;
+    /** The refusing step's text, `[CODE]` prefix included when it had one. */
+    transitionError: string;
+}
+/**
+ * What re-sending a fulfillment's label to the store's 3PL came to (`resendLabelHandoff`):
+ * - `QUEUED`: the email with the label is queued for the 3PL recipient;
+ * - `NOT_READY`: the fulfillment has no ready MyParcel label yet, so nothing was sent;
+ * - `DISABLED`: the store has the label hand-off notification switched off;
+ * - `NO_RECIPIENT`: it is on, but names no recipient;
+ * - `UNAVAILABLE`: the platform's email delivery is not installed.
+ */
+export type LabelHandoffOutcome = 'QUEUED' | 'DISABLED' | 'NO_RECIPIENT' | 'NOT_READY' | 'UNAVAILABLE';
 /**
  * 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 +329,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 +355,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 +391,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 +413,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 +450,91 @@ export interface FulfillmentsModule {
     allowUncovered(orderId: string, reason: string, options?: Call & {
         idempotencyKey?: string;
     }): Promise<FulfillmentCoverageOverride>;
+    /**
+     * Move a fulfillment to one of its `nextStates` (the order page's "Mark as Shipped" and "Mark as
+     * Delivered"). Needs `UpdateOrder`. The move runs the store's own fulfillment process, so the
+     * order's state follows and whatever the store does on a shipped or delivered fulfillment (its
+     * events, its notifications: the customer gets the shipped e-mail) happens; the process has no
+     * way back to an earlier state. Shipping an order's last open lines moves the ORDER to
+     * `Shipped`, which on a store that pushes orders to its ERP when they ship (Exact Online's
+     * "fulfilled" auto-push) sends the order there, where it cannot be taken back.
+     *
+     * A move into `Cancelled` is a cancel: it ends the fulfillment for good and has its carrier let
+     * go of the shipment, and the delivery charge it added comes off what each of its orders bills.
+     * It is refused, before the carrier is told, while the customer has PAID such a charge
+     * (`FULFILLMENT_CANCEL_OVERPAYMENT_CHOICE_REQUIRED`): {@link FulfillmentsModule.cancel} takes the
+     * choice of how that money goes back. An unpaid charge simply leaves the bill.
+     *
+     * Tagged `money`, its strongest effect: a cancel changes what a placed order bills.
+     *
+     * Refused, with nothing moved:
+     * - a step of the store's process that refuses the move answers ITS OWN code, which the engine
+     *   prefixes to its text as `[CODE]`, with the text after it as the message, classed as the
+     *   warehouse API classes the same code: `ORDER_NOT_COVERED` (the store requires full payment
+     *   and an order is not paid in full: `coverage` reads what it owes, `allowUncovered` records
+     *   an override), `ORDER_ON_HOLD` (release the order's fulfilment hold first),
+     *   `BOOKING_REQUIRED`, `PARCELS_REQUIRED`, `CONSOLIDATION_ADDRESS_DIVERGED`, …;
+     * - any other refusal of the process, an edge it does not have included, is
+     *   `FULFILLMENT_STATE_TRANSITION_ERROR` (`BusinessRuleError`, 422) with the refusing step's
+     *   text as the message;
+     * - both carry {@link FulfillmentTransitionRefusalFacts} on `extensions`;
+     * - another store's or a missing fulfillment is `ENTITY_NOT_FOUND` (`NotFoundError`); a
+     *   credential restricted to stock locations (an API token or app installation with
+     *   `locationIds`) moves only a fulfillment that ships from one of them
+     *   (`LOCATION_OUT_OF_SCOPE`, 422);
+     * - a blank id or state is refused before any request (`FULFILLMENT_TRANSITION_INVALID`,
+     *   `ValidationError`).
+     *
+     * Takes no idempotency key: repeating a move that went through asks for an edge the process no
+     * longer has, and is refused as above, never moved twice.
+     *
+     * @effect money
+     * @permission UpdateOrder
+     */
+    transition(fulfillmentId: string, state: string, options?: Call): Promise<FulfillmentStateChange>;
+    /**
+     * E-mail the fulfillment's ready MyParcel label again to the store's 3PL recipient (the
+     * `fulfillment_label_handoff` notification), whatever the store's automatic hand-off setting.
+     * Answers what came of it ({@link LabelHandoffOutcome}): only `QUEUED` sent anything; the
+     * others say why nothing was sent. Every outcome leaves an audit row. Needs `UpdateOrder`.
+     *
+     * Takes no idempotency key: a repeat sends the e-mail again.
+     *
+     * Refused: another store's or a missing fulfillment is `ENTITY_NOT_FOUND` (`NotFoundError`); a
+     * store without the MyParcel plugin `PLUGIN_ACCESS_DENIED` (`PermissionDeniedError`, 403) for
+     * an ordinary caller; a credential restricted to other stock locations `LOCATION_OUT_OF_SCOPE`
+     * (422). A blank id is refused before any request (`MYPARCEL_LABEL_INPUT_INVALID`,
+     * `ValidationError`).
+     *
+     * @effect irreversible
+     * @permission UpdateOrder
+     */
+    resendLabelHandoff(fulfillmentId: string, options?: Call): Promise<LabelHandoffOutcome>;
+    /**
+     * 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";
+/**
+ * The refusal member is selected for its facts: `message` is core's per-code template ("Cannot
+ * transition Fulfillment from X to Y"), and the refusing step's reason is `transitionError` alone.
+ */
+export declare const TRANSITION_FULFILLMENT_MUTATION = "\n  mutation TransitionFulfillment($id: ID!, $state: String!) {\n    transitionFulfillmentToState(id: $id, state: $state) {\n      __typename\n      ... on Fulfillment {\n        id\n        state\n        nextStates\n      }\n      ... on FulfillmentStateTransitionError {\n        errorCode\n        message\n        fromState\n        toState\n        transitionError\n      }\n    }\n  }\n";
+export declare const RESEND_FULFILLMENT_LABEL_HANDOFF_MUTATION = "\n  mutation ResendFulfillmentLabelHandoff($fulfillmentId: ID!) {\n    resendFulfillmentLabelHandoff(fulfillmentId: $fulfillmentId)\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. */
@@ -434,4 +572,18 @@ export declare const MYPARCEL_LABEL_TIMEOUT_MS = 55000;
 export declare function toUnretractedShipments(raw: readonly MyparcelUnretractedShipment[] | null | undefined): MyparcelUnretractedShipment[];
 /** The bytes of a base64 label document (`atob`: no Node `Buffer`, it ships to browsers). */
 export declare function decodeBase64(base64: string): Uint8Array;
+interface RawTransitionRefusal {
+    errorCode: string;
+    message: string;
+    fromState?: string | null;
+    toState?: string | null;
+    transitionError?: string | null;
+}
+/**
+ * A refused move as the coded error it is. Core carries a step's refusal only as text, so the
+ * step's own code is read off its `[CODE]` prefix and classed through the GraphQL dialect, as the
+ * warehouse API's refusals of the same codes are (`warehouseRefusalError`): one code, one class,
+ * whichever door answered it.
+ */
+export declare function fulfillmentTransitionRefusal(result: RawTransitionRefusal): PlatformError;
 export declare function createFulfillmentsModule(transport: Transport): FulfillmentsModule;