@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/feeds/types.js

@@ -0,0 +1,135 @@
+/**
+ * The product-feed contract: the rule AST a merchant builds, the configuration
+ * it lives in, and everything the generator, the review queues and the AI
+ * helpers report back.
+ *
+ * TWO CASING WORLDS meet here, and the difference is not cosmetic.
+ *
+ * 1. **The DTOs are camelCase**, like every other module: the wire is
+ *    snake_case (`language_code`, `refresh_interval_minutes` — the plugins
+ *    controllers project every row onto it) and the transport converts in both
+ *    directions.
+ * 2. **The rule AST inside `mappingJson`, `filtersJson`, `settingsJson`,
+ *    `rulesJson`, `entriesJson`, `perDestinationJson`, `payloadJson`,
+ *    `statsJson` and `defaultSource` is camelCase ON THE WIRE**, stored and
+ *    echoed byte-for-byte by the service. Those subtrees are never converted
+ *    (see `preserve.ts`), so what a consumer builds is what the compiler reads.
+ *
+ * SYNC NOTE — the AST block mirrors `services/plugins/src/feeds/rules/types.ts`
+ * (plus `destinations/types.ts` for the destination and delivery keys, and the
+ * entity modules for the string unions). It is a hand-kept mirror, not
+ * generated: every shape is copied verbatim, never "improved" in transit. When
+ * the engine's AST changes, change this file in the same branch, or the rules a
+ * consumer emits come back as a 400 `INVALID_RULES`.
+ */
+/** Every `FeedValueSource.kind`, in the order a builder should offer them. */
+export const FEED_VALUE_SOURCE_KINDS = [
+    'field',
+    'static',
+    'combine',
+    'lookup',
+    'extract',
+    'internal',
+];
+/** Discriminates a {@link FeedValueSource} without a switch at every call site. */
+export function isFeedValueSourceKind(source, kind) {
+    return source.kind === kind;
+}
+export const FEED_CONDITION_OPERATORS = [
+    'eq',
+    'neq',
+    'contains',
+    'not_contains',
+    'blank',
+    'not_blank',
+    'gt',
+    'lt',
+    'gte',
+    'lte',
+    'in',
+];
+/** Operators that take NO `value` — a builder must hide the operand input for these. */
+export const VALUELESS_FEED_CONDITION_OPERATORS = [
+    'blank',
+    'not_blank',
+];
+/** Narrows a node of a {@link FeedConditionGroup.conditions} array. */
+export function isFeedConditionGroup(node) {
+    return 'logic' in node && Array.isArray(node.conditions);
+}
+/** Every `FeedTransformSpec.kind`, in the order a builder should offer them. */
+export const FEED_TRANSFORM_KINDS = [
+    'strip_html',
+    'truncate',
+    'upper',
+    'lower',
+    'capitalize',
+    'price_format',
+];
+/** Enforced by a CHECK constraint on `feed_config.destination`. */
+export const FEED_DESTINATIONS = ['google', 'meta', 'tiktok', 'pinterest'];
+/** Server default page size; a list that omits `limit` gets this many rows. */
+export const DEFAULT_FEED_PAGE_LIMIT = 20;
+/** Hard ceiling — a larger `limit` is a 400, not a silent clamp. */
+export const MAX_FEED_PAGE_LIMIT = 100;
+/**
+ * Accepted range for `refreshIntervalMinutes` — mirrors the DTO's own bounds.
+ *
+ * The floor is the sweep's, not an arbitrary one: the scheduler ticks every 10
+ * minutes and refuses to rebuild a feed more often than every 30, so a shorter
+ * interval was accepted and then quietly held to 30 — a setting that read back
+ * as something the platform never did.
+ */
+export const MIN_REFRESH_INTERVAL_MINUTES = 30;
+export const MAX_REFRESH_INTERVAL_MINUTES = 10080;
+/** Column default: rebuild every 6 hours. */
+export const DEFAULT_REFRESH_INTERVAL_MINUTES = 360;
+export const FEED_RUN_STATUSES = ['running', 'completed', 'failed'];
+export const FEED_RUN_TRIGGERS = ['scheduled', 'source_changed', 'manual'];
+export const FEED_ITEM_ISSUE_SEVERITIES = ['error', 'warning'];
+/**
+ * The 429 a forced regeneration is refused with while the CHANNEL's throttle
+ * window is still open. Every forced pass walks the whole catalogue on a
+ * `concurrency: 1` worker shared by every tenant, so a tenant with twenty feeds
+ * cannot queue twenty walks ahead of everyone else's scheduled refresh.
+ *
+ * It is NOT the dedup case above: that one is a 202 and means "your job is
+ * already running". This one means "nothing was queued, come back later".
+ */
+export const FEED_REGENERATE_THROTTLED = 'FEED_REGENERATE_THROTTLED';
+/**
+ * Read a rejected {@link FeedsModule.regenerate} as a throttle refusal, or
+ * `null` for anything else (a 404, a network failure) — those stay generic.
+ *
+ * A guard rather than a class check: the transport maps the problem body onto a
+ * `RateLimitedError`, and a caller should key on the stable CODE rather than on
+ * an instance that a future mapping change could swap.
+ */
+export function readFeedRegenerateThrottle(error) {
+    if (error === null || typeof error !== 'object')
+        return null;
+    const candidate = error;
+    if (candidate.code !== FEED_REGENERATE_THROTTLED)
+        return null;
+    const seconds = candidate.retryAfterSeconds;
+    return typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0
+        ? { retryAfterSeconds: Math.ceil(seconds) }
+        : {};
+}
+/** Sample size when the caller does not ask for one. */
+export const DEFAULT_PREVIEW_SAMPLE_SIZE = 10;
+/** Hard ceiling on a preview sample; a bigger request is a 400. */
+export const MAX_PREVIEW_SAMPLE_SIZE = 50;
+/** Identifier rule shared by internal fields and lookup tables. */
+export const FEED_IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]*$/;
+/** Server cap on `entriesJson` length. */
+export const MAX_LOOKUP_ENTRIES = 5000;
+export const FEED_CATEGORY_MATCH_TYPES = ['collection', 'facet_value', 'default'];
+export const FEED_CATEGORY_MAPPING_SOURCES = ['manual', 'ai'];
+export const FEED_CATEGORY_MAPPING_STATUSES = ['approved', 'suggested', 'rejected'];
+/** Server cap on one bulk status call. */
+export const MAX_BULK_STATUS_IDS = 500;
+export const TAXONOMY_DEFAULT_LIMIT = 20;
+export const TAXONOMY_MAX_LIMIT = 50;
+/** The 409 both AI endpoints refuse with when no LLM is configured. */
+export const AI_UNAVAILABLE_CODE = 'AI_UNAVAILABLE';

