@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/content/items.d.ts

@@ -0,0 +1,269 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/** The statuses the CMS gives an item; a read types `status` open, as {@link ContentItem} says. */
+export type ContentItemStatus = 'draft' | 'published' | 'archived';
+/**
+ * An item's own row: what every item answer carries, the write answers included.
+ *
+ * `collectionId` is the id of the item's content type (what the CMS calls a collection).
+ */
+export interface ContentItemRecord {
+    id: string;
+    channelId: string;
+    collectionId: string;
+    /** Unique within the type; null for an item that has none (it then has no URL either). */
+    slug: string | null;
+    /** One of {@link ContentItemStatus}, typed open so a newer CMS's status still reads. */
+    status: string;
+    publishedAt: string | null;
+    /** The parent item in a hierarchical type; null at the top level. */
+    parentId: string | null;
+    /**
+     * The storefront URL path; null when the type has no `basePath` or the item has no slug.
+     */
+    path: string | null;
+    /** Order among its siblings. */
+    position: number;
+    createdAt: string;
+    updatedAt: string;
+    [extra: string]: unknown;
+}
+/** An item with its field values, as `items.list` answers it. */
+export interface ContentItem extends ContentItemRecord {
+    /**
+     * Field slug → value, stored verbatim: the keys are the merchant's own field slugs and a
+     * value's inner keys are whatever was written, so neither is ever case-converted. With a
+     * `languageCode`, a localizable field's value in that language where one is stored, else its
+     * base value; without one, base values only.
+     */
+    values: Record<string, unknown>;
+}
+/** An item's slug and URL path in one language other than the store's default. */
+export interface ContentItemSlugTranslation {
+    slug: string;
+    path: string | null;
+}
+/** One item as `items.get` answers it. */
+export interface ContentItemDetail extends ContentItem {
+    /** Language code → the item's translated slug and path, for each language that has one. */
+    slugTranslations: Record<string, ContentItemSlugTranslation>;
+}
+/** One item as `items.lookup` resolves it: enough to label a reference to it. */
+export interface ContentItemSummary {
+    id: string;
+    slug: string | null;
+    /** One of {@link ContentItemStatus}. */
+    status: string;
+    /** The item's content type. */
+    collectionId: string;
+    collectionName: string;
+    collectionTitleFieldSlug: string | null;
+    /** The item's base title-field value when it is a string, else null. */
+    title: string | null;
+    [extra: string]: unknown;
+}
+/** One item as `items.lookupWithFields` resolves it. */
+export interface ContentItemWithFields {
+    id: string;
+    title: string | null;
+    /**
+     * Base (unlocalized) values of the requested field slugs, stored verbatim; a slug with no
+     * stored value is absent.
+     */
+    fieldValues: Record<string, unknown>;
+    [extra: string]: unknown;
+}
+export interface ContentItemListOptions extends ListOptions {
+    /**
+     * Only items in this status. Honoured for a credential holding `ReadCmsContent` on the
+     * store; any other caller is served published items only, whatever it asks for.
+     */
+    status?: ContentItemStatus;
+    /** Only the children of this item; `null` for the top-level items. Ignored with `search`. */
+    parentId?: string | null;
+    /** Only the item with this exact slug. Ignored with `search`. */
+    slug?: string;
+    /**
+     * Full-text search over the items' values; its results come in relevance order. The CMS's
+     * search applies `status` but not `parentId`, `slug` or `sort`, which it then ignores.
+     */
+    search?: string;
+    /**
+     * `position` (or `-position`) orders by the items' own order; without it, newest first.
+     * Ignored with `search`.
+     */
+    sort?: 'position' | '-position';
+    /**
+     * Each localizable value in this language where one is stored, else the base value. Without
+     * one, base values only: the client's tenant `language` is NOT applied here, so a list read
+     * and an `update` that writes it back name the same rows.
+     */
+    languageCode?: string;
+}
+export interface GetContentItemOptions extends Call {
+    /** As on {@link ContentItemListOptions.languageCode}: base values when omitted. */
+    languageCode?: string;
+}
+/**
+ * Exactly what `CreateItemDto` whitelists (the CMS runs `forbidNonWhitelisted`, so a fetched
+ * item handed back is a 400). No index signature, so excess-property checking fires.
+ */
+export interface CreateContentItemInput {
+    /**
+     * Lowercase letters, digits and hyphens. Without one, the slug is made from the type's title
+     * field value when the type has one.
+     */
+    slug?: string;
+    /** A parent item of the same type; only a hierarchical type takes one. */
+    parentId?: string | null;
+    position?: number;
+    /**
+     * Field slug → value for the type's top-level `item` fields, sent verbatim. A slug that is
+     * not one of them is refused and nothing is written.
+     */
+    values?: Record<string, unknown>;
+    /**
+     * The language `values` are written in: a localizable field's value goes to that language,
+     * every other field's to the base. Omit it for the base values (the store's default
+     * language); naming the default language explicitly writes a separate language row.
+     */
+    languageCode?: string;
+}
+/**
+ * The members `items.update` acts on, the same DTO as create. An absent key leaves the stored
+ * value alone, and `values` writes only the slugs it names.
+ */
+export interface UpdateContentItemInput {
+    /**
+     * The base slug; moves the item's path and every descendant's. With a non-default
+     * `languageCode`, the slug of that language instead. `null` clears the base slug (the item
+     * then has no URL).
+     */
+    slug?: string | null;
+    /** Moves the item under another parent of the same type; `null` to the top level. */
+    parentId?: string | null;
+    position?: number;
+    values?: Record<string, unknown>;
+    languageCode?: string;
+}
+/**
+ * The entries of a content type, read and written through the CMS.
+ *
+ * Reads need no permission, but what they answer depends on the credential: drafts and archived
+ * items are served only to a holder of `ReadCmsContent` on the store, and everyone else reads
+ * published items alone (`items.get` of an unpublished item is then `NotFoundError`). Writes
+ * need the permission each method names (`@permission`).
+ *
+ * Refusals are the CMS's problem+json, mapped by status:
+ * - `NotFoundError` (404, `NOT_FOUND`): no such type or item in this store.
+ * - `ConflictError` (409, `CONFLICT`): the slug or the URL path is taken, or a singleton type
+ *   already has its item.
+ * - `ValidationError` (400): `VALIDATION_FAILED` with one `details[]` entry per refused input
+ *   member; `VALIDATION_ERROR` for what the CMS refuses on its own (a value for no field, a
+ *   parent on a type that is not hierarchical, a slug reserved by the storefront, publishing an
+ *   item with a required field empty, deleting an item that has children).
+ * - `PermissionDeniedError` (403): the credential lacks the write's permission.
+ *
+ * The CMS records the platform events (`content.published`, `content.updated`,
+ * `content.unpublished`) itself; nothing here emits one. No write here is deduplicated: an
+ * `idempotencyKey` is sent and acts on nothing, so a repeated `create` is a second item.
+ */
+export interface ContentItemsModule {
+    /**
+     * The type's items, a page at a time, newest first unless `sort` says otherwise. Pages are
+     * offset-based (`Page.total` counts the matches), so `after: offsetCursor((n - 1) * size)`
+     * opens page `n`, and an item written while a walk runs can be seen twice or not at all.
+     *
+     * @effect read
+     */
+    list(typeId: string, options?: ContentItemListOptions): Promise<Page<ContentItem>>;
+    /**
+     * One item with its values and its translated slugs.
+     *
+     * @effect read
+     */
+    get(typeId: string, itemId: string, options?: GetContentItemOptions): Promise<ContentItemDetail>;
+    /**
+     * Adds an item as a draft. Answers its row; read its values back with `get`.
+     *
+     * @effect write
+     * @permission CreateCmsContent
+     */
+    create(typeId: string, input: CreateContentItemInput, options?: Call): Promise<ContentItemRecord>;
+    /**
+     * Writes what the input names in one transaction. Answers the item's row; read its values
+     * back with `get`.
+     *
+     * @effect write
+     * @permission UpdateCmsContent
+     */
+    update(typeId: string, itemId: string, input: UpdateContentItemInput, options?: Call): Promise<ContentItemRecord>;
+    /**
+     * Removes the item: it leaves the storefront and its URL is freed, and nothing in the SDK
+     * brings it back. An item that still has children is refused (`ValidationError`).
+     *
+     * @effect destructive
+     * @permission DeleteCmsContent
+     */
+    delete(typeId: string, itemId: string, options?: Call): Promise<void>;
+    /**
+     * Puts the item on the storefront. Refused (`ValidationError`, naming the fields) while a
+     * required field is empty.
+     *
+     * @effect write
+     * @permission UpdateCmsContent
+     */
+    publish(typeId: string, itemId: string, options?: Call): Promise<ContentItemRecord>;
+    /**
+     * Takes the item off the storefront; it becomes a draft.
+     *
+     * @effect write
+     * @permission UpdateCmsContent
+     */
+    unpublish(typeId: string, itemId: string, options?: Call): Promise<ContentItemRecord>;
+    /**
+     * Sets one status on several items of the type in one transaction, and answers how many it
+     * changed. An id that is not a live item of this type in this store is skipped, not refused.
+     * Unlike `publish`, it does not check required fields.
+     *
+     * @effect write
+     * @permission UpdateCmsContent
+     */
+    bulkSetStatus(typeId: string, itemIds: readonly string[], status: ContentItemStatus, options?: Call): Promise<{
+        updated: number;
+    }>;
+    /**
+     * Removes several items of the type in one transaction, and answers how many it removed. An
+     * id that is not a live item of this type is skipped; a selected item whose child is not
+     * selected too refuses the whole call (`ValidationError`) and removes nothing.
+     *
+     * @effect destructive
+     * @permission DeleteCmsContent
+     */
+    bulkDelete(typeId: string, itemIds: readonly string[], options?: Call): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Resolves item ids of ANY content type of the store to a label: what a content reference
+     * field, a menu entry or a product property stores. Any number of ids; the SDK splits them
+     * into the CMS's batches of 50. Answers the ids that resolved, in the order given, each once:
+     * an unknown id, another store's, or one the credential may not see is absent, never an
+     * error. An id that is not a UUID is refused instead (`ValidationError`, `INVALID_DATA`), and
+     * the whole call fails with it: no other id is resolved.
+     *
+     * Every status for a holder of `ReadCmsContent`, `UpdateCatalog` or `UpdateProduct` on the
+     * store (a catalog writer resolves a draft its product references); published items only for
+     * everyone else.
+     *
+     * @effect read
+     */
+    lookup(ids: readonly string[], options?: Call): Promise<ContentItemSummary[]>;
+    /**
+     * As `lookup`, with the base values of the named field slugs. With no ids or no slugs it
+     * answers `[]` without a request.
+     *
+     * @effect read
+     */
+    lookupWithFields(ids: readonly string[], fieldSlugs: readonly string[], options?: Call): Promise<ContentItemWithFields[]>;
+}
+export declare function createContentItemsModule(transport: Transport): ContentItemsModule;

