@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/dist/integrations/index.d.ts

@@ -1,15 +1,17 @@
 /**
  * Integrations (headless spec §9.2): the store's connections to other systems. The data
- * pipelines' source connections, connectors and import and export set-ups, the e-mail marketing
- * connection (`esp`), the AFAS Profit connection with what is sent to it (`afas`) and the Exact
- * Online connection with its settings (`exactOnline`); the pipelines themselves, their runs and
- * their progress streams follow in phase 7.
+ * pipelines with their source connections, connectors and import and export set-ups, the e-mail
+ * marketing connection (`esp`), the AFAS Profit connection with what is sent to it (`afas`) and
+ * the Exact Online connection with its settings, its inbound sync, its shipping-method mapping
+ * and its connection logs (`exactOnline`), and the bulk price import with
+ * its AI conversion (`priceImport`).
  */
 import type { Transport } from '@sixtyninecommerce/core';
 import { type AfasModule } from './afas.js';
 import { type EspModule } from './esp.js';
 import { type ExactOnlineModule } from './exact-online.js';
 import { type IntegrationPipelinesModule } from './pipelines.js';
+import { type PriceImportModule } from './price-import.js';
 export type { AfasConfigModule, AfasModule, AfasPaymentTermsModule, AfasWarehouseMappingsModule, } from './afas.js';
 export { AFAS_SYNC_LOG_PAGE_LIMIT } from './afas.js';
 export type { AfasCustomersModule, AfasOrdersModule, AfasStockTransfersModule, } from './afas-actions.js';
@@ -19,22 +21,35 @@ export type { PipelineConnectionsModule } from './connections.js';
 export { PIPELINE_CONNECTION_PRESERVE_KEYS } from './connections.js';
 export type { ConnectEspWithTokenInput, EspBackfillResource, EspConnection, EspConnectionTestResult, EspConnectMetadata, EspCredentialsPushState, EspInboundWebhookState, EspModule, EspSyncLog, EspSyncLogFilter, UpdateEspConnectionInput, } from './esp.js';
 export { ESP_BACKFILL_RESOURCES, ESP_SYNC_LOG_PAGE_LIMIT } from './esp.js';
-export type { ExactOnlineConfigModule, ExactOnlineCredentialsModule, ExactOnlineModule, ExactOnlineSamplesModule, ExactOnlineStructureModule, ExactOnlineWebhooksModule, } from './exact-online.js';
+export type { ExactOnlineConfigModule, ExactOnlineConnectionLogsModule, ExactOnlineCredentialsModule, ExactOnlineCustomersModule, ExactOnlineModule, ExactOnlineOrdersModule, ExactOnlineProductsModule, ExactOnlineSamplesModule, ExactOnlineShippingModule, ExactOnlineStructureModule, ExactOnlineSyncModule, ExactOnlineTermsModule, ExactOnlineWebhooksModule, } from './exact-online.js';
+export { EXACT_ONLINE_LOG_EXPORT_TIMEOUT_MS, EXACT_ONLINE_SYNC_LOG_LIMIT } from './exact-online.js';
 export type * from './exact-online-types.js';
+export type { PipelineDiscoveriesModule } from './pipeline-discoveries.js';
+export type { PipelineRunsModule } from './pipeline-runs.js';
 export type { IntegrationPipelinesModule, PipelineDraftsModule } from './pipelines.js';
 export { PIPELINE_DRAFT_PRESERVE_KEYS, PIPELINE_DRAFT_SLOW_TIMEOUT_MS } from './pipelines.js';
