@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/dist/integrations/price-import.d.ts

@@ -0,0 +1,223 @@
+/**
+ * The bulk price import (headless spec §9.2 `integrations`: "price import, AI conversion"): the
+ * plugins service's `POST /prices/import`, and its AI conversion of any supplier file into a
+ * document that import accepts (`POST /prices/import/ai/conversions`, then the
+ * `price-import-ai-conversion` progress stream).
+ *
+ * A thin wrapper over the routes the dashboard has always used (ruling G119): the same documents,
+ * the same tax handling, the same dry run and row selection. A dry run and an import are two
+ * methods because an assistant asks before an import and never before a dry run (G81).
+ */
+import { type PlatformError, type PriceImportAiConversionResult, type PriceImportAiConversionStep, type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** What the plugins service reads a price document as. */
+export type PriceImportFormat = 'csv' | 'json' | 'xml';
+/** Whether the amounts in a document include tax. */
+export type PriceImportTaxMode = 'inclusive' | 'exclusive';
+/** A price document, as its text. */
+export interface PriceImportDocument {
+    format: PriceImportFormat;
+    /** The whole document, at most 6,000,000 characters and 5,000 data rows. */
+    content: string;
+    /**
+     * Whether the document's amounts include tax. Left out, they are read in the store's own tax
+     * mode and nothing is converted. Given and different from the store's, each amount is converted
+     * at its variant's tax rate (`taxConverted` on the row).
+     */
+    fileTaxMode?: PriceImportTaxMode;
+}
+export interface PriceImportRunInput extends PriceImportDocument {
+    /**
+     * The rows to write, by `rowNumber` as {@link PriceImportModule.preview} answered them. Rows
+     * left out answer `skipped`, so `[]` writes nothing. Left out entirely, every row the preview
+     * marks `updated` is written (never a `duplicate`). At most 5,000.
+     */
+    selectedRows?: readonly number[];
+}
+/**
+ * One row's outcome.
+ * - `updated`: a variant matched and its price differs; written by {@link PriceImportModule.run}.
+ * - `unchanged`: the price is already the stored one.
+ * - `not_found`: no variant of the store has this SKU.
+ * - `duplicate`: an earlier row sets the same SKU and currency (`duplicateOfRow`); a preview only.
+ *   A selected duplicate that is written answers `updated`.
+ * - `invalid`: the row's content failed validation (its `message` says why); never written.
+ * - `skipped`: an import only: a row left out of `selectedRows`.
+ * - `error`: the row cannot be written (an ambiguous SKU, a tax rate that cannot be resolved, a
+ *   Price field group an app or API token owns) or its write failed; `message` says why.
+ */
+export type PriceImportRowStatus = 'updated' | 'unchanged' | 'not_found' | 'duplicate' | 'invalid' | 'skipped' | 'error';
+export interface PriceImportRow {
+    /**
+     * Where the row is in the document: its line in a CSV (the header is line 1, so the first data
+     * row is 2; blank lines count), its position among the entries of a JSON or XML document (from
+     * 1). `selectedRows` names rows by it.
+     */
+    rowNumber: number;
+    /** Empty when the row carried no SKU that could be read (only on `invalid`). */
+    sku: string;
+    /** The row's currency, or the store's default when the document named none. */
+    currency: string;
+    status: PriceImportRowStatus;
+    /** The amount as the document states it, in major units. */
+    amount: number;
+    /** The stored price in minor units, in the store's tax mode; null when no variant matched. */
+    oldPrice: number | null;
+    /** The price in minor units, in the store's tax mode, that is or would be written. */
+    newPrice: number | null;
+    /** True when the document's tax mode differs from the store's and the amount was converted. */
+    taxConverted: boolean;
+    /** The earlier row with the same SKU and currency, or null. */
+    duplicateOfRow: number | null;
+    message?: string;
+}
+export interface PriceImportSummary {
+    /** Data rows read from the document. */
+    total: number;
+    updated: number;
+    unchanged: number;
+    notFound: number;
+    duplicate: number;
+    invalid: number;
+    skipped: number;
+    errored: number;
+}
+/** What a dry run or an import answers: per row, and summed. */
+export interface PriceImportReport {
+    dryRun: boolean;
+    /** Whether the store's prices include tax: the basis of `oldPrice` and `newPrice`. */
+    channelPricesIncludeTax: boolean;
+    channelDefaultCurrency: string;
+    /** The basis the amounts were read in: the one sent, else the store's own. */
+    fileTaxMode: PriceImportTaxMode;
+    summary: PriceImportSummary;
+    results: PriceImportRow[];
+}
+/** A file handed to the AI conversion. */
+export interface PriceImportConvertInput {
+    /**
+     * The supplier's file: `.xlsx`, `.xlsm`, `.csv`, `.tsv`, `.txt`, `.json`, `.xml`, `.md`, `.pdf`
+     * or `.docx`, at most 20 MB (a workbook 8 MB). The service reads the format from the name.
+     */
+    file: Blob;
+    /** The file's name. Defaults to a `File`'s own; a bare `Blob` needs one. */
+    fileName?: string;
+}
+/** The upload's receipt: follow the conversion with its id. */
+export interface PriceImportUpload {
+    conversionId: string;
+    /** The name the service stored, without any path. */
+    fileName: string;
+}
+/** The converted document, with what the converter read. `document` goes to `preview` as `json`. */
+export type PriceImportConversion = PriceImportAiConversionResult;
+export type PriceImportConversionStep = PriceImportAiConversionStep;
+/** One progress line of a conversion. */
+export interface PriceImportConversionProgress {
+    step: PriceImportConversionStep;
+    message: string;
+}
+export interface PriceImportFollowOptions {
+    /** Aborting it closes the stream; `follow` then throws `REQUEST_ABORTED`. */
+    signal?: AbortSignal;
+    /** Called with each progress line, in order. A callback that throws ends `follow` with its error. */
+    onProgress?: (progress: PriceImportConversionProgress) => void;
+    /** Give up after this long without a byte, keepalives included. Default 45000 ms. */
+    idleTimeoutMs?: number;
+    /** Deadline for the stream's response headers. Defaults to the client's own timeout. */
+    connectTimeoutMs?: number;
+}
+/**
+ * The store's bulk price import, and the AI conversion that turns any supplier file into a
+ * document it accepts.
+ *
+ * - **Every method needs `UpdateCatalog` or `UpdateProduct`** on the store (either is enough,
+ *   so no method carries a `@permission` tag), and acts on the
+ *   client's store (`admin.withTenant(...)` for another one). The prices are written through the
+ *   Admin API with the caller's own credential, so the engine's rules for a price write apply
+ *   to each row.
+ * - **A document the service cannot read at all is refused whole, and nothing is written:** a
+ *   `BusinessRuleError` (422) coded `PRICE_IMPORT_FORMAT_ERROR` whose `details[]` name each
+ *   problem (`field` is `header`, `document` or `row N`; at most 100 entries, the last one coded
+ *   `TRUNCATED` and counting the rest when there are more). More than 5,000 data rows is one of
+ *   those problems (`TOO_MANY_ROWS`). A row whose CONTENT is wrong is not a refusal: it comes
+ *   back `invalid`.
+ * - **The service records an `idempotencyKey` and acts on nothing**: two calls are two imports.
+ */
+export interface PriceImportModule {
+    /**
+     * Read a document and say, row by row, what an import would do. Nothing is written.
+     *
+     * Refused: `PRICE_IMPORT_FORMAT_ERROR` (422, see the module), `VALIDATION_FAILED` (400) for a
+     * body the service does not accept (an unknown format, an empty document).
+     *
+     * @effect read
+     */
+    preview(document: PriceImportDocument, options?: Call): Promise<PriceImportReport>;
+    /**
+     * Write the document's prices: the rows `selectedRows` names, or every `updated` row when it
+     * names none. Rows are written per variant as they come, so a row that fails (`error`) does
+     * not undo the others; the report says which were written. A selection naming two rows that
+     * set the same SKU and currency is refused whole, `PRICE_IMPORT_SELECTION_CONFLICT` (422, one
+     * `details[]` entry per pair), and nothing is written.
+     *
+     * The prices are what customers pay from the moment each is written, and the import cannot be
+     * undone except by importing the old prices again (each row's `oldPrice`). A timeout or a
+     * dropped connection does not say whether the prices were written: run {@link preview} with
+     * the same document, where rows already at their new price read `unchanged`, before repeating.
+     *
+     * @effect irreversible
+     */
+    run(input: PriceImportRunInput, options?: Call): Promise<PriceImportReport>;
+    /**
+     * Upload a supplier file for the AI conversion and answer the id to {@link follow}. Nothing is
+     * converted until it is followed, and nothing is ever written: the converted document goes to
+     * {@link preview} and {@link run} like any other. The upload is kept for a few minutes and
+     * read once.
+     *
+     * Refused before sending: a file with no name (`PRICE_IMPORT_FILE_NAME_REQUIRED`, 400). By the
+     * service: a file with no extension, a legacy `.xls`, another unsupported type, an empty file
+     * or a workbook over 8 MB (400, the sentence says which and what to do); a file over 20 MB
+     * (413); too many uploads waiting, on the service (`AI_CONVERSION_CAPACITY_REACHED`) or for
+     * this store (`AI_CONVERSION_CHANNEL_BACKLOG`), both 503 and worth repeating later. Never
+     * retried by the client: a repeat stores the file twice.
+     *
+     * @effect write
+     */
+    convert(input: PriceImportConvertInput, options?: Call): Promise<PriceImportUpload>;
+    /**
+     * Run the conversion of an upload and follow it to its end: progress lines through
+     * `onProgress`, then the converted document. The service sends the file's text to the
+     * platform's AI provider while this runs (30 seconds to 3 minutes). Abort it to stop the
+     * conversion. It acts on the client's store: an upload of another store answers
+     * `AI_IMPORT_NOT_FOUND`.
+     *
+     * The conversion's own refusal is thrown with its code:
+     * - `AI_IMPORT_NOT_FOUND` (`NotFoundError`): the upload expired, was already followed, or is
+     *   another store's;
+     * - `AI_IMPORT_UNSUPPORTED_FILE`, `AI_IMPORT_EXTRACTION_FAILED` (a file with no text: a scan,
+     *   a protected workbook), `AI_IMPORT_NO_PRICES_FOUND`, `AI_IMPORT_TOO_MANY_ROWS`
+     *   (`BusinessRuleError`);
+     * - `AI_IMPORT_BUSY` (`RateLimitedError`): the service is converting as many files as it can;
+     * - `AI_IMPORT_NOT_CONFIGURED` (`UpstreamError`, 503): this deployment has no AI provider;
+     * - `AI_IMPORT_LLM_FAILED`, `AI_IMPORT_STREAM_FAILED` and any code this client does not know
+     *   (`UpstreamError`, 502).
+     *
+     * The stream itself can fail with `PROGRESS_STREAM_CLOSED`, `PROGRESS_STREAM_STALLED`,
+     * `MALFORMED_RESPONSE` or `REQUEST_ABORTED`; an id that is not a conversion id is refused
+     * before anything is sent (`PROGRESS_STREAM_ID_INVALID`, 400). Nothing here is retryable: the
+     * upload is gone once its conversion ends, so convert the file again.
+     *
+     * @effect read
+     */
+    follow(conversionId: string, options?: PriceImportFollowOptions): Promise<PriceImportConversion>;
+}
+/** A conversion's terminal `error` event as the error {@link PriceImportModule.follow} throws. */
+export declare function conversionRefusal(code: string, message: string): PlatformError;
+/**
+ * The deadlines `preview` and `run` give the service, longer than the client's default: a
+ * 5,000-row import is measured in tens of seconds (the dashboard has always allowed these).
+ */
+export declare const PRICE_IMPORT_PREVIEW_TIMEOUT_MS = 30000;
+export declare const PRICE_IMPORT_RUN_TIMEOUT_MS = 120000;
+export declare function createPriceImportModule(transport: Transport): PriceImportModule;

package/dist/integrations/price-import.js

@@ -0,0 +1,124 @@
+/**
+ * The bulk price import (headless spec §9.2 `integrations`: "price import, AI conversion"): the
+ * plugins service's `POST /prices/import`, and its AI conversion of any supplier file into a
+ * document that import accepts (`POST /prices/import/ai/conversions`, then the
+ * `price-import-ai-conversion` progress stream).
+ *
+ * A thin wrapper over the routes the dashboard has always used (ruling G119): the same documents,
+ * the same tax handling, the same dry run and row selection. A dry run and an import are two
+ * methods because an assistant asks before an import and never before a dry run (G81).
+ */
+import { errorForStatus, openProgressStream, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
+/** The HTTP status each conversion refusal stands for, which picks its error class. */
+const CONVERSION_REFUSAL_STATUS = {
+    AI_IMPORT_NOT_FOUND: 404,
+    AI_IMPORT_UNSUPPORTED_FILE: 422,
+    AI_IMPORT_EXTRACTION_FAILED: 422,
+    AI_IMPORT_NO_PRICES_FOUND: 422,
+    AI_IMPORT_TOO_MANY_ROWS: 422,
+    AI_IMPORT_BUSY: 429,
+    AI_IMPORT_NOT_CONFIGURED: 503,
+    AI_IMPORT_LLM_FAILED: 502,
+    AI_IMPORT_STREAM_FAILED: 502,
+};
+/** A conversion's terminal `error` event as the error {@link PriceImportModule.follow} throws. */
+export function conversionRefusal(code, message) {
+    const status = Object.hasOwn(CONVERSION_REFUSAL_STATUS, code)
+        ? CONVERSION_REFUSAL_STATUS[code]
+        : 502;
+    // Never retryable: the service deletes the upload when its stream ends, so the same `follow`
+    // can only answer AI_IMPORT_NOT_FOUND. The remedy is a fresh `convert`.
+    return errorForStatus(status, { code, message, service: 'plugins', retryable: false });
+}
+/**
+ * The deadlines `preview` and `run` give the service, longer than the client's default: a
+ * 5,000-row import is measured in tens of seconds (the dashboard has always allowed these).
+ */
+export const PRICE_IMPORT_PREVIEW_TIMEOUT_MS = 30_000;
+export const PRICE_IMPORT_RUN_TIMEOUT_MS = 120_000;
+function nameOf(file) {
+    const name = file.name;
+    return typeof name === 'string' ? name : undefined;
+}
+function readUpload(answer) {
+    const record = answer !== null && typeof answer === 'object' ? answer : {};
+    const { conversionId, fileName } = record;
+    if (typeof conversionId !== 'string' || conversionId.trim() === '') {
+        // The file is stored; only its ticket is missing. Repeating would store it again.
+        throw new UpstreamError({
+            code: 'MALFORMED_RESPONSE',
+            message: 'The price import upload answered without a conversion id.',
+            status: 502,
+            service: 'plugins',
+            retryable: false,
+        });
+    }
+    return { conversionId, fileName: typeof fileName === 'string' ? fileName : '' };
+}
+export function createPriceImportModule(transport) {
+    const importDocument = (body, timeoutMs, options) => {
+        const callOptions = { ...options, timeoutMs };
+        return transport.rest('plugins', { method: 'POST', path: '/prices/import', body }, callOptions);
+    };
+    const documentBody = (document) => ({
+        format: document.format,
+        content: document.content,
+        ...(document.fileTaxMode === undefined ? {} : { fileTaxMode: document.fileTaxMode }),
+    });
+    return {
+        preview(document, options) {
+            return importDocument({ ...documentBody(document), dryRun: true }, PRICE_IMPORT_PREVIEW_TIMEOUT_MS, options);
+        },
+        run(input, options) {
+            return importDocument({
+                ...documentBody(input),
+                dryRun: false,
+                // `[]` and "none named" differ: the first writes nothing, the second every changed row.
+                ...(input.selectedRows === undefined ? {} : { selectedRows: [...input.selectedRows] }),
+            }, PRICE_IMPORT_RUN_TIMEOUT_MS, options);
+        },
+        async convert(input, options) {
+            const fileName = input.fileName ?? nameOf(input.file);
+            if (fileName === undefined || fileName.trim() === '') {
+                throw new ValidationError({
+                    code: 'PRICE_IMPORT_FILE_NAME_REQUIRED',
+                    message: 'A file needs a name: pass fileName, or a File that carries one. The service reads the format from its extension. Nothing was sent.',
+                    status: 400,
+                    service: 'plugins',
+                });
+            }
+            const answer = await transport.rest('plugins', {
+                method: 'POST',
+                path: '/prices/import/ai/conversions',
+                multipart: { files: [{ field: 'file', file: input.file, fileName }] },
+            }, options);
+            return readUpload(answer);
+        },
+        async follow(conversionId, options = {}) {
+            const stream = openProgressStream(transport, { kind: 'price-import-ai-conversion', id: conversionId }, {
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+                ...(options.idleTimeoutMs === undefined ? {} : { idleTimeoutMs: options.idleTimeoutMs }),
+                ...(options.connectTimeoutMs === undefined
+                    ? {}
+                    : { connectTimeoutMs: options.connectTimeoutMs }),
+            });
+            for await (const event of stream) {
+                if (event.type === 'progress') {
+                    options.onProgress?.({ step: event.step, message: event.message });
+                    continue;
+                }
+                if (event.type === 'error')
+                    throw conversionRefusal(event.code, event.message);
+                return event.result;
+            }
+            // The stream ends only after a terminal event, or throws; this is the contract's backstop.
+            throw new UpstreamError({
+                code: 'PROGRESS_STREAM_CLOSED',
+                message: 'The price import conversion ended without an answer; convert the file again.',
+                status: 502,
+                service: 'plugins',
+                retryable: false,
+            });
+        },
+    };
+}

package/dist/integrations/types.d.ts

@@ -1,10 +1,13 @@
 /**
- * The shapes of `admin.integrations.pipelines` (headless spec §7 `pipelines.drafts`).
+ * The shapes of `admin.integrations.pipelines` (headless spec §7 `pipelines.drafts`, §9.2
+ * `integrations`).
  *
  * 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`.
+ * `toState`), a pipeline's `config`, `siteAnalysis` and `publicCredentials` (the connector's own
+ * keys), and a schema map's `sourceSchema`, `targetSchema` and `subCounts`.
  */
+import type { ProgressStreamOptions } from '@sixtyninecommerce/core';
+import type { ListOptions } from '../types.js';
 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';
@@ -320,3 +323,218 @@ export interface DetectPipelineConnectionConfigInput {
     connectorType: string;
     credentials: Record<string, string>;
 }
+/** The connection a pipeline runs over, as a pipeline read embeds it. Never a credential. */
+export interface PipelineConnectionSummary {
+    id: string;
+    connectorType: string;
+    name: string;
+    sourceUrl: string;
+    /** As of the connection's last probe. */
+    status: PipelineConnectionStatus;
+    /** `null`: no throttle. */
+    requestDelayMs: number | null;
+    /** Old hostnames whose image URLs an import rewrites to `sourceUrl`'s host. */
+    legacyAssetHosts: string[] | null;
+    lastTestedAt: string | null;
+    /**
+     * Set when the connection was deleted while this pipeline still ran over it (possible only
+     * before deleting a used connection was refused): the pipeline keeps running over it.
+     */
+    removedAt: string | null;
+}
+/**
+ * An export pipeline's settings: what it exports, and how a scheduled or "Run now" read is
+ * narrowed.
+ */
+export interface ExportPipelineConfig {
+    /** `orders`: the entity types this deployment can export (`connectors()`'s `supportedExportEntityTypes`). */
+    entityTypes: string[];
+    /**
+     * Keyed by the reader's own field names (`toState`), kept verbatim. The keys and values a
+     * filter may name are one shared list (the orders reader's: `toState` and the order states); a
+     * save naming anything else is refused (`PIPELINE_EXPORT_FILTER_*`).
+     */
+    triggerFilter?: Record<string, string>;
+}
+/** An import pipeline's settings. */
+export interface ImportPipelineConfig {
+    /** Where a stock import writes its levels: one of the store's stock locations. */
+    stockLocationId?: string;
+    /** Import the source's Yoast SEO fields (WooCommerce); `true` unless set. */
+    importYoastSeo?: boolean;
+    /** The language the source writes its names in; the store's default unless set. */
+    sourceLanguageCode?: string;
+}
+/**
+ * A data pipeline of the store: an import from, or an export to, another system over one of its
+ * connections, run by hand or on a schedule.
+ */
+export interface Pipeline {
+    id: string;
+    name: string;
+    direction: PipelineDirection;
+    connectionId: string;
+    /** The discovery whose schema maps an import reads; `null` for an export. */
+    discoveryId: string | null;
+    /** Whether an import overwrites the store's own edits (`always_source`) or keeps them. */
+    syncPolicy: PipelineSyncPolicy;
+    /**
+     * `one_time`: runs only when started (by hand, or by a commerce plugin for an export). `daily`:
+     * every day at 03:00 in `timezone`; `weekly`: Mondays at 03:00 in `timezone`; `custom`: on
+     * `cronExpression` in `timezone`. A wall-clock time in that zone, so it follows its daylight
+     * saving changes.
+     */
+    scheduleType: PipelineScheduleType;
+    /** A 5-part cron for a `custom` schedule; `null` otherwise. */
+    cronExpression: string | null;
+    /** The IANA zone the schedule is read in. A pipeline made before zones were asked for holds `UTC`. */
+    timezone: string;
+    /**
+     * `false`: paused. A paused pipeline's schedule is unregistered and a commerce plugin's export
+     * through it is refused; starting a run by hand still works.
+     */
+    isActive: boolean;
+    /** Whether the source's prices include tax (an import). */
+    sourcePricesIncludeTax: boolean;
+    /** As stored, kept verbatim. */
+    config: ExportPipelineConfig | ImportPipelineConfig | null;
+    createdAt: string;
+    updatedAt: string;
+    connection: PipelineConnectionSummary;
+}
+export interface ListPipelinesOptions extends ListOptions {
+    /** Only imports, or only exports. */
+    direction?: PipelineDirection;
+}
+/** Every field optional: one left out stays as stored. */
+export interface UpdatePipelineInput {
+    name?: string;
+    syncPolicy?: PipelineSyncPolicy;
+    scheduleType?: PipelineScheduleType;
+    /** A 5-part cron (`*\/30 * * * *`), required when `scheduleType` is `custom`. */
+    cronExpression?: string;
+    /** An IANA zone (`Europe/Amsterdam`). */
+    timezone?: string;
+    /** `false` pauses the pipeline, `true` resumes it. */
+    isActive?: boolean;
+    sourcePricesIncludeTax?: boolean;
+    /**
+     * An export's filter. MERGED over the stored settings at the top level, so the entity types
+     * stay; `triggerFilter: {}` removes the filter (every order not yet sent is exported).
+     */
+    config?: {
+        triggerFilter: Record<string, string>;
+    };
+}
+/**
+ * `pending`: queued, not started yet; `running`; `paused` (by an operator, resumable); and the
+ * ends: `completed`, `failed`, `cancelled`.
+ */
+export type PipelineRunStatus = 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+/** `manual`: started by hand (`runs.start`, a set-up's commit); `scheduled`; `event`: a commerce plugin's single-order export. */
+export type PipelineRunTrigger = 'manual' | 'scheduled' | 'event';
+/**
+ * How an import run folds its product→collection assignments into each collection: `merge`
+ * (previous ∪ this run, the default and every scheduled run's), `replace_dry_run` (a `merge` run
+ * that also logs what `replace` would change, `entityType: 'collection_assignments'`), `replace`
+ * (each collection the pipeline maps gets exactly what this run assigned; SuperAdmin only).
+ */
+export type PipelineCollectionAssignmentMode = 'merge' | 'replace_dry_run' | 'replace';
+/** One entity type's counts in a run. */
+export interface PipelineRunEntityProgress {
+    /** How many the source holds (an estimate until the run has read them all). */
+    total: number;
+    created: number;
+    updated: number;
+    skipped: number;
+    errored: number;
+    /** Sent to the target system (an export). */
+    exported: number;
+}
+/** One run of a pipeline: an import from, or an export to, the other system. */
+export interface PipelineRun {
+    id: string;
+    pipelineId: string;
+    trigger: PipelineRunTrigger;
+    status: PipelineRunStatus;
+    /** Keyed by the entity type as the pipeline names it (`product_variants`, `orders`), verbatim. */
+    progress: Record<string, PipelineRunEntityProgress>;
+    /**
+     * Why it failed, in the operator's words. Also set on a run its pipeline's deletion cancelled,
+     * saying so ("The pipeline was deleted, so this run stopped after the batch it was working on.
+     * Nothing more was sent."); `null` on a run cancelled by hand.
+     */
+    errorMessage: string | null;
+    /** The sync policy this run imports with: the pipeline's, or the one `start` named. */
+    syncPolicy: PipelineSyncPolicy;
+    collectionAssignmentMode: PipelineCollectionAssignmentMode;
+    /** When it first started (kept across a pause and a resume); `null` while queued. */
+    startedAt: string | null;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface StartPipelineRunInput {
+    /** This run only: whether an import overwrites the store's own edits. The pipeline's otherwise. */
+    syncPolicy?: PipelineSyncPolicy;
+    /** An import only; `merge` unless set. `replace` needs SuperAdmin. Such a run cannot be resumed. */
+    collectionAssignments?: PipelineCollectionAssignmentMode;
+}
+/** What a run did with one record. */
+export type PipelineRunLogResult = 'created' | 'updated' | 'skipped' | 'errored' | 'exported';
+/** One record a run handled, and what became of it. */
+export interface PipelineRunLog {
+    id: string;
+    runId: string;
+    entityType: string;
+    /** The record's id in the system it came from. */
+    sourceId: string | null;
+    /** Its id (an import) or remote path (an export) in the system it went to. */
+    targetId: string | null;
+    result: PipelineRunLogResult;
+    /** Why it was skipped or errored, in the operator's words. */
+    message: string | null;
+    createdAt: string;
+}
+export interface ListPipelineRunLogsOptions extends ListOptions {
+    /** One entity type's records (`orders`, `products`). */
+    entityType?: string;
+    /** Only the records with this outcome: the errors, or the skipped ones. */
+    result?: PipelineRunLogResult;
+}
+/**
+ * How to follow a run or a discovery as it happens (`runs.watch`, `discoveries.watch`).
+ *
+ * - `signal` closes the connection; the iteration then throws `REQUEST_ABORTED`.
+ * - `idleTimeoutMs` (default 45 s, three of the server's keepalives): silence this long counts as
+ *   a dropped connection.
+ * - `connectTimeoutMs`: the deadline for the response headers (the client's own by default).
+ * - `maxReconnects` (default 5; 0 never): how many times in a row a connection that closed, broke,
+ *   stalled or could not open (a network error, 5xx, 429) is reopened before the iteration throws.
+ *   An event received resets the count. A refusal (401, 403, 404) is never retried.
+ * - `reconnectDelayMs` (default 1000): the first reopen's delay, doubling up to 30 s.
+ * - `onReconnect`: told before each reopen (attempt, delay, and the error that ended it).
+ */
+export type PipelineWatchOptions = ProgressStreamOptions;
+/** A discovery of a connection's source. */
+export interface PipelineDiscovery {
+    id: string;
+    connectionId: string;
+    /** `pending` → `running` → `completed` | `failed`. */
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    /** `ai`: the AI proposed the maps; `connector_default`: a fixed-schema connector brought them. */
+    source: 'ai' | 'connector_default';
+    /** Why it failed, in the operator's words. */
+    errorMessage: string | null;
+    /** What the merchant should know about the source; empty until it completes. */
+    warnings: string[];
+    /** The source's plugins it recognised; empty until it completes. */
+    detectedPlugins: string[];
+    startedAt: string | null;
+    completedAt: string | null;
+    createdAt: string;
+}
+/** A discovery's proposal for one kind of record, as stored. */
+export interface PipelineSchemaMap extends PipelineDraftSchemaMap {
+    discoveryId: string;
+}

package/dist/integrations/types.js

@@ -1,8 +1,9 @@
 /**
- * The shapes of `admin.integrations.pipelines` (headless spec §7 `pipelines.drafts`).
+ * The shapes of `admin.integrations.pipelines` (headless spec §7 `pipelines.drafts`, §9.2
+ * `integrations`).
  *
  * 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`.
+ * `toState`), a pipeline's `config`, `siteAnalysis` and `publicCredentials` (the connector's own
+ * keys), and a schema map's `sourceSchema`, `targetSchema` and `subCounts`.
  */
 export {};

package/dist/meta/index.d.ts

@@ -44,6 +44,11 @@ export interface MetaCatalogLabels {
      * with purchase orders; absent before.
      */
     purchaseOrderStatus?: LabelMap;
+    /**
+     * A return of goods to a supplier's status (`admin.purchasing.returns`). Served by a platform
+     * with supplier returns; absent before.
+     */
+    supplierReturnStatus?: LabelMap;
     /**
      * A vocabulary added after this SDK release arrives camelised, with its map
      * untouched.
@@ -65,6 +70,11 @@ export interface MetaCatalogTransitions {
      * absent before.
      */
     purchaseOrder?: TransitionMap;
+    /**
+     * A return of goods to a supplier's lifecycle (`admin.purchasing.returns`): `draft → shipped →
+     * resolved`, and `draft → cancelled`. Served by a platform with supplier returns; absent before.
+     */
+    supplierReturn?: TransitionMap;
     [extra: string]: unknown;
 }
 export interface PermissionGroup {

package/dist/metafields/index.d.ts

@@ -8,8 +8,15 @@ import type { Call } from '../types.js';
  * fields, and commerce refuses a value written against it
  * (`METAFIELD_OWNER_INVALID`). A manifest declaring one still registers; only
  * the value surface says no.
+ *
+ * `purchase_order`, `purchase_order_line` and `supplier` are the purchasing
+ * records, which belong to the store's legal entity rather than to the store:
+ * one of another legal entity answers `NotFoundError` like an id of nothing,
+ * and a store that does not purchase answers `PURCHASING_NOT_ENABLED`. Their
+ * values are still the store's own. An engine older than them refuses them with
+ * `METAFIELD_OWNER_INVALID`.
  */
-export declare const METAFIELD_OWNER_TYPES: readonly ["product", "variant", "customer", "order", "order_line", "location", "collection"];
+export declare const METAFIELD_OWNER_TYPES: readonly ["product", "variant", "customer", "order", "order_line", "location", "collection", "purchase_order", "purchase_order_line", "supplier"];
 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"];

package/dist/metafields/index.js

@@ -7,6 +7,13 @@ import { createPage } from '@sixtyninecommerce/core';
  * fields, and commerce refuses a value written against it
  * (`METAFIELD_OWNER_INVALID`). A manifest declaring one still registers; only
  * the value surface says no.
+ *
+ * `purchase_order`, `purchase_order_line` and `supplier` are the purchasing
+ * records, which belong to the store's legal entity rather than to the store:
+ * one of another legal entity answers `NotFoundError` like an id of nothing,
+ * and a store that does not purchase answers `PURCHASING_NOT_ENABLED`. Their
+ * values are still the store's own. An engine older than them refuses them with
+ * `METAFIELD_OWNER_INVALID`.
  */
 export const METAFIELD_OWNER_TYPES = [
     'product',
@@ -16,6 +23,9 @@ export const METAFIELD_OWNER_TYPES = [
     'order_line',
     'location',
     'collection',
+    'purchase_order',
+    'purchase_order_line',
+    'supplier',
 ];
 /** Scalar value types. `list<T>` of any of them is also a type. */
 export const METAFIELD_SCALAR_TYPES = [