@sixtyninecommerce/admin 0.8.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

@@ -0,0 +1,74 @@
+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`, `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`.
+ */
+/**
+ * `QUEUED` → `RUNNING` → `SUCCEEDED` (every item ran and has its own outcome, a `FAILED` item
+ * included), or `FAILED` (the run stopped before every item had an outcome; `items` lists the ones
+ * it reached), or `CANCELLED` (the items after the cancel did not run; `items` lists every one
+ * the run reached, the one running when the cancel landed included). A run cancelled while an item
+ * ran stays `RUNNING` until that item has its outcome. A string on the wire: a newer engine may add
+ * a status.
+ */
+export type BulkActionRunStatus = 'QUEUED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
+/** A run nothing more will happen to. */
+export declare const TERMINAL_BULK_ACTION_STATUSES: readonly string[];
+/** One record's outcome. */
+export interface BulkActionItem {
+    /** The record (a product id for `products.bulk`). */
+    id: string;
+    status: 'OK' | 'FAILED' | (string & {});
+    /**
+     * When `FAILED`: the single door's OWN code, the one a call of that door would have raised:
+     * `ENTITY_NOT_FOUND` (not in this store, another store's included), `SHARED_PRODUCT_NOT_ALLOWED`,
+     * `MANAGED_BY_ORGANIZATION`, `FIELD_GROUP_LOCKED`, `EXTERNAL_LINE_CARRIER_PROTECTED`,
+     * `PRODUCT_NOT_DELETED`, … Null when `OK`.
+     */
+    code: string | null;
+    /** When `FAILED`: the door's sentence. Null when `OK`. */
+    message: string | null;
+    /** What the action made: the new product of a `CLONE`. Null otherwise. */
+    newId: string | null;
+}
+export interface BulkActionRun<Action extends string = string> {
+    /** The run's id: the receipt `bulk()` answered. */
+    id: string;
+    /** `products.bulk`. */
+    kind: string;
+    action: Action | (string & {});
+    status: BulkActionRunStatus | (string & {});
+    /** How many records the run was asked to act on. */
+    total: number;
+    /** How many of them have an outcome. */
+    done: number;
+    /** One outcome per record reached, in the order the records were named. */
+    items: BulkActionItem[];
+    /** Why the RUN stopped early (`FAILED`); each item keeps its own code. Null otherwise. */
+    failure: {
+        code: string;
+        message: string;
+    } | null;
+}
+export declare const BULK_ACTION_RUN_QUERY = "\n  query BulkActionRun($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      }\n      failure {\n        code\n        message\n      }\n    }\n  }\n";
+/** One read of a run. A run of another store, or one that does not exist, is `NotFoundError`. */
+export declare function readBulkActionRun<Action extends string>(transport: Transport, runId: string, options?: Call): Promise<BulkActionRun<Action>>;
+/**
+ * The handle a bulk submit answers. `wait()` polls the run until it is terminal and resolves with
+ * it WHATEVER the ending (a run whose items all failed still `SUCCEEDED` as a run); it throws only
+ * 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, 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

@@ -0,0 +1,69 @@
+import { TransportError } from '@sixtyninecommerce/core';
+import { fieldOf } from '../catalog/types.js';
+import { pollUntilTerminal } from './index.js';
+/** A run nothing more will happen to. */
+export const TERMINAL_BULK_ACTION_STATUSES = [
+    'SUCCEEDED',
+    'FAILED',
+    'CANCELLED',
+];
+export const BULK_ACTION_RUN_QUERY = /* GraphQL */ `
+  query BulkActionRun($runId: ID!) {
+    bulkActionRun(runId: $runId) {
+      id
+      kind
+      action
+      status
+      total
+      done
+      items {
+        id
+        status
+        code
+        message
+        newId
+      }
+      failure {
+        code
+        message
+      }
+    }
+  }
+`;
+/** One read of a run. A run of another store, or one that does not exist, is `NotFoundError`. */
+export function readBulkActionRun(transport, runId, options) {
+    return fieldOf(transport, BULK_ACTION_RUN_QUERY, 'bulkActionRun', { runId }, options);
+}
+/**
+ * The handle a bulk submit answers. `wait()` polls the run until it is terminal and resolves with
+ * it WHATEVER the ending (a run whose items all failed still `SUCCEEDED` as a run); it throws only
+ * 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, 
+/** 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) => read(runId, { ...options, ...(signal ? { signal } : {}) }),
+                isTerminal: (run) => TERMINAL_BULK_ACTION_STATUSES.includes(run.status),
+                onTimeout: (seen) => bulkWaitTimeout(runId, seen),
+                ...waitOptions,
+            });
+        },
+    };
+}
+function bulkWaitTimeout(runId, run) {
+    const at = run
+        ? `while it was ${run.status} (${String(run.done)} of ${String(run.total)} done)`
+        : 'without reading it successfully';
+    return new TransportError({
+        code: 'JOB_WAIT_TIMEOUT',
+        message: `Stopped waiting for bulk run ${runId} ${at}. The run may still be going: read it again with its runId to follow it.`,
+        status: 0,
+        service: 'vendure',
+        retryable: true,
+    });
+}

package/dist/locations/index.d.ts

@@ -81,7 +81,7 @@ export interface LocationProfile {
  *
  * `address` is the one exception, because it writes through to the stock
  * location's own field: omit it to leave that field alone, pass `null` to clear
- * it.
+ * it. An address equal to the stored one writes nothing to that field.
  */
 export interface UpsertLocationProfileInput {
     stockLocationId: string;
@@ -107,7 +107,11 @@ export interface UpsertLocationProfileInput {
  * cannot probe another store's ids; `LOCATION_CODE_TAKEN` (→ `ConflictError`);
  * and `INVALID_LOCATION_CODE` / `INVALID_LOCATION_NAME` /
  * `INVALID_LOCATION_PHONE` / `INVALID_TIMEZONE` / `INVALID_OPENING_HOURS` /
- * `INVALID_ADDRESS` (→ `ValidationError`).
+ * `INVALID_ADDRESS` (→ `ValidationError`); and `LOCATION_NOT_ALLOWED`
+ * (→ `PermissionDeniedError`) when `upsert` changes or clears the `address` of a
+ * location a token or app installation restricted with `locationIds` does not
+ * hold. The address is the location's parcel sender. Sending the stored address
+ * back unchanged passes, and the profile's other fields are not restricted.
  *
  * `LOCATION_NOT_IN_CHANNEL` is NOT one of these: it belongs to the two places
  * that take a location id from outside this surface — `apiTokens.create`/

package/dist/meta/index.d.ts

@@ -24,11 +24,21 @@ export interface MetaCatalogLabels {
     subscriptionStatus: LabelMap;
     quoteStatus: LabelMap;
     settlementMethod: LabelMap;
+    /** What a RETAIL credit note did, keyed by its `kind`. */
     creditNoteKind: LabelMap;
+    /**
+     * The same four kinds on the accounts-receivable ledger, in its own words:
+     * there `return` also covers a settled refund and a manual credit, so the
+     * retail "Return credited" would mislabel it. Pick the map by the note's
+     * ledger. Served by a platform from this release on.
+     */
+    arCreditNoteKind: LabelMap;
     auditService: LabelMap;
     auditCategory: LabelMap;
     auditEventOutcome: LabelMap;
     auditCallOutcome: LabelMap;
+    /** Who sends a notification event's email: `platform` or `none` (`admin.tenant.notifications`). */
+    notificationSender: LabelMap;
     /**
      * A vocabulary added after this SDK release arrives camelised, with its map
      * untouched.
@@ -59,10 +69,32 @@ export interface RoleTemplate {
     permissions: string[];
 }
 export interface ApiTokenTemplate {
+    /**
+     * The preset's stable key, accepted by `admin.apiTokens.create({ templateKeys })`.
+     * Shipped presets: `content`, `forms`, `catalog` (catalogue CRUD — the spec's
+     * "catalog-writer"), `readonly`, `external-tracking`, `platform-events` (event
+     * feed, read-only), `audit`, `pos`, `order-entry` (place and recover orders,
+     * caller-priced lines, find or create the customer), `customers` (customer CRUD
+     * without delete or erasure), `stock` (stock reads, adjustments and transfers
+     * through `AdjustStock`; it cannot edit locations or their settings), `events` (the
+     * event feed plus managing webhook subscriptions: `ReadPlatformEvents` +
+     * `ManageEventSubscriptions`), `full`, `sandbox-full` (for CI against a
+     * sandbox store: Full access plus the event feed and subscriptions, the audit
+     * trail, POS, tracking and stock moves; never user, token or app management)
+     * and `custom`. Read the live list from `meta.catalog()`; this one is
+     * documentation.
+     */
     key: string;
     label: string;
     description: string;
     permissions: string[];
+    /**
+     * `true` on a preset minted on a SANDBOX store only (`sandbox-full`);
+     * `apiTokens.create({ templateKeys })` refuses it elsewhere with
+     * `SANDBOX_ONLY_TEMPLATE`. A picker hides such a preset on a live store.
+     * Absent on every other preset, and on a platform older than this field.
+     */
+    sandbox?: boolean;
 }
 export interface MetaCatalogPermissions {
     /** Every permission name the Admin API registers. */

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>;