@sixtyninecommerce/admin 0.6.0 → 0.8.0

package/dist/documents/index.js

@@ -0,0 +1,289 @@
+import { createPage, ValidationError } from '@sixtyninecommerce/core';
+const API_DOCUMENT_TYPE = {
+    invoice: 'INVOICE',
+    'credit-note': 'CREDIT_NOTE',
+    'packing-slip': 'PACKING_SLIP',
+};
+/**
+ * Most blocks one document may carry. A longer list refuses the whole document
+ * (`DOCUMENT_EXTENSION_INVALID`) rather than issuing a numbered one that
+ * dropped the overflow — a document is a page, not a feed.
+ */
+export const MAX_DOCUMENT_EXTENSIONS = 10;
+const INVOICE_FIELDS = /* GraphQL */ `
+  id
+  invoiceNumber
+  invoicedOn
+  orderId
+  languageCode
+  storageKey
+  totalWithTax
+  currencyCode
+  note
+  voidedOn
+  kind
+  createdAt
+`;
+const CREDIT_NOTE_FIELDS = /* GraphQL */ `
+  id
+  creditNoteNumber
+  issuedOn
+  totalWithTax
+  currencyCode
+  reason
+  invoiceId
+  kind
+  storageKey
+  createdAt
+`;
+const PACKING_SLIP_FIELDS = /* GraphQL */ `
+  id
+  packingSlipNumber
+  fulfillmentId
+  languageCode
+  storageKey
+  createdAt
+`;
+const DOCUMENT_EXTENSION_FIELDS = /* GraphQL */ `
+  key
+  documentTypes
+  schemaVersion
+  jsonSchema
+  templateFragment
+  createdAt
+  updatedAt
+`;
+export const GENERATE_INVOICE_MUTATION = /* GraphQL */ `
+  mutation GenerateInvoice(
+    $orderId: ID!
+    $invoicedOn: String!
+    $languageCode: String
+    $note: String
+    $extensions: [DocumentExtensionInput!]
+  ) {
+    generateInvoice(
+      orderId: $orderId
+      invoicedOn: $invoicedOn
+      languageCode: $languageCode
+      note: $note
+      extensions: $extensions
+    ) { ${INVOICE_FIELDS} }
+  }
+`;
+export const GENERATE_PACKING_SLIP_MUTATION = /* GraphQL */ `
+  mutation GeneratePackingSlip(
+    $fulfillmentId: ID!
+    $languageCode: String
+    $extensions: [DocumentExtensionInput!]
+  ) {
+    generatePackingSlip(
+      fulfillmentId: $fulfillmentId
+      languageCode: $languageCode
+      extensions: $extensions
+    ) { ${PACKING_SLIP_FIELDS} }
+  }
+`;
+export const DOCUMENT_DATA_QUERY = /* GraphQL */ `
+  query DocumentData($documentId: ID!, $type: DocumentType!) {
+    documentData(documentId: $documentId, type: $type)
+  }
+`;
+export const ORDER_INVOICES_QUERY = /* GraphQL */ `
+  query OrderInvoices($orderId: ID!) {
+    orderInvoices(orderId: $orderId) { ${INVOICE_FIELDS} }
+  }
+`;
+export const ORDER_CREDIT_NOTES_QUERY = /* GraphQL */ `
+  query OrderCreditNotes($orderId: ID!) {
+    orderCreditNotes(orderId: $orderId) { ${CREDIT_NOTE_FIELDS} }
+  }
+`;
+export const PREVIEW_INVOICE_MUTATION = /* GraphQL */ `
+  mutation PreviewInvoice($orderId: ID!, $invoicedOn: String!, $languageCode: String, $note: String) {
+    previewInvoice(orderId: $orderId, invoicedOn: $invoicedOn, languageCode: $languageCode, note: $note)
+  }
+`;
+export const SEND_INVOICE_EMAIL_MUTATION = /* GraphQL */ `
+  mutation SendInvoiceEmail($input: SendInvoiceEmailInput!) {
+    sendInvoiceEmail(input: $input)
+  }
+`;
+export const ISSUE_PARTIAL_CREDIT_NOTE_MUTATION = /* GraphQL */ `
+  mutation IssuePartialCreditNote($input: IssuePartialCreditNoteInput!) {
+    issuePartialCreditNote(input: $input) { ${CREDIT_NOTE_FIELDS} }
+  }
+`;
+export const ISSUE_SUPPLEMENTARY_INVOICE_MUTATION = /* GraphQL */ `
+  mutation IssueSupplementaryInvoice($input: IssueSupplementaryInvoiceInput!) {
+    issueSupplementaryInvoice(input: $input) { ${INVOICE_FIELDS} }
+  }
+`;
+export const DOCUMENT_EXTENSIONS_QUERY = /* GraphQL */ `
+  query DocumentExtensions {
+    documentExtensions { ${DOCUMENT_EXTENSION_FIELDS} }
+  }
+`;
+export const REGISTER_DOCUMENT_EXTENSION_MUTATION = /* GraphQL */ `
+  mutation RegisterDocumentExtension($input: RegisterDocumentExtensionInput!) {
+    registerDocumentExtension(input: $input) { ${DOCUMENT_EXTENSION_FIELDS} }
+  }
+`;
+export const DELETE_DOCUMENT_EXTENSION_MUTATION = /* GraphQL */ `
+  mutation DeleteDocumentExtension($key: String!) {
+    deleteDocumentExtension(key: $key)
+  }
+`;
+/** A complete array behind the SDK's page shape (spec §9.2). */
+function wholeList(items, what) {
+    return createPage(items, { nextCursor: null, hasNext: false, total: items.length }, () => {
+        throw new Error(`${what} returns a complete list; there is no next page`);
+    });
+}
+function toApiType(type) {
+    const mapped = API_DOCUMENT_TYPE[type];
+    if (mapped === undefined) {
+        throw new ValidationError({
+            code: 'INVALID_DOCUMENT_TYPE',
+            message: `"${String(type)}" is not a document type. Expected one of ${Object.keys(API_DOCUMENT_TYPE).join(', ')}.`,
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    return mapped;
+}
+/**
+ * Decode leniently: a kind this SDK does not know is passed through as the
+ * server spelled it rather than dropped, so a client one version behind still
+ * sees that the block is registered for something — which is why the decoded
+ * field is typed `string[]`.
+ */
+function fromApiTypes(values) {
+    const byApi = new Map(Object.entries(API_DOCUMENT_TYPE).map(([type, api]) => [api, type]));
+    return values.map((value) => byApi.get(value) ?? value);
+}
+function toSchema(raw) {
+    return { ...raw, documentTypes: fromApiTypes(raw.documentTypes) };
+}
+/** Decode the base64 a PDF-returning mutation answers with. */
+function decodePdf(base64) {
+    // Node and every modern runtime have `atob`; Buffer would tie this package
+    // to Node, and it ships to browsers as the dashboard's client.
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}
+export function createDocumentsModule(transport) {
+    return {
+        // One implementation behind the two overloads the interface declares; the
+        // cast is the standard TypeScript shape for that, since an implementation
+        // signature is never itself part of the public type.
+        generate: (async (subjectId, type, options = {}) => {
+            if (type === 'invoice') {
+                if (!options.invoicedOn) {
+                    // Not defaulted to today: the document date decides which period the
+                    // money books into, and the caller's clock is not the store's.
+                    throw new ValidationError({
+                        code: 'INVALID_INVOICED_ON',
+                        message: 'generate(orderId, "invoice") requires options.invoicedOn (YYYY-MM-DD) — an invoice date is never assumed.',
+                        status: 400,
+                        service: 'vendure',
+                    });
+                }
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: GENERATE_INVOICE_MUTATION,
+                    variables: {
+                        orderId: subjectId,
+                        invoicedOn: options.invoicedOn,
+                        languageCode: options.languageCode ?? null,
+                        note: options.note ?? null,
+                        extensions: options.extensions ?? null,
+                    },
+                }, options);
+                return data.generateInvoice;
+            }
+            if (options.invoicedOn !== undefined || options.note !== undefined) {
+                throw new ValidationError({
+                    code: 'INVALID_DOCUMENT_OPTIONS',
+                    message: 'A packing slip has no invoice date and no note; pass only languageCode and extensions.',
+                    status: 400,
+                    service: 'vendure',
+                });
+            }
+            const data = await transport.graphql({
+                api: 'admin',
+                query: GENERATE_PACKING_SLIP_MUTATION,
+                variables: {
+                    fulfillmentId: subjectId,
+                    languageCode: options.languageCode ?? null,
+                    extensions: options.extensions ?? null,
+                },
+            }, options);
+            return data.generatePackingSlip;
+        }),
+        async data(documentId, type, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: DOCUMENT_DATA_QUERY,
+                variables: { documentId, type: toApiType(type) },
+            }, options);
+            return data.documentData;
+        },
+        async invoices(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_INVOICES_QUERY, variables: { orderId } }, options);
+            return wholeList(data.orderInvoices, 'orderInvoices');
+        },
+        async creditNotes(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_CREDIT_NOTES_QUERY, variables: { orderId } }, options);
+            return wholeList(data.orderCreditNotes, 'orderCreditNotes');
+        },
+        async previewInvoice(orderId, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: PREVIEW_INVOICE_MUTATION,
+                variables: {
+                    orderId,
+                    invoicedOn: options.invoicedOn,
+                    languageCode: options.languageCode ?? null,
+                    note: options.note ?? null,
+                },
+            }, options);
+            return decodePdf(data.previewInvoice);
+        },
+        async sendInvoiceEmail(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: SEND_INVOICE_EMAIL_MUTATION, variables: { input } }, options);
+            return data.sendInvoiceEmail;
+        },
+        async issuePartialCreditNote(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: ISSUE_PARTIAL_CREDIT_NOTE_MUTATION, variables: { input } }, options);
+            return data.issuePartialCreditNote;
+        },
+        async issueSupplementaryInvoice(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: ISSUE_SUPPLEMENTARY_INVOICE_MUTATION, variables: { input } }, options);
+            return data.issueSupplementaryInvoice;
+        },
+        extensions: {
+            async list(options) {
+                const data = await transport.graphql({ api: 'admin', query: DOCUMENT_EXTENSIONS_QUERY }, options);
+                return wholeList(data.documentExtensions.map(toSchema), 'documentExtensions');
+            },
+            async register(input, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: REGISTER_DOCUMENT_EXTENSION_MUTATION,
+                    variables: {
+                        input: { ...input, documentTypes: input.documentTypes.map(toApiType) },
+                    },
+                }, options);
+                return toSchema(data.registerDocumentExtension);
+            },
+            async delete(key, options) {
+                const data = await transport.graphql({ api: 'admin', query: DELETE_DOCUMENT_EXTENSION_MUTATION, variables: { key } }, options);
+                return data.deleteDocumentExtension;
+            },
+        },
+    };
+}