+export type { PriceImportConversion, PriceImportConversionProgress, PriceImportConversionStep, PriceImportConvertInput, PriceImportDocument, PriceImportFollowOptions, PriceImportFormat, PriceImportModule, PriceImportReport, PriceImportRow, PriceImportRowStatus, PriceImportRunInput, PriceImportSummary, PriceImportTaxMode, PriceImportUpload, } from './price-import.js';
+export { PRICE_IMPORT_PREVIEW_TIMEOUT_MS, PRICE_IMPORT_RUN_TIMEOUT_MS } from './price-import.js';
 export type * from './types.js';
 export interface IntegrationsModule {
     /**
-     * Data pipelines: the source connections (`connections`), the connectors, and the import and
-     * export set-ups kept on the server (`drafts`).
+     * Data pipelines: the pipelines themselves, the source connections (`connections`), the
+     * connectors, and the import and export set-ups kept on the server (`drafts`).
      */
     pipelines: IntegrationPipelinesModule;
     /** The store's e-mail marketing connection (sixtynine.email). See {@link EspModule}. */
     esp: EspModule;
     /** The store's AFAS Profit connection and its settings. See {@link AfasModule}. */
     afas: AfasModule;
-    /** The store's Exact Online connection and its settings. See {@link ExactOnlineModule}. */
+    /**
+     * The store's Exact Online connection, its settings, its inbound sync, its shipping-method
+     * mapping and its connection logs. See {@link ExactOnlineModule}.
+     */
     exactOnline: ExactOnlineModule;
+    /**
+     * The bulk price import (a dry run, then the rows to write) and the AI conversion of a
+     * supplier file into a document it accepts. See {@link PriceImportModule}.
+     */
+    priceImport: PriceImportModule;
 }
 export declare function createIntegrationsModule(transport: Transport): IntegrationsModule;

package/dist/integrations/index.js

@@ -1,24 +1,29 @@
 /**
  * Integrations (headless spec §9.2): the store's connections to other systems. The data
- * pipelines' source connections, connectors and import and export set-ups, the e-mail marketing
- * connection (`esp`), the AFAS Profit connection with what is sent to it (`afas`) and the Exact
- * Online connection with its settings (`exactOnline`); the pipelines themselves, their runs and
- * their progress streams follow in phase 7.
+ * pipelines with their source connections, connectors and import and export set-ups, the e-mail
+ * marketing connection (`esp`), the AFAS Profit connection with what is sent to it (`afas`) and
+ * the Exact Online connection with its settings, its inbound sync, its shipping-method mapping
+ * and its connection logs (`exactOnline`), and the bulk price import with
+ * its AI conversion (`priceImport`).
  */
 import { createAfasModule } from './afas.js';
 import { createEspModule } from './esp.js';
 import { createExactOnlineModule } from './exact-online.js';
 import { createIntegrationPipelinesModule } from './pipelines.js';
+import { createPriceImportModule } from './price-import.js';
 export { AFAS_SYNC_LOG_PAGE_LIMIT } from './afas.js';
 export { AFAS_CUSTOMER_SEARCH_LIMIT } from './afas-actions.js';
 export { PIPELINE_CONNECTION_PRESERVE_KEYS } from './connections.js';
 export { ESP_BACKFILL_RESOURCES, ESP_SYNC_LOG_PAGE_LIMIT } from './esp.js';
+export { EXACT_ONLINE_LOG_EXPORT_TIMEOUT_MS, EXACT_ONLINE_SYNC_LOG_LIMIT } from './exact-online.js';
 export { PIPELINE_DRAFT_PRESERVE_KEYS, PIPELINE_DRAFT_SLOW_TIMEOUT_MS } from './pipelines.js';
+export { PRICE_IMPORT_PREVIEW_TIMEOUT_MS, PRICE_IMPORT_RUN_TIMEOUT_MS } from './price-import.js';
 export function createIntegrationsModule(transport) {
     return {
         pipelines: createIntegrationPipelinesModule(transport),
         esp: createEspModule(transport),
         afas: createAfasModule(transport),
         exactOnline: createExactOnlineModule(transport),
+        priceImport: createPriceImportModule(transport),
     };
 }

package/dist/integrations/pipeline-discoveries.d.ts

