@sixtyninecommerce/admin 0.6.0 → 0.7.0

package/dist/metafields/index.d.ts

@@ -0,0 +1,291 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * The entities a metafield may hang off.
+ *
+ * `content_item` is in the app manifest's vocabulary and is deliberately NOT
+ * here: content rows live in the CMS, which already models tenant-defined
+ * fields, and commerce refuses a value written against it
+ * (`METAFIELD_OWNER_INVALID`). A manifest declaring one still registers; only
+ * the value surface says no.
+ */
+export declare const METAFIELD_OWNER_TYPES: readonly ["product", "variant", "customer", "order", "order_line", "location", "collection"];
+export type MetafieldOwnerType = (typeof METAFIELD_OWNER_TYPES)[number];
+/** Scalar value types. `list<T>` of any of them is also a type. */
+export declare const METAFIELD_SCALAR_TYPES: readonly ["text", "number", "money", "boolean", "date", "json", "reference", "attachment"];
+export type MetafieldScalarType = (typeof METAFIELD_SCALAR_TYPES)[number];
+export type MetafieldType = MetafieldScalarType | `list<${MetafieldScalarType}>`;
+/** §8.4's attachment: opaque to commerce, rendered as a reference on documents. */
+export interface MetafieldAttachment {
+    kind: string;
+    ref: string;
+    label?: string | null;
+}
+/** A `reference` value. The platform does not resolve or fetch it. */
+export interface MetafieldReference {
+    entityType: string;
+    id: string;
+}
+/**
+ * A `money` value is a bare INTEGER in minor units — `1999` is 19.99 — never a
+ * decimal, and it carries no currency of its own, exactly as the app-manifest
+ * schema describes it. A channel may sell in several currencies, so an app
+ * storing money on an entity that has no currency of its own declares a
+ * separate field for the currency beside it.
+ *
+ * `min` / `max` in the definition's `validation` are minor units too, and the
+ * engine refuses a decimal bound.
+ */
+export type MetafieldMoney = number;
+/**
+ * What a merchant, an app and a storefront may each do with a field.
+ *
+ * **Visibility is not authority.** `app` is always `read_write`; whether an app
+ * may actually write is decided by namespace ownership — its own slug, never
+ * another app's and never `platform`.
+ */
+export interface MetafieldVisibility {
+    app: 'read_write';
+    /** `edit` is the ONLY value that lets the tenant write the field. */
+    merchant: 'hidden' | 'read' | 'edit';
+    /** `read` is what the Shop API projects; `hidden` keeps it back-office. */
+    storefront: 'hidden' | 'read';
+}
+/** One stored value. */
+export interface Metafield {
+    ownerType: MetafieldOwnerType;
+    ownerId: string;
+    /** The declaring app's slug, or `platform` for the built-ins of §8.3/§8.4. */
+    namespace: string;
+    key: string;
+    /** Shaped by the definition's `type`. */
+    value: unknown;
+    /** ISO-8601 instant. */
+    updatedAt: string;
+}
+/**
+ * What MAY be stored on an entity.
+ *
+ * Three kinds. A definition this STORE registered (`definitions.upsert`, `id`
+ * set and `appId` null). A `platform` built-in of §8.3/§8.4, which is code
+ * rather than a row (`id` and `appId` both null, present on every store). And an
+ * APP's, provisioned from its manifest when the app is installed and on every
+ * consent approval (`appId` set) — so `appId` is how you tell an app's field
+ * from your own, which is the distinction the engine enforces: only a store's
+ * own definitions are editable and removable through this module.
+ *
+ * `active` goes false when the declaring app withdraws the field or is
+ * uninstalled. The VALUES are kept for a redaction window, so the definition
+ * still appears here and still describes them, but nothing new can be written
+ * under it and the Shop API stops publishing it at once. Withdrawing also ENDS
+ * the merchant's consent to that field: declaring it again asks for consent
+ * afresh, however the new declaration compares with the inactive row.
+ */
+export interface MetafieldDefinition {
+    /** Null for a platform built-in, which is code rather than a row. */
+    id: string | null;
+    /** The declaring app, or null for a platform built-in. */
+    appId: string | null;
+    ownerType: MetafieldOwnerType;
+    namespace: string;
+    key: string;
+    type: MetafieldType;
+    /** The rules values are checked against; null when the app declared none. */
+    validation: Record<string, unknown> | null;
+    visibility: MetafieldVisibility;
+    /**
+     * Declared and stored, read by nothing yet. §8.13 promises admin filters and
+     * Meilisearch facets on an indexed field; neither exists, so treat this as
+     * the app's intent rather than a capability.
+     */
+    indexed: boolean;
+    /**
+     * False once the declaring app was uninstalled, or stopped declaring the
+     * field. Existing VALUES are kept — §6.9 gives an uninstalled app a 48 h
+     * redaction window — but no new value can be written.
+     */
+    active: boolean;
+}
+export interface SetMetafieldInput {
+    ownerType: MetafieldOwnerType;
+    ownerId: string;
+    /** Your own namespace. An app's is its slug; `platform` is never writable. */
+    namespace: string;
+    /** Lower snake_case, as the manifest declared it. */
+    key: string;
+    value: unknown;
+}
+/**
+ * A definition this store registers for itself. Whole-record, not a patch: an
+ * omitted `validation` clears it.
+ */
+export interface UpsertMetafieldDefinitionInput {
+    ownerType: MetafieldOwnerType;
+    /**
+     * Lower snake_case. Never `platform`, and never the namespace of an app
+     * installed on this store — both answer `METAFIELD_NAMESPACE_FORBIDDEN`.
+     */
+    namespace: string;
+    /** Lower snake_case. */
+    key: string;
+    type: MetafieldType;
+    validation?: Record<string, unknown> | null;
+    /**
+     * How the field is PRESENTED, not who owns it: a definition your store
+     * registered stays writable AND readable by your store at any `merchant`
+     * setting. The flag governs an APP's fields, where `edit` is what lets the
+     * merchant write one at all and `hidden` keeps it out of `definitions.list`
+     * and `get`.
+     */
+    visibility: {
+        merchant: 'hidden' | 'read' | 'edit';
+        storefront: 'hidden' | 'read';
+    };
+    /** Stored; no search or facet reads it yet. */
+    indexed?: boolean;
+}
+export interface MetafieldDefinitionsModule {
+    /**
+     * Every definition this store has, including the platform built-ins.
+     *
+     * A `Page` because every list in this SDK is one (spec §9.2), not because
+     * this query pages: the Admin API answers the complete array, so the page is
+     * always the last one.
+     *
+     * Filtered by what the CALLER may see, on BOTH axes: an app gets its own
+     * namespace and the platform built-ins while a human or an API token gets
+     * everything but `merchant: hidden`, and either way a definition only appears
+     * when the caller holds its owner entity's READ permission — so a principal
+     * that cannot read customers never learns which customer fields an app keeps.
+     */
+    list(options?: {
+        ownerType?: MetafieldOwnerType;
+    } & Call): Promise<Page<MetafieldDefinition>>;
+    /**
+     * Register or replace one of THIS store's own definitions.
+     *
+     * Needs the owner entity's own WRITE permission — `UpdateOrder` to declare a
+     * field on orders, `UpdateCatalog` on products — so nothing has to be granted
+     * before a store can use it. Re-registering a key that was withdrawn revives
+     * it, with the values it still holds.
+     *
+     * An APP cannot call this: an app declares its fields in its manifest, which
+     * is what the merchant consents to (`METAFIELD_NAMESPACE_FORBIDDEN`).
+     *
+     * Two refusals that are easy to trip over: changing a definition's `type`
+     * while values exist (`METAFIELD_DEFINITION_IN_USE` — nothing re-validates or
+     * migrates them, so clear them first), and a `validation.pattern` that can
+     * backtrack catastrophically such as `^(a+)+$` (`METAFIELD_INVALID` — the
+     * regex runs on the engine every store shares).
+     */
+    upsert(input: UpsertMetafieldDefinitionInput, options?: Call): Promise<MetafieldDefinition>;
+    /**
+     * Remove one of this store's own definitions. True when one was removed,
+     * false when there was none.
+     *
+     * Refused while values still exist under it
+     * (`METAFIELD_DEFINITION_IN_USE` → `BusinessRuleError`): a value whose
+     * definition is gone can never be read back. Clear them with
+     * {@link MetafieldsModule.delete} first — which reaches them even on a
+     * deleted product or customer. An app's declaration and a `platform` built-in
+     * are never removable here.
+     */
+    delete(ownerType: MetafieldOwnerType, namespace: string, key: string, options?: Call): Promise<boolean>;
+}
+/**
+ * App and platform custom data on core entities (spec §8.13, §8.4).
+ *
+ * **Nothing undeclared is stored.** A value needs a definition — one this store
+ * registered (`definitions.upsert`) or a `platform` built-in of §8.3/§8.4. An
+ * unknown `(ownerType, namespace, key)` is `METAFIELD_DEFINITION_NOT_FOUND`
+ * (→ `NotFoundError`).
+ *
+ * **An app's declarations arrive with consent.** They are provisioned when the
+ * app is installed and on every consent approval. A re-registration applies at
+ * once what only NARROWS an active field, and withdraws one at once; it holds
+ * back what widens an active field, what is brand new, and — because a
+ * withdrawal ends consent — anything declared again over an INACTIVE row, even
+ * a narrowing. So a field an app has asked to make more visible keeps its old
+ * visibility, a field it has withdrawn stops being published without waiting
+ * for anyone, and a field it withdrew and wants back waits for the merchant
+ * exactly as a new one does.
+ *
+ * **Who may write what** (`METAFIELD_NAMESPACE_FORBIDDEN` /
+ * `METAFIELD_EDIT_FORBIDDEN`, both → `PermissionDeniedError`):
+ *
+ * | Principal | May write |
+ * |---|---|
+ * | an app installation | its OWN namespace (its slug), whatever the visibility says |
+ * | a human session or an API token | a definition whose `visibility.merchant` is `edit` |
+ * | anybody | never the `platform` namespace — the platform writes its own built-ins |
+ *
+ * Reading needs the owner entity's own READ permission and writing its own
+ * WRITE permission (`UpdateOrder` for an order and its lines, `UpdateCatalog`
+ * for a product, and so on). There is no separate metafield permission, so
+ * nothing has to be granted before this works.
+ *
+ * **Everything is per channel.** The owner must belong to the client's tenant
+ * (`METAFIELD_OWNER_NOT_FOUND` → `NotFoundError`, the same answer for an id
+ * that belongs to another store and one that belongs to nobody), and the value
+ * is stored against that channel — a product shared by two stores holds two
+ * independent values.
+ *
+ * Other coded refusals: `METAFIELD_INVALID` (→ `ValidationError`) when the
+ * value does not fit the definition's `type` and `validation`, and
+ * `METAFIELD_OWNER_INVALID` (→ `ValidationError`) for an owner commerce does
+ * not store.
+ *
+ * **What a storefront sees** (Shop API, server-side in this release): only
+ * `visibility.storefront = read` definitions, only on `product`, `variant` and
+ * `collection`, and only while the owner itself is public — a disabled product,
+ * a variant of a disabled product and a private collection all answer as if
+ * they did not exist.
+ */
+export interface MetafieldsModule {
+    /**
+     * Every value on one entity that the caller may see.
+     *
+     * Not a `Page`: this is the set of fields attached to ONE record — bounded by
+     * the definitions the store has declared — the way an entity's own columns
+     * are, not a collection to walk.
+     */
+    get(ownerType: MetafieldOwnerType, ownerId: string, options?: {
+        namespace?: string;
+    } & Call): Promise<Metafield[]>;
+    /**
+     * Write one value. Replaces whatever was there; there is no partial merge.
+     *
+     * The value must fit the definition's `type`: a `money` is a bare integer in
+     * minor units, a `date` is an ISO-8601 instant with an explicit offset (and a
+     * calendar date that exists — `2026-02-30` is refused rather than rolled over
+     * to March), an `attachment` is exactly `{ kind, ref, label? }` and a
+     * `reference` exactly `{ entityType, id }`.
+     *
+     * To CLEAR a field use {@link delete} — `null` is refused, because a stored
+     * JSON `null` and an absent row cannot be told apart afterwards.
+     *
+     * `options.idempotencyKey` is inert on this surface today: the Admin API has
+     * no idempotency header yet, so a repeat is a second write. It is harmless to
+     * pass and starts being honoured when the engine grows the store.
+     */
+    set(input: SetMetafieldInput, options?: Call): Promise<Metafield>;
+    /**
+     * Remove a value. True when one was removed, false when there was none.
+     *
+     * This is the CLEANUP route, so it is deliberately more permissive than
+     * `set`: it works on a withdrawn definition, on a definition that is gone
+     * entirely, and on a soft-deleted owner — a deleted product's or customer's
+     * values are exactly what a GDPR erasure has to reach. Only WRITING needs a
+     * live declaration and a live owner. Namespace ownership is not relaxed: an
+     * app still clears only its own namespace.
+     */
+    delete(ownerType: MetafieldOwnerType, ownerId: string, namespace: string, key: string, options?: Call): Promise<boolean>;
+    definitions: MetafieldDefinitionsModule;
+}
+export declare const METAFIELDS_QUERY = "\n  query Metafields($ownerType: String!, $ownerId: ID!, $namespace: String) {\n    metafields(ownerType: $ownerType, ownerId: $ownerId, namespace: $namespace) {\n      \n  ownerType\n  ownerId\n  namespace\n  key\n  value\n  updatedAt\n\n    }\n  }\n";
+export declare const UPSERT_METAFIELD_DEFINITION_MUTATION = "\n  mutation UpsertMetafieldDefinition($input: UpsertMetafieldDefinitionInput!) {\n    upsertMetafieldDefinition(input: $input) { \n  id\n  appId\n  ownerType\n  namespace\n  key\n  type\n  validation\n  visibility {\n    app\n    merchant\n    storefront\n  }\n  indexed\n  active\n }\n  }\n";
+export declare const DELETE_METAFIELD_DEFINITION_MUTATION = "\n  mutation DeleteMetafieldDefinition($ownerType: String!, $namespace: String!, $key: String!) {\n    deleteMetafieldDefinition(ownerType: $ownerType, namespace: $namespace, key: $key)\n  }\n";
+export declare const METAFIELD_DEFINITIONS_QUERY = "\n  query MetafieldDefinitions($ownerType: String) {\n    metafieldDefinitions(ownerType: $ownerType) { \n  id\n  appId\n  ownerType\n  namespace\n  key\n  type\n  validation\n  visibility {\n    app\n    merchant\n    storefront\n  }\n  indexed\n  active\n }\n  }\n";
+export declare const SET_METAFIELD_MUTATION = "\n  mutation SetMetafield($input: SetMetafieldInput!) {\n    setMetafield(input: $input) { \n  ownerType\n  ownerId\n  namespace\n  key\n  value\n  updatedAt\n }\n  }\n";
+export declare const DELETE_METAFIELD_MUTATION = "\n  mutation DeleteMetafield($ownerType: String!, $ownerId: ID!, $namespace: String!, $key: String!) {\n    deleteMetafield(ownerType: $ownerType, ownerId: $ownerId, namespace: $namespace, key: $key)\n  }\n";
+export declare function createMetafieldsModule(transport: Transport): MetafieldsModule;