package/dist/fulfillments/index.d.ts

@@ -0,0 +1,437 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { OrderOverpaymentChoice, OverpaymentOption } from '../orders/surcharges.js';
+import type { Call } from '../types.js';
+/**
+ * A fulfillment's parcels as the order records them: one MyParcel shipment per
+ * parcel, and the barcodes the carrier has issued so far.
+ */
+export interface OrderFulfillmentParcels {
+    fulfillmentId: string;
+    /**
+     * Every parcel's MyParcel shipment id, in parcel order, as the engine reads
+     * them: the list only while its first entry IS the single
+     * `myparcelShipmentId` (older writers rewrite that one alone, e.g. a
+     * recreate), else `[single]`, or `[]` when there is none.
+     */
+    shipmentIds: string[];
+    /** How many parcels were asked for. Null when the fulfillment never said. */
+    parcelCount: number | null;
+    /** The fulfillment's own tracking code, or null. */
+    trackingCode: string | null;
+    /**
+     * Every barcode to show, in parcel order. The carrier's list is used only
+     * while its first entry IS `trackingCode`: another writer (a code typed at
+     * ship, an external tracking sync) may have replaced `trackingCode` alone,
+     * and the list it went stale under names the wrong parcels. Otherwise this is
+     * `[trackingCode]`, or `[]` when there is none.
+     */
+    trackingCodes: string[];
+}
+/** A warehouse fulfillment's barcodes, per parcel. */
+export interface FulfillmentParcelTracking {
+    /** Every barcode the fulfillment is known to have, holes collapsed. */
+    trackingCodes: string[];
+    /**
+     * Parcel i+1's OWN barcode at index i, null until it has one. Null as a whole
+     * when the carrier bookkeeping could not be read.
+     */
+    parcelTrackingCodes: Array<string | null> | null;
+    /** Packed parcels, else the instructed count, else 1. */
+    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:
+ * pass the ones the entry you show was read with.
+ */
+export interface ChargedParcelCountInput {
+    stockLocationId: string;
+    orderId: string;
+    /** Office staff only: also an order the queue leaves out (on hold, …). */
+    includeIneligible?: boolean;
+    /** Default: preferred, allocated, unrouted. `no_stock` is honoured for office staff only. */
+    routing?: WarehouseDemandRouting[];
+}
+/** What `labelMyparcelParcels` asks for. */
+export interface LabelMyparcelParcelsInput {
+    /**
+     * Ask MyParcel again for EVERY parcel's label in this format (the operator's
+     * request), even beside a ready label. Omitted: only the parcels still
+     * missing their label or barcode are labelled, in the formats the
+     * fulfillment recorded.
+     */
+    format?: FulfillmentLabelFormat;
+}
+/** What `labelMyparcelParcels` did (`MyparcelLabelParcelsQueued`). */
+export interface MyparcelParcelsLabelRequest {
+    fulfillmentId: string;
+    /** How many parcels (MyParcel shipments) the fulfillment holds. */
+    parcels: number;
+    /** How many of them were still missing their label or their barcode. */
+    missing: number;
+    /**
+     * `false` when every parcel already had its label and barcode and no
+     * `format` was asked for: nothing was queued. `true` means ONE job was
+     * queued; the labels land when it has run, not when this call answers.
+     */
+    queued: boolean;
+}
+/**
+ * What the latest attempt to retract a MyParcel shipment found:
+ * - `KEPT`: MyParcel keeps it (only a concept can be deleted; a registered
+ *   label cannot be deleted through the API);
+ * - `UNREACHABLE`: not deleted yet and not known to be kept (MyParcel could
+ *   not be reached, or refused to delete a concept);
+ * - `DELETED` / `ALREADY_GONE`: a later attempt deleted it, or MyParcel no
+ *   longer holds it. Such an entry carries `resolvedAt` and stays listed.
+ */
+export type MyparcelRetractionVerdict = 'KEPT' | 'UNREACHABLE' | 'DELETED' | 'ALREADY_GONE';
+/**
+ * A MyParcel shipment a fulfillment or stock transfer let go of (a cancel, a
+ * recreate, a removed shipment) that MyParcel did not delete. The engine keeps
+ * the record for good and never adopts the shipment again: its label must not
+ * be handed to the carrier.
+ */
+export interface MyparcelUnretractedShipment {
+    shipmentId: number;
+    /** What MyParcel knows it by (`F-12`, `F-12#2`, a transfer's reference); null when unknown. */
+    reference: string | null;
+    verdict: MyparcelRetractionVerdict;
+    /** MyParcel's status as last read; null when it could not be read. */
+    status: number | null;
+    /** MyParcel's machine name for `status` (`pending_registered`, …). */
+    statusName: string | null;
+    /**
+     * MyParcel bills it (handed to the carrier, or a registered digital stamp).
+     * `null` is UNKNOWN, which is not `false`.
+     */
+    billable: boolean | null;
+    /** MyParcel accepted the request to hide it from its own lists. */
+    hidden: boolean;
+    /** The engine's operator-readable explanation. */
+    reason: string;
+    /** Why it was let go (`fulfillment_cancelled`, `recreated`, `transfer_removed`, …). */
+    cause: string;
+    /** ISO-8601 UTC. */
+    firstRecordedAt: string;
+    /** ISO-8601 UTC. */
+    lastCheckedAt: string;
+    /** ISO-8601 UTC when a later attempt found it deleted or gone; null while it is not. */
+    resolvedAt: string | null;
+}
+/** One fulfillment's record of the MyParcel shipments it could not retract. */
+export interface OrderFulfillmentUnretractedShipments {
+    fulfillmentId: string;
+    /** Every entry, resolved ones included, in the order the engine recorded them. */
+    shipments: MyparcelUnretractedShipment[];
+}
+/** One PDF holding every parcel's label, in parcel order. */
+export interface FulfillmentLabel {
+    format: FulfillmentLabelFormat;
+    contentType: string;
+    filename: string;
+    bytes: Uint8Array;
+}
+/** Where the goods of an app-fulfilled shipment are, as the app reports it. */
+export type AppFulfillmentReportState = 'Shipped' | 'Delivered';
+/** A fulfilment app's report on a fulfillment it accepted. At least one field. */
+export interface ReportAppFulfillmentInput {
+    /** The shipment's tracking code, at most 255 characters. Replaces the fulfillment's. */
+    trackingCode?: string;
+    /**
+     * `Shipped` or `Delivered`. Forward only: a state the fulfillment is already
+     * at or past is ignored, so a repeated report is harmless.
+     */
+    state?: AppFulfillmentReportState;
+}
+/** The fulfillment as it stands after an app's report. */
+export interface ReportedAppFulfillment {
+    id: string;
+    /** `Pending`, `Shipped`, `Delivered`, … */
+    state: string;
+    trackingCode: string | null;
+    method: string;
+}
+/**
+ * What cancelling a fulfillment would owe one order's customer back: a delivery charge they
+ * already paid, held to what the order's payments can still hand back (an order still owing
+ * gets back only what goes beyond what it owes). Money is integer MINOR UNITS.
+ */
+export interface FulfillmentCancelOverpayment {
+    orderId: string;
+    orderCode: string;
+    amount: number;
+    currencyCode: string;
+    /** Refund to the customer's payment: open, or the refusal choosing it would answer. */
+    refund: OverpaymentOption;
+    /** Credit to the customer's account: open, or the refusal choosing it would answer. */
+    accountCredit: OverpaymentOption;
+}
+/** What a fulfillment cancel would owe back (`cancelPreview`). Nothing was written. */
+export interface FulfillmentCancelPreview {
+    fulfillmentId: string;
+    /** One entry per order the cancel would leave overpaid; empty when it owes nobody anything. */
+    overpayments: FulfillmentCancelOverpayment[];
+}
+/** How one order's paid delivery charge goes back when the fulfillment is cancelled. */
+export interface FulfillmentCancelChoice {
+    orderId: string;
+    choice: OrderOverpaymentChoice;
+}
+/** What `cancel` sends besides the fulfillment. */
+export interface CancelFulfillmentInput {
+    /**
+     * One choice for EACH order the cancel leaves overpaid (`cancelPreview` lists them). An order
+     * named twice, or one this fulfillment does not ship, is refused before any request.
+     */
+    overpayment?: FulfillmentCancelChoice[];
+}
+/** What a cancel queued for one order. */
+export interface FulfillmentCancelSettlement {
+    orderId: string;
+    orderCode: string;
+    amount: number;
+    currencyCode: string;
+    choice: OrderOverpaymentChoice;
+}
+/** A cancelled fulfillment and what its cancel queued. */
+export interface CancelledFulfillment {
+    fulfillment: {
+        id: string;
+        state: string;
+    };
+    /**
+     * One entry per order the cancel left overpaid. The refund or account credit is made right
+     * after the cancel commits (normally within seconds): it is QUEUED here, not done. A card
+     * refund then stays `Pending` until the provider confirms it; if it cannot be made, the
+     * order's history says so and why.
+     */
+    settlements: FulfillmentCancelSettlement[];
+}
+/** Why an order that is not paid in full may still be handed over. */
+export type FulfillmentCoverageExemption = 'NET_TERMS' | 'EXEMPT_METHOD';
+/** Who granted a coverage override, as the platform names principals. */
+export type FulfillmentCoverageActorKind = 'user' | 'api_token' | 'app_installation';
+/**
+ * A recorded decision to hand an order's goods over before it is paid in full. The latest one
+ * of an order holds while the order owes no more than `outstandingAtGrant`, in the same currency.
+ * Money is integer MINOR UNITS.
+ */
+export interface FulfillmentCoverageOverride {
+    id: string;
+    orderId: string;
+    reason: string;
+    actorKind: FulfillmentCoverageActorKind;
+    /** The user, API token or app installation id. */
+    actorId: string;
+    outstandingAtGrant: number;
+    currencyCode: string;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+    /** Whether it still allows a hand-over now. */
+    active: boolean;
+}
+/**
+ * Whether an order's goods may be handed over now under the store's fulfilment payment policy
+ * (Channel `fulfillmentPaymentPolicy`). Collected money is settled or held by a payment provider;
+ * an offline authorization (bank transfer, invoice, cash on delivery) does not count.
+ */
+export interface OrderFulfillmentCoverage {
+    orderId: string;
+    orderCode: string;
+    currencyCode: string;
+    /** The store requires full payment before a fulfilment is created, extended or shipped. */
+    policyActive: boolean;
+    /** The collected money covers what the order bills. */
+    covered: boolean;
+    /** What is still to collect, minor units. */
+    outstanding: number;
+    exempt: boolean;
+    exemptReason: FulfillmentCoverageExemption | null;
+    /** A fulfilment may be created, extended and shipped now. */
+    allowed: boolean;
+    /** The order's latest override, whether or not it still holds. */
+    override: FulfillmentCoverageOverride | null;
+}
+/** The longest override reason the engine stores. */
+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.
+ */
+export interface FulfillmentsModule {
+    /** Every fulfillment of an order, with its parcels. Needs `ReadOrder`. */
+    parcelsOfOrder(orderId: string, options?: Call): Promise<OrderFulfillmentParcels[]>;
+    /**
+     * One fulfillment's barcodes per parcel. Needs `ReadFulfillment` and the
+     * warehouse entitlement — a Warehouse-role user has no `ReadOrder`.
+     */
+    parcelTracking(fulfillmentId: string, options?: Call): Promise<FulfillmentParcelTracking>;
+    /**
+     * Every fulfillment of an order with the MyParcel shipments it let go of
+     * (a cancel, a recreate, an abandoned booking) that MyParcel kept or could
+     * not be reached to delete, resolved entries included. Needs `ReadOrder`.
+     * Reads the engine only, never MyParcel.
+     */
+    unretractedShipmentsOfOrder(orderId: string, options?: Call): Promise<OrderFulfillmentUnretractedShipments[]>;
+    /**
+     * 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.
+     */
+    myparcelLabel(fulfillmentId: string, format: FulfillmentLabelFormat, options?: Call): Promise<FulfillmentLabel>;
+    /**
+     * The parcel count the customer paid shipping for, as the warehouse's "To
+     * ship" entry of the order reports it: only while that entry holds the whole
+     * order (every line, nothing of it in a fulfillment yet). `null` otherwise,
+     * when the order is not in that queue, or when it was not priced per parcel.
+     * Needs `ReadFulfillment` with the warehouse entitlement, or office staff
+     * (`UpdateOrder`) — no `ReadOrder`, unlike `admin.orders.parcelCharge`.
+     */
+    chargedParcelCount(input: ChargedParcelCountInput, options?: Call): Promise<number | null>;
+    /**
+     * Acquire the MyParcel label of EVERY parcel of a fulfillment: one job asks
+     * MyParcel for each parcel's missing label, then reads its barcode back.
+     * Labels only — a parcel never booked is booked by the booking's Retry or a
+     * recreate. Needs `UpdateOrder`.
+     *
+     * A refusal throws its coded error: another store's fulfillment is a
+     * `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.
+     */
+    labelMyparcelParcels(fulfillmentId: string, input?: LabelMyparcelParcelsInput, options?: Call): Promise<MyparcelParcelsLabelRequest>;
+    /**
+     * **For a fulfilment app, with its installation token.** Report the tracking
+     * code of a fulfillment the platform asked you to fulfil (your
+     * `fulfillment.service` hook's `request`, whose `data.fulfillment.id` is the
+     * `fulfillmentId` here) and/or that its goods shipped or arrived. The move
+     * goes through the store's own fulfillment process, so the order's state and
+     * the `fulfillment.shipped` / `fulfillment.delivered` events follow; the
+     * tracking code is written first, so `fulfillment.shipped` carries it.
+     *
+     * Only the installation the fulfillment was requested from may report, and
+     * only while it may act at the fulfillment's stock location (the
+     * installation's `locationIds`). `options.idempotencyKey` is optional: a
+     * repeat under it answers the fulfillment as it now is.
+     *
+     * Refusals: `FULFILLMENT_NOT_OWNED_BY_INSTALLATION` (a `PermissionDeniedError`,
+     * 403: not a fulfillment requested from this installation on this store — one
+     * answer whatever the reason), `LOCATION_NOT_ALLOWED` (403: your installation
+     * is restricted to other stock locations), `APP_FULFILLMENT_NOT_BOOKED` (your
+     * acceptance is not recorded yet: answer the request, which the platform
+     * retries), `APP_FULFILLMENT_STATE_NOT_REPORTABLE` (the fulfillment is
+     * cancelled, or the store refused the move), `APP_FULFILLMENT_REPORT_INVALID`.
+     */
+    reportAppFulfillment(fulfillmentId: string, input: ReportAppFulfillmentInput, options?: Call & {
+        idempotencyKey?: string;
+    }): Promise<ReportedAppFulfillment>;
+    /**
+     * 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`).
+     */
+    cancelPreview(fulfillmentId: string, options?: Call): Promise<FulfillmentCancelPreview>;
+    /**
+     * Cancel a fulfillment (the order page's Remove). Its delivery charge comes off every order it
+     * charged; where the customer already paid it, `input.overpayment` says for EACH such order
+     * whether it is refunded to their payment (`REFUND`) or credited to their account
+     * (`ACCOUNT_CREDIT`). Needs `UpdateOrder`.
+     *
+     * Refusals, each before anything is written and before the carrier is told:
+     * `FULFILLMENT_CANCEL_OVERPAYMENT_CHOICE_REQUIRED` (→ `BusinessRuleError`) when an order owing
+     * money has no choice: read `cancelPreview`, ask, and cancel again;
+     * `FULFILLMENT_CANCEL_OVERPAYMENT_NOT_SETTLEABLE` (→ `BusinessRuleError`) when neither way is
+     * open for an order; `FULFILLMENT_CANCEL_OVERPAYMENT_INVALID` (→ `ValidationError`) for an
+     * order the fulfillment does not ship; a closed way chosen anyway answers its own refusal
+     * (`REFUND_EXCEEDS_PAYMENT`, `REFUND_METHOD_UNAVAILABLE`, `AR_ACCOUNT_REQUIRED`,
+     * `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`.
+     *
+     * `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`.
+     */
+    cancel(fulfillmentId: string, input?: CancelFulfillmentInput, options?: Call & {
+        idempotencyKey?: string;
+    }): Promise<CancelledFulfillment>;
+    /**
+     * Whether the order's goods may be handed over now under the store's fulfilment payment
+     * policy, and why: covered, exempt (net terms, an exempt method), or an override that still
+     * holds. Needs `ReadOrder`. Another store's order is a `NotFoundError`
+     * (`FULFILLMENT_COVERAGE_ORDER_NOT_FOUND`).
+     *
+     * On a store that requires full payment, creating, extending or shipping a fulfilment of an
+     * uncovered order is refused `ORDER_NOT_COVERED` (→ `BusinessRuleError`; the GraphQL error's
+     * `extensions` carry `orderId`, `orderCode`, `outstanding` and `currencyCode`, and this call
+     * reads the same facts); a warehouse API call answers it as
+     * `WarehouseError { code: ORDER_NOT_COVERED }`.
+     */
+    coverage(orderId: string, options?: Call): Promise<OrderFulfillmentCoverage>;
+    /**
+     * Record that the order may be handed over before it is paid in full, while it owes no more
+     * than it does now. Needs `OverrideFulfillmentPaymentCoverage`. Append-only: a later grant
+     * supersedes the earlier ones. The order's history gets a private entry and the audit trail
+     * an event.
+     *
+     * A blank reason, or one over 500 characters, is refused before any request
+     * (`FULFILLMENT_COVERAGE_OVERRIDE_INVALID`, → `ValidationError`), as the engine would.
+     * `options.idempotencyKey`: a repeat under it answers the first grant, never a second one.
+     */
+    allowUncovered(orderId: string, reason: string, options?: Call & {
+        idempotencyKey?: string;
+    }): Promise<FulfillmentCoverageOverride>;
+}
+/**
+ * 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";
+/** `$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";
+/** 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. */
+export declare const ALLOW_UNCOVERED_FULFILLMENT_MUTATION = "\n  mutation AllowUncoveredFulfillment($orderId: ID!, $reason: String!, $idempotencyKey: String) {\n    allowUncoveredFulfillment(orderId: $orderId, reason: $reason, idempotencyKey: $idempotencyKey) {\n      \n  id\n  orderId\n  reason\n  actorKind\n  actorId\n  outstandingAtGrant\n  currencyCode\n  createdAt\n  active\n\n    }\n  }\n";
+export declare const REPORT_APP_FULFILLMENT_MUTATION = "\n  mutation ReportAppFulfillment(\n    $fulfillmentId: ID!\n    $input: ReportAppFulfillmentInput!\n    $idempotencyKey: String\n  ) {\n    reportAppFulfillment(\n      fulfillmentId: $fulfillmentId\n      input: $input\n      idempotencyKey: $idempotencyKey\n    ) {\n      id\n      state\n      trackingCode\n      method\n    }\n  }\n";
+export declare const ORDER_FULFILLMENT_PARCELS_QUERY = "\n  query OrderFulfillmentParcels($id: ID!) {\n    order(id: $id) {\n      id\n      fulfillments {\n        id\n        trackingCode\n        customFields {\n          myparcelShipmentId\n          myparcelShipmentIds\n          parcelCount\n          trackingCodes\n        }\n      }\n    }\n  }\n";
+/** Every field of `MyparcelUnretractedShipment`, shared with the stock-transfer twin. */
+export declare const UNRETRACTED_SHIPMENT_FIELDS = "\n  shipmentId\n  reference\n  verdict\n  status\n  statusName\n  billable\n  hidden\n  reason\n  cause\n  firstRecordedAt\n  lastCheckedAt\n  resolvedAt\n";
+/**
+ * Its own document, never part of the parcel read: an engine without the
+ * field refuses this call alone, and the order card still renders.
+ */
+export declare const ORDER_FULFILLMENT_UNRETRACTED_SHIPMENTS_QUERY = "\n  query OrderFulfillmentUnretractedShipments($id: ID!) {\n    order(id: $id) {\n      id\n      fulfillments {\n        id\n        myparcelUnretractedShipments { \n  shipmentId\n  reference\n  verdict\n  status\n  statusName\n  billable\n  hidden\n  reason\n  cause\n  firstRecordedAt\n  lastCheckedAt\n  resolvedAt\n }\n      }\n    }\n  }\n";
+export declare const FULFILLMENT_PARCEL_TRACKING_QUERY = "\n  query FulfillmentParcelTracking($id: ID!) {\n    warehouseFulfillment(id: $id) {\n      trackingCodes\n      parcelTrackingCodes\n      parcelCount\n    }\n  }\n";
+/**
+ * Its own document on purpose: `chargedParcelCount` exists only on an engine
+ * that serves it, so on an older one this call alone fails validation and the
+ * demand the create flow reads beside it does not.
+ */
+export declare const WAREHOUSE_CHARGED_PARCEL_COUNT_QUERY = "\n  query WarehouseChargedParcelCount($input: WarehouseDemandInput!) {\n    warehouseDemand(input: $input) {\n      items {\n        orderId\n        chargedParcelCount\n      }\n    }\n  }\n";
+export declare const MYPARCEL_FULFILLMENT_LABEL_MUTATION = "\n  mutation MyparcelFulfillmentLabel($fulfillmentId: ID!, $format: MyparcelLabelFormatEnum!) {\n    getMyparcelFulfillmentLabel(fulfillmentId: $fulfillmentId, format: $format) {\n      format\n      base64\n      contentType\n      filename\n    }\n  }\n";
+/**
+ * Its own document, like every call here: on an engine without the mutation
+ * this call alone fails validation. `$format` is optional and left out of the
+ * variables when not asked for.
+ */
+export declare const LABEL_MYPARCEL_FULFILLMENT_PARCELS_MUTATION = "\n  mutation LabelMyparcelFulfillmentParcels($fulfillmentId: ID!, $format: MyparcelLabelFormatEnum) {\n    labelMyparcelFulfillmentParcels(fulfillmentId: $fulfillmentId, format: $format) {\n      __typename\n      ... on MyparcelLabelParcelsQueued {\n        fulfillmentId\n        parcels\n        missing\n        queued\n      }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+/**
+ * Clears the engine's MyParcel budget: 3 × 10s attempts plus two capped waits.
+ * Every merged MyParcel label (a fulfillment's, a stock transfer's) runs the
+ * same engine download, so they share it.
+ */
+export declare const MYPARCEL_LABEL_TIMEOUT_MS = 55000;
+/** The engine's entries as they are: the fields are the SDK's, one to one. */
+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;
+export declare function createFulfillmentsModule(transport: Transport): FulfillmentsModule;