@sixtyninecommerce/admin 0.8.0 → 0.9.0

package/dist/bulk/index.d.ts

@@ -0,0 +1,323 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Job, JobHandle, JobsModule } from '../jobs/index.js';
+import type { Call, ListOptions } from '../types.js';
+import type { UploadsModule } from '../uploads/index.js';
+/**
+ * What each line of a bulk file is.
+ *
+ * `order` carries external order entry's semantics (spec §8.1): see
+ * {@link BulkRow} for its row, and {@link BulkModule.export} for what an
+ * export of it holds. Content items are absent — they live in the CMS, which
+ * has no bulk writer yet.
+ */
+export type BulkEntity = 'product' | 'variant' | 'price' | 'stock_level' | 'customer' | 'metafield' | 'order';
+/**
+ * How an import applies each row.
+ *
+ * - `upsert` (the default) creates what is missing and updates what is there,
+ *   so re-sending a file that was half applied CONVERGES. It is the only mode
+ *   that is safe to repeat, which is why it is the default.
+ * - `create` skips a key that already exists rather than failing it.
+ * - `update` fails a row whose key does not exist.
+ *
+ * `price` and `stock_level` take no `create`: both belong to a variant that
+ * already exists, so there is nothing to create. `metafield` takes only
+ * `upsert`, because `setMetafield` is one by construction. `order` takes only
+ * `create`: an order is composed once and then moved by its own lifecycle
+ * (payments, park, settle), and is never RESTATED through bulk — so pass
+ * `mode: 'create'` explicitly, since the default is `upsert`. A mode an entity
+ * cannot apply is refused when you submit, not once per row.
+ */
+export type BulkMode = 'create' | 'upsert' | 'update';
+/**
+ * A row of a bulk file: one entity, as a JSON object, on one line.
+ *
+ * **The shapes are the SDK's own write inputs.** A `customer` row is what
+ * `admin.customers.create()` takes; a `metafield` row is what
+ * `admin.metafields.set()` takes. That is the contract of the resource, and it
+ * is what lets you test one row interactively and then send a million identical
+ * ones.
+ *
+ * The accepted fields per entity, with their keys (what a row is matched on):
+ *
+ * | entity | key | fields |
+ * | --- | --- | --- |
+ * | `product` | `slug` | `slug`, `name`, `description`, `enabled`, `facetValueIds`, `languageCode`, `customFields` |
+ * | `variant` | `sku` | `sku`, `productSlug` (to create), `name`, `price`, `prices`, `enabled`, `optionIds`, `facetValueIds`, `taxCategoryId`, `trackInventory`, `outOfStockThreshold`, `useGlobalOutOfStockThreshold`, `languageCode`, `customFields` |
+ * | `price` | `sku` | `sku`, `price`, `prices` |
+ * | `stock_level` | `sku` (+ location) | `sku`, `stockOnHand`, `stockLocationId` |
+ * | `customer` | `emailAddress` | `emailAddress`, `firstName`, `lastName`, `title`, `phoneNumber`, `customFields` |
+ * | `metafield` | the four together | `ownerType`, `ownerId`, `namespace`, `key`, `value` |
+ * | `order` | `idempotency_key` (+ `externalRef`) | `idempotency_key`, then every field of `admin.orders.createOrRecover()`'s input: `externalRef`, `customerId`, `location`, `billingAddress`, `lines` (with `kind: 'catalog' \| 'external'`), `surcharges`, `fulfilment`, `transitionTo`, `attachments` |
+ *
+ * **A `stock_level` row** writes only a location of this store: another
+ * store's location (or an id that does not exist) fails the row with
+ * `LOCATION_NOT_IN_CHANNEL`. A token or app restricted with `locationIds`
+ * writes only its own locations (`LOCATION_NOT_ALLOWED` for any other, dry run
+ * included), and its `stock_level` export holds only rows at those locations.
+ * The restriction is the one the credential had when the operation was
+ * submitted. Such a credential can read (`get`, `results`) only the
+ * `stock_level` operations it submitted itself.
+ *
+ * **An `order` row** is `admin.orders.createOrRecover(input, { idempotencyKey })`
+ * written as one object: the input's fields under their SDK names, and the key
+ * as `idempotency_key` (snake_case, like the rest of the bulk envelope, because
+ * it is the call's option rather than a field of the input). The key is
+ * REQUIRED and bulk never makes one up — a row without it fails. Re-sending a
+ * row is the entry call's own recovery: the same key and body answer `ok` with
+ * the id of the order the first send created (never a second order), a changed
+ * body under the key is `IDEMPOTENCY_CONFLICT`, and the same `externalRef` with
+ * a different basket is `EXTERNAL_REF_CONFLICT`. Every refusal the interactive
+ * call documents (`LINE_MISPRICED`, `TAX_CLASS_UNMAPPED`, …) is that row's
+ * `problem`, with the line's position as `details[].field` (`lines[1]`), and the
+ * rest of the file carries on. A row that prices a line or a surcharge itself
+ * needs `ImportExternalLines`, exactly as the interactive call does. A dry run
+ * checks the row's shape and that every variant, the `location` and the
+ * `customerId` exist in this store — and never calls order entry, so pricing
+ * and tax-class refusals only a real run can report.
+ *
+ * Two things worth knowing before you build a file:
+ *
+ * - **An unknown field is REFUSED, not ignored.** A misspelled `stockOnhand` in
+ *   a ten-thousand-row feed fails those rows with a message naming the field,
+ *   rather than completing green having changed nothing.
+ * - **Money is integer minor units**, like everywhere else on this platform:
+ *   `1999`, never `19.99`. A fractional value is refused with that sentence.
+ */
+export type BulkRow = Record<string, unknown>;
+export type BulkRowStatus = 'ok' | 'skipped' | 'failed';
+/** What happened to one row. */
+export interface BulkRowResult {
+    /** 1-based, counting the file's NON-BLANK lines. */
+    row: number;
+    /**
+     * `ok` — applied (or, in a dry run, would have been). `skipped` — understood
+     * and deliberately not applied, which today means `create` mode meeting a key
+     * that already exists. `failed` — refused; `problem` says why.
+     */
+    status: BulkRowStatus;
+    /** The id of the entity written, when one was. */
+    id?: string;
+    /**
+     * RFC 9457, and the SAME document the interactive call would have answered
+     * with for the same input — same `code`, same `detail`. A client that already
+     * handles `admin.customers.create()` being refused handles this.
+     */
+    problem?: {
+        type: string;
+        title: string;
+        status: number;
+        code: string;
+        detail?: string;
+    };
+    [extra: string]: unknown;
+}
+export type BulkOperationStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+/** One bulk operation, and where its output is. */
+export interface BulkOperation {
+    id: string;
+    operation: 'import' | 'export';
+    entity: BulkEntity;
+    mode: BulkMode | null;
+    dryRun: boolean;
+    containerId: string | null;
+    status: BulkOperationStatus;
+    /** Rows SEEN so far; the total once the operation is terminal. */
+    totalRows: number;
+    okRows: number;
+    skippedRows: number;
+    failedRows: number;
+    /**
+     * A signed link to the JSONL output — an export's rows, or an import's per-row
+     * results.
+     *
+     * **Minted per read and good for about fifteen minutes.** It is not stored, so
+     * do not persist it: read the operation again when you need a fresh one. The
+     * object itself lives in private storage and is not reachable any other way.
+     *
+     * For an IMPORT, check {@link resultTruncated} before treating this file as
+     * complete — `results(id)` is the authoritative set either way.
+     */
+    resultUrl: string | null;
+    /**
+     * The file behind {@link resultUrl} stopped SHORT of the run.
+     *
+     * The operation still succeeded and every row is still there — but in the
+     * TABLE, not in the file: `admin.bulk.results(id)` pages the complete set.
+     * It happens when the outcomes exceed the size one object may hold, which a
+     * file with tens of thousands of REFUSED rows reaches long before the row
+     * limit, because each refusal carries a problem document.
+     *
+     * Check it before you treat the downloaded file as the whole story.
+     */
+    resultTruncated: boolean;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    createdAt: string | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    [extra: string]: unknown;
+}
+export interface BulkImportOptions extends Call {
+    /** Default `upsert`. */
+    mode?: BulkMode;
+    /**
+     * Validate and look every row up, write NOTHING.
+     *
+     * The results say what each row WOULD have done, including "row 412's sku
+     * does not exist on this store" — a dry run makes the same lookups a real run
+     * makes. The staged file is still consumed, so a rehearsal and the real run
+     * mean staging the bytes twice.
+     */
+    dryRun?: boolean;
+    /**
+     * Your own handle for "these files are one logical import".
+     *
+     * It GROUPS; it does not coordinate. The operations sharing one still succeed
+     * and fail independently, because a multi-file import whose parts had to agree
+     * would need a transaction across a million rows.
+     */
+    containerId?: string;
+    /** Makes a retried submit return the SAME operation instead of a second one. */
+    idempotencyKey?: string;
+    /**
+     * Your own handle for the STAGING call, when this SDK has to stage the bytes.
+     *
+     * Staging is the call that hands out a signed URL, and a dropped response on
+     * it is the ordinary failure: without a token every retry would reserve
+     * another place and leave an object nobody ever claims. One is generated when
+     * you do not give one, which is right for a single attempt and wrong for a
+     * retry you drive yourself.
+     */
+    clientToken?: string;
+    /** A label for a human reading the upload list. Default `bulk.jsonl`. */
+    filename?: string;
+}
+export interface BulkExportOptions extends Call {
+    containerId?: string;
+    idempotencyKey?: string;
+}
+export interface BulkResultsFilter extends ListOptions {
+}
+/**
+ * What you can hand `admin.bulk.import` as the file.
+ *
+ * - **bytes** (`Uint8Array`, `ArrayBuffer`, `Blob`) — staged and PUT for you;
+ * - a **`ReadableStream`** — collected, then staged. A presigned PUT signs one
+ *   exact length, so the bytes have to be counted before they are sent; there
+ *   is no way to stage a stream of unknown size;
+ * - a **staged upload id** you staged yourself with
+ *   `admin.uploads.stage({ purpose: 'bulk', … })`, which is how to send a file
+ *   this process never holds whole.
+ *
+ * **A filesystem PATH is deliberately not one of them.** This package is
+ * isomorphic and depends on `@sixtyninecommerce/core` and nothing else, so it
+ * cannot reach `node:fs` — a dynamic import of it would break every browser
+ * bundle and every external install. In Node it is one line at the call site,
+ * and it is YOUR `readFile`, not a hidden one:
+ *
+ * ```ts
+ * const bytes = await readFile('./prices.jsonl');
+ * ```
+ */
+export type BulkFile = {
+    stagedUploadId: string;
+} | Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>;
+/**
+ * JSONL bulk import and export (spec §6.11, §15.22).
+ *
+ * **The shape of it.** One line per entity, of the same shapes the SDK's own
+ * writes take. One operation becomes one job; a malformed row fails THAT row
+ * and never the job; the per-row outcomes are a page you can walk, and the
+ * whole thing is also a JSONL file behind a signed link.
+ *
+ * ```ts
+ * const entity = 'price' as const;
+ * const bytes = await readFile('./prices.jsonl');
+ * const handle = await admin.bulk.import(entity, bytes, {
+ *   mode: 'update',
+ *   idempotencyKey: crypto.randomUUID(),
+ * });
+ * const result = await handle.wait();
+ * if (result.failedRows > 0) {
+ *   for await (const row of await admin.bulk.results(result.id)) {
+ *     if (row.status === 'failed') console.error(row.row, row.problem?.detail);
+ *   }
+ * }
+ * ```
+ *
+ * **Field groups.** While an app or API token owns a field group on the store, a row that would
+ * change that group's data fails with `problem.code` `FIELD_GROUP_LOCKED` (the detail names the
+ * group and its owner), on every entity, unless the owner itself submitted the import. An
+ * unchanged value passes. A row that creates a record is never refused for it.
+ *
+ * **Feed identifiers.** A `product` row whose `customFields.brand`, or a `variant` row whose
+ * `customFields.gtin`, is NEW or CHANGED and breaks the feed rule (a brand over 70 characters, a
+ * GTIN that is not 8, 12, 13 or 14 digits, both after trimming) fails with `problem.code`
+ * `FEED_IDENTIFIER_INVALID` (status 400), creates included; the other rows carry on. A value the
+ * record already holds passes, so an edited export sent back is never refused for a value it did
+ * not change. A `dryRun` does not reach this rule: it stops before the write.
+ *
+ * **It does not spend your rate limit.** Submitting costs one request like any
+ * other write; the rows themselves are applied by the platform's own worker, so
+ * a million of them spend nothing of your budget (§15.22). Nothing is bypassed
+ * either — the same hooks, provenance and validation run as for an interactive
+ * write.
+ *
+ * **Rehearse first.** `dryRun` runs every check and every lookup and writes
+ * nothing. It is the cheapest way to find out that a column in a supplier's
+ * spreadsheet is in the wrong units.
+ *
+ * **An app installation's `customerData` level applies.** An export an app
+ * submits comes back as that app reads the Admin API: at `none` a customer
+ * row's `emailAddress`, `firstName` and `lastName` are `""`, and any field its
+ * level withholds is blank. A `customer` import, and a `customer` export
+ * filtered by `emails`, need `identity` (each row is matched by its email, so
+ * the outcome says whether an address is a customer); below it they are
+ * refused with `PermissionDeniedError` code `CUSTOMER_DATA_NOT_GRANTED`. An
+ * operation is readable (`get`, `results`) only at or above the level it was
+ * submitted at. A human's and a personal token's operations are unaffected.
+ */
+export interface BulkModule {
+    /**
+     * Import a file of rows. Answers a handle whose `wait()` resolves with the
+     * finished operation, whatever the ending was.
+     */
+    import(entity: BulkEntity, file: BulkFile, options?: BulkImportOptions): Promise<JobHandle<BulkOperation>>;
+    /**
+     * Export rows to JSONL. The output is exactly what `import` accepts, so an
+     * export can be edited and sent back — except for `order`, below.
+     *
+     * `filter` narrows it, and an UNRECOGNISED key is refused rather than ignored
+     * — a filter nothing honours would turn an intended narrowing into a
+     * whole-store export that completes green. Common keys: `updated_after` (an
+     * ISO-8601 instant WITH an offset), and a key list per entity (`slugs`,
+     * `skus`, `emails`, and `ids` for `order`). `metafield` requires `owner_type`
+     * and `owner_ids`.
+     *
+     * **An `order` export is a record of the entry, not an input to re-import**
+     * (orders are not restated). One row per order — a shopper's open cart is not
+     * an order and is left out — with `id`, `code`, `externalRef`, `state`,
+     * `placedAt`, `customerId` and `currencyCode`; `lines` in the order the entry
+     * request sent them, each with its `id` and `position`: an externally priced
+     * line as `kind: 'external'` with its `label`, `taxClass`, and the `unitPrice`
+     * and `priceBasis` it was STATED in (the pair the platform holds fixed), a
+     * catalog line as `kind: 'catalog'` with its `productVariantId` and `sku`, and
+     * on every line `charged` — what the order computed, in both bases: `unitPrice`/`linePrice` before discounts, `proratedLinePrice(WithTax)` after line and order-level promotions (the figure the lines' sum to `subTotal` on). Then the
+     * `surcharges`, the order's totals, `billableTotalWithTax` (what the invoice
+     * charges, goodwill rounding folded in) beside the raw `totalWithTax`, and
+     * `payment` — `covered`, `settled`, `authorized`, `refunded`, `outstanding` at
+     * the moment of export. Money is integer minor units of `currencyCode`.
+     * Customer identity is the id only: no name, email or address leaves through
+     * an export, the same rule the `order.*` events keep.
+     */
+    export(entity: BulkEntity, filter?: Record<string, unknown>, options?: BulkExportOptions): Promise<JobHandle<BulkOperation>>;
+    /** One operation, with a freshly signed `resultUrl`. */
+    get(id: string, options?: Call): Promise<BulkOperation>;
+    /** The per-row outcomes, in ROW order. Iterate the page to walk them all. */
+    results(id: string, filter?: BulkResultsFilter): Promise<Page<BulkRowResult>>;
+}
+export declare function createBulkModule(transport: Transport, uploads: UploadsModule, jobs: JobsModule): BulkModule;
+export type { Job, JobHandle };