@@ -0,0 +1,65 @@
+import { type PipelineDiscoveryProgressEvent, type ProgressStream, type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import type { PipelineDiscovery, PipelineSchemaMap, PipelineWatchOptions } from './types.js';
+/**
+ * What a source holds and how it maps onto the store: a discovery samples a connection's source
+ * (a fixed-schema connector answers at once; any other asks the AI) and proposes a schema map per
+ * kind of record. The import set-ups (`drafts.discover`) start theirs themselves; these doors are
+ * for following one, and for a caller that runs a discovery outside a set-up.
+ *
+ * - **A discovery belongs to its connection's store**: another store's is not found (`get`
+ *   answers `null`; `schemaMaps` and `watch` are refused `NotFoundError`; an older plugins
+ *   service refuses `watch` inside the opened stream, `PROGRESS_STREAM_REFUSED`).
+ * - Refusals: `PIPELINES_NOT_CONFIGURED` (503, `start`): the platform cannot read connection
+ *   credentials; `ORGANIZATION_WORKSPACE_NOT_A_STORE` (422, `start`); an app below
+ *   `customerData: full` is refused every door (`CUSTOMER_DATA_NOT_GRANTED`): the schema maps
+ *   quote sample records of the source.
+ * - Reads and `watch` need `ReadCatalog`; `start` needs `UpdateCatalog`.
+ */
+export interface PipelineDiscoveriesModule {
+    /**
+     * Start a discovery of the connection's source. Answers it `pending`; follow it with `watch` or
+     * `get`. Not idempotent: every call samples the source again (and may ask the AI again; an
+     * unchanged source is answered from a 24-hour cache).
+     *
+     * @effect write
+     * @permission UpdateCatalog
+     */
+    start(connectionId: string, options?: Call): Promise<PipelineDiscovery>;
+    /**
+     * One discovery, or `null` when the store has none with that id.
+     *
+     * @effect read
+     * @permission ReadCatalog
+     */
+    get(discoveryId: string, options?: Call): Promise<PipelineDiscovery | null>;
+    /**
+     * The discovery's schema maps, the most records first: one per kind of record the source holds,
+     * with its field mappings and sample values as stored. Empty until the discovery completes.
+     *
+     * @effect read
+     * @permission ReadCatalog
+     */
+    schemaMaps(discoveryId: string, options?: Call): Promise<PipelineSchemaMap[]>;
+    /**
+     * The discovery as it happens: an async iterable of its `progress` events (phase, sentence,
+     * percentage), ending after its terminal event, `complete` (with its warnings and the source's
+     * detected plugins; read the maps with `schemaMaps`) or `error` (the reason, yielded, not
+     * thrown). A discovery that had already ended answers its ended state at once.
+     *
+     * It opens on the first `next()`, and reopens a connection that drops before the end (see
+     * {@link PipelineWatchOptions.maxReconnects}); it never retries a refusal: a 401 or 403, or
+     * a discovery the store does not have (another store's included), which the plugins service
+     * refuses with a 404 `PIPELINE_DISCOVERY_NOT_FOUND` (`NotFoundError`) before the stream opens;
+     * a plugins service from before that refuses inside the opened stream,
+     * `PROGRESS_STREAM_REFUSED` (`UpstreamError`). It throws `PROGRESS_STREAM_CLOSED` /
+     * `PROGRESS_STREAM_STALLED` once the reopens are spent, and
+     * `REQUEST_ABORTED` when `signal` fires. An id that is not a discovery id is refused
+     * `PROGRESS_STREAM_ID_INVALID` before anything is sent.
+     *
+     * @effect read
+     * @permission ReadCatalog
+     */
+    watch(discoveryId: string, options?: PipelineWatchOptions): ProgressStream<PipelineDiscoveryProgressEvent>;
+}
+export declare function createPipelineDiscoveriesModule(transport: Transport): PipelineDiscoveriesModule;

package/dist/integrations/pipeline-discoveries.js

@@ -0,0 +1,65 @@
+import { NotFoundError, openProgressStream, } from '@sixtyninecommerce/core';
+import { PIPELINE_DRAFT_PRESERVE_KEYS } from './pipeline-keys.js';
+const segment = (value) => encodeURIComponent(value);
+const texts = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
+/** The documented fields: the wire also answers the connection row and the result bag. */
+function toDiscovery(raw) {
+    return {
+        id: raw.id,
+        connectionId: raw.connectionId,
+        status: raw.status,
+        source: raw.source ?? 'ai',
+        errorMessage: raw.errorMessage ?? null,
+        warnings: texts(raw.result?.warnings),
+        detectedPlugins: texts(raw.result?.detectedPlugins),
+        startedAt: raw.startedAt ?? null,
+        completedAt: raw.completedAt ?? null,
+        createdAt: raw.createdAt,
+    };
+}
+function toSchemaMap(raw) {
+    return {
+        id: raw.id,
+        discoveryId: raw.discoveryId,
+        entityType: raw.entityType,
+        enabled: raw.enabled,
+        confidence: raw.confidence,
+        entityCount: raw.entityCount,
+        subCounts: raw.subCounts ?? null,
+        sourceSchema: raw.sourceSchema ?? {},
+        targetSchema: raw.targetSchema ?? {},
+        fieldMappings: (raw.fieldMappings ?? []).map((mapping) => ({
+            sourceField: mapping.sourceField,
+            sourcePath: mapping.sourcePath,
+            targetField: mapping.targetField,
+            targetPath: mapping.targetPath,
+            transform: mapping.transform ?? null,
+            confidence: mapping.confidence,
+            enabled: mapping.enabled,
+        })),
+    };
+}
+export function createPipelineDiscoveriesModule(transport) {
+    return {
+        async start(connectionId, options) {
+            return toDiscovery(await transport.rest('plugins', { method: 'POST', path: `/pipelines/connections/${segment(connectionId)}/discover` }, { ...options, preserveKeys: PIPELINE_DRAFT_PRESERVE_KEYS }));
+        },
+        async get(discoveryId, options) {
+            try {
+                return toDiscovery(await transport.rest('plugins', { method: 'GET', path: `/pipelines/discoveries/${segment(discoveryId)}` }, { ...options, preserveKeys: PIPELINE_DRAFT_PRESERVE_KEYS }));
+            }
+            catch (error) {
+                if (error instanceof NotFoundError)
+                    return null;
+                throw error;
+            }
+        },
+        async schemaMaps(discoveryId, options) {
+            const maps = await transport.rest('plugins', { method: 'GET', path: `/pipelines/discoveries/${segment(discoveryId)}/schema-maps` }, 
+            // `source_schema` / `target_schema` carry the source's own names: never re-cased.
+            { ...options, preserveKeys: PIPELINE_DRAFT_PRESERVE_KEYS });
+            return (Array.isArray(maps) ? maps : []).map(toSchemaMap);
+        },
+        watch: (discoveryId, options = {}) => openProgressStream(transport, { kind: 'pipeline-discovery', id: discoveryId }, options),
+    };
+}

package/dist/integrations/pipeline-runs.d.ts

@@ -0,0 +1,119 @@
+import { type Page, type PipelineRunProgressEvent, type ProgressStream, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+import type { ListPipelineRunLogsOptions, PipelineRun, PipelineRunLog, PipelineWatchOptions, StartPipelineRunInput } from './types.js';
+/**
+ * A pipeline's runs: start one, follow it, pause, resume or cancel it, and read what it did with
+ * each record (its logs).
+ *
+ * - **A run is also a job** with the same id (`admin.jobs`, kind `pipeline.import` or
+ *   `pipeline.export`), once the jobs resource has indexed it: `admin.jobs.list()` indexes the
+ *   runs it has not seen yet, and `admin.jobs.wait(run.id)` then waits for the run to end.
+ *   `get` here reads the run itself, with its per-entity counts.
+ * - **Pause and cancel take effect at the next batch boundary**: the batch in flight finishes and
+ *   is recorded, then the run stops. Only a `running` run can be paused or cancelled (a `paused`
+ *   one can be cancelled too); a queued (`pending`) one is refused `PIPELINE_RUN_NOT_STARTED`.
+ * - **Deleting the pipeline cancels its runs** (`pipelines.delete`): a queued or paused run ends
+ *   `cancelled` at once, a running one stops after the batch it is working on, and nothing more
+ *   is imported or sent. Each says so in `errorMessage`. Such a run can still be read here by its
+ *   id; the pipeline's run list is gone with the pipeline.
+ * - Refusals, all `PlatformError`s branching on `code`:
+ *   - `PIPELINE_RUN_NOT_FOUND` (404): no such run in this store (another store's included);
+ *   - `PIPELINE_RUN_ALREADY_ENDED`, `PIPELINE_RUN_NOT_STARTED`, `PIPELINE_RUN_NOT_RUNNING`,
+ *     `PIPELINE_RUN_NOT_PAUSED` (409): the run is not in a state the action accepts;
+ *   - `PIPELINE_CHANNEL_TOKEN_MISMATCH` (403, `start` and `resume`): the client's channel token
+ *     is not this store's any more (the store was renamed); build a client with the new one;
+ *   - `PIPELINE_COLLECTION_*`: a collection rebuild the pipeline cannot do (an export, no
+ *     products, a resume, `replace` without SuperAdmin);
+ *   - `PIPELINES_NOT_CONFIGURED` (503): the platform cannot read connection credentials;
+ *   - `ORGANIZATION_WORKSPACE_NOT_A_STORE` (422): `start` and `resume` in an organization
+ *     workspace.
+ * - Reads need `ReadCatalog`; `start`, `pause`, `resume` and `cancel` need `UpdateCatalog`. An app
+ *   below `customerData: full` is refused every door (`CUSTOMER_DATA_NOT_GRANTED`): a run's logs
+ *   quote the records it moved.
+ */
+export interface PipelineRunsModule {
+    /**
+     * Queue a run of the pipeline now, whatever its schedule (a paused pipeline too). Answers the
+     * run, `pending`. Not idempotent: every call queues another run, so a caller that lost the
+     * answer lists the runs before starting again. An export run sends the store's orders to the
+     * other system, which cannot be taken back.
+     *
+     * @effect irreversible
+     * @permission UpdateCatalog
+     */
+    start(pipelineId: string, input?: StartPipelineRunInput, options?: Call): Promise<PipelineRun>;
+    /**
+     * The pipeline's runs, newest first. A pipeline the store does not have (deleted included) is a
+     * `NotFoundError`.
+     *
+     * @effect read
+     * @permission ReadCatalog
+     */
+    list(pipelineId: string, options?: ListOptions): Promise<Page<PipelineRun>>;
+    /**
+     * One run, or `null` when the store has none with that id.
+     *
+     * @effect read
+     * @permission ReadCatalog
+     */
+    get(runId: string, options?: Call): Promise<PipelineRun | null>;
+    /**
+     * Pause a `running` run at its next batch boundary; resume it later. A run already paused
+     * answers as it is.
+     *
+     * @effect write
+     * @permission UpdateCatalog
+     */
+    pause(runId: string, options?: Call): Promise<PipelineRun>;
+    /**
+     * Queue a `paused` run again (`pending`); it continues where it stopped. A run started with a
+     * collection rebuild cannot be resumed (`PIPELINE_COLLECTION_REBUILD_NOT_RESUMABLE`).
+     *
+     * @effect irreversible
+     * @permission UpdateCatalog
+     */
+    resume(runId: string, options?: Call): Promise<PipelineRun>;
+    /**
+     * Cancel a `running` or `paused` run: it ends `cancelled` now, and a running one stops at its
+     * next batch boundary. What it already did stays done. A run already cancelled answers as it is.
+     *
+     * @effect write
+     * @permission UpdateCatalog
+     */
+    cancel(runId: string, options?: Call): Promise<PipelineRun>;
+    /**
+     * What the run did with each record, newest first, `total` counting every match. Filter by
+     * `entityType` and by `result` (its errors: `errored`; what it skipped: `skipped`). There is no
+     * level to filter by: a record's outcome is its `result`.
+     *
+     * @effect read
+     * @permission ReadCatalog
+     */
+    logs(runId: string, options?: ListPipelineRunLogsOptions): Promise<Page<PipelineRunLog>>;
+    /**
+     * The run as it happens: an async iterable of its events, each with the run's `phase`, a
+     * `message` and the per-entity counts so far (`progress`). `progress` events arrive while it
+     * works (at most about one a second, naming the `entityType` it is on), and the iteration ENDS
+     * after the one terminal event: `complete`, `error` (the run failed; the reason is the event's
+     * `message`, yielded, not thrown), `cancelled` or `paused`. A run that had already ended answers
+     * its ended state at once; a queued one says nothing until it starts. A resumed run is followed
+     * by watching it again.
+     *
+     * The counts are the stream's: a run cancelled by its pipeline's deletion ends the stream at
+     * once, and the batch it was working on may still finish after that; `get` reads the final
+     * counts. It opens on the first `next()` and reopens a connection that drops before the end (see
+     * {@link PipelineWatchOptions.maxReconnects}); it never retries a refusal: a 401 or 403, or a
+     * run the store does not have (another store's included), which the plugins service refuses
+     * with a 404 `PIPELINE_RUN_NOT_FOUND` (`NotFoundError`) before the stream opens; a plugins
+     * service from before that refuses inside the opened stream, `PROGRESS_STREAM_REFUSED`
+     * (`UpstreamError`). It throws
+     * `PROGRESS_STREAM_CLOSED` / `PROGRESS_STREAM_STALLED` once the reopens are spent, and
+     * `REQUEST_ABORTED` when `signal` fires. An id that is not a run id is refused
+     * `PROGRESS_STREAM_ID_INVALID` before anything is sent.
+     *
+     * @effect read
+     * @permission ReadCatalog
+     */
+    watch(runId: string, options?: PipelineWatchOptions): ProgressStream<PipelineRunProgressEvent>;
+}
+export declare function createPipelineRunsModule(transport: Transport): PipelineRunsModule;

package/dist/integrations/pipeline-runs.js

@@ -0,0 +1,87 @@
+import { createPage, NotFoundError, openProgressStream, readRestPage, } from '@sixtyninecommerce/core';
+import { PIPELINE_DRAFT_PRESERVE_KEYS } from './pipeline-keys.js';
+const PIPELINES = '/pipelines';
+const RUNS = '/pipelines/runs';
+const segment = (value) => encodeURIComponent(value);
+/**
+ * The documented fields only. The wire also carries the run's internal id maps (every source id
+ * the run mapped, which can run to tens of thousands of entries) and, on some answers, its
+ * pipeline's row.
+ */
+function toRun(raw) {
+    return {
+        id: raw.id,
+        pipelineId: raw.pipelineId,
+        trigger: raw.trigger,
+        status: raw.status,
+        progress: raw.progress ?? {},
+        errorMessage: raw.errorMessage ?? null,
+        syncPolicy: raw.syncPolicy,
+        collectionAssignmentMode: raw.collectionAssignmentMode ?? 'merge',
+        startedAt: raw.startedAt ?? null,
+        completedAt: raw.completedAt ?? null,
+        createdAt: raw.createdAt,
+        updatedAt: raw.updatedAt,
+    };
+}
+function toLog(raw) {
+    return {
+        id: raw.id,
+        runId: raw.runId,
+        entityType: raw.entityType,
+        sourceId: raw.sourceId ?? null,
+        targetId: raw.targetId ?? null,
+        result: raw.result,
+        message: raw.message ?? null,
+        createdAt: raw.createdAt,
+    };
+}
+export function createPipelineRunsModule(transport) {
+    // `progress` (keyed by entity type) and `idMaps` are stored data: preserved, never re-cased.
+    const call = async (method, path, options, body) => toRun(await transport.rest('plugins', { method, path, ...(body === undefined ? {} : { body }) }, { ...options, preserveKeys: PIPELINE_DRAFT_PRESERVE_KEYS }));
+    async function list(pipelineId, options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: `${PIPELINES}/${segment(pipelineId)}/runs`,
+            // `cursor=1` asks for a keyset page; without it the door answers every run as an array.
+            query: { cursor: 1, after: options?.after, limit: options?.limit },
+        }, { ...options, preserveKeys: PIPELINE_DRAFT_PRESERVE_KEYS });
+        const { items, meta } = readRestPage(body);
+        return createPage(items.map(toRun), meta, (cursor) => list(pipelineId, { ...options, after: cursor }));
+    }
+    async function logs(runId, options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: `${RUNS}/${segment(runId)}/logs`,
+            query: {
+                cursor: 1,
+                entity_type: options?.entityType,
+                result: options?.result,
+                after: options?.after,
+                limit: options?.limit,
+            },
+        }, options);
+        const { items, meta } = readRestPage(body);
+        return createPage(items.map(toLog), meta, (cursor) => logs(runId, { ...options, after: cursor }));
+    }
+    return {
+        // No body unless something is overridden: the door's body is optional.
+        start: (pipelineId, input, options) => call('POST', `${PIPELINES}/${segment(pipelineId)}/runs`, options, input && Object.keys(input).length > 0 ? input : undefined),
+        list,
+        async get(runId, options) {
+            try {
+                return await call('GET', `${RUNS}/${segment(runId)}`, options);
+            }
+            catch (error) {
+                if (error instanceof NotFoundError)
+                    return null;
+                throw error;
+            }
+        },
+        pause: (runId, options) => call('POST', `${RUNS}/${segment(runId)}/pause`, options),
+        resume: (runId, options) => call('POST', `${RUNS}/${segment(runId)}/resume`, options),
+        cancel: (runId, options) => call('POST', `${RUNS}/${segment(runId)}/cancel`, options),
+        logs,
+        watch: (runId, options = {}) => openProgressStream(transport, { kind: 'pipeline-run', id: runId }, options),
+    };
+}

