@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/content/assets.d.ts

@@ -0,0 +1,286 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/** An image's alt text in one language. */
+export interface ContentAssetTranslation {
+    languageCode: string;
+    altText: string;
+}
+/** One scaled copy of an image: the original format and WebP. */
+export interface ContentAssetPresetUrls {
+    url: string;
+    webpUrl: string;
+}
+/**
+ * A file in the store's media library (the CMS's assets): what a content item's image, file or
+ * video field refers to.
+ *
+ * `storageKey` is where the bytes live, under the store's own prefix (`{store code}/content/…`):
+ * a content field stores it, and a storefront resolves it to a URL. The platform chooses it from
+ * the store the call is made for; no call here takes one.
+ */
+export interface ContentAsset {
+    id: string;
+    channelId: string;
+    /** The folder it sits in; null at the top level. */
+    folderId: string | null;
+    /** The stored file name, made safe for a URL. */
+    filename: string;
+    /** The file name as uploaded. */
+    originalFilename: string;
+    mimeType: string;
+    /** Bytes. */
+    fileSize: number;
+    storageKey: string;
+    contentHash: string | null;
+    /** Pixels; null for a file that is not an image, or one the CMS could not measure. */
+    width: number | null;
+    height: number | null;
+    /** The alt text in no particular language; see `translations` for the per-language ones. */
+    altText: string | null;
+    /** Stored verbatim: its keys are never case-converted. */
+    metadata: Record<string, unknown> | null;
+    /**
+     * The scaled copies of a raster image, by preset name (`xxs` … `xl`); null for any other file.
+     * They are made in the background after an upload, so a URL can answer 404 for a few seconds.
+     */
+    presets: Record<string, ContentAssetPresetUrls> | null;
+    /** The alt text per language, as `update` last wrote each one. */
+    translations: ContentAssetTranslation[];
+    createdAt: string;
+    updatedAt: string;
+    [extra: string]: unknown;
+}
+/** A folder of the media library. */
+export interface ContentAssetFolder {
+    id: string;
+    channelId: string;
+    name: string;
+    /** The folder it sits in; null at the top level. */
+    parentId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /** Its direct subfolders: answered by `folders.get` only. */
+    children?: ContentAssetFolder[];
+    [extra: string]: unknown;
+}
+export interface ContentAssetListOptions extends ListOptions {
+    /** Only the files in this folder; `null` for the ones in no folder. */
+    folderId?: string | null;
+    /** Only the files whose MIME type starts with this (`image/`, `application/pdf`). */
+    mimeType?: string;
+    /**
+     * Full-text search over the file names and the alt text; the results come in relevance order.
+     * The CMS searches with a narrower filter than a list: `mimeType` must then be a whole type
+     * (`image/png`), because a prefix matches nothing, and `folderId: null` is not applied, so the
+     * search covers every folder.
+     */
+    search?: string;
+}
+/** What `upload` sends: the file and where it goes. */
+export interface UploadContentAssetInput {
+    file: Blob;
+    /**
+     * The name the file is stored under. Required unless `file` is a `File` (which carries its
+     * own): a bare Blob would otherwise be stored as "blob".
+     */
+    fileName?: string;
+    /** A folder of the store; the top level when omitted. */
+    folderId?: string;
+    altText?: string;
+}
+/** What `uploadFromUrl` sends. */
+export interface UploadContentAssetFromUrlInput {
+    /** An `http` or `https` URL the CMS fetches the file from. */
+    url: string;
+    /** A folder of the store; the top level when omitted. */
+    folderId?: string;
+    altText?: string;
+}
+/** The members `update` acts on; an absent key leaves the stored value alone. */
+export interface UpdateContentAssetInput {
+    /**
+     * Moves the file into this folder of the store; `null` to the top level. A CMS older than the
+     * platform release that fixed it (headless W10-6) answers the update and keeps the file where
+     * it was.
+     */
+    folderId?: string | null;
+    /** At most 255 characters; `null` clears it. */
+    altText?: string | null;
+    /** Replaces the stored metadata, sent verbatim; `null` clears it. */
+    metadata?: Record<string, unknown> | null;
+    /**
+     * The alt text of each named language (at most 500 characters), written as given. A language
+     * left out keeps the alt text it had: nothing here removes one.
+     */
+    translations?: readonly ContentAssetTranslation[];
+}
+export interface CreateContentAssetFolderInput {
+    /** At most 255 characters. */
+    name: string;
+    /** A folder of the store to create it in; the top level when omitted. */
+    parentId?: string;
+}
+export interface UpdateContentAssetFolderInput {
+    name?: string;
+    /**
+     * Moves the folder into another of the store's folders; `null` to the top level. A CMS older
+     * than the platform release of headless W10-6 moves it but answers `parentId: null`.
+     */
+    parentId?: string | null;
+}
+export interface ListContentAssetFoldersOptions extends Call {
+    /** The folders inside this one; the top-level folders when omitted. */
+    parentId?: string;
+}
+/**
+ * The folders of the media library. Reads need `ReadCmsAsset`; writes the permission each method
+ * names.
+ */
+export interface ContentAssetFoldersModule {
+    /**
+     * Every folder directly inside `parentId` (the top level when omitted), ordered by name. The
+     * CMS answers them whole: there is no page.
+     *
+     * @effect read
+     * @permission ReadCmsAsset
+     */
+    list(options?: ListContentAssetFoldersOptions): Promise<ContentAssetFolder[]>;
+    /**
+     * One folder with its direct subfolders (`children`). `NotFoundError` for a folder this store
+     * does not hold.
+     *
+     * @effect read
+     * @permission ReadCmsAsset
+     */
+    get(id: string, options?: Call): Promise<ContentAssetFolder>;
+    /**
+     * Adds a folder. A `parentId` this store does not hold is `NotFoundError`.
+     *
+     * @effect write
+     * @permission CreateCmsAsset
+     */
+    create(input: CreateContentAssetFolderInput, options?: Call): Promise<ContentAssetFolder>;
+    /**
+     * Renames or moves a folder. Moving it into itself or into one of its own subfolders is refused
+     * (`ValidationError`).
+     *
+     * @effect write
+     * @permission UpdateCmsAsset
+     */
+    update(id: string, input: UpdateContentAssetFolderInput, options?: Call): Promise<ContentAssetFolder>;
+    /**
+     * Removes an empty folder. One that still holds a subfolder or a file is refused
+     * (`ValidationError`) and nothing is removed.
+     *
+     * @effect destructive
+     * @permission DeleteCmsAsset
+     */
+    delete(id: string, options?: Call): Promise<void>;
+}
+/**
+ * The store's media library (the CMS's assets and folders): the files content items show.
+ * Product images are a different library, `catalog.assets`.
+ *
+ * Everything is scoped to the store the client is for: another store's file or folder answers
+ * `NotFoundError` (404, `NOT_FOUND`), as one that never existed does, and is never listed.
+ *
+ * Refusals are the CMS's problem+json, mapped by status:
+ * - `ValidationError` (400): a file type the platform does not accept, a file over the size limit
+ *   the CMS is configured with, a URL it cannot fetch or that points into a private network, a
+ *   refused input member (`VALIDATION_FAILED`, with `details[]`).
+ * - 413 (`PlatformError`): a multipart body over the 200 MB the upload route reads at most.
+ * - `PermissionDeniedError` (403): the credential lacks the method's permission on the store.
+ * - `NotFoundError` (404): no such file or folder in this store.
+ *
+ * `upload` sends the file through the CMS as `multipart/form-data` and is never retried: a retry
+ * would store it twice. For a large file, `uploads` (spec §6.11) puts it straight into storage
+ * instead. No write here is deduplicated: an `idempotencyKey` is sent and acts on nothing.
+ */
+export interface ContentAssetsModule {
+    folders: ContentAssetFoldersModule;
+    /**
+     * The store's files, newest first, a page at a time (relevance order with `search`). Pages are
+     * offset-based (`Page.total` counts the matches), so `after: offsetCursor((n - 1) * size)` opens
+     * page `n`, and a file uploaded while a walk runs can be seen twice or not at all.
+     *
+     * @effect read
+     * @permission ReadCmsAsset
+     */
+    list(options?: ContentAssetListOptions): Promise<Page<ContentAsset>>;
+    /**
+     * One file. `NotFoundError` for a file this store does not hold.
+     *
+     * @effect read
+     * @permission ReadCmsAsset
+     */
+    get(id: string, options?: Call): Promise<ContentAsset>;
+    /**
+     * The file stored under `storageKey` (what a content field holds), or null when this store holds
+     * none. The same bytes uploaded twice under the same name share a key; then the newest file
+     * answers.
+     *
+     * @effect read
+     * @permission ReadCmsAsset
+     */
+    byStorageKey(storageKey: string, options?: Call): Promise<ContentAsset | null>;
+    /**
+     * Stores a file in the media library. Raster images get their scaled copies in the background.
+     * A file without a name is refused before anything is sent (`ValidationError`,
+     * `ASSET_FILE_NAME_REQUIRED`). Never retried.
+     *
+     * @effect write
+     * @permission CreateCmsAsset
+     */
+    upload(input: UploadContentAssetInput, options?: Call): Promise<ContentAsset>;
+    /**
+     * Has the CMS fetch a file from a public URL and store it, as `upload` would. The CMS refuses a
+     * URL into a private network, one that answers an error, redirects too often or takes over 30
+     * seconds (`ValidationError`).
+     *
+     * @effect write
+     * @permission CreateCmsAsset
+     */
+    uploadFromUrl(input: UploadContentAssetFromUrlInput, options?: Call): Promise<ContentAsset>;
+    /**
+     * Changes a file's folder, alt text, metadata or per-language alt text, in one transaction.
+     *
+     * @effect write
+     * @permission UpdateCmsAsset
+     */
+    update(id: string, input: UpdateContentAssetInput, options?: Call): Promise<ContentAsset>;
+    /**
+     * Removes the file from the library. Its bytes and scaled copies are deleted from storage too
+     * unless another file of the store shares them, so a content field still holding its key then
+     * shows nothing. Nothing in the SDK brings it back.
+     *
+     * @effect destructive
+     * @permission DeleteCmsAsset
+     */
+    delete(id: string, options?: Call): Promise<void>;
+    /**
+     * A URL to download the original file with, valid for one hour.
+     *
+     * @effect read
+     * @permission ReadCmsAsset
+     */
+    downloadUrl(id: string, options?: Call): Promise<string>;
+    /**
+     * Has the CMS fetch a file from a public URL and hand it back, storing nothing: how a browser
+     * gets a file it may not fetch itself (another origin) to upload somewhere else, such as
+     * `catalog.assets.create`. The CMS refuses what `uploadFromUrl` refuses. The `File` is named
+     * as the CMS names it, else after the URL's last path segment.
+     *
+     * @effect read
+     * @permission CreateCmsAsset
+     */
+    proxyFetch(url: string, options?: Call): Promise<File>;
+}
+/**
+ * The file name a `Content-Disposition` header carries. The CMS percent-encodes it inside a
+ * quoted `filename` (`attachment; filename="logo%20dark.png"`), and RFC 6266's `filename*`
+ * (`UTF-8''…`) is read too.
+ */
+export declare function fileNameOfDisposition(header: string | null): string | null;
+/** The URL's last path segment when it names a file (has an extension), else a generic name. */
+export declare function fileNameOfUrl(url: string, mimeType: string): string;
+export declare function createContentAssetsModule(transport: Transport): ContentAssetsModule;