package/dist/bulk/index.js

@@ -0,0 +1,162 @@
+import { createPage, readRestPage } from '@sixtyninecommerce/core';
+/** The type a bulk file is staged as. */
+const JSONL_CONTENT_TYPE = 'application/x-ndjson';
+export function createBulkModule(transport, uploads, jobs) {
+    async function get(id, options) {
+        return transport.rest('plugins', { method: 'GET', path: `/bulk/${encodeURIComponent(id)}` }, options);
+    }
+    /**
+     * Wait for the JOB, then read the OPERATION.
+     *
+     * Two reads rather than one, because they answer different questions and the
+     * job resource is the one that knows when to stop polling. The operation is
+     * then read once, at the end, which is also when its `resultUrl` is worth
+     * having — a link minted while the run was going would have expired by the
+     * time the file existed.
+     */
+    function handleFor(jobId, options) {
+        return {
+            runId: jobId,
+            async wait(waitOptions) {
+                await jobs.wait(jobId, { ...options, ...waitOptions });
+                return get(jobId, options);
+            },
+        };
+    }
+    async function resultsPage(id, filter) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: `/bulk/${encodeURIComponent(id)}/results`,
+            query: { after: filter?.after, limit: filter?.limit },
+        }, filter);
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => resultsPage(id, { ...filter, after: cursor }));
+    }
+    return {
+        async import(entity, file, options) {
+            const stagedUploadId = await resolveStagedUpload(uploads, file, options);
+            // `jobId`, not `job_id`. The transport camelises every response key
+            // (`snakeToCamelKeys`, on by default), so the controller's `{ job_id }`
+            // arrives as `{ jobId }` — destructuring the wire spelling yields
+            // `undefined` and every handle then polls `/jobs/undefined`.
+            const { jobId } = await transport.rest('plugins', {
+                method: 'POST',
+                path: '/bulk/imports',
+                body: {
+                    entity,
+                    ...(options?.mode === undefined ? {} : { mode: options.mode }),
+                    ...(options?.dryRun === undefined ? {} : { dry_run: options.dryRun }),
+                    staged_upload_id: stagedUploadId,
+                    ...(options?.containerId === undefined ? {} : { container_id: options.containerId }),
+                },
+            }, 
+            // `idempotencyKey` rides on the OPTIONS, which is where the transport
+            // reads it to compose the `Idempotency-Key` header. Putting it in the
+            // call would have been silently ignored — the header would never be
+            // sent and a retried submit would start a second operation.
+            options);
+            return handleFor(jobId, options);
+        },
+        async export(entity, filter, options) {
+            const { jobId } = await transport.rest('plugins', {
+                method: 'POST',
+                path: '/bulk/exports',
+                body: {
+                    entity,
+                    ...(filter === undefined ? {} : { filter }),
+                    ...(options?.containerId === undefined ? {} : { container_id: options.containerId }),
+                },
+            }, {
+                ...options,
+                // The filter is the CALLER's own vocabulary — `updated_after`,
+                // `owner_type` — and the transport camelises every key unless told
+                // not to. Without this, `updated_after` would arrive as `updatedAfter`
+                // and be refused as an unknown filter key, which is the one mistake
+                // that is impossible to debug from the outside.
+                preserveKeys: FILTER_PASSTHROUGH,
+            });
+            return handleFor(jobId, options);
+        },
+        get,
+        results: resultsPage,
+    };
+}
+/**
+ * `filter` keys travel EXACTLY as the caller spelled them.
+ *
+ * The service refuses an unrecognised filter key on purpose, so a transport
+ * that camelised `updated_after` into `updatedAfter` would turn every filtered
+ * export into a 400 naming a key the caller never typed.
+ */
+const FILTER_PASSTHROUGH = new Set(['filter']);
+/**
+ * Turn whatever the caller gave us into a staged upload id.
+ *
+ * The bytes are COUNTED before they are staged, because a presigned PUT signs
+ * one exact `Content-Length` and there is no way to sign an upper bound. That
+ * is also why a `ReadableStream` is collected rather than piped: the size has
+ * to be known first. A caller whose file is too large to hold should stage it
+ * themselves and pass the id.
+ */
+async function resolveStagedUpload(uploads, file, options) {
+    if (typeof file === 'object' && file !== null && 'stagedUploadId' in file) {
+        return file.stagedUploadId;
+    }
+    const bytes = await readBytes(file);
+    const ticket = await uploads.stage({
+        purpose: 'bulk',
+        mimeType: JSONL_CONTENT_TYPE,
+        size: bytes.byteLength,
+        // A token of the caller's, when they gave one, so a dropped response on
+        // the staging call does not strand an object nobody will claim.
+        clientToken: options?.clientToken ?? randomToken(),
+        // A label for a human reading the upload list; it never reaches the
+        // object's location, which the platform composes from the store and an
+        // id it minted.
+        filename: options?.filename ?? 'bulk.jsonl',
+    }, 
+    // The CALLER's options, forwarded. Staging is a request like any other, and
+    // dropping them here sends it to the client's DEFAULT tenant while the
+    // submit that follows names the one the caller asked for — so the bytes
+    // land under the wrong store's prefix and the import then answers
+    // `UPLOAD_NOT_FOUND`, after they have already been uploaded. `signal` goes
+    // the same way: without it an abort cannot cancel the upload leg, which is
+    // the long one.
+    options);
+    await uploads.put(ticket, bytes);
+    return ticket.id;
+}
+async function readBytes(file) {
+    if (file instanceof Uint8Array)
+        return file;
+    if (file instanceof ArrayBuffer)
+        return new Uint8Array(file);
+    if (typeof Blob !== 'undefined' && file instanceof Blob) {
+        return new Uint8Array(await file.arrayBuffer());
+    }
+    return collectStream(file);
+}
+async function collectStream(stream) {
+    const chunks = [];
+    let total = 0;
+    const reader = stream.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value) {
+            chunks.push(value);
+            total += value.byteLength;
+        }
+    }
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return out;
+}
+function randomToken() {
+    return globalThis.crypto.randomUUID();
+}

