@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/dist/documents/emails.d.ts

@@ -0,0 +1,150 @@
+/**
+ * `admin.documents.emails` — the store's email delivery log, its counts, a retry of one delivery,
+ * and a test send of a template (headless spec §9.2 `documents`, "email sends"; W10-103).
+ *
+ * Every call needs `UpdateSettings` on the active store. A delivery's recipients, subject, error
+ * and metadata are customer data: below `customerData: full` (an app installation) they read
+ * `''`/`null` and the row carries `redacted: true`.
+ */
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * Where a delivery stands. `skipped`: the store's `sender: none` for the event (the platform sent
+ * nothing, on purpose). `suppressed_sandbox`: a sandbox store withheld the customer's copy. The
+ * engine may add others; a reader keeps a default branch.
+ */
+export type EmailDeliveryStatus = 'sent' | 'failed' | 'blocked' | 'pending' | 'skipped' | 'suppressed_sandbox' | (string & {});
+/** One email the store sent, or tried to. */
+export interface EmailDelivery {
+    id: string;
+    /** The template it was rendered from (`order_confirmation`, …). */
+    templateType: string;
+    /** The notification event that sent it (`order_placed`, …). */
+    notificationEvent: string;
+    /** Comma-separated addresses. */
+    recipientTo: string;
+    recipientCc: string | null;
+    recipientBcc: string | null;
+    subject: string;
+    gatewayId: string | null;
+    status: EmailDeliveryStatus;
+    /** 1 for the first send; each retry adds one. */
+    attempt: number;
+    /** The mail provider's message id, when it took the email. */
+    messageId: string | null;
+    /** Why the last attempt failed, as the provider or the mail server said it. */
+    error: string | null;
+    durationMs: number | null;
+    /** The ids the email was rendered from (`orderId`, `invoiceId`, …) and other send facts. */
+    metadata: Record<string, unknown> | null;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+    /**
+     * Set when the caller's customer-data level withheld part of the row (an app installation
+     * below `customerData: full`): the recipients, subject, error and metadata then read `''` or
+     * `null`, meaning "not granted", never "none on record".
+     */
+    redacted?: true;
+}
+/**
+ * Which deliveries a list or a count covers. The two instants need an explicit offset (`Z` or
+ * `±HH:mm`) and are refused before the request leaves without one (`INVALID_DATETIME`): a store's
+ * day is not the caller's. To cover the store's days, send the first instant of the first day as
+ * `createdFrom` and the first instant of the day AFTER the last one as `createdBefore`
+ * ({@link EmailDeliveriesModule.list}).
+ */
+export interface EmailDeliveryFilter {
+    status?: EmailDeliveryStatus;
+    templateType?: string;
+    /** Created at or after this instant. */
+    createdFrom?: string;
+    /** Created strictly before this instant. */
+    createdBefore?: string;
+}
+/** How many of the store's deliveries are in each state, over a filter. */
+export interface EmailDeliveryStats {
+    sent: number;
+    failed: number;
+    /** Never sent: every recipient is on the mail provider's suppression list. */
+    blocked: number;
+    pending: number;
+}
+export interface SendTestEmailInput {
+    /** A template type the platform renders (`admin.tenant.emailTemplates.catalog()`). */
+    templateType: string;
+    /** One email address. */
+    recipientEmail: string;
+}
+export interface EmailDeliveriesModule {
+    /**
+     * The store's deliveries, newest first, one page at a time (`limit` 1–100, 50 when omitted).
+     *
+     * **Store days.** The page that shows "from 24 to 25 October" in Europe/Amsterdam sends
+     * `createdFrom: '2026-10-24T00:00:00+02:00'` and `createdBefore: '2026-10-26T00:00:00+01:00'`:
+     * 25 October 2026 is 25 hours long there (the clocks go back), and the end is exclusive, so
+     * the whole last day is in and nothing of the next.
+     *
+     * **Coded refusals:** `INVALID_DATETIME` → `ValidationError` (400), an instant without an
+     * offset, before the request leaves; `EMAIL_DELIVERY_FILTER_INVALID` → `ValidationError`
+     * (400), a `limit` outside 1–100 or a range that ends before it starts.
+     *
+     * Rows carry `redacted: true` below `customerData: full` (see {@link EmailDelivery}).
+     *
+     * @effect read
+     * @permission UpdateSettings
+     */
+    list(filter?: EmailDeliveryFilter, options?: ListOptions): Promise<Page<EmailDelivery>>;
+    /**
+     * How many deliveries are `sent`, `failed`, `blocked` and `pending`, over the same filter as
+     * {@link list} without its `status` (a count by status). Without a filter: the store's whole
+     * log. On an engine from before this release (no filter argument) a filtered count is made
+     * from the list's totals, one read per status.
+     *
+     * @effect read
+     * @permission UpdateSettings
+     */
+    stats(filter?: Omit<EmailDeliveryFilter, 'status'>, options?: Call): Promise<EmailDeliveryStats>;
+    /**
+     * Send a `failed` or `blocked` delivery again, now, and answer the row with the new outcome:
+     * `status` is `sent`, `failed` again (with its `error`), `blocked` (the address is still on the
+     * provider's suppression list) or `suppressed_sandbox`. It resolves either way; read `status`.
+     * Synchronous: the email has been handed to the provider (or not) when it resolves.
+     *
+     * This sends the email to the CUSTOMER (or whoever it was addressed to) once more. Never call
+     * it in a loop or on a timer without a person deciding to.
+     *
+     * **Coded refusals** (nothing is sent): `EMAIL_DELIVERY_NOT_FOUND` → `NotFoundError` (404), no
+     * such delivery in this store; `EMAIL_DELIVERY_NOT_RETRYABLE` → `BusinessRuleError` (422), the
+     * delivery is not `failed` or `blocked`, it is a gift card's email (its code is not kept), or
+     * another retry of it started first.
+     *
+     * @effect irreversible
+     * @permission UpdateSettings
+     */
+    retry(id: string, options?: Call): Promise<EmailDelivery>;
+}
+export interface DocumentEmailsModule {
+    deliveries: EmailDeliveriesModule;
+    /**
+     * Render `templateType` with sample data and send it, now, through the store's own email
+     * gateway, to `recipientEmail`. It is real mail. The send writes no delivery row.
+     *
+     * **Coded refusals:** `INVALID_TEST_EMAIL_RECIPIENT` and `INVALID_TEST_EMAIL_TEMPLATE` →
+     * `ValidationError` (400), before anything is sent; `TEST_EMAIL_SEND_FAILED` →
+     * `BusinessRuleError` (422), the gateway did not take it (the message names the SMTP step or
+     * the provider's code, never the server's own words).
+     *
+     * @effect irreversible
+     * @permission UpdateSettings
+     */
+    sendTest(input: SendTestEmailInput, options?: Call): Promise<void>;
+}
+export declare const EMAIL_DELIVERIES_QUERY = "\n  query AdminEmailDeliveries($options: EmailDeliveryLogListOptions) {\n    emailDeliveryLogs(options: $options) {\n      items { \n  id\n  templateType\n  notificationEvent\n  recipientTo\n  recipientCc\n  recipientBcc\n  subject\n  gatewayId\n  status\n  attempt\n  messageId\n  error\n  durationMs\n  metadata\n  createdAt\n }\n      totalItems\n    }\n  }\n";
+export declare const EMAIL_DELIVERY_STATS_QUERY = "\n  query AdminEmailDeliveryStats($options: EmailDeliveryStatsOptions) {\n    emailDeliveryStats(options: $options) {\n      sent\n      failed\n      blocked\n      pending\n    }\n  }\n";
+/** The store's whole log, without the filter argument an older engine does not know. */
+export declare const EMAIL_DELIVERY_STATS_ALL_QUERY = "\n  query AdminEmailDeliveryStatsAll {\n    emailDeliveryStats {\n      sent\n      failed\n      blocked\n      pending\n    }\n  }\n";
+/** How many deliveries match: the older engine's way to count over a filter. */
+export declare const EMAIL_DELIVERY_COUNT_QUERY = "\n  query AdminEmailDeliveryCount($options: EmailDeliveryLogListOptions) {\n    emailDeliveryLogs(options: $options) {\n      totalItems\n    }\n  }\n";
+export declare const RETRY_EMAIL_DELIVERY_MUTATION = "\n  mutation AdminRetryEmailDelivery($id: ID!) {\n    retryEmailDelivery(id: $id) { \n  id\n  templateType\n  notificationEvent\n  recipientTo\n  recipientCc\n  recipientBcc\n  subject\n  gatewayId\n  status\n  attempt\n  messageId\n  error\n  durationMs\n  metadata\n  createdAt\n }\n  }\n";
+export declare const SEND_TEST_EMAIL_MUTATION = "\n  mutation AdminSendTestEmail($templateType: String!, $recipientEmail: String!) {\n    sendTestEmail(templateType: $templateType, recipientEmail: $recipientEmail)\n  }\n";
+export declare function createDocumentEmailsModule(transport: Transport): DocumentEmailsModule;

