@sixtyninecommerce/admin 0.9.0 → 0.10.0

package/dist/integrations/pipelines.d.ts

@@ -0,0 +1,113 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+import type { CommittedPipelineDraft, ImportDependency, PipelineDirection, PipelineDraft, PipelineDraftSummary, UpdatePipelineDraftInput, UpdatePipelineDraftSchemaMapInput } from './types.js';
+/**
+ * Every key whose VALUE is stored data, not DTO shape: the platform's passthrough set
+ * (`credentials`, `public_credentials`, `site_analysis`, `trigger_filter`, …) plus a schema map's
+ * jsonb columns, which carry the source's own field names and sample records. Converting them
+ * would rename a sample's `date_created` to `dateCreated`, and a `triggerFilter`'s `toState` would
+ * reach the reader as `to_state`, which it ignores.
+ */
+export declare const PIPELINE_DRAFT_PRESERVE_KEYS: ReadonlySet<string>;
+/**
+ * A creation probes the source over the network, and a commit creates the pipeline and may start
+ * its run: both outlast the SDK's 15-second default on a slow source.
+ */
+export declare const PIPELINE_DRAFT_SLOW_TIMEOUT_MS = 60000;
+/**
+ * Half-finished import and export set-ups, kept on the server for the store (headless spec §7).
+ *
+ * - **Any admin of the store with pipeline rights (`UpdateCatalog`) continues a draft, from any
+ *   device.** Drafts belong to the store, not to the person who started one: the list shows every
+ *   unfinished set-up of the active store, and another store's draft is `PIPELINE_DRAFT_NOT_FOUND`.
+ * - **Kept 7 days after its LAST change.** Every write moves `expiresAt`; reads do not. An expired
+ *   draft answers `PIPELINE_DRAFT_NOT_FOUND` at once, and the platform then deletes it together
+ *   with the connection (and its stored password) the draft created, unless a pipeline or another
+ *   draft uses that connection. A connection that existed before any draft is never deleted; one
+ *   another draft created is the picking draft's too (`connection.createdByDraft`), and goes when
+ *   the last draft holding it lets go of it unused.
+ * - **A draft never holds a secret.** Credentials go to {@link PipelineDraftsModule.connect} only,
+ *   which creates the connection and stores them there, encrypted. A set-up resumed before its
+ *   connection exists asks for the credentials again; the source URL and the other settings are
+ *   kept.
+ * - **Every change names the `version` it was made against** and answers the draft with the next
+ *   one. A change made on an older version is refused with a `ConflictError` coded
+ *   `PIPELINE_DRAFT_CONFLICT` (409) and changes nothing: another admin, or another tab, changed it
+ *   first. Read it again and reapply.
+ * - What a step still needs is a `BusinessRuleError` coded `PIPELINE_DRAFT_INCOMPLETE` (422) whose
+ *   `details[]` name each field; a change the set-up refuses (a step of the other direction, a
+ *   connector that cannot work in it) is a `ValidationError` coded `PIPELINE_DRAFT_INVALID` (400).
+ * - An organization workspace is not a store and is refused every door; an app below
+ *   `customerData: full` is too, and `connect` refuses every app (`APP_CREDENTIAL_NOT_ALLOWED`).
+ */
+export interface PipelineDraftsModule {
+    /** The store's unexpired drafts, newest first. */
+    list(options?: ListOptions): Promise<Page<PipelineDraftSummary>>;
+    /**
+     * One draft with its connection, discovery status, schema maps, the served dependencies and their
+     * warnings, and the name the configure step would suggest in the store's zone. Poll it while
+     * `discovery.status` is `pending` or `running`.
+     */
+    get(id: string, options?: Call): Promise<PipelineDraft>;
+    /** Start a set-up. The schedule zone starts as the store's, and the step is `connector`. */
+    create(input: {
+        direction: PipelineDirection;
+    }, options?: Call): Promise<PipelineDraft>;
+    /**
+     * Change fields. `connectorType` starts the connection over (no source URL, connection,
+     * discovery or stock location), even for the same connector; `direction` alone moves to the
+     * connector step; entering `configure` with no name gives the default one. A credential is
+     * refused here (400): send it to {@link PipelineDraftsModule.connect}.
+     */
+    update(id: string, input: UpdatePipelineDraftInput, options?: Call): Promise<PipelineDraft>;
+    /**
+     * Create the draft's connection from its connector, source URL, throttle and legacy hosts, plus
+     * the `credentials` sent now: the source is probed first (a failed probe saves nothing), then
+     * the credentials are stored encrypted ON THE CONNECTION, never on the draft. The draft then
+     * owns the connection, so discarding or expiring it deletes the connection too. A previous
+     * connection the draft created, and its discovery, are let go.
+     */
+    connect(id: string, input: {
+        version: number;
+        credentials: Record<string, string>;
+    }, options?: Call): Promise<PipelineDraft>;
+    /**
+     * Use one of the store's existing connections. Discarding the draft never deletes a connection
+     * that existed before any draft; one another draft created and still holds is this draft's too
+     * (`connection.createdByDraft` says so), and the last draft to let go of it unused deletes it.
+     */
+    useConnection(id: string, input: {
+        version: number;
+        connectionId: string;
+    }, options?: Call): Promise<PipelineDraft>;
+    /** Start the discovery of an import draft's connection; poll {@link PipelineDraftsModule.get}. */
+    discover(id: string, input: {
+        version: number;
+    }, options?: Call): Promise<PipelineDraft>;
+    /** Change one schema map of the draft's discovery. */
+    updateSchemaMap(id: string, entityType: string, input: UpdatePipelineDraftSchemaMapInput, options?: Call): Promise<PipelineDraft>;
+    /**
+     * Save the draft as a pipeline and delete the draft; with `startRun` also start its first run.
+     * A run that does not start leaves the pipeline in place and answers `runError`. Takes an
+     * `idempotencyKey`: a commit retried after a lost answer replays the first one.
+     */
+    commit(id: string, input: {
+        version: number;
+        startRun?: boolean;
+    }, options?: Call): Promise<CommittedPipelineDraft>;
+    /**
+     * Delete the draft, and the connection it created with its stored password unless a pipeline
+     * or another draft uses it.
+     */
+    discard(id: string, options?: Call): Promise<void>;
+}
+/** Data pipelines (imports and exports between the store and another system). */
+export interface IntegrationPipelinesModule {
+    drafts: PipelineDraftsModule;
+    /**
+     * What each importable entity type needs imported first, from the import writers themselves
+     * (the warnings' data; the words are yours).
+     */
+    importDependencies(options?: Call): Promise<ImportDependency[]>;
+}
+export declare function createIntegrationPipelinesModule(transport: Transport): IntegrationPipelinesModule;

