@endora-commerce/contracts 0.100.0

package/dist/assets-library.d.ts

@@ -0,0 +1,684 @@
+import { z } from 'zod';
+export declare const assetVisibilitySchema: z.ZodEnum<{
+    public: "public";
+    private: "private";
+}>;
+export type AssetVisibility = z.infer<typeof assetVisibilitySchema>;
+/**
+ * Storage-backend identifier persisted on every Asset row so that switching the
+ * platform's *active* adapter does not orphan files uploaded under a previous
+ * adapter. `'legacy'` is a runtime-only escape hatch for rows whose pre-013
+ * `storage_url` is an absolute URL — see specs/013-assets-library/research.md R11.
+ */
+export declare const storageBackendCodeSchema: z.ZodEnum<{
+    local: "local";
+    s3: "s3";
+    gcs: "gcs";
+    legacy: "legacy";
+}>;
+export type StorageBackendCode = z.infer<typeof storageBackendCodeSchema>;
+/** What kind of consumer pointed at a given Asset (used in delete-blocked dialogs). */
+export declare const assetReferenceKindSchema: z.ZodEnum<{
+    product_gallery: "product_gallery";
+    product_attachment: "product_attachment";
+    product_virtual_download: "product_virtual_download";
+    category_main_image: "category_main_image";
+    cms_body_embed: "cms_body_embed";
+    megamenu_item_target: "megamenu_item_target";
+    blog_category_main_image: "blog_category_main_image";
+    blog_post_content: "blog_post_content";
+    blog_category_description: "blog_category_description";
+}>;
+export type AssetReferenceKind = z.infer<typeof assetReferenceKindSchema>;
+export declare const assetReferenceSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        product_gallery: "product_gallery";
+        product_attachment: "product_attachment";
+        product_virtual_download: "product_virtual_download";
+        category_main_image: "category_main_image";
+        cms_body_embed: "cms_body_embed";
+        megamenu_item_target: "megamenu_item_target";
+        blog_category_main_image: "blog_category_main_image";
+        blog_post_content: "blog_post_content";
+        blog_category_description: "blog_category_description";
+    }>;
+    entityId: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+export type AssetReference = z.infer<typeof assetReferenceSchema>;
+export declare const assetFolderSchema: z.ZodObject<{
+    id: z.ZodString;
+    parentId: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    position: z.ZodNumber;
+    childIds: z.ZodArray<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type AssetFolder = z.infer<typeof assetFolderSchema>;
+export declare const listFoldersResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodNullable<z.ZodString>;
+        name: z.ZodString;
+        position: z.ZodNumber;
+        childIds: z.ZodArray<z.ZodString>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ListFoldersResponse = z.infer<typeof listFoldersResponseSchema>;
+export declare const createFolderRequestSchema: z.ZodObject<{
+    parentId: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type CreateFolderRequest = z.infer<typeof createFolderRequestSchema>;
+export declare const patchFolderRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    position: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PatchFolderRequest = z.infer<typeof patchFolderRequestSchema>;
+export declare const deleteFolderRequestSchema: z.ZodObject<{
+    ifNonEmpty: z.ZodDefault<z.ZodEnum<{
+        cancel: "cancel";
+        moveContentsToParent: "moveContentsToParent";
+        deleteRecursively: "deleteRecursively";
+    }>>;
+}, z.core.$strip>;
+export type DeleteFolderRequest = z.infer<typeof deleteFolderRequestSchema>;
+export declare const deleteFolderResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        deletedFolderId: z.ZodString;
+        softDeletedAssetIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DeleteFolderResponse = z.infer<typeof deleteFolderResponseSchema>;
+/**
+ * Public asset summary — appears in the Library list, the picker, and embedded
+ * inside Catalog/CMS storefront responses. `url` is freshly produced by the
+ * active adapter on every read; for `private` assets it is a short-lived
+ * signed URL whose TTL is governed by the `assets.privateUrlTtlSec` setting.
+ */
+export declare const assetSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    folderId: z.ZodNullable<z.ZodString>;
+    filename: z.ZodString;
+    label: z.ZodNullable<z.ZodString>;
+    mimeType: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    visibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    storageBackend: z.ZodEnum<{
+        local: "local";
+        s3: "s3";
+        gcs: "gcs";
+        legacy: "legacy";
+    }>;
+    url: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    deletedAt: z.ZodNullable<z.ZodString>;
+    pendingCleanup: z.ZodBoolean;
+}, z.core.$strip>;
+export type AssetSummary = z.infer<typeof assetSummarySchema>;
+/** Detail extends summary with multilingual alt text + the deletion-protection list. */
+export declare const assetDetailSchema: z.ZodObject<{
+    id: z.ZodString;
+    folderId: z.ZodNullable<z.ZodString>;
+    filename: z.ZodString;
+    label: z.ZodNullable<z.ZodString>;
+    mimeType: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    visibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    storageBackend: z.ZodEnum<{
+        local: "local";
+        s3: "s3";
+        gcs: "gcs";
+        legacy: "legacy";
+    }>;
+    url: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    deletedAt: z.ZodNullable<z.ZodString>;
+    pendingCleanup: z.ZodBoolean;
+    altText: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>;
+    references: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            product_gallery: "product_gallery";
+            product_attachment: "product_attachment";
+            product_virtual_download: "product_virtual_download";
+            category_main_image: "category_main_image";
+            cms_body_embed: "cms_body_embed";
+            megamenu_item_target: "megamenu_item_target";
+            blog_category_main_image: "blog_category_main_image";
+            blog_post_content: "blog_post_content";
+            blog_category_description: "blog_category_description";
+        }>;
+        entityId: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AssetDetail = z.infer<typeof assetDetailSchema>;
+export declare const listAssetsQuerySchema: z.ZodObject<{
+    folderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    q: z.ZodOptional<z.ZodString>;
+    mime: z.ZodOptional<z.ZodString>;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>>;
+    includeDeleted: z.ZodDefault<z.ZodCoercedBoolean<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type ListAssetsQuery = z.infer<typeof listAssetsQuerySchema>;
+export declare const listAssetsResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        folderId: z.ZodNullable<z.ZodString>;
+        filename: z.ZodString;
+        label: z.ZodNullable<z.ZodString>;
+        mimeType: z.ZodString;
+        sizeBytes: z.ZodNumber;
+        visibility: z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>;
+        storageBackend: z.ZodEnum<{
+            local: "local";
+            s3: "s3";
+            gcs: "gcs";
+            legacy: "legacy";
+        }>;
+        url: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        deletedAt: z.ZodNullable<z.ZodString>;
+        pendingCleanup: z.ZodBoolean;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ListAssetsResponse = z.infer<typeof listAssetsResponseSchema>;
+export declare const getAssetResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        id: z.ZodString;
+        folderId: z.ZodNullable<z.ZodString>;
+        filename: z.ZodString;
+        label: z.ZodNullable<z.ZodString>;
+        mimeType: z.ZodString;
+        sizeBytes: z.ZodNumber;
+        visibility: z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>;
+        storageBackend: z.ZodEnum<{
+            local: "local";
+            s3: "s3";
+            gcs: "gcs";
+            legacy: "legacy";
+        }>;
+        url: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        deletedAt: z.ZodNullable<z.ZodString>;
+        pendingCleanup: z.ZodBoolean;
+        altText: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>;
+        references: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                product_gallery: "product_gallery";
+                product_attachment: "product_attachment";
+                product_virtual_download: "product_virtual_download";
+                category_main_image: "category_main_image";
+                cms_body_embed: "cms_body_embed";
+                megamenu_item_target: "megamenu_item_target";
+                blog_category_main_image: "blog_category_main_image";
+                blog_post_content: "blog_post_content";
+                blog_category_description: "blog_category_description";
+            }>;
+            entityId: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type GetAssetResponse = z.infer<typeof getAssetResponseSchema>;
+export declare const getAssetUrlResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        url: z.ZodString;
+        expiresAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type GetAssetUrlResponse = z.infer<typeof getAssetUrlResponseSchema>;
+export declare const patchAssetRequestSchema: z.ZodObject<{
+    filename: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>>;
+    folderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type PatchAssetRequest = z.infer<typeof patchAssetRequestSchema>;
+export declare const moveAssetRequestSchema: z.ZodObject<{
+    folderId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type MoveAssetRequest = z.infer<typeof moveAssetRequestSchema>;
+export declare const moveManyAssetsRequestSchema: z.ZodObject<{
+    assetIds: z.ZodArray<z.ZodString>;
+    folderId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type MoveManyAssetsRequest = z.infer<typeof moveManyAssetsRequestSchema>;
+export declare const moveManyAssetsResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        movedCount: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type MoveManyAssetsResponse = z.infer<typeof moveManyAssetsResponseSchema>;
+export declare const storageSelfCheckResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        adapter: z.ZodEnum<{
+            local: "local";
+            s3: "s3";
+            gcs: "gcs";
+        }>;
+        ok: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type StorageSelfCheckResponse = z.infer<typeof storageSelfCheckResponseSchema>;
+export declare const storageStateResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        activeAdapter: z.ZodEnum<{
+            local: "local";
+            s3: "s3";
+            gcs: "gcs";
+        }>;
+        selfCheck: z.ZodObject<{
+            ok: z.ZodBoolean;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        pendingCleanupCount: z.ZodNumber;
+        softDeletedCount: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type StorageStateResponse = z.infer<typeof storageStateResponseSchema>;
+export declare const assetRefNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"asset_ref">;
+    assetId: z.ZodString;
+    rendering: z.ZodOptional<z.ZodEnum<{
+        link: "link";
+        image: "image";
+        embed: "embed";
+    }>>;
+}, z.core.$loose>;
+export type AssetRefNode = z.infer<typeof assetRefNodeSchema>;
+/** Resolved view of an embedded asset, returned alongside the body in CMS responses. */
+export declare const assetEmbedResolutionSchema: z.ZodObject<{
+    url: z.ZodString;
+    mimeType: z.ZodString;
+    filename: z.ZodString;
+    label: z.ZodNullable<z.ZodString>;
+    visibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+}, z.core.$strip>;
+export type AssetEmbedResolution = z.infer<typeof assetEmbedResolutionSchema>;
+/**
+ * An asset row as it crosses a module boundary — a plain shape, never the ORM
+ * entity (FR-011). Distinct from `AssetSummary` / `AssetDetail` above, which
+ * are the HTTP projections: those carry ISO strings and a resolved URL, this
+ * carries the columns a module reads when it embeds or attaches one.
+ */
+/**
+ * What the library stores, as the column records it.
+ *
+ * Deliberately **not** `catalog`'s `AssetKind`, which the two attach surfaces
+ * narrow to: this one carries `other`, and a record typed with the narrower
+ * union would make every row the library holds unrepresentable in the shape
+ * that reads it.
+ */
+export type AssetStoredKind = 'image' | 'video' | 'pdf' | 'certificate' | 'other';
+export interface AssetRecord {
+    id: string;
+    kind: AssetStoredKind;
+    filename: string;
+    mimeType: string;
+    /** Byte count as a decimal string — the column is `bigint`. */
+    sizeBytes: string;
+    storageUrl: string;
+    altText: Record<string, string> | null;
+    folderId: string | null;
+    visibility: AssetVisibility;
+    label: string | null;
+    storageBackend: 'local' | 's3' | 'gcs' | 'legacy';
+    storageLocator: string;
+    pendingCleanup: boolean;
+    purgeAfterAt: Date | null;
+    mimeTypeOverridden: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+}
+/**
+ * Container name: `assetReadPort`. Owner: `assets_library`.
+ *
+ * Five inbound sites read the `Asset` entity to validate that an id an admin
+ * supplied exists and is the right kind before attaching it — `catalog`'s
+ * gallery, attachments and product links, and `orders`' invoice branding.
+ *
+ * When `assets_library` is off the read fails closed, which is right: an
+ * attach that cannot verify the asset would store a dangling id.
+ *
+ * Whether `assets_library` has an off state at all is its manifest's `activation` to
+ * say, not this line's: a module declaring `nonDeactivatable` never enters one.
+ */
+export interface AssetReadPort {
+    findById(id: string, options?: {
+        liveOnly?: boolean;
+    }): Promise<AssetRecord | null>;
+    findByIds(ids: readonly string[], options?: {
+        liveOnly?: boolean;
+    }): Promise<AssetRecord[]>;
+    /**
+     * The **stable, publicly reachable** URL of each of these assets, keyed by
+     * asset id — and nothing for the rest.
+     *
+     * Absence is the answer, not an exception: an id that names no row, a
+     * soft-deleted one, a `private` one and one whose URL could only be produced
+     * as an expiring signed link are all simply missing from the map. That is the
+     * degrade expressed in the return type rather than at a caller's `catch`,
+     * which is the only place it can be decided — a consumer holding an asset id
+     * cannot tell a signed URL from a stable one, and a consumer that guesses
+     * publishes a link that 403s the day after it is fetched.
+     *
+     * `product_feeds` is the requirement (FR-043): a marketplace fetches a feed
+     * from its own network days after it was written, so an expiring URL is not a
+     * slightly worse URL, it is no URL at all. It came here from a composition
+     * root's closure in `specs/110-instance-repository/` T118c.
+     *
+     * **Batched, and that is why it is here rather than
+     * {@link AssetsLibraryPort.getAsset}.** `getAsset` answers the same question
+     * for one asset and carries a resolved `url` already, which is the right
+     * answer for `cms` resolving a handful of embeds on one page. It is the wrong
+     * one for a feed: it builds the full detail, and the detail carries the
+     * deletion-protection `references` list, which is one query per registered
+     * reference descriptor. Measured on this tree — seven descriptors, so roughly
+     * ten queries per asset — against a feed hydration batch of 500 products
+     * whose gallery is one to four images each. This is one query plus a string
+     * build per row, and the run walks the whole sellable catalogue.
+     */
+    resolvePublicUrls(assetIds: readonly string[]): Promise<Map<string, string>>;
+    /**
+     * The **bytes** of one asset, buffered, with the MIME type they were stored
+     * under — or nothing.
+     *
+     * Absence is the answer and not an exception, for the reason
+     * {@link resolvePublicUrls} gives: an id that names no row, a soft-deleted
+     * one, a row whose bytes this platform never issued (`storageBackend` is
+     * `legacy` — a URL this library can resolve and an object it cannot open) and
+     * a configured store that would not stream are all simply `null`. That is the
+     * degrade expressed in the return type rather than at a caller's `catch`,
+     * which is composition checklist item 7's rule and the only place it can be
+     * decided: the caller cannot tell "this asset is not there" from "the bucket
+     * did not answer", and neither should turn a document into an error page.
+     *
+     * `invoices` is the requirement. pdfmake resolves an `image:` by **fetching**
+     * it, so an `InvoiceLogo` pointing at `/assets/file/<id>` makes the process
+     * serving the preview request issue an HTTP request to itself — which
+     * deadlocks for a public asset and 403s for a private one. The document
+     * embeds an inline `data:` URI instead, and that needs the bytes. It came
+     * here from a composition root's closure in
+     * `specs/110-instance-repository/` T118c.
+     *
+     * **Here rather than on {@link AssetsLibraryPort}, and rather than left at
+     * the caller over {@link ObjectStoragePort}.** It is a read, and a consumer
+     * that wants a logo must not thereby acquire `upload`, `patchAsset` and
+     * `softDelete` — the argument `ObjectStoragePort`'s own doc block makes in
+     * the other direction. A caller that opened the store itself would carry
+     * three facts about this module's storage layout instead: that `legacy` has
+     * no `open`, that a locator falls back to `storageUrl` when the column is
+     * empty, and that the stream has to be drained. Those are what the root
+     * closure knew, and moving them here is what publishing a port is for.
+     *
+     * `Uint8Array` and not `Buffer`: this package is compiled by
+     * `@endora-commerce/admin-kit` with `types: ["vite/client"]`, so the `Buffer`
+     * global is not in scope — the reason {@link AssetByteStream} gives in full.
+     * Buffered and not a stream, because the one consumer base64-encodes the
+     * whole object and the objects this answers for are document decorations. A
+     * consumer that wants to *stream* bytes it owns takes
+     * {@link ObjectStoragePort}.
+     *
+     * **It does not filter by kind, and that is the caller's half.** Which MIME
+     * types a consumer can use is the consumer's rule — pdfmake embeds PNG and
+     * JPEG and nothing else — so ask {@link findById} first when the answer
+     * decides whether the bytes are worth moving.
+     */
+    openAssetBytes(assetId: string): Promise<AssetBytes | null>;
+}
+/** One asset's stored bytes, with the MIME type they were stored under. */
+export interface AssetBytes {
+    bytes: Uint8Array;
+    mimeType: string;
+}
+/**
+ * One contributed "who points at this asset" scanner.
+ *
+ * `ownerModuleId` is required and is the whole mechanism (D-39): without it the
+ * registry could not state a policy for an absent owner at all — not "honour",
+ * not "skip", only "nobody looked".
+ */
+export interface AssetReferenceDescriptor {
+    ownerModuleId: string;
+    /**
+     * Given a list of asset ids, return every reference that points at any of
+     * them. MUST issue a single batched query, one per descriptor regardless of
+     * batch size.
+     */
+    findReferences(assetIds: string[]): Promise<AssetReference[]>;
+}
+/**
+ * Container name: `assetReferenceRegistry`. Owner: `assets_library`.
+ *
+ * A **contribution seam**: `catalog` (four descriptors), `cms`, `blog` and
+ * `megamenu` register from their boot hooks, and the library consults the
+ * table before every soft-delete (feature 013 FR-030).
+ *
+ * **Enumeration policy: honoured while the contributing module is absent**,
+ * and that is the deviation from D-39's default, with the reason D-39 requires.
+ * This registry is referential integrity, not a surface. If `blog` is switched
+ * off its posts still exist and still embed assets; skipping `blog`'s scanner
+ * would let an operator delete an asset that comes back as a broken image the
+ * moment `blog` is switched on again — data loss caused by an action
+ * Constitution XVII promises is non-destructive and reversible.
+ *
+ * `skip` is right for surface-like contributions, where a switched-off module
+ * must contribute nothing a user can see. Nobody sees these; they exist to
+ * refuse a delete. Publishing the shape must not change that classification.
+ */
+export interface AssetReferenceRegistryPort {
+    register(descriptor: AssetReferenceDescriptor): void;
+    /** The contributing module of every registered descriptor, in registration order. */
+    owners(): readonly string[];
+    /** Every reference pointing at **one** asset, across all descriptors. */
+    findReferences(assetId: string): Promise<AssetReference[]>;
+    /**
+     * The same question for many assets at once, keyed by asset id. Every id
+     * asked for is present in the result, with an empty list when nothing points
+     * at it — a caller deleting in bulk needs to tell "no references" from "not
+     * asked about".
+     */
+    findReferencesMany(assetIds: string[]): Promise<Map<string, AssetReference[]>>;
+}
+export interface AssetPatchInput {
+    filename?: string;
+    label?: string | null;
+    mimeType?: string;
+    visibility?: AssetVisibility;
+    folderId?: string | null;
+    /**
+     * Per-language alternate text. Feature 068 needs it, because an imported
+     * image must keep the alternate text the source supplied, per language
+     * (FR-047). Deliberately absent from the HTTP patch schema — this is a
+     * module-caller field.
+     */
+    altText?: Record<string, string> | null;
+}
+/**
+ * The byte source an upload streams from, described structurally.
+ *
+ * Deliberately **not** `NodeJS.ReadableStream`: this package is imported by
+ * the admin SPA and the storefront as well as the backend, and naming the
+ * `NodeJS` namespace here fails the compile of a consumer that type-checks
+ * without `@types/node`. It named `@endora-commerce/api-client` until D-202
+ * deleted that package; measured again on the tree that replaced it, the
+ * consumer that goes red is `@endora-commerce/admin-kit`, which compiles this
+ * file with `types: ["vite/client"]`. A Node `Readable` satisfies this shape —
+ * `Buffer` extends `Uint8Array` — so the one caller passes its multipart part
+ * through unchanged.
+ */
+export interface AssetUploadStream {
+    [Symbol.asyncIterator](): AsyncIterableIterator<string | Uint8Array>;
+}
+export interface AssetUploadInput {
+    /** Original filename from the multipart part. Used for extension + display. */
+    filename: string;
+    /** MIME from the multipart Content-Type header (may be wrong; sniffed on ingest). */
+    declaredMime: string;
+    /** Streaming source — must be consumed exactly once. */
+    stream: AssetUploadStream;
+    /** Best-effort byte count from headers; `0` when unknown. */
+    declaredSize: number;
+    /** Folder id chosen by the caller, or null for "Unsorted". */
+    folderId: string | null;
+    /** Optional storefront-visible label. */
+    label: string | null;
+    visibility: AssetVisibility;
+}
+/**
+ * Container name: `assetsLibraryPort`. Owner: `assets_library`.
+ *
+ * `pim_ergonode` ingests media during an import run: it uploads the file the
+ * source supplied, patches the alternate text onto it, and soft-deletes the
+ * asset an item stopped pointing at. Four methods, which is the whole of the
+ * demand — the module's own admin surface is much larger and stays unpublished.
+ *
+ * `cms` is the second consumer and takes `getAsset` alone, to turn an asset id a
+ * page or block embeds into the detail the storefront response carries. It reached
+ * the same service through a composition-root contribution until
+ * `specs/110-instance-repository/` T118c; nothing about this interface changed to
+ * admit it, which is the point of publishing one.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`, so nothing
+ * half-executes. Whether `assets_library` has an off state at all is its manifest's
+ * `activation` to say, not this line's: a module declaring
+ * `nonDeactivatable` never enters one.
+ */
+export interface AssetsLibraryPort {
+    upload(input: AssetUploadInput): Promise<AssetDetail>;
+    getAsset(assetId: string): Promise<AssetDetail>;
+    patchAsset(assetId: string, patch: AssetPatchInput): Promise<AssetDetail>;
+    softDelete(assetId: string): Promise<{
+        deletedAt: Date;
+        purgeAfterAt: Date;
+    }>;
+}
+/**
+ * The byte source an object read streams into, described structurally.
+ *
+ * {@link AssetUploadStream}'s twin, for the reason that one gives in full: this
+ * package is compiled by `@endora-commerce/admin-kit` with
+ * `types: ["vite/client"]`, so naming the `NodeJS` namespace here fails a
+ * consumer's build. A Node `Readable` satisfies it — `NodeJS.ReadableStream`
+ * declares `[Symbol.asyncIterator](): AsyncIterableIterator<string | Buffer>`
+ * and `Buffer` extends `Uint8Array` — so an adapter returns its stream
+ * unchanged and a consumer that needs `.pipe` wraps it once with
+ * `Readable.from`, in a backend layer where `node:stream` is legal.
+ */
+export interface AssetByteStream {
+    [Symbol.asyncIterator](): AsyncIterableIterator<string | Uint8Array>;
+}
+/**
+ * A backend that physically stores objects.
+ *
+ * {@link StorageBackendCode} minus `legacy`, and the exclusion is the whole
+ * point: `legacy` is not a store, it is a resolver for pre-013 rows whose URL
+ * this platform did not issue. It can answer a URL and it can stream nothing,
+ * which is why {@link ObjectStoragePort.getForBackend} is total here and the
+ * module-internal registry's equivalent is not.
+ */
+export type ObjectStorageBackendCode = Exclude<StorageBackendCode, 'legacy'>;
+export interface ObjectStoragePutInput {
+    locator: string;
+    mimeType: string;
+    visibility: AssetVisibility;
+    /** Consumed exactly once. */
+    stream: AssetUploadStream;
+    /** Best-effort byte count; `0` when the length is not known up front. */
+    sizeBytes: number;
+}
+/** One configured object store — bytes in, bytes out, bytes gone. */
+export interface ObjectStore {
+    /** Which backend this is, so a caller can record where an object's bytes went. */
+    readonly code: ObjectStorageBackendCode;
+    put(input: ObjectStoragePutInput): Promise<void>;
+    open(input: {
+        locator: string;
+    }): Promise<AssetByteStream>;
+    delete(input: {
+        locator: string;
+    }): Promise<void>;
+}
+/**
+ * Container name: `objectStoragePort`. Owner: `assets_library`.
+ *
+ * **Which bucket this deployment writes to, with which credentials** — and
+ * nothing about assets. A consumer of this port stores its own bytes under its
+ * own locator prefix and creates no `Asset` row: the objects are its data, they
+ * do not appear in the asset browser, they are not counted in library quotas
+ * and they are not reachable through the assets routes.
+ *
+ * `product_feeds` is the first consumer (FR-043): a generated feed artefact is
+ * written under `product-feeds/…` and served by that module's own tokenised
+ * route, which streams `open()` rather than handing out a store URL, so
+ * rotating a feed token actually revokes access. `invoices` asks the same
+ * question of the same registry today through a composition root, to embed a
+ * logo in a PDF.
+ *
+ * **A sibling of {@link AssetsLibraryPort} rather than four more methods on
+ * it.** That port's demand is an *asset* — upload it, read it, patch its
+ * alternate text, soft-delete it — and hanging a byte store off it would hand
+ * an importer a capability it never asked for. These are two capabilities that
+ * happen to share a configuration.
+ *
+ * **Retiring condition.** This is really an object store and not an asset
+ * library, and it lives here because that is where the configuration lives. If
+ * a byte-store module is ever extracted, this port moves to it wholesale and no
+ * consumer's call site changes. Nothing is owed today: `assets_library`
+ * declares `nonDeactivatable`, so the coupling costs an operator no control.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`, so nothing
+ * half-executes. Whether `assets_library` has an off state at all is its
+ * manifest's `activation` to say, not this line's: a module declaring
+ * `nonDeactivatable` never enters one.
+ */
+export interface ObjectStoragePort {
+    /** The store new objects are written to. */
+    getActive(): Promise<ObjectStore>;
+    /**
+     * The store that owns an existing object's bytes. Reads and deletes MUST go
+     * through this and never through {@link getActive}: after a backend switch
+     * the active store would resolve an object written under the old one to the
+     * wrong place.
+     */
+    getForBackend(backend: ObjectStorageBackendCode): Promise<ObjectStore>;
+}
+//# sourceMappingURL=assets-library.d.ts.map