package/dist/content/assets.js

@@ -0,0 +1,181 @@
+import { createPage, offsetCursor, PLATFORM_PASSTHROUGH_KEYS, readOffsetCursor, ValidationError, } from '@sixtyninecommerce/core';
+const DEFAULT_PAGE_SIZE = 50;
+/** The cursor-mode opener: `after` present and empty starts the CMS's keyset walk. */
+const FIRST_PAGE = '';
+/** `metadata` is a stored-verbatim bag; nothing else in an asset is merchant-keyed. */
+const ASSET_KEYS = PLATFORM_PASSTHROUGH_KEYS;
+function assetPath(id) {
+    return `/assets/${encodeURIComponent(id)}`;
+}
+function folderPath(id) {
+    return `/asset-folders/${encodeURIComponent(id)}`;
+}
+/** A `File` without depending on the DOM lib: anything Blob-like carrying a `name`. */
+function nameOf(file) {
+    const name = file.name;
+    return typeof name === 'string' && name !== '' ? name : undefined;
+}
+/**
+ * The file name a `Content-Disposition` header carries. The CMS percent-encodes it inside a
+ * quoted `filename` (`attachment; filename="logo%20dark.png"`), and RFC 6266's `filename*`
+ * (`UTF-8''…`) is read too.
+ */
+export function fileNameOfDisposition(header) {
+    if (header === null)
+        return null;
+    const extended = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/.exec(header)?.[1];
+    const plain = /filename\s*=\s*"([^"]*)"|filename\s*=\s*([^;\s]+)/.exec(header);
+    const raw = extended ?? plain?.[1] ?? plain?.[2];
+    if (raw === undefined || raw.trim() === '')
+        return null;
+    try {
+        return decodeURIComponent(raw.trim());
+    }
+    catch {
+        return raw.trim();
+    }
+}
+/** The URL's last path segment when it names a file (has an extension), else a generic name. */
+export function fileNameOfUrl(url, mimeType) {
+    try {
+        const segment = new URL(url).pathname.split('/').pop();
+        if (segment?.includes('.'))
+            return decodeURIComponent(segment);
+    }
+    catch {
+        // An unparseable URL or segment falls through to the generic name.
+    }
+    const subtype = mimeType.split(';')[0]?.split('/')[1]?.trim();
+    return `fetched-file.${subtype !== undefined && subtype !== '' ? subtype : 'bin'}`;
+}
+export function createContentAssetsModule(transport) {
+    async function listPage(offset, limit, options) {
+        const body = await transport.rest('cms', {
+            method: 'GET',
+            path: '/assets',
+            query: {
+                // `offset` is always sent: it keeps the CMS out of its keyset mode, which cannot search
+                // or open page n. Without `limit` an offset read answers the WHOLE library.
+                limit,
+                offset,
+                folder_id: options?.folderId === null ? 'null' : options?.folderId,
+                mime_type: options?.mimeType,
+                search: options?.search,
+            },
+        }, { ...options, preserveKeys: ASSET_KEYS });
+        const items = body.data ?? [];
+        // An offset read echoes neither the offset nor a cursor: the page is built from what THIS
+        // call asked for.
+        const total = body.pagination?.total ?? items.length;
+        const advanced = offset + (items.length > 0 ? items.length : limit);
+        const hasNext = advanced < total;
+        return createPage(items, { nextCursor: hasNext ? offsetCursor(advanced) : null, hasNext, total }, (cursor) => listPage(readOffsetCursor(cursor), limit, options));
+    }
+    async function writeAsset(method, path, body, options) {
+        const answer = await transport.rest('cms', { method, path, body }, { ...options, preserveKeys: ASSET_KEYS });
+        return answer.data;
+    }
+    async function folderCall(method, path, body, options) {
+        const answer = await transport.rest('cms', { method, path, ...(body === undefined ? {} : { body }) }, options);
+        return answer.data;
+    }
+    return {
+        folders: {
+            async list(options) {
+                // No `after`: only then does the CMS keep the folders in name order and answer them all.
+                const body = await transport.rest('cms', { method: 'GET', path: '/asset-folders', query: { parent_id: options?.parentId } }, options);
+                return body.data ?? [];
+            },
+            get(id, options) {
+                return folderCall('GET', folderPath(id), undefined, options);
+            },
+            create(input, options) {
+                return folderCall('POST', '/asset-folders', {
+                    name: input.name,
+                    ...(input.parentId === undefined ? {} : { parentId: input.parentId }),
+                }, options);
+            },
+            update(id, input, options) {
+                return folderCall('PATCH', folderPath(id), input, options);
+            },
+            async delete(id, options) {
+                await transport.rest('cms', { method: 'DELETE', path: folderPath(id), expect: 'void' }, options);
+            },
+        },
+        list(options) {
+            const limit = options?.limit ?? DEFAULT_PAGE_SIZE;
+            const offset = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+            return listPage(offset, limit, options);
+        },
+        async get(id, options) {
+            const body = await transport.rest('cms', { method: 'GET', path: assetPath(id) }, { ...options, preserveKeys: ASSET_KEYS });
+            return body.data;
+        },
+        async byStorageKey(storageKey, options) {
+            const body = await transport.rest('cms', {
+                method: 'GET',
+                path: '/assets',
+                // Keyset mode on purpose: it pages the ids first and then loads each file whole. An
+                // offset read limits the joined translation rows instead, so `limit: 1` there would
+                // answer the file with one of its translations.
+                query: { storage_key: storageKey, limit: 1, after: FIRST_PAGE },
+            }, { ...options, preserveKeys: ASSET_KEYS });
+            return body.data?.[0] ?? null;
+        },
+        async upload(input, options) {
+            const fileName = input.fileName ?? nameOf(input.file);
+            if (fileName === undefined || fileName.trim() === '') {
+                throw new ValidationError({
+                    code: 'ASSET_FILE_NAME_REQUIRED',
+                    message: 'A file needs a name: pass fileName, or a File that carries one. A bare Blob would be stored as "blob". Nothing was sent.',
+                    status: 400,
+                    service: 'cms',
+                });
+            }
+            const fields = {};
+            if (input.folderId !== undefined)
+                fields.folder_id = input.folderId;
+            if (input.altText !== undefined)
+                fields.alt_text = input.altText;
+            const answer = await transport.rest('cms', {
+                method: 'POST',
+                path: '/assets/upload',
+                multipart: { fields, files: [{ field: 'file', file: input.file, fileName }] },
+            }, { ...options, preserveKeys: ASSET_KEYS });
+            return answer.data;
+        },
+        uploadFromUrl(input, options) {
+            return writeAsset('POST', '/assets/upload-from-url', {
+                url: input.url,
+                ...(input.folderId === undefined ? {} : { folderId: input.folderId }),
+                ...(input.altText === undefined ? {} : { altText: input.altText }),
+            }, options);
+        },
+        update(id, input, options) {
+            return writeAsset('PATCH', assetPath(id), {
+                ...input,
+                ...(input.translations === undefined
+                    ? {}
+                    : {
+                        translations: input.translations.map(({ languageCode, altText }) => ({
+                            languageCode,
+                            altText,
+                        })),
+                    }),
+            }, options);
+        },
+        async delete(id, options) {
+            await transport.rest('cms', { method: 'DELETE', path: assetPath(id), expect: 'void' }, options);
+        },
+        async downloadUrl(id, options) {
+            const body = await transport.rest('cms', { method: 'GET', path: `${assetPath(id)}/download-url` }, options);
+            return body.data.url;
+        },
+        async proxyFetch(url, options) {
+            const answer = await transport.rest('cms', { method: 'POST', path: '/assets/proxy-fetch', body: { url }, expect: 'blob' }, options);
+            const type = answer.blob.type || (answer.contentType ?? '');
+            const name = fileNameOfDisposition(answer.contentDisposition) ?? fileNameOfUrl(url, type);
+            return new File([answer.blob], name, { type });
+        },
+    };
+}