package/dist/integrations/pipelines.js

@@ -0,0 +1,62 @@
+import { createPage, PLATFORM_PASSTHROUGH_KEYS, readRestPage, } from '@sixtyninecommerce/core';
+/**
+ * Every key whose VALUE is stored data, not DTO shape: the platform's passthrough set
+ * (`credentials`, `public_credentials`, `site_analysis`, `trigger_filter`, …) plus a schema map's
+ * jsonb columns, which carry the source's own field names and sample records. Converting them
+ * would rename a sample's `date_created` to `dateCreated`, and a `triggerFilter`'s `toState` would
+ * reach the reader as `to_state`, which it ignores.
+ */
+export const PIPELINE_DRAFT_PRESERVE_KEYS = new Set([
+    ...PLATFORM_PASSTHROUGH_KEYS,
+    'source_schema',
+    'sourceSchema',
+    'target_schema',
+    'targetSchema',
+    'sub_counts',
+    'subCounts',
+]);
+/**
+ * A creation probes the source over the network, and a commit creates the pipeline and may start
+ * its run: both outlast the SDK's 15-second default on a slow source.
+ */
+export const PIPELINE_DRAFT_SLOW_TIMEOUT_MS = 60_000;
+const DRAFTS = '/pipelines/drafts';
+const segment = (value) => encodeURIComponent(value);
+export function createIntegrationPipelinesModule(transport) {
+    const read = (path, options) => transport.rest('plugins', { method: 'GET', path }, { ...options, preserveKeys: PIPELINE_DRAFT_PRESERVE_KEYS });
+    const write = (method, path, body, options, timeoutMs) => transport.rest('plugins', { method, path, body }, {
+        ...options,
+        preserveKeys: PIPELINE_DRAFT_PRESERVE_KEYS,
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    });
+    async function list(options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: DRAFTS,
+            query: { after: options?.after, limit: options?.limit },
+        }, { ...options, preserveKeys: PIPELINE_DRAFT_PRESERVE_KEYS });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => list({ ...options, after: cursor }));
+    }
+    const drafts = {
+        list,
+        get: (id, options) => read(`${DRAFTS}/${segment(id)}`, options),
+        create: (input, options) => write('POST', DRAFTS, input, options),
+        update: (id, input, options) => write('PATCH', `${DRAFTS}/${segment(id)}`, input, options),
+        connect: (id, input, options) => write('POST', `${DRAFTS}/${segment(id)}/connection`, input, options, PIPELINE_DRAFT_SLOW_TIMEOUT_MS),
+        useConnection: (id, input, options) => write('POST', `${DRAFTS}/${segment(id)}/connection/existing`, input, options),
+        discover: (id, input, options) => write('POST', `${DRAFTS}/${segment(id)}/discover`, input, options),
+        updateSchemaMap: (id, entityType, input, options) => write('PATCH', `${DRAFTS}/${segment(id)}/schema-maps/${segment(entityType)}`, input, options),
+        commit: (id, input, options) => write('POST', `${DRAFTS}/${segment(id)}/commit`, input, options, PIPELINE_DRAFT_SLOW_TIMEOUT_MS),
+        async discard(id, options) {
+            await transport.rest('plugins', { method: 'DELETE', path: `${DRAFTS}/${segment(id)}`, expect: 'void' }, options);
+        },
+    };
+    return {
+        drafts,
+        async importDependencies(options) {
+            const body = await read('/pipelines/import-dependencies', options);
+            return body.data;
+        },
+    };
+}