package/dist/integrations/pipelines.d.ts

@@ -1,7 +1,9 @@
 import { type Page, type Transport } from '@sixtyninecommerce/core';
 import type { Call, ListOptions } from '../types.js';
 import { type PipelineConnectionsModule } from './connections.js';
-import type { CommittedPipelineDraft, ImportDependency, PipelineConnector, PipelineDirection, PipelineDraft, PipelineDraftSummary, UpdatePipelineDraftInput, UpdatePipelineDraftSchemaMapInput } from './types.js';
+import { type PipelineDiscoveriesModule } from './pipeline-discoveries.js';
+import { type PipelineRunsModule } from './pipeline-runs.js';
+import type { CommittedPipelineDraft, ImportDependency, ListPipelinesOptions, Pipeline, PipelineConnector, PipelineDirection, PipelineDraft, PipelineDraftSummary, UpdatePipelineDraftInput, UpdatePipelineDraftSchemaMapInput, UpdatePipelineInput } from './types.js';
 export { PIPELINE_DRAFT_PRESERVE_KEYS, PIPELINE_DRAFT_SLOW_TIMEOUT_MS } from './pipeline-keys.js';
 /**
  * Half-finished import and export set-ups, kept on the server for the store (headless spec §7).
@@ -90,9 +92,78 @@ export interface PipelineDraftsModule {
      */
     discard(id: string, options?: Call): Promise<void>;
 }
