@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/integrations/pipelines.js

@@ -1,25 +1,10 @@
-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;
+import { createPage, NotFoundError, readRestPage, } from '@sixtyninecommerce/core';
+import { createPipelineConnectionsModule, listPipelineConnectors, } from './connections.js';
+import { createPipelineDiscoveriesModule, } from './pipeline-discoveries.js';
+import { PIPELINE_DRAFT_PRESERVE_KEYS, PIPELINE_DRAFT_SLOW_TIMEOUT_MS } from './pipeline-keys.js';
+import { createPipelineRunsModule } from './pipeline-runs.js';
+export { PIPELINE_DRAFT_PRESERVE_KEYS, PIPELINE_DRAFT_SLOW_TIMEOUT_MS } from './pipeline-keys.js';
+const PIPELINES = '/pipelines';
 const DRAFTS = '/pipelines/drafts';
 const segment = (value) => encodeURIComponent(value);
 export function createIntegrationPipelinesModule(transport) {
@@ -52,8 +37,42 @@ export function createIntegrationPipelinesModule(transport) {
             await transport.rest('plugins', { method: 'DELETE', path: `${DRAFTS}/${segment(id)}`, expect: 'void' }, options);
         },
     };
+    async function listPipelines(options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: PIPELINES,
+            // `cursor=1` asks for a keyset page; without it the door answers the whole list as an array.
+            query: {
+                cursor: 1,
+                direction: options?.direction,
+                after: options?.after,
+                limit: options?.limit,
+            },
+        }, { ...options, preserveKeys: PIPELINE_DRAFT_PRESERVE_KEYS });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => listPipelines({ ...options, after: cursor }));
+    }
     return {
+        list: listPipelines,
+        async get(id, options) {
+            try {
+                return await read(`${PIPELINES}/${segment(id)}`, options);
+            }
+            catch (error) {
+                if (error instanceof NotFoundError)
+                    return null;
+                throw error;
+            }
+        },
+        update: (id, input, options) => write('PATCH', `${PIPELINES}/${segment(id)}`, input, options),
+        async delete(id, options) {
+            await transport.rest('plugins', { method: 'DELETE', path: `${PIPELINES}/${segment(id)}`, expect: 'void' }, options);
+        },
+        runs: createPipelineRunsModule(transport),
         drafts,
+        discoveries: createPipelineDiscoveriesModule(transport),
+        connections: createPipelineConnectionsModule(transport),
+        connectors: (options) => listPipelineConnectors(transport, options),
         async importDependencies(options) {
             const body = await read('/pipelines/import-dependencies', options);
             return body.data;

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,
+            });
+        },
+    };
+}