package/dist/index.d.ts

@@ -18,31 +18,63 @@
  * are defined — without this they can only pass inline literals.
  */
 export type { DeprecationNotice, Page, PageMeta, RateLimitInfo, RetryPolicy, } from '@sixtyninecommerce/core';
+/**
+ * The canonical app-manifest grammar, re-exported for the same reason the error
+ * hierarchy is: it is defined in `@sixtyninecommerce/core`, which is a
+ * transitive dependency pnpm does not resolve for a consumer. A surface that
+ * accepts a pasted manifest — the dashboard's registry page — needs the schema
+ * to say which keys exist at all without hand-copying a second, looser list.
+ *
+ * The registry is deliberately STRICTER than this schema (it refuses a padded
+ * string, a duplicate entry, a namespace naming another app), so validating
+ * against it says "worth sending", never "certain to be accepted".
+ */
 /**
  * The error hierarchy this package throws, re-exported so a consumer can catch
  * it without adding a direct dependency on `@sixtyninecommerce/core` — which,
  * being transitive, pnpm would not resolve for them anyway.
  */
-export { AuthenticationError, BusinessRuleError, ConflictError, type ErrorDetail, NotFoundError, PermissionDeniedError, PlatformError, type ProblemDetails, RateLimitedError, TransportError, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
+export { APP_MANIFEST_SCHEMA, APP_MANIFEST_SCHEMA_SOURCE, AuthenticationError, BusinessRuleError, ConflictError, type ErrorDetail, NotFoundError, PermissionDeniedError, PlatformError, type ProblemDetails, RateLimitedError, TransportError, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
 export type { ApiTokensModule, CreatedApiToken } from './api-tokens/index.js';
 export type { AppCryptoKey, AppPrivateKey } from './apps/assertion.js';
+export type { AppInstallationConfig, AppInstallationConfigModule } from './apps/config.js';
 export type { AppCredential, AppCredentialConfig } from './apps/credential.js';
 export type { App, AppInstallation, ApproveConsentInput, AppsModule, InstallAppInput, } from './apps/index.js';
 export type { AuditCall, AuditCallFilter, AuditCorrelation, AuditEvent, AuditEventFilter, AuditModule, } from './audit/index.js';
 export type { AuthModule } from './auth/index.js';
 export { type AdminClient, type AdminClientConfig, type AppAuthConfig, createAdminClient, type SessionConfig, } from './client.js';
 export type { Form, FormField, FormFieldInput, FormFieldTranslation, FormFieldTranslationInput, FormInput, FormsModule, FormTranslation, FormTranslationInput, } from './content/forms.js';
+export type { CustomObject, CustomObjectsModule } from './custom-objects/index.js';
+export type { CreateCustomerInput, CreatedCustomer, Customer, CustomerAddress, CustomerAddressesModule, CustomerErasureRecord, CustomerGroupRef, CustomerGroupsModule, CustomerInvitation, CustomerInviteMode, CustomersModule, EraseCustomerOptions, UpdateCustomerInput, } from './customers/index.js';
+export type { CreditNote, DocumentData, DocumentDataIssuer, DocumentDataLine, DocumentDataNumbering, DocumentDataParty, DocumentDataTaxRow, DocumentDataTotals, DocumentExtensionInput, DocumentExtensionSchema, DocumentExtensionsModule, DocumentLineInput, DocumentsModule, DocumentType, GenerateDocumentOptions, Invoice, IssuePartialCreditNoteInput, IssueSupplementaryInvoiceInput, PackingSlip, RegisterDocumentExtensionInput, SendInvoiceEmailInput, } from './documents/index.js';
+export { MAX_DOCUMENT_EXTENSIONS } from './documents/index.js';
 export { AdminProjectionError } from './errors.js';
 export type { CreateHeadInput, Head, HeadsModule, UpdateHeadInput, } from './heads/index.js';
+/**
+ * `JobHandle` and `WaitOptions` are exported from here AND from
+ * `./platform/provision-store.js`, which re-exports them: they used to live
+ * there, and a consumer's import must not break because the platform grew a
+ * generic jobs resource around them.
+ */
+export type { Job, JobFilter, JobHandle, JobStatus, JobsModule, WaitOptions, } from './jobs/index.js';
+export { TERMINAL_JOB_STATUSES } from './jobs/index.js';
 export type { LocationProfile, LocationStockLocation, LocationsModule, OpeningHours, OpeningHoursDay, OpeningHoursInterval, StockLocationAddress, StockLocationAddressInput, UpsertLocationProfileInput, } from './locations/index.js';
 export { OPENING_HOURS_DAYS } from './locations/index.js';
 export type { ApiTokenTemplate, JsonSchema, LabelMap, MetaCatalog, MetaCatalogLabels, MetaCatalogPermissions, MetaCatalogPlugins, MetaCatalogTransitions, MetaModule, PermissionGroup, PluginCatalogEntry, RoleTemplate, StatusMetaMap, StatusTone, TransitionMap, } from './meta/index.js';
+export type { Metafield, MetafieldAttachment, MetafieldDefinition, MetafieldDefinitionsModule, MetafieldMoney, MetafieldOwnerType, MetafieldReference, MetafieldScalarType, MetafieldsModule, MetafieldType, MetafieldVisibility, SetMetafieldInput, UpsertMetafieldDefinitionInput, } from './metafields/index.js';
+export { METAFIELD_OWNER_TYPES, METAFIELD_SCALAR_TYPES } from './metafields/index.js';
+export type { OrderSettlement, OrdersModule } from './orders/index.js';
+export type { SurchargeCall, SurchargedOrder, SurchargeInput, SurchargesModule, } from './orders/surcharges.js';
+export type { IssuedRefund, OrderPaymentPosition, OrderRefundPosition, PaidOrder, PaymentsModule, ProviderConnection, ProviderCredentialPath, ProviderOnboardingStart, ProviderReadiness, ProvidersModule, ProviderTerminal, ProviderTerminalsModule, ProvisionTerminalInput, ReadinessOptions, RecordPaymentInput, RefundablePayment, RefundPaymentInput, } from './payments/index.js';
 export type { AppKey, PlatformAppsModule, RegisterAppResult, RegisteredApp, } from './platform/apps.js';
 export { requireHumanSession } from './platform/guard.js';
-export type { JobHandle, PlatformModule, ProvisionProfile, ProvisionRun, ProvisionRunStatus, ProvisionStep, ProvisionStepStatus, ProvisionStoreInput, ProvisionStoreResult, WaitOptions, } from './platform/provision-store.js';
+export type { PlatformModule, ProvisionProfile, ProvisionRun, ProvisionRunStatus, ProvisionStep, ProvisionStepStatus, ProvisionStoreInput, ProvisionStoreResult, } from './platform/provision-store.js';
 export { PROVISION_PROFILES } from './platform/provision-store.js';
 export type { Redirect, RedirectCreateInput, RedirectsModule, RedirectUpdateInput, } from './seo/redirects.js';
+export type { TaxClass, TaxClassesModule, TaxClassMapping, TaxClassTaxCategory, TaxMappingsModule, TaxModule, UpsertTaxClassInput, } from './tax/index.js';
+export { TAX_CLASS_FALLBACK_COUNTRY } from './tax/index.js';
 export type { CapabilitiesModule, Capability, CapabilityManifest, } from './tenant/capabilities.js';
 export type { ChannelsModule } from './tenant/channels.js';
 export type { ChannelRetention, RetentionHold, RetentionModule, SetRetentionInput, } from './tenant/retention.js';
 export type { ApiToken, Call, ChannelInfo, CreateApiTokenInput, ListOptions, Me, TenantContext, TenantScope, UpdateApiTokenInput, WhoAmI, } from './types.js';
+export type { ClaimAsAssetInput, StagedUpload, StagedUploadTicket, StageUploadInput, UploadBody, UploadPurpose, UploadStatus, UploadsModule, } from './uploads/index.js';

package/dist/index.js

@@ -11,14 +11,29 @@
  * dashboard is one — but constructing a client with an API token there throws
  * `CREDENTIAL_IN_BROWSER` (spec §18 amendment 3).
  */
+/**
+ * The canonical app-manifest grammar, re-exported for the same reason the error
+ * hierarchy is: it is defined in `@sixtyninecommerce/core`, which is a
+ * transitive dependency pnpm does not resolve for a consumer. A surface that
+ * accepts a pasted manifest — the dashboard's registry page — needs the schema
+ * to say which keys exist at all without hand-copying a second, looser list.
+ *
+ * The registry is deliberately STRICTER than this schema (it refuses a padded
+ * string, a duplicate entry, a namespace naming another app), so validating
+ * against it says "worth sending", never "certain to be accepted".
+ */
 /**
  * The error hierarchy this package throws, re-exported so a consumer can catch
  * it without adding a direct dependency on `@sixtyninecommerce/core` — which,
  * being transitive, pnpm would not resolve for them anyway.
  */
-export { AuthenticationError, BusinessRuleError, ConflictError, NotFoundError, PermissionDeniedError, PlatformError, RateLimitedError, TransportError, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
+export { APP_MANIFEST_SCHEMA, APP_MANIFEST_SCHEMA_SOURCE, AuthenticationError, BusinessRuleError, ConflictError, NotFoundError, PermissionDeniedError, PlatformError, RateLimitedError, TransportError, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
 export { createAdminClient, } from './client.js';
+export { MAX_DOCUMENT_EXTENSIONS } from './documents/index.js';
 export { AdminProjectionError } from './errors.js';
+export { TERMINAL_JOB_STATUSES } from './jobs/index.js';
 export { OPENING_HOURS_DAYS } from './locations/index.js';
+export { METAFIELD_OWNER_TYPES, METAFIELD_SCALAR_TYPES } from './metafields/index.js';
 export { requireHumanSession } from './platform/guard.js';
 export { PROVISION_PROFILES } from './platform/provision-store.js';
+export { TAX_CLASS_FALLBACK_COUNTRY } from './tax/index.js';

package/dist/jobs/index.d.ts

@@ -0,0 +1,143 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * One long-running operation, whatever runs it (spec §6.11).
+ *
+ * Several engines run behind this — store provisioning, demo seeding, the
+ * platform's object-storage moves and purges, data pipelines, and the commerce
+ * engine's own job queue — and a caller needs none of that: one id, one status
+ * vocabulary, one way to wait. More engines are adopted over time, and a `kind`
+ * this release does not list simply has no jobs to return yet.
+ */
+export interface Job {
+    id: string;
+    /**
+     * The tenant the work belongs to, or null for platform work that has none yet
+     * — a store provisioning run has no channel until it builds one. A tenant
+     * credential only ever sees its own.
+     */
+    channelId: string | null;
+    /**
+     * `<domain>.<verb>`: `store.provision`, `demo.seed`, `r2.move`, `r2.purge`,
+     * `pipeline.import`, `pipeline.export`, `store.rename`, `store.delete`,
+     * `warehouse.document`.
+     */
+    kind: string;
+    status: JobStatus;
+    /**
+     * What the engine can say about how far it is. Every field is optional
+     * because the engines genuinely differ: a provisioning run counts the steps
+     * it has finished, an object-storage move counts objects, and a seeding run
+     * only names the step it is on.
+     */
+    progress: {
+        done?: number;
+        total?: number;
+        message?: string;
+    };
+    /** The principal that asked for the work, when the engine recorded one. */
+    submittedBy: string | null;
+    /** ISO-8601 UTC, or null while the work is still queued. */
+    startedAt: string | null;
+    finishedAt: string | null;
+    /** Where the output landed, for the kinds that produce one. */
+    resultUrl?: string | null;
+    /**
+     * Why it failed. `code` is stable and safe to branch on — a provisioning run
+     * that undid everything it had built answers `PROVISION_RUN_COMPENSATED`,
+     * which is the difference between "retry" and "call an operator".
+     */
+    error?: {
+        code: string;
+        message: string;
+    } | null;
+    createdAt: string;
+    [extra: string]: unknown;
+}
+/** The five statuses, whatever the engine's own vocabulary is. */
+export type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+/** A job nothing more will happen to. */
+export declare const TERMINAL_JOB_STATUSES: readonly JobStatus[];
+export interface JobFilter extends ListOptions {
+    /** Exact kind, e.g. `store.provision`. */
+    kind?: string;
+    status?: JobStatus;
+    /**
+     * One channel's jobs. Only a platform credential has anything to narrow —
+     * every other caller is already confined to its own channel, and naming
+     * another one simply returns nothing.
+     */
+    channelId?: string;
+}
+export interface WaitOptions {
+    /** How often to poll. Default 2000 ms; anything below 250 ms is raised to it. */
+    intervalMs?: number;
+    /** Give up after this long. Default 300000 ms (5 minutes). */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * A long-running operation in flight (spec §6.11). `runId` is the receipt: it
+ * outlives this process, so a caller that cannot wait can hand it on and poll
+ * it later.
+ */
+export interface JobHandle<T> {
+    runId: string;
+    /**
+     * Poll until the run reaches a terminal status, then resolve with its result
+     * — or throw what the failure means for the caller.
+     */
+    wait(options?: WaitOptions): Promise<T>;
+}
+export interface JobsModule {
+    /** This tenant's jobs, newest first. */
+    list(filter?: JobFilter): Promise<Page<Job>>;
+    get(id: string, options?: Call): Promise<Job>;
+    /**
+     * Wait for a job to end, and resolve with it WHATEVER the ending was —
+     * `succeeded`, `failed` or `cancelled`. It does not throw on a failed job:
+     * this resource covers engines whose failures mean different things, and the
+     * job carries its own `error.code` to tell them apart. It throws only
+     * when waiting itself could not continue: `JOB_WAIT_TIMEOUT`, an aborted
+     * signal, or a read that failed for a reason polling cannot fix.
+     */
+    wait(id: string, options?: WaitOptions & Call): Promise<Job>;
+    /**
+     * Ask the engine to stop.
+     *
+     * Best-effort BY KIND, and honest about it: a kind whose engine cannot stop a
+     * run in flight is refused with `CANCEL_NOT_SUPPORTED` (a `BusinessRuleError`)
+     * rather than reported as cancelled. A provisioning run never can — it either
+     * finishes or undoes itself — while an object-storage move stops at its next
+     * page.
+     */
+    cancel(id: string, options?: Call): Promise<{
+        id: string;
+        status: JobStatus;
+    }>;
+}
+export declare function createJobsModule(transport: Transport): JobsModule;
+/** What a poll loop needs to know about the thing it is waiting for. */
+export interface PollUntilTerminal<T> extends WaitOptions {
+    read(signal?: AbortSignal): Promise<T>;
+    isTerminal(value: T): boolean;
+    /**
+     * Build the error when waiting gives up. It receives the last value read, so
+     * a timeout can say what the work was doing — which is the whole reason the
+     * loop keeps it.
+     */
+    onTimeout(lastSeen: T | undefined): Error;
+}
+/**
+ * The polling loop every `wait()` in this SDK shares.
+ *
+ * Promoted out of `platform/provision-store.ts`, where it was written for one
+ * resource: the backoff, the abort handling and — the part worth keeping — the
+ * distinction between a read that failed because the SERVER hiccuped and one
+ * that failed because the answer is no. The first is retried a few times; the
+ * second is thrown at once, because polling a 404 forever helps nobody.
+ */
+export declare function pollUntilTerminal<T>(options: PollUntilTerminal<T>): Promise<T>;
+/** A read that failed for a reason polling again cannot fix. */
+export declare function isTerminalPollError(error: unknown): boolean;
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/jobs/index.js

@@ -0,0 +1,132 @@
+import { createPage, PLATFORM_PASSTHROUGH_KEYS, readRestPage, TransportError, } from '@sixtyninecommerce/core';
+/** A job nothing more will happen to. */
+export const TERMINAL_JOB_STATUSES = ['succeeded', 'failed', 'cancelled'];
+const DEFAULT_INTERVAL_MS = 2_000;
+const MIN_INTERVAL_MS = 250;
+const DEFAULT_TIMEOUT_MS = 300_000;
+/**
+ * Consecutive failed READS tolerated while waiting. A poll is a read of work
+ * that is still going: one 503 from a rolling restart must not report a failure
+ * for a run that is fine. Reset by any successful read, so only a sustained
+ * outage gives up — and a refusal that is ABOUT the job (not found, no
+ * permission) is not retried at all.
+ */
+const MAX_CONSECUTIVE_POLL_FAILURES = 3;
+/**
+ * `progress` is an engine's OWN bag — a pipeline counts per entity type, a
+ * seeding run names a step — so its keys are passed through uncased and read
+ * exactly as the engine wrote them.
+ *
+ * `error` is NOT in that set and is not meant to be: it is a fixed
+ * `{ code, message }` DTO, and `error` is also the legacy envelope member, so
+ * preserving it platform-wide would be wrong. An engine that ever wants keyed
+ * failure detail puts it under `progress` or gets its own passthrough key.
+ */
+const JOB_PASSTHROUGH = PLATFORM_PASSTHROUGH_KEYS;
+export function createJobsModule(transport) {
+    async function list(filter) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: '/jobs',
+            query: {
+                after: filter?.after,
+                limit: filter?.limit,
+                kind: filter?.kind,
+                status: filter?.status,
+                channel_id: filter?.channelId,
+            },
+        }, { ...filter, preserveKeys: JOB_PASSTHROUGH });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => list({ ...filter, after: cursor }));
+    }
+    async function get(id, options) {
+        return transport.rest('plugins', { method: 'GET', path: `/jobs/${encodeURIComponent(id)}` }, { ...options, preserveKeys: JOB_PASSTHROUGH });
+    }
+    return {
+        list,
+        get,
+        async wait(id, options) {
+            return pollUntilTerminal({
+                read: (signal) => get(id, { ...options, ...(signal ? { signal } : {}) }),
+                isTerminal: (job) => TERMINAL_JOB_STATUSES.includes(job.status),
+                onTimeout: (seen) => jobWaitTimeout(id, seen),
+                ...options,
+            });
+        },
+        async cancel(id, options) {
+            return transport.rest('plugins', { method: 'POST', path: `/jobs/${encodeURIComponent(id)}/cancel` }, options);
+        },
+    };
+}
+/**
+ * The polling loop every `wait()` in this SDK shares.
+ *
+ * Promoted out of `platform/provision-store.ts`, where it was written for one
+ * resource: the backoff, the abort handling and — the part worth keeping — the
+ * distinction between a read that failed because the SERVER hiccuped and one
+ * that failed because the answer is no. The first is retried a few times; the
+ * second is thrown at once, because polling a 404 forever helps nobody.
+ */
+export async function pollUntilTerminal(options) {
+    const intervalMs = Math.max(options.intervalMs ?? DEFAULT_INTERVAL_MS, MIN_INTERVAL_MS);
+    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let consecutiveFailures = 0;
+    let lastSeen;
+    for (;;) {
+        let value;
+        try {
+            value = await options.read(options.signal);
+            consecutiveFailures = 0;
+        }
+        catch (error) {
+            if (options.signal?.aborted === true)
+                throw error;
+            consecutiveFailures += 1;
+            if (isTerminalPollError(error) || consecutiveFailures > MAX_CONSECUTIVE_POLL_FAILURES) {
+                throw error;
+            }
+            if (Date.now() >= deadline)
+                throw options.onTimeout(lastSeen);
+            await delay(intervalMs, options.signal);
+            continue;
+        }
+        lastSeen = value;
+        if (options.isTerminal(value))
+            return value;
+        if (Date.now() >= deadline)
+            throw options.onTimeout(value);
+        await delay(intervalMs, options.signal);
+    }
+}
+/** A read that failed for a reason polling again cannot fix. */
+export function isTerminalPollError(error) {
+    const status = error?.status;
+    return typeof status === 'number' && status >= 400 && status < 500 && status !== 429;
+}
+function jobWaitTimeout(id, job) {
+    const at = job ? `while it was ${job.status}` : 'without reading it successfully';
+    return new TransportError({
+        code: 'JOB_WAIT_TIMEOUT',
+        message: `Stopped waiting for job ${id} ${at}. The job may still be going — poll jobs.get("${id}") to follow it.`,
+        status: 0,
+        service: 'plugins',
+        retryable: true,
+    });
+}
+export function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason instanceof Error ? signal.reason : new Error('Aborted'));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(signal?.reason instanceof Error ? signal.reason : new Error('Aborted'));
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}