-/** Data pipelines (imports and exports between the store and another system). */
+/**
+ * Data pipelines (imports and exports between the store and another system): the pipelines
+ * themselves (`list`, `get`, `update`, `delete`), their runs and the runs' logs (`runs`), the
+ * set-ups that create them (`drafts`), the discoveries of a source (`discoveries`), their source
+ * connections and the connectors.
+ *
+ * A pipeline is created by committing a set-up (`drafts.commit`). A run is followed live with
+ * `runs.watch` (or read with `runs.get`), and is also a `jobs` entry.
+ *
+ * - **Schedules are wall-clock times in the pipeline's own `timezone`** (an IANA zone): `daily`
+ *   runs at 03:00 there and `weekly` on Mondays at 03:00, through its daylight saving changes.
+ *   A set-up starts with the store's zone; a pipeline made before zones were asked for holds `UTC`.
+ * - **Pausing is `update(id, { isActive: false })`**: the schedule is unregistered and a commerce
+ *   plugin's export through it (Hendriks) is refused until `isActive: true`. Starting a run by hand
+ *   still works.
+ * - Reads need `ReadCatalog`, `update` and `delete` need `UpdateCatalog`. Another store's pipeline
+ *   is not found (`get` answers `null`, a write a `NotFoundError`). An organization workspace is
+ *   not a store: an `update` there is refused `ORGANIZATION_WORKSPACE_NOT_A_STORE` (422) unless it
+ *   only pauses. An app below `customerData: full` is refused every door (`CUSTOMER_DATA_NOT_GRANTED`).
+ */
 export interface IntegrationPipelinesModule {
+    /**
+     * The store's pipelines, newest first, each with the connection it runs over (never a
+     * credential). `direction` lists only imports or only exports.
+     *
+     * @effect read
+     * @permission ReadCatalog
+     */
+    list(options?: ListPipelinesOptions): Promise<Page<Pipeline>>;
+    /**
+     * One pipeline, or `null` when the store has none with that id (deleted, or another store's).
+     *
+     * @effect read
+     * @permission ReadCatalog
+     */
+    get(id: string, options?: Call): Promise<Pipeline | null>;
+    /**
+     * Change a pipeline: its name, its schedule (`scheduleType`, `cronExpression`, `timezone`), its
+     * sync policy, whether it is paused (`isActive`), or an export's filter (`config.triggerFilter`).
+     * A field left out stays as stored. A change to the schedule or to `isActive` re-registers the
+     * schedule at once. Refused, saving nothing, with a `ValidationError` (400) coded:
+     *
+     * - `PIPELINE_CRON_REQUIRED`: a `custom` schedule with no cron;
+     * - `PIPELINE_CRON_NEVER_FIRES`: a cron the scheduler can never run (`0 0 31 4 *`), checked in
+     *   `timezone`;
+     * - `PIPELINE_EXPORT_FILTER_UNSUPPORTED`, `PIPELINE_EXPORT_FILTER_BLANK`,
+     *   `PIPELINE_EXPORT_FILTER_VALUE_UNKNOWN`: a filter key the export does not honour, a key with
+     *   no value, or a value no order can have (`details[].field` is `triggerFilter`). An
+     *   unhonoured filter would export everything, an impossible one nothing at all;
+     * - `VALIDATION_FAILED`: a field of the wrong shape (an unknown zone, a cron that is not 5
+     *   parts).
+     *
+     * @effect write
+     * @permission UpdateCatalog
+     */
+    update(id: string, input: UpdatePipelineInput, options?: Call): Promise<Pipeline>;
+    /**
+     * Delete a pipeline: its schedule is unregistered at once and it leaves the list. Its runs that
+     * have not ended are cancelled in the same step: a queued or paused one at once, a running one
+     * after the batch it is working on, and nothing more is imported or sent (each says so in
+     * `errorMessage`; read them with `runs.get`). Its past runs and their logs are kept. Its
+     * connection is not deleted, and can be once nothing else uses it.
+     *
+     * @effect destructive
+     * @permission UpdateCatalog
+     */
+    delete(id: string, options?: Call): Promise<void>;
+    /** The pipelines' runs and their logs. See {@link PipelineRunsModule}. */
+    runs: PipelineRunsModule;
     drafts: PipelineDraftsModule;
+    /** The discoveries of a connection's source. See {@link PipelineDiscoveriesModule}. */
+    discoveries: PipelineDiscoveriesModule;
     /** The store's source connections. See {@link PipelineConnectionsModule}. */
     connections: PipelineConnectionsModule;
     /**

package/dist/integrations/pipelines.js

@@ -1,7 +1,10 @@
-import { createPage, readRestPage } from '@sixtyninecommerce/core';
+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) {
@@ -34,8 +37,40 @@ 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) {