package/dist/catalog/assets.d.ts

@@ -0,0 +1,147 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+import { type CatalogueOwnership } from './types.js';
+export interface Asset {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    name: string;
+    type: 'IMAGE' | 'VIDEO' | 'BINARY';
+    mimeType: string;
+    fileSize: number;
+    width: number;
+    height: number;
+    source: string;
+    preview: string;
+    /** Fractions of width and height (0–1); null when never set. */
+    focalPoint: {
+        x: number;
+        y: number;
+    } | null;
+    tags: string[];
+    /** The store's own asset, or its organization's; see {@link CatalogueOwnership}. */
+    catalogueOwnership: CatalogueOwnership;
+}
+export interface CreateAssetInput {
+    file: Blob;
+    /**
+     * The name the asset is stored and listed under. Required unless `file` is a
+     * `File` (which carries its own): a bare Blob would otherwise be stored as
+     * "blob".
+     */
+    fileName?: string;
+    tags?: string[];
+}
+export interface UpdateAssetInput {
+    id: string;
+    name?: string;
+    focalPoint?: {
+        x: number;
+        y: number;
+    } | null;
+    /** Replaces the tag list. */
+    tags?: string[];
+}
+/** One language's description of an image: its alt text in that language. */
+export interface AssetDescription {
+    /** A language the store offers (`en`, `nl`, `pt_BR`). */
+    languageCode: string;
+    description: string;
+}
+/** What {@link AssetDescriptionsModule.set} saved. */
+export interface AssetDescriptionsResult {
+    assetId: string;
+    /** The image's descriptions in the store, ordered by language. */
+    descriptions: AssetDescription[];
+    /** The image's alt text: the store's default-language description, or null when it has none. */
+    altText: string | null;
+}
+/**
+ * An image's descriptions in the client's store: what a storefront shows as its alt text, per
+ * language (headless W9-38). The content system keeps them per store; the engine keeps one alt
+ * text per image (`customFields.altText`), the store's default-language description.
+ */
+export interface AssetDescriptionsModule {
+    /**
+     * The image's descriptions in the client's store, ordered by language; `[]` when it has none.
+     * The content system's public read: it can also hold a language the store no longer offers,
+     * which `set` refuses, so leave such an entry out when sending the set back.
+     */
+    get(assetId: string, options?: Call): Promise<AssetDescription[]>;
+    /**
+     * Save the image's descriptions in the client's store AND its alt text, as one change.
+     * `descriptions` is the WHOLE set, one entry per language the store offers: a language left
+     * out is removed, and leaving out the store's default language clears the alt text. The alt
+     * text is one value wherever the image is used: another store holding it reads the new one.
+     *
+     * Both change or neither does. Repeating a call is safe: both are set to its input again,
+     * whatever an earlier attempt left, so a call that failed with `outcomeUnknown` is settled by
+     * sending it again. No idempotency key is needed (and none is acted on).
+     *
+     * Refused, nothing written: `CMS_PERMISSION_NOT_ALLOWED` (403, the caller holds no
+     * UpdateCmsAsset in the store), `ENTITY_NOT_FOUND` (404, an image this store does not hold),
+     * `MANAGED_BY_ORGANIZATION` (422, an image of the store's organization: change it in the
+     * workspace), `SHARED_ASSET_NOT_ALLOWED` (403, an image another store holds that the caller
+     * cannot change), `ASSET_DESCRIPTIONS_INVALID` (400, a language the store does not offer or
+     * named twice, a blank text, a text over 500 characters; `details[]` points at each),
+     * `FORBIDDEN` (403, neither UpdateCatalog nor UpdateAsset). `CMS_REQUEST_FAILED` (422): the
+     * content system did not save; nothing changed, or, with `outcomeUnknown`, the descriptions may
+     * have been saved while the alt text was not: send the same call again.
+     *
+     * Requires a platform release that serves `setAssetDescriptions`.
+     */
+    set(assetId: string, descriptions: readonly AssetDescription[], options?: Call): Promise<AssetDescriptionsResult>;
+}
+export interface AssetListOptions extends ListOptions {
+    /** Case-insensitive substring of the name. */
+    name?: string;
+    /** Assets carrying ALL of these tags. */
+    tags?: string[];
+}
+/**
+ * The asset library. Assign an asset to a product, variant or collection with
+ * `assetIds` / `featuredAssetId` on that entity's own write.
+ *
+ * `create` uploads through the Admin API (GraphQL multipart), and is never
+ * retried by the SDK — a retry would upload the file twice. A file type the
+ * store does not permit is refused with `MIME_TYPE_ERROR`
+ * (`BusinessRuleError`): "The MIME type "…" is not permitted." For large files,
+ * `uploads` (spec §6.11) stages them directly to storage instead.
+ *
+ * A refused delete — "The selected Asset is featured by N Products" — is a
+ * `ConflictError` (`ASSET_NOT_DELETED`) unless `force` is set.
+ */
+export interface AssetsModule {
+    /** An image's descriptions (its alt text per language) in the store. */
+    descriptions: AssetDescriptionsModule;
+    list(options?: AssetListOptions): Promise<Page<Asset>>;
+    get(id: string, options?: Call): Promise<Asset | null>;
+    create(input: CreateAssetInput, options?: Call): Promise<Asset>;
+    update(input: UpdateAssetInput, options?: Call): Promise<Asset>;
+    delete(id: string, options?: Call & {
+        force?: boolean;
+    }): Promise<void>;
+}
+/**
+ * An asset's own fields, without `catalogueOwnership`: what a read outside the catalogue (the
+ * settings images) selects, so it keeps working against an engine older than the field.
+ */
+export declare const ASSET_FILE_FIELDS = "\n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n";
+export declare const ASSET_FIELDS = "\n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n";
+export declare const ASSETS_QUERY = "\n  query CatalogAssets($options: AssetListOptions) {\n    assets(options: $options) {\n      items { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n      totalItems\n    }\n  }\n";
+export declare const ASSET_QUERY = "\n  query CatalogAsset($id: ID!) {\n    asset(id: $id) { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n  }\n";
+export declare const CREATE_ASSETS_MUTATION = "\n  mutation CatalogCreateAssets($input: [CreateAssetInput!]!) {\n    createAssets(input: $input) {\n      ... on Asset { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+export declare const UPDATE_ASSET_MUTATION = "\n  mutation CatalogUpdateAsset($input: UpdateAssetInput!) {\n    updateAsset(input: $input) { \n  \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n  }\n";
+export declare const DELETE_ASSET_MUTATION = "\n  mutation CatalogDeleteAsset($input: DeleteAssetInput!) {\n    deleteAsset(input: $input) { \n  result\n  message\n }\n  }\n";
+export declare const SET_ASSET_DESCRIPTIONS_MUTATION = "\n  mutation CatalogSetAssetDescriptions(\n    $assetId: ID!\n    $descriptions: [AssetDescriptionInput!]!\n  ) {\n    setAssetDescriptions(assetId: $assetId, descriptions: $descriptions) {\n      assetId\n      descriptions {\n        languageCode\n        description\n      }\n      altText\n    }\n  }\n";
+/** An asset as {@link ASSET_FILE_FIELDS} reads it: no `catalogueOwnership`. */
+export type AssetFile = Omit<Asset, 'catalogueOwnership'>;
+/** An asset as the Admin API answers it: tags as objects. */
+export type WireOf<T extends AssetFile> = Omit<T, 'tags'> & {
+    tags: Array<{
+        value: string;
+    }>;
+};
+export declare function toAsset(wire: WireOf<Asset>): Asset;
+export declare function toAsset(wire: WireOf<AssetFile>): AssetFile;
+export declare function createAssetsModule(transport: Transport): AssetsModule;