package/dist/integrations/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * The shapes of `admin.integrations.pipelines` (headless spec §7 `pipelines.drafts`).
+ *
+ * Kept verbatim (stored data, never renamed): `triggerFilter`'s keys (reader field names such as
+ * `toState`), `siteAnalysis` and `publicCredentials` (the connector's own keys), and a schema
+ * map's `sourceSchema`, `targetSchema` and `subCounts`.
+ */
+export type PipelineDirection = 'import' | 'export';
+/** The wizard's steps before a commit; `import`/`done` come after one, when no draft exists. */
+export type PipelineDraftStep = 'direction' | 'connector' | 'credentials' | 'discovery' | 'review' | 'entities' | 'trigger' | 'configure' | 'preview';
+export type PipelineSyncPolicy = 'preserve_local' | 'always_source';
+export type PipelineScheduleType = 'one_time' | 'daily' | 'weekly' | 'custom';
+export type PipelineTriggerType = 'manual' | 'scheduled';
+/** One draft in the store's list. */
+export interface PipelineDraftSummary {
+    id: string;
+    direction: PipelineDirection;
+    step: PipelineDraftStep;
+    connectorType: string | null;
+    /** The pipeline's name, once the configure step gave it one. */
+    name: string | null;
+    connectionId: string | null;
+    discoveryId: string | null;
+    /** Send it back with the next change; a change made on an older one is refused 409. */
+    version: number;
+    /** Vendure User.id of whoever started it (an API token's own administrator for a token). */
+    createdByUserId: string;
+    updatedByUserId: string;
+    createdAt: string;
+    updatedAt: string;
+    /** 7 days after the last change; the draft answers 404 from then on. */
+    expiresAt: string;
+}
+/** The connection a draft holds. Never a credential: `publicCredentials` holds non-password fields only. */
+export interface PipelineDraftConnection {
+    id: string;
+    name: string;
+    connectorType: string;
+    sourceUrl: string;
+    status: string;
+    /** Soft-deleted on the Connections page since the draft took it: connect again. */
+    removed: boolean;
+    /** The draft (or another draft holding it) created it, so discarding the draft deletes it. */
+    createdByDraft: boolean;
+    siteAnalysis: Record<string, unknown> | null;
+    publicCredentials: Record<string, string> | null;
+    lastTestedAt: string | null;
+}
+export interface PipelineDraftDiscovery {
+    id: string;
+    /** `pending` → `running` → `completed` | `failed`. Poll the draft to follow it. */
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    source: string;
+    errorMessage: string | null;
+    warnings: string[];
+    detectedPlugins: string[];
+    startedAt: string | null;
+    completedAt: string | null;
+}
+export interface PipelineDraftFieldMapping {
+    sourceField: string;
+    sourcePath: string;
+    targetField: string;
+    targetPath: string;
+    transform: string | null;
+    confidence: number;
+    enabled: boolean;
+}
+export interface PipelineDraftSchemaMap {
+    id: string;
+    entityType: string;
+    enabled: boolean;
+    confidence: number;
+    entityCount: number;
+    subCounts: Record<string, number> | null;
+    /** As stored: `{ sourceEntityType, fields: [{ name, path, type, sampleValues, … }], notes }`. */
+    sourceSchema: Record<string, unknown>;
+    /** As stored: `{ targetEntityType, allowedTargetEntityTypes? }`. */
+    targetSchema: Record<string, unknown>;
+    fieldMappings: PipelineDraftFieldMapping[];
+}
+/** What an importable entity type needs imported first, from the import writers themselves. */
+export interface ImportDependency {
+    entityType: string;
+    dependsOn: string[];
+    /** It also depends on every type in the run starting with one of these (`cms_`). */
+    dependsOnPrefixes: string[];
+}
+/** An enabled entity type whose dependencies were discovered but switched off. */
+export interface ImportDependencyWarning {
+    entityType: string;
+    missing: string[];
+}
+/** A draft and everything the set-up screen shows, read now. */
+export interface PipelineDraft extends PipelineDraftSummary {
+    sourceUrl: string;
+    requestDelayMs: number;
+    /** As typed: a comma-separated list, parsed when the connection is created. */
+    legacyAssetHosts: string;
+    syncPolicy: PipelineSyncPolicy;
+    scheduleType: PipelineScheduleType;
+    cronExpression: string;
+    /** The schedule's zone; a new draft starts with the store's. */
+    timezone: string;
+    /**
+     * Whether the source's prices include tax. Until the merchant sets it (`sourcePricesIncludeTaxChosen`)
+     * it follows what the source reports when a connection is made, and before that the store's own
+     * setting.
+     */
+    sourcePricesIncludeTax: boolean;
+    sourcePricesIncludeTaxChosen: boolean;
+    stockLocationId: string | null;
+    triggerType: PipelineTriggerType;
+    exportEntityTypes: string[];
+    triggerFilter: Record<string, string>;
+    connection: PipelineDraftConnection | null;
+    discovery: PipelineDraftDiscovery | null;
+    schemaMaps: PipelineDraftSchemaMap[];
+    dependencies: ImportDependency[];
+    dependencyWarnings: ImportDependencyWarning[];
+    /** The name the configure step would give it now, in the store's zone. */
+    suggestedName: string | null;
+    /** The store's business time zone; null when it could not be read just now. */
+    storeTimeZone: string | null;
+}
+/** A field change. `version` is the draft's current one. */
+export interface UpdatePipelineDraftInput {
+    version: number;
+    direction?: PipelineDirection;
+    step?: PipelineDraftStep;
+    /** Starts the connection over, even for the same connector. */
+    connectorType?: string;
+    sourceUrl?: string;
+    requestDelayMs?: 50 | 100 | 200 | 300 | 500;
+    legacyAssetHosts?: string;
+    name?: string;
+    syncPolicy?: PipelineSyncPolicy;
+    scheduleType?: PipelineScheduleType;
+    /** A 5-part cron, or '' to clear it. */
+    cronExpression?: string;
+    timezone?: string;
+    sourcePricesIncludeTax?: boolean;
+    /** `null` clears it. */
+    stockLocationId?: string | null;
+    triggerType?: PipelineTriggerType;
+    exportEntityTypes?: string[];
+    triggerFilter?: Record<string, string>;
+}
+export interface UpdatePipelineDraftSchemaMapInput {
+    version: number;
+    enabled?: boolean;
+    fieldMappings?: PipelineDraftFieldMapping[];
+    /** Move a taxonomy to another target its schema map allows. */
+    targetEntityType?: string;
+}
+/** `commit`'s answer: the pipeline, and its first run when one was asked for. */
+export interface CommittedPipelineDraft {
+    pipeline: {
+        id: string;
+        name: string;
+        direction: PipelineDirection;
+        connectionId: string;
+        discoveryId: string | null;
+        scheduleType: PipelineScheduleType;
+        isActive: boolean;
+    };
+    run: {
+        id: string;
+        status: string;
+    } | null;
+    /** The pipeline was saved but its first run did not start; start it from the pipeline. */
+    runError: {
+        code: string;
+        message: string;
+    } | null;
+}

package/dist/integrations/types.js

@@ -0,0 +1,8 @@
+/**
+ * The shapes of `admin.integrations.pipelines` (headless spec §7 `pipelines.drafts`).
+ *
+ * Kept verbatim (stored data, never renamed): `triggerFilter`'s keys (reader field names such as
+ * `toState`), `siteAnalysis` and `publicCredentials` (the connector's own keys), and a schema
+ * map's `sourceSchema`, `targetSchema` and `subCounts`.
+ */
+export {};

package/dist/jobs/bulk-action-run.d.ts

@@ -2,7 +2,7 @@ import { type Transport } from '@sixtyninecommerce/core';
 import type { Call } from '../types.js';
 import { type JobHandle } from './index.js';
 /**
- * A bulk action run (`catalog.products.bulk`, and the orders kind of a later release): one call
+ * A bulk action run (`catalog.products.bulk`, `orders.bulk`): one call
  * that acts on many records of the store as a job, each record through its single door and
  * reported on its own. Read back through the Admin API's `bulkActionRun`.
  */
@@ -62,4 +62,13 @@ export declare function readBulkActionRun<Action extends string>(transport: Tran
  * when waiting itself cannot go on: `JOB_WAIT_TIMEOUT`, an aborted signal, or a read refused for
  * a reason polling cannot fix.
  */
-export declare function bulkActionHandle<Action extends string>(transport: Transport, runId: string, options?: Call): JobHandle<BulkActionRun<Action>>;
+export declare function bulkActionHandle<Action extends string, Run extends RunProgress = BulkActionRun<Action>>(transport: Transport, runId: string, options?: Call, 
+/** How one read is made, when the kind selects more than the shared fields (orders). */
+read?: (runId: string, call: Call) => Promise<Run>): JobHandle<Run>;
+/** What waiting on a run reads of it, whatever its kind. */
+interface RunProgress {
+    status: string;
+    done: number;
+    total: number;
+}
+export {};

package/dist/jobs/bulk-action-run.js

@@ -40,15 +40,14 @@ export function readBulkActionRun(transport, runId, options) {
  * when waiting itself cannot go on: `JOB_WAIT_TIMEOUT`, an aborted signal, or a read refused for
  * a reason polling cannot fix.
  */
-export function bulkActionHandle(transport, runId, options) {
+export function bulkActionHandle(transport, runId, options, 
+/** How one read is made, when the kind selects more than the shared fields (orders). */
+read = (id, call) => readBulkActionRun(transport, id, call)) {
     return {
         runId,
         wait(waitOptions) {
             return pollUntilTerminal({
-                read: (signal) => readBulkActionRun(transport, runId, {
-                    ...options,
-                    ...(signal ? { signal } : {}),
-                }),
+                read: (signal) => read(runId, { ...options, ...(signal ? { signal } : {}) }),
                 isTerminal: (run) => TERMINAL_BULK_ACTION_STATUSES.includes(run.status),
                 onTimeout: (seen) => bulkWaitTimeout(runId, seen),
                 ...waitOptions,

package/dist/orders/bulk.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `admin.orders.bulk`, `admin.orders.bulkRun` and `admin.orders.delete` (headless spec §7
+ * `orders.bulk`, plan W9-43; rulings G19, G28, G29).
+ */
+import { type Transport } from '@sixtyninecommerce/core';
+import { type BulkActionItem, type BulkActionRun } from '../jobs/bulk-action-run.js';
+import type { JobHandle } from '../jobs/index.js';
+import type { Call } from '../types.js';
+/** What each order of one bulk run gets. */
+export type OrderBulkAction = 'TRANSITION' | 'CANCEL' | 'DELETE' | 'MARK_PAID';
+export declare const ORDER_BULK_ACTIONS: readonly OrderBulkAction[];
+/** The engine's bound on one bulk run (`MAX_BULK_ACTION_ITEMS`). Split a larger selection. */
+export declare const MAX_BULK_ORDERS = 50;
+/**
+ * The states a TRANSITION never names, each with its own action or door: `Cancelled` (CANCEL),
+ * `PaymentSettled` (MARK_PAID), `Modifying` (the order edit) and `AddingItems`.
+ */
+export declare const ORDER_BULK_TRANSITION_REFUSED: readonly string[];
+export interface OrderBulkInput {
+    action: OrderBulkAction;
+    /** 1 to {@link MAX_BULK_ORDERS} orders of the store, each named once. */
+    orderIds: readonly string[];
+    /** TRANSITION only, and required there: the state each order moves to. */
+    toState?: string;
+    /** CANCEL only: the reason recorded on each cancelled order. */
+    reason?: string;
+}
+/** One payment a MARK_PAID item acted on. */
+export interface OrderBulkCapture {
+    paymentId: string;
+    /** The payment's state after the capture: `Settled`, or what a decline left. */
+    state: string;
+    /**
+     * Why it was not captured, null when it was: `SETTLE_PAYMENT_ERROR` (declined; `message`
+     * quotes the provider), `PAYMENT_NOT_AUTHORIZED` (captured by someone else meanwhile),
+     * `PAYMENT_METHOD_UNAVAILABLE` (its method is switched off, not on this store, or no longer installed; nothing asked),
+     * `IDEMPOTENCY_IN_PROGRESS` (a capture under the same request may still run: check the order
+     * before trying again), `IDEMPOTENCY_OUTCOME_UNKNOWN` (the provider was asked and its answer
+     * was lost: reconcile with the provider, never retry blind), or a fault's code.
+     */
+    code: string | null;
+    message: string | null;
+}
+/** One order's outcome. */
+export interface OrderBulkItem extends BulkActionItem {
+    /**
+     * When `code` is `ORDER_ACTION_UNAVAILABLE`: why the order's own status (`orders.status`) did
+     * not offer the action, in that read's vocabulary (`STATE`, `INVOICE_LOCKED`, `SHOPPER_CART`,
+     * `HAS_RECORDS`, `UNITS_SHIPPED`, `ACTIVE_FULFILLMENT`, `NOTHING_TO_CANCEL`, …). Null otherwise.
+     */
+    reasonCode: string | null;
+    /** MARK_PAID: each payment the order's item acted on, in order. Null for other actions. */
+    captured: OrderBulkCapture[] | null;
+}
+/** A bulk order run, as `wait()` and `bulkRun()` answer it. */
+export type OrderBulkRun = Omit<BulkActionRun<OrderBulkAction>, 'items'> & {
+    items: OrderBulkItem[];
+};
+export declare const BULK_ORDER_ACTION_MUTATION = "\n  mutation BulkOrderAction($input: BulkOrderActionInput!, $idempotencyKey: String) {\n    bulkOrderAction(input: $input, idempotencyKey: $idempotencyKey) {\n      runId\n    }\n  }\n";
+/**
+ * The run read with the order fields. Its own document, so `catalog.products.bulkRun` keeps
+ * selecting only what an engine without the orders kind has.
+ */
+export declare const ORDER_BULK_RUN_QUERY = "\n  query OrderBulkRun($runId: ID!) {\n    bulkActionRun(runId: $runId) {\n      id\n      kind\n      action\n      status\n      total\n      done\n      items {\n        id\n        status\n        code\n        message\n        newId\n        reasonCode\n        captured {\n          paymentId\n          state\n          code\n          message\n        }\n      }\n      failure {\n        code\n        message\n      }\n    }\n  }\n";
+export declare const DELETE_ORDER_MUTATION = "\n  mutation DeleteOrder($orderId: ID!) {\n    deleteOrder(orderId: $orderId) {\n      result\n      message\n    }\n  }\n";
+/** One read of a bulk order run. A run of another store, or a missing one, is `NotFoundError`. */
+export declare function readOrderBulkRun(transport: Transport, runId: string, options?: Call): Promise<OrderBulkRun>;
+/** `orders.bulk`; see `OrdersModule.bulk`. */
+export declare function bulkOrders(transport: Transport, input: OrderBulkInput, options?: Call): Promise<JobHandle<OrderBulkRun>>;
+/**
+ * `orders.delete`; see `OrdersModule.delete`. The engine's `NOT_DELETED` is raised as every other
+ * `*_NOT_DELETED` refusal of this SDK is (`assertDeleted`): a `ConflictError` with the engine's own
+ * reason.
+ */
+export declare function deleteOrder(transport: Transport, orderId: string, options?: Call): Promise<void>;

package/dist/orders/bulk.js

@@ -0,0 +1,150 @@
+/**
+ * `admin.orders.bulk`, `admin.orders.bulkRun` and `admin.orders.delete` (headless spec §7
+ * `orders.bulk`, plan W9-43; rulings G19, G28, G29).
+ */
+import { idempotencyKey, ValidationError } from '@sixtyninecommerce/core';
+import { assertDeleted, fieldOf } from '../catalog/types.js';
+import { bulkActionHandle, } from '../jobs/bulk-action-run.js';
+export const ORDER_BULK_ACTIONS = [
+    'TRANSITION',
+    'CANCEL',
+    'DELETE',
+    'MARK_PAID',
+];
+/** The engine's bound on one bulk run (`MAX_BULK_ACTION_ITEMS`). Split a larger selection. */
+export const MAX_BULK_ORDERS = 50;
+/**
+ * The states a TRANSITION never names, each with its own action or door: `Cancelled` (CANCEL),
+ * `PaymentSettled` (MARK_PAID), `Modifying` (the order edit) and `AddingItems`.
+ */
+export const ORDER_BULK_TRANSITION_REFUSED = [
+    'Cancelled',
+    'PaymentSettled',
+    'Modifying',
+    'AddingItems',
+];
+export const BULK_ORDER_ACTION_MUTATION = /* GraphQL */ `
+  mutation BulkOrderAction($input: BulkOrderActionInput!, $idempotencyKey: String) {
+    bulkOrderAction(input: $input, idempotencyKey: $idempotencyKey) {
+      runId
+    }
+  }
+`;
+/**
+ * The run read with the order fields. Its own document, so `catalog.products.bulkRun` keeps
+ * selecting only what an engine without the orders kind has.
+ */
+export const ORDER_BULK_RUN_QUERY = /* GraphQL */ `
+  query OrderBulkRun($runId: ID!) {
+    bulkActionRun(runId: $runId) {
+      id
+      kind
+      action
+      status
+      total
+      done
+      items {
+        id
+        status
+        code
+        message
+        newId
+        reasonCode
+        captured {
+          paymentId
+          state
+          code
+          message
+        }
+      }
+      failure {
+        code
+        message
+      }
+    }
+  }
+`;
+export const DELETE_ORDER_MUTATION = /* GraphQL */ `
+  mutation DeleteOrder($orderId: ID!) {
+    deleteOrder(orderId: $orderId) {
+      result
+      message
+    }
+  }
+`;
+function refuse(message) {
+    return new ValidationError({
+        code: 'BULK_ACTION_INPUT_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+    });
+}
+/** The engine's own checks of a submit (`BULK_ACTION_INPUT_INVALID`), before sending. */
+function assertBulkInput(input) {
+    if (!ORDER_BULK_ACTIONS.includes(input?.action)) {
+        throw refuse(`"${String(input?.action)}" is not a bulk order action: ${ORDER_BULK_ACTIONS.join(', ')}. Nothing was sent.`);
+    }
+    const ids = input.orderIds;
+    if (!Array.isArray(ids) || ids.length === 0) {
+        throw refuse('Name at least one order. Nothing was sent.');
+    }
+    if (ids.length > MAX_BULK_ORDERS) {
+        throw refuse(`Name at most ${String(MAX_BULK_ORDERS)} orders in one bulk action; this one named ${String(ids.length)}. Split the selection into several actions. Nothing was sent.`);
+    }
+    if (new Set(ids.map((id) => String(id).toLowerCase())).size !== ids.length) {
+        throw refuse('The selection names an order more than once. Name each order once. Nothing was sent.');
+    }
+    const toState = input.toState?.trim() ?? '';
+    if (input.action === 'TRANSITION') {
+        if (toState === '')
+            throw refuse('Name the status to move the orders to. Nothing was sent.');
+        if (ORDER_BULK_TRANSITION_REFUSED.includes(toState)) {
+            throw refuse(`Orders are not moved to "${toState}" by a status change${toState === 'Cancelled'
+                ? ': use CANCEL'
+                : toState === 'PaymentSettled'
+                    ? ': use MARK_PAID'
+                    : ''}. Nothing was sent.`);
+        }
+    }
+    else if (toState !== '') {
+        throw refuse(`toState is only for TRANSITION, not ${input.action}. Nothing was sent.`);
+    }
+    if ((input.reason?.trim() ?? '') !== '' && input.action !== 'CANCEL') {
+        throw refuse(`reason is only for CANCEL, not ${input.action}. Nothing was sent.`);
+    }
+}
+/** One read of a bulk order run. A run of another store, or a missing one, is `NotFoundError`. */
+export function readOrderBulkRun(transport, runId, options) {
+    return fieldOf(transport, ORDER_BULK_RUN_QUERY, 'bulkActionRun', { runId }, options);
+}
+/** `orders.bulk`; see `OrdersModule.bulk`. */
+export async function bulkOrders(transport, input, options) {
+    assertBulkInput(input);
+    // Minted when the caller gave none, so a retry of THIS call answers the same run instead of
+    // starting a second one (and capturing nothing twice).
+    const key = options?.idempotencyKey ?? idempotencyKey();
+    const toState = input.toState?.trim();
+    const reason = input.reason?.trim();
+    const { runId } = await fieldOf(transport, BULK_ORDER_ACTION_MUTATION, 'bulkOrderAction', {
+        input: {
+            action: input.action,
+            orderIds: [...input.orderIds],
+            // Omitted, never null, when not given: an absent option stays off the wire.
+            ...(toState ? { toState } : {}),
+            ...(reason ? { reason } : {}),
+        },
+        idempotencyKey: key,
+    }, { ...options, idempotencyKey: key });
+    return bulkActionHandle(transport, runId, options, (id, call) => readOrderBulkRun(transport, id, call));
+}
+/**
+ * `orders.delete`; see `OrdersModule.delete`. The engine's `NOT_DELETED` is raised as every other
+ * `*_NOT_DELETED` refusal of this SDK is (`assertDeleted`): a `ConflictError` with the engine's own
+ * reason.
+ */
+export async function deleteOrder(transport, orderId, options) {
+    assertDeleted('ORDER_NOT_DELETED', [
+        await fieldOf(transport, DELETE_ORDER_MUTATION, 'deleteOrder', { orderId }, options),
+    ]);
+}