package/dist/metafields/index.js

@@ -0,0 +1,141 @@
+import { createPage } from '@sixtyninecommerce/core';
+/**
+ * The entities a metafield may hang off.
+ *
+ * `content_item` is in the app manifest's vocabulary and is deliberately NOT
+ * here: content rows live in the CMS, which already models tenant-defined
+ * fields, and commerce refuses a value written against it
+ * (`METAFIELD_OWNER_INVALID`). A manifest declaring one still registers; only
+ * the value surface says no.
+ */
+export const METAFIELD_OWNER_TYPES = [
+    'product',
+    'variant',
+    'customer',
+    'order',
+    'order_line',
+    'location',
+    'collection',
+];
+/** Scalar value types. `list<T>` of any of them is also a type. */
+export const METAFIELD_SCALAR_TYPES = [
+    'text',
+    'number',
+    'money',
+    'boolean',
+    'date',
+    'json',
+    'reference',
+    'attachment',
+];
+const METAFIELD_FIELDS = /* GraphQL */ `
+  ownerType
+  ownerId
+  namespace
+  key
+  value
+  updatedAt
+`;
+const METAFIELD_DEFINITION_FIELDS = /* GraphQL */ `
+  id
+  appId
+  ownerType
+  namespace
+  key
+  type
+  validation
+  visibility {
+    app
+    merchant
+    storefront
+  }
+  indexed
+  active
+`;
+export const METAFIELDS_QUERY = /* GraphQL */ `
+  query Metafields($ownerType: String!, $ownerId: ID!, $namespace: String) {
+    metafields(ownerType: $ownerType, ownerId: $ownerId, namespace: $namespace) {
+      ${METAFIELD_FIELDS}
+    }
+  }
+`;
+export const UPSERT_METAFIELD_DEFINITION_MUTATION = /* GraphQL */ `
+  mutation UpsertMetafieldDefinition($input: UpsertMetafieldDefinitionInput!) {
+    upsertMetafieldDefinition(input: $input) { ${METAFIELD_DEFINITION_FIELDS} }
+  }
+`;
+export const DELETE_METAFIELD_DEFINITION_MUTATION = /* GraphQL */ `
+  mutation DeleteMetafieldDefinition($ownerType: String!, $namespace: String!, $key: String!) {
+    deleteMetafieldDefinition(ownerType: $ownerType, namespace: $namespace, key: $key)
+  }
+`;
+export const METAFIELD_DEFINITIONS_QUERY = /* GraphQL */ `
+  query MetafieldDefinitions($ownerType: String) {
+    metafieldDefinitions(ownerType: $ownerType) { ${METAFIELD_DEFINITION_FIELDS} }
+  }
+`;
+export const SET_METAFIELD_MUTATION = /* GraphQL */ `
+  mutation SetMetafield($input: SetMetafieldInput!) {
+    setMetafield(input: $input) { ${METAFIELD_FIELDS} }
+  }
+`;
+export const DELETE_METAFIELD_MUTATION = /* GraphQL */ `
+  mutation DeleteMetafield($ownerType: String!, $ownerId: ID!, $namespace: String!, $key: String!) {
+    deleteMetafield(ownerType: $ownerType, ownerId: $ownerId, namespace: $namespace, key: $key)
+  }
+`;
+export function createMetafieldsModule(transport) {
+    return {
+        async get(ownerType, ownerId, options) {
+            const { namespace, ...call } = options ?? {};
+            const data = await transport.graphql({
+                api: 'admin',
+                query: METAFIELDS_QUERY,
+                // `null`, not omitted: the argument is nullable and "every namespace"
+                // is what null means to the server.
+                variables: { ownerType, ownerId, namespace: namespace ?? null },
+            }, call);
+            return data.metafields;
+        },
+        async set(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: SET_METAFIELD_MUTATION, variables: { input } }, options);
+            return data.setMetafield;
+        },
+        async delete(ownerType, ownerId, namespace, key, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: DELETE_METAFIELD_MUTATION,
+                variables: { ownerType, ownerId, namespace, key },
+            }, options);
+            return data.deleteMetafield;
+        },
+        definitions: {
+            async list(options) {
+                const { ownerType, ...call } = options ?? {};
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: METAFIELD_DEFINITIONS_QUERY,
+                    variables: { ownerType: ownerType ?? null },
+                }, call);
+                const items = data.metafieldDefinitions;
+                return createPage(items, { nextCursor: null, hasNext: false, total: items.length }, () => {
+                    // Unreachable while `hasNext` is false — `Page.next()` short-circuits
+                    // — and a rejection rather than a silent re-fetch if that changes.
+                    throw new Error('metafieldDefinitions returns a complete list; there is no next page');
+                });
+            },
+            async upsert(input, options) {
+                const data = await transport.graphql({ api: 'admin', query: UPSERT_METAFIELD_DEFINITION_MUTATION, variables: { input } }, options);
+                return data.upsertMetafieldDefinition;
+            },
+            async delete(ownerType, namespace, key, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: DELETE_METAFIELD_DEFINITION_MUTATION,
+                    variables: { ownerType, namespace, key },
+                }, options);
+                return data.deleteMetafieldDefinition;
+            },
+        },
+    };
+}