package/dist/content/items.js

@@ -0,0 +1,170 @@
+import { createPage, offsetCursor, PLATFORM_PASSTHROUGH_KEYS, readOffsetCursor, } from '@sixtyninecommerce/core';
+const DEFAULT_PAGE_SIZE = 50;
+/**
+ * `GET /items/lookup*` refuses more ids than this (`ITEM_LOOKUP_MAX_IDS` in the CMS's
+ * `collections.controller.ts`): it once sliced to 50 and dropped the rest without a word.
+ */
+const LOOKUP_BATCH_SIZE = 50;
+/**
+ * Item `values` are keyed by the merchant's field slugs (`hero_2_image` camelised is
+ * `hero2Image`, and back is `hero2_image`), in both directions. `slug_translations` is keyed by
+ * language code. `values` cannot join the platform set: content strings use the name for a DTO
+ * array.
+ */
+const ITEM_PASSTHROUGH = new Set([
+    ...PLATFORM_PASSTHROUGH_KEYS,
+    'values',
+    'slug_translations',
+]);
+function itemsPath(typeId) {
+    return `/collections/${encodeURIComponent(typeId)}/items`;
+}
+function itemPath(typeId, itemId) {
+    return `${itemsPath(typeId)}/${encodeURIComponent(itemId)}`;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * A write answers the item ENTITY: `values` there is the stored value rows (with each row's
+ * field), not the slug-keyed map a read answers, and `slugTranslations` the translation rows.
+ * Neither is the read shape, so neither is passed on.
+ */
+function toRecord(item) {
+    const { values: _rows, slugTranslations: _translations, ...record } = item;
+    return record;
+}
+/**
+ * The item read sends both the translation rows (`slugTranslations`) and the same data keyed by
+ * language (`slug_translations`); camelised, the two land on ONE key and the later one wins.
+ * Today that is the map; a row array (the CMS reordering its answer) is folded into one.
+ */
+function slugTranslationMap(value) {
+    if (!Array.isArray(value))
+        return isRecord(value) ? value : {};
+    const map = {};
+    for (const row of value) {
+        if (isRecord(row) && typeof row.languageCode === 'string' && typeof row.slug === 'string') {
+            map[row.languageCode] = {
+                slug: row.slug,
+                path: typeof row.path === 'string' ? row.path : null,
+            };
+        }
+    }
+    return map;
+}
+function batched(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+/** The CMS answers a lookup in no guaranteed order; give it back in the caller's. */
+function inOrderOf(ids, found) {
+    const byId = new Map(found.map((item) => [item.id, item]));
+    return ids.flatMap((id) => {
+        const item = byId.get(id);
+        return item === undefined ? [] : [item];
+    });
+}
+export function createContentItemsModule(transport) {
+    async function listPage(typeId, offset, limit, options) {
+        const body = await transport.rest('cms', {
+            method: 'GET',
+            path: itemsPath(typeId),
+            query: {
+                // `offset` is always sent: it keeps the CMS out of its keyset mode, which can resume
+                // neither `sort` nor `search` and cannot open page n. Without `limit` an offset read
+                // answers the WHOLE list.
+                limit,
+                offset,
+                status: options?.status,
+                parent_id: options?.parentId === null ? 'root' : options?.parentId,
+                slug: options?.slug,
+                search: options?.search,
+                sort: options?.sort,
+                // Always sent, empty for the base values: the transport adds the tenant's `language`
+                // to any read that names none, and a write never gets it.
+                language_code: options?.languageCode ?? '',
+            },
+        }, { ...options, preserveKeys: ITEM_PASSTHROUGH });
+        const items = body.data ?? [];
+        // An offset read echoes neither the offset nor a cursor, so 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(typeId, readOffsetCursor(cursor), limit, options));
+    }
+    async function writeItem(method, path, body, options) {
+        const answer = await transport.rest('cms', { method, path, ...(body === undefined ? {} : { body }) }, { ...options, preserveKeys: ITEM_PASSTHROUGH });
+        return toRecord(answer.data);
+    }
+    return {
+        list(typeId, options) {
+            const limit = options?.limit ?? DEFAULT_PAGE_SIZE;
+            const offset = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+            return listPage(typeId, offset, limit, options);
+        },
+        async get(typeId, itemId, options) {
+            const body = await transport.rest('cms', {
+                method: 'GET',
+                path: itemPath(typeId, itemId),
+                query: { language_code: options?.languageCode ?? '' },
+            }, { ...options, preserveKeys: ITEM_PASSTHROUGH });
+            return {
+                ...body.data,
+                slugTranslations: slugTranslationMap(body.data.slugTranslations),
+            };
+        },
+        create(typeId, input, options) {
+            return writeItem('POST', itemsPath(typeId), input, options);
+        },
+        update(typeId, itemId, input, options) {
+            return writeItem('PATCH', itemPath(typeId, itemId), input, options);
+        },
+        async delete(typeId, itemId, options) {
+            await transport.rest('cms', { method: 'DELETE', path: itemPath(typeId, itemId), expect: 'void' }, options);
+        },
+        publish(typeId, itemId, options) {
+            return writeItem('POST', `${itemPath(typeId, itemId)}/publish`, undefined, options);
+        },
+        unpublish(typeId, itemId, options) {
+            return writeItem('POST', `${itemPath(typeId, itemId)}/unpublish`, undefined, options);
+        },
+        async bulkSetStatus(typeId, itemIds, status, options) {
+            const body = await transport.rest('cms', {
+                method: 'POST',
+                path: `${itemsPath(typeId)}/bulk-status`,
+                body: { itemIds: [...itemIds], status },
+            }, options);
+            return { updated: body.data.updated };
+        },
+        async bulkDelete(typeId, itemIds, options) {
+            const body = await transport.rest('cms', {
+                method: 'POST',
+                path: `${itemsPath(typeId)}/bulk-delete`,
+                body: { itemIds: [...itemIds] },
+            }, options);
+            return { deleted: body.data.deleted };
+        },
+        async lookup(ids, options) {
+            const unique = [...new Set(ids)];
+            if (unique.length === 0)
+                return [];
+            const pages = await Promise.all(batched(unique, LOOKUP_BATCH_SIZE).map((batch) => transport.rest('cms', { method: 'GET', path: '/items/lookup', query: { ids: batch.join(',') } }, options)));
+            return inOrderOf(unique, pages.flatMap((page) => page.data));
+        },
+        async lookupWithFields(ids, fieldSlugs, options) {
+            const unique = [...new Set(ids)];
+            if (unique.length === 0 || fieldSlugs.length === 0)
+                return [];
+            const pages = await Promise.all(batched(unique, LOOKUP_BATCH_SIZE).map((batch) => transport.rest('cms', {
+                method: 'GET',
+                path: '/items/lookup-with-fields',
+                query: { ids: batch.join(','), field_slugs: fieldSlugs.join(',') },
+            }, { ...options, preserveKeys: PLATFORM_PASSTHROUGH_KEYS })));
+            return inOrderOf(unique, pages.flatMap((page) => page.data));
+        },
+    };
+}