package/dist/documents/emails.js

@@ -0,0 +1,220 @@
+/**
+ * `admin.documents.emails` — the store's email delivery log, its counts, a retry of one delivery,
+ * and a test send of a template (headless spec §9.2 `documents`, "email sends"; W10-103).
+ *
+ * Every call needs `UpdateSettings` on the active store. A delivery's recipients, subject, error
+ * and metadata are customer data: below `customerData: full` (an app installation) they read
+ * `''`/`null` and the row carries `redacted: true`.
+ */
+import { pageFromVendureList, readOffsetCursor, ValidationError, } from '@sixtyninecommerce/core';
+import { assertInstant } from '../catalog/types.js';
+import { customerDataField } from '../customers/wire.js';
+const DELIVERY_FIELDS = /* GraphQL */ `
+  id
+  templateType
+  notificationEvent
+  recipientTo
+  recipientCc
+  recipientBcc
+  subject
+  gatewayId
+  status
+  attempt
+  messageId
+  error
+  durationMs
+  metadata
+  createdAt
+`;
+export const EMAIL_DELIVERIES_QUERY = /* GraphQL */ `
+  query AdminEmailDeliveries($options: EmailDeliveryLogListOptions) {
+    emailDeliveryLogs(options: $options) {
+      items { ${DELIVERY_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const EMAIL_DELIVERY_STATS_QUERY = /* GraphQL */ `
+  query AdminEmailDeliveryStats($options: EmailDeliveryStatsOptions) {
+    emailDeliveryStats(options: $options) {
+      sent
+      failed
+      blocked
+      pending
+    }
+  }
+`;
+/** The store's whole log, without the filter argument an older engine does not know. */
+export const EMAIL_DELIVERY_STATS_ALL_QUERY = /* GraphQL */ `
+  query AdminEmailDeliveryStatsAll {
+    emailDeliveryStats {
+      sent
+      failed
+      blocked
+      pending
+    }
+  }
+`;
+/** How many deliveries match: the older engine's way to count over a filter. */
+export const EMAIL_DELIVERY_COUNT_QUERY = /* GraphQL */ `
+  query AdminEmailDeliveryCount($options: EmailDeliveryLogListOptions) {
+    emailDeliveryLogs(options: $options) {
+      totalItems
+    }
+  }
+`;
+export const RETRY_EMAIL_DELIVERY_MUTATION = /* GraphQL */ `
+  mutation AdminRetryEmailDelivery($id: ID!) {
+    retryEmailDelivery(id: $id) { ${DELIVERY_FIELDS} }
+  }
+`;
+export const SEND_TEST_EMAIL_MUTATION = /* GraphQL */ `
+  mutation AdminSendTestEmail($templateType: String!, $recipientEmail: String!) {
+    sendTestEmail(templateType: $templateType, recipientEmail: $recipientEmail)
+  }
+`;
+/** The engine's default page; the SDK states it so the cursor arithmetic knows the size. */
+const DELIVERIES_PAGE_SIZE = 50;
+function toDelivery(row) {
+    return {
+        id: String(row.id),
+        templateType: row.templateType,
+        notificationEvent: row.notificationEvent,
+        recipientTo: row.recipientTo,
+        recipientCc: row.recipientCc ?? null,
+        recipientBcc: row.recipientBcc ?? null,
+        subject: row.subject,
+        gatewayId: row.gatewayId ?? null,
+        status: row.status,
+        attempt: row.attempt,
+        messageId: row.messageId ?? null,
+        error: row.error ?? null,
+        durationMs: row.durationMs ?? null,
+        metadata: row.metadata ?? null,
+        createdAt: row.createdAt,
+    };
+}
+/** The engine's filter input: only the keys the caller set, so an older engine still answers. */
+function wireFilter(filter) {
+    if (filter === undefined)
+        return {};
+    if (filter === null || typeof filter !== 'object' || Array.isArray(filter)) {
+        throw new ValidationError({
+            code: 'EMAIL_DELIVERY_FILTER_INVALID',
+            message: 'The delivery filter must be an object.',
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    assertInstant('createdFrom', filter.createdFrom);
+    assertInstant('createdBefore', filter.createdBefore);
+    return {
+        ...(filter.status ? { status: filter.status } : {}),
+        ...(filter.templateType ? { templateType: filter.templateType } : {}),
+        ...(filter.createdFrom ? { dateFrom: filter.createdFrom } : {}),
+        ...(filter.createdBefore ? { dateBefore: filter.createdBefore } : {}),
+    };
+}
+/**
+ * The engine refused the document over a field or argument it does not know: an engine from
+ * before this release (no `dateBefore`, no `emailDeliveryStats(options:)`). The dashboard can be
+ * live before vendure-server (`.claude/rules/backend.md`, additive rule), so the module falls
+ * back to the older spelling instead of failing. Matched on the names this module added, so a
+ * real refusal is never retried.
+ */
+function isOlderEngineRejection(error) {
+    if (!(error instanceof ValidationError) || error.service !== 'vendure')
+        return false;
+    // Apollo answers a document that fails validation (an unknown type or argument: the stats
+    // filter) with HTTP 400, which the transport reports as BAD_REQUEST without the engine's
+    // words; an unknown input field (dateBefore) is a variable coercion error at HTTP 200 and
+    // keeps them. Only ever asked about the documents this module added the names to.
+    return (error.code === 'BAD_REQUEST' ||
+        error.code === 'GRAPHQL_VALIDATION_FAILED' ||
+        /dateBefore|EmailDeliveryStatsOptions|Unknown argument "options"/.test(error.message));
+}
+/** The old inclusive spelling of an exclusive end: one millisecond before it. */
+function legacyFilter(filter) {
+    const { dateBefore, ...rest } = filter;
+    if (typeof dateBefore !== 'string')
+        return rest;
+    return { ...rest, dateTo: new Date(Date.parse(dateBefore) - 1).toISOString() };
+}
+const COUNTED_STATUSES = ['sent', 'failed', 'blocked', 'pending'];
+export function createDocumentEmailsModule(transport) {
+    /** Latched once the engine proved it predates `dateBefore` (one refused request per client). */
+    let olderEngine = false;
+    const listPage = async (skip, take, filter, options) => {
+        const read = (wire) => customerDataField(transport, EMAIL_DELIVERIES_QUERY, 'emailDeliveryLogs', { options: { ...wire, take, skip } }, options);
+        let answer;
+        if (olderEngine || !('dateBefore' in filter)) {
+            answer = await read(olderEngine ? legacyFilter(filter) : filter);
+        }
+        else {
+            try {
+                answer = await read(filter);
+            }
+            catch (error) {
+                if (!isOlderEngineRejection(error))
+                    throw error;
+                olderEngine = true;
+                answer = await read(legacyFilter(filter));
+            }
+        }
+        const { value, mark } = answer;
+        const items = value.items.map((row) => mark(toDelivery(row)));
+        // Each following page re-sends the same filter and per-call options.
+        return pageFromVendureList({ items, totalItems: value.totalItems }, skip, take, (cursor) => listPage(readOffsetCursor(cursor), take, filter, options));
+    };
+    return {
+        deliveries: {
+            async list(filter, options) {
+                const wire = wireFilter(filter);
+                const take = options?.limit ?? DELIVERIES_PAGE_SIZE;
+                const skip = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+                return listPage(skip, take, wire, options);
+            },
+            async stats(filter, options) {
+                const { status: _status, ...counted } = wireFilter(filter);
+                if (Object.keys(counted).length === 0) {
+                    const data = await transport.graphql({ api: 'admin', query: EMAIL_DELIVERY_STATS_ALL_QUERY }, options);
+                    return data.emailDeliveryStats;
+                }
+                if (!olderEngine) {
+                    try {
+                        const data = await transport.graphql({ api: 'admin', query: EMAIL_DELIVERY_STATS_QUERY, variables: { options: counted } }, options);
+                        return data.emailDeliveryStats;
+                    }
+                    catch (error) {
+                        if (!isOlderEngineRejection(error))
+                            throw error;
+                        olderEngine = true;
+                    }
+                }
+                // An older engine counts only the whole log: count each status over the filter through
+                // the list's totals instead (one row read per status).
+                const totals = await Promise.all(COUNTED_STATUSES.map(async (status) => {
+                    const data = await transport.graphql({
+                        api: 'admin',
+                        query: EMAIL_DELIVERY_COUNT_QUERY,
+                        variables: { options: { ...legacyFilter(counted), status, take: 1, skip: 0 } },
+                    }, options);
+                    return data.emailDeliveryLogs.totalItems;
+                }));
+                const [sent = 0, failed = 0, blocked = 0, pending = 0] = totals;
+                return { sent, failed, blocked, pending };
+            },
+            async retry(id, options) {
+                const { value, mark } = await customerDataField(transport, RETRY_EMAIL_DELIVERY_MUTATION, 'retryEmailDelivery', { id }, options);
+                return mark(toDelivery(value));
+            },
+        },
+        async sendTest(input, options) {
+            await transport.graphql({
+                api: 'admin',
+                query: SEND_TEST_EMAIL_MUTATION,
+                variables: { templateType: input.templateType, recipientEmail: input.recipientEmail },
+            }, options);
+        },
+    };
+}

package/dist/documents/index.d.ts

@@ -1,6 +1,7 @@
 import { type Page, type Transport } from '@sixtyninecommerce/core';
 import type { Call, ListOptions } from '../types.js';
 import { type ArDocumentsModule } from './ar.js';
+import { type DocumentEmailsModule } from './emails.js';
 import { decodePdf } from './pdf.js';
 export { decodePdf };
 /**
@@ -402,6 +403,16 @@ export interface InvoiceCorrectionInput {
     refundPaymentId?: string;
     /** RETAIL only: move the credited amount to the customer's account instead (`accountCredit`). */
     creditToAccount?: boolean;
+    /**
+     * `commitCorrection` with `creditToAccount` in a store whose book is store credit (the plan's
+     * `accountCredit.book` `STORE_CREDIT`): whether the 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 move records it on its ledger entries (`StoredValueEntry.customerAgreed`); never a
+     * condition, nothing is refused for it. The plan ignores it and its `planHash` never sees it, so
+     * leave it out of `planCorrection` (an engine before the field, incentives sprint 8 PR 6a,
+     * refuses any call that gives it) and add it to the commit's input.
+     */
+    customerAgreed?: boolean;
     /**
      * Details wrong only: the order's payment term in days. The corrected invoice is reissued
      * under it and the order keeps it (its `paymentTermsDays`; its payment condition is cleared).
@@ -1591,6 +1602,8 @@ export interface DocumentsModule {
     extensions: DocumentExtensionsModule;
     /** The accounts-receivable ledger's documents: AR invoices, statements and credit notes. */
     ar: ArDocumentsModule;
+    /** The store's email delivery log (counts, a retry) and a template's test send. */
+    emails: DocumentEmailsModule;
 }
 export declare const GENERATE_INVOICE_MUTATION = "\n  mutation GenerateInvoice(\n    $orderId: ID!\n    $invoicedOn: String!\n    $languageCode: String\n    $note: String\n    $extensions: [DocumentExtensionInput!]\n  ) {\n    generateInvoice(\n      orderId: $orderId\n      invoicedOn: $invoicedOn\n      languageCode: $languageCode\n      note: $note\n      extensions: $extensions\n    ) { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  reversedByCreditNoteId\n  supersededByInvoiceId\n  reissueOfInvoiceId\n  kind\n  supplementsInvoiceId\n  lines { \n  description\n  sku\n  orderLineId\n  quantity\n  unitPriceNet\n  unitPriceWithTax\n  taxRate\n  lineTotalNet\n  lineTotalWithTax\n  unitPriceBasis\n }\n  numberingProvider\n  amountPaid\n  amountDue\n  createdAt\n }\n  }\n";
 export declare const GENERATE_PACKING_SLIP_MUTATION = "\n  mutation GeneratePackingSlip(\n    $fulfillmentId: ID!\n    $languageCode: String\n    $extensions: [DocumentExtensionInput!]\n  ) {\n    generatePackingSlip(\n      fulfillmentId: $fulfillmentId\n      languageCode: $languageCode\n      extensions: $extensions\n    ) { \n  id\n  packingSlipNumber\n  fulfillmentId\n  languageCode\n  storageKey\n  createdAt\n }\n  }\n";

package/dist/documents/index.js

@@ -1,6 +1,7 @@
 import { createPage, idempotencyKey as mintIdempotencyKey, pageFromVendureList, readOffsetCursor, ValidationError, } from '@sixtyninecommerce/core';
 import { storeCreditAware } from '../payments/store-credit-fields.js';
 import { createArDocumentsModule } from './ar.js';
+import { createDocumentEmailsModule } from './emails.js';
 import { decodePdf } from './pdf.js';
 // Also what `documents.ar.pdf` decodes with (headless W10-30).
 export { decodePdf };
@@ -903,6 +904,7 @@ export function createDocumentsModule(transport) {
             },
         },
         ar: createArDocumentsModule(transport),
+        emails: createDocumentEmailsModule(transport),
         extensions: {
             async list(options) {
                 const data = await transport.graphql({ api: 'admin', query: DOCUMENT_EXTENSIONS_QUERY }, options);

package/dist/fulfillments/index.d.ts

@@ -1,4 +1,4 @@
-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';
@@ -182,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 {
@@ -265,6 +274,35 @@ 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
@@ -412,6 +450,66 @@ export interface FulfillmentsModule extends FulfillmentCreateMethods {
     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
@@ -431,6 +529,12 @@ export interface FulfillmentsModule extends FulfillmentCreateMethods {
 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        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. */
@@ -468,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;