package/dist/orders/index.d.ts

@@ -0,0 +1,106 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { OrderPaymentPosition, PaidOrder } from '../payments/index.js';
+import type { Call } from '../types.js';
+import { type SurchargesModule } from './surcharges.js';
+export type { PaidOrder } from '../payments/index.js';
+/** The result of settling an order. */
+export interface OrderSettlement {
+    order: PaidOrder;
+    position: OrderPaymentPosition;
+    /**
+     * What you asked for. Settling does NOT create a fulfilment: choosing a
+     * handler, a method and lines for a merchant is not the platform's decision
+     * to make, so the flag is reported back rather than acted on.
+     */
+    fulfilRequested: boolean;
+}
+/**
+ * Orders (spec §8.2, §12.2).
+ *
+ * `surcharges` is W5-1's module, unchanged. The three methods beside it are the
+ * deposit flow: hold an order while the rest of the money is arranged, read
+ * what it stands at, and settle it once the money is really there.
+ */
+export interface OrdersModule {
+    surcharges: SurchargesModule;
+    /**
+     * Hold a placed order while the rest of its money is arranged. Needs
+     * `UpdateOrder`.
+     *
+     * Reachable only from `ArrangingPayment`, and only once something has been
+     * paid — unless the store's deposit policy allows a zero-deposit park, which
+     * is off unless a merchant chose it. Refusals carry the order's position:
+     * `DEPOSITS_NOT_ENABLED` (the store has not turned deposits on — the default,
+     * so this is the first one you will meet), `DEPOSIT_REQUIRED` (nothing paid,
+     * and the store does not allow that), `DEPOSIT_BELOW_MINIMUM`,
+     * `ORDER_NOT_PARKABLE` (wrong state), `PARK_REASON_TOO_LONG` (500
+     * characters).
+     *
+     * Parking does not RESERVE stock: the platform allocates at the payment edge,
+     * so an order parked while arranging payment usually holds no allocations
+     * yet. What it protects is the ORDER — the stock-allocation sweeper leaves a
+     * parked order alone deliberately, so an expiring allocation TTL cannot
+     * cancel an order a customer has already paid a deposit on, and allocations
+     * it does hold stay put while it waits.
+     */
+    park(orderId: string, options?: Call & {
+        reason?: string;
+    }): Promise<PaidOrder>;
+    /**
+     * End a hold: hand a parked order back to the state it was parked FROM, and
+     * clear its park reason. Needs `UpdateOrder`.
+     *
+     * The target is read from the ORDER'S OWN HISTORY, never chosen by the
+     * caller and never assumed, so un-parking reverses exactly the move that
+     * parked it. `PARK_ORIGIN_UNKNOWN` is the refusal when that history does not
+     * say — move such an order on explicitly with a state transition instead.
+     *
+     * There is no storefront equivalent today: a parked order's remainder is
+     * recorded WHERE IT STANDS with `payments.record`, and the payment that
+     * clears it settles, places and allocates the order without ever leaving
+     * `Parked` first. Use this when the order has to be EDITED, which is the one
+     * thing it cannot do while held.
+     *
+     * It moves no money and changes no payment. Other refusals:
+     * `ORDER_NOT_PARKED`, `UNPARK_TRANSITION_REFUSED` (the origin was known and
+     * another guard in the order process refused the way back — an order
+     * minimum, a stock check — with its own reason). All carry the order's
+     * position.
+     */
+    unpark(orderId: string, options?: Call): Promise<PaidOrder>;
+    /** What the order has actually been paid. Needs `ReadOrder`. */
+    paymentPosition(orderId: string, options?: Call): Promise<OrderPaymentPosition>;
+    /**
+     * Move a fully paid order to `PaymentSettled`. Needs `UpdateOrder`.
+     *
+     * Refuses `COVERAGE_INSUFFICIENT` while the order's SETTLED money does not
+     * cover its total, with the position attached. Settled, not covered: an
+     * authorization is permission to take money, not money, so an order whose
+     * remainder is merely authorized is settled from `ArrangingPayment` after the
+     * authorization is captured, like any other order. `ORDER_NOT_SETTLEABLE` is
+     * the other refusal — a state a settlement cannot be reached from, which
+     * paying more can never fix.
+     *
+     * Calling this on an order the platform ALREADY settled succeeds rather than
+     * refusing. Expect that to be the common case: the engine settles an order as
+     * soon as its settled payments cover its total, so recording the payment that
+     * clears a deposit usually settles the order on its own, and this call is then
+     * a confirmation.
+     *
+     * So do not wait on a settle CALL to learn that a deposit was paid off — in
+     * the ordinary flow nobody makes one. The close signal is the platform event
+     * `payment.partial_recorded` with `outstanding_after: 0`, on the payment that
+     * cleared the balance. That figure nets settled PLUS authorized money, so it
+     * means fully COVERED; "fully settled" is `settled >= total` on the position,
+     * which is what this method requires. For money recorded through
+     * `payments.record` the two coincide — it only creates settled payments.
+     */
+    settle(orderId: string, options?: Call & {
+        fulfil?: boolean;
+    }): Promise<OrderSettlement>;
+}
+export declare const PARK_ORDER_MUTATION = "\n  mutation ParkOrder($orderId: ID!, $reason: String, $idempotencyKey: String) {\n    parkOrder(orderId: $orderId, reason: $reason, idempotencyKey: $idempotencyKey) {\n      id\n      code\n      state\n      currencyCode\n      total\n      totalWithTax\n    }\n  }\n";
+export declare const UNPARK_ORDER_MUTATION = "\n  mutation UnparkOrder($orderId: ID!, $idempotencyKey: String) {\n    unparkOrder(orderId: $orderId, idempotencyKey: $idempotencyKey) {\n      id\n      code\n      state\n      currencyCode\n      total\n      totalWithTax\n    }\n  }\n";
+export declare const SETTLE_ORDER_MUTATION = "\n  mutation SettleOrder($orderId: ID!, $fulfil: Boolean!, $idempotencyKey: String) {\n    settleOrder(orderId: $orderId, fulfil: $fulfil, idempotencyKey: $idempotencyKey) {\n      \n  order {\n    id\n    code\n    state\n    currencyCode\n    total\n    totalWithTax\n  }\n  position {\n    total\n    covered\n    settled\n    authorized\n    refunded\n    outstanding\n    overpaid\n    availableToCharge\n  }\n  fulfilRequested\n\n    }\n  }\n";
+export declare const ORDER_POSITION_QUERY = "\n  query OrderPosition($orderId: ID!) {\n    orderPaymentPosition(orderId: $orderId) {\n      total\n      covered\n      settled\n      authorized\n      refunded\n      outstanding\n      overpaid\n      availableToCharge\n    }\n  }\n";
+export declare function createOrdersModule(transport: Transport): OrdersModule;

package/dist/orders/index.js

@@ -0,0 +1,115 @@
+import { createSurchargesModule } from './surcharges.js';
+const SETTLEMENT_FIELDS = /* GraphQL */ `
+  order {
+    id
+    code
+    state
+    currencyCode
+    total
+    totalWithTax
+  }
+  position {
+    total
+    covered
+    settled
+    authorized
+    refunded
+    outstanding
+    overpaid
+    availableToCharge
+  }
+  fulfilRequested
+`;
+export const PARK_ORDER_MUTATION = /* GraphQL */ `
+  mutation ParkOrder($orderId: ID!, $reason: String, $idempotencyKey: String) {
+    parkOrder(orderId: $orderId, reason: $reason, idempotencyKey: $idempotencyKey) {
+      id
+      code
+      state
+      currencyCode
+      total
+      totalWithTax
+    }
+  }
+`;
+export const UNPARK_ORDER_MUTATION = /* GraphQL */ `
+  mutation UnparkOrder($orderId: ID!, $idempotencyKey: String) {
+    unparkOrder(orderId: $orderId, idempotencyKey: $idempotencyKey) {
+      id
+      code
+      state
+      currencyCode
+      total
+      totalWithTax
+    }
+  }
+`;
+export const SETTLE_ORDER_MUTATION = /* GraphQL */ `
+  mutation SettleOrder($orderId: ID!, $fulfil: Boolean!, $idempotencyKey: String) {
+    settleOrder(orderId: $orderId, fulfil: $fulfil, idempotencyKey: $idempotencyKey) {
+      ${SETTLEMENT_FIELDS}
+    }
+  }
+`;
+export const ORDER_POSITION_QUERY = /* GraphQL */ `
+  query OrderPosition($orderId: ID!) {
+    orderPaymentPosition(orderId: $orderId) {
+      total
+      covered
+      settled
+      authorized
+      refunded
+      outstanding
+      overpaid
+      availableToCharge
+    }
+  }
+`;
+export function createOrdersModule(transport) {
+    return {
+        surcharges: createSurchargesModule(transport),
+        async park(orderId, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: PARK_ORDER_MUTATION,
+                // `undefined`, never an explicit null: `JSON.stringify` drops it, so an
+                // omitted option stays off the wire entirely rather than arriving as a
+                // value a future server could read as one.
+                variables: {
+                    orderId,
+                    reason: options?.reason,
+                    idempotencyKey: options?.idempotencyKey,
+                },
+            }, options);
+            return data.parkOrder;
+        },
+        async unpark(orderId, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: UNPARK_ORDER_MUTATION,
+                // `undefined`, never an explicit null — see `park`.
+                variables: { orderId, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.unparkOrder;
+        },
+        async paymentPosition(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_POSITION_QUERY, variables: { orderId } }, options);
+            return data.orderPaymentPosition;
+        },
+        async settle(orderId, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SETTLE_ORDER_MUTATION,
+                variables: {
+                    // Explicit `false` rather than omitted: the argument is non-null on
+                    // the wire, and "did the caller ask for fulfilment?" is recorded on
+                    // the settlement event.
+                    orderId,
+                    fulfil: options?.fulfil ?? false,
+                    idempotencyKey: options?.idempotencyKey,
+                },
+            }, options);
+            return data.settleOrder;
+        },
+    };
+}