@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/content/types.d.ts

@@ -0,0 +1,282 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * The field types the CMS accepts (`FIELD_TYPES` in `services/cms`), pinned against the CMS's
+ * published `openapi.json` by `content-coverage.spec.ts`. A read types `fieldType` as a plain
+ * string on purpose: a type the CMS adds later must not turn a read into a type error.
+ */
+export type ContentFieldType = 'string' | 'textarea' | 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'image' | 'images' | 'file' | 'video' | 'color' | 'link' | 'enum' | 'multi_enum' | 'json' | 'collection_ref' | 'multi_collection_ref' | 'product' | 'product_collection' | 'content_item' | 'form' | 'location' | 'group' | 'filtered_products';
+/**
+ * `item` fields are the schema of the type's entries; `page` fields are the content of the
+ * type's own index page (`content.pageValues`).
+ */
+export type ContentFieldScope = 'item' | 'page';
+/**
+ * One field of a content type, as the CMS stores it.
+ *
+ * `config` is stored VERBATIM and its keys are the CMS's own snake_case vocabulary
+ * (`min_length`, `target_collection_id`, `allowed_link_types`): this SDK never case-converts it,
+ * in either direction, so a fetched `config` can be written back unchanged.
+ */
+export interface ContentField {
+    id: string;
+    collectionId: string;
+    name: string;
+    /** Unique per type and scope (per group for a sub-field); the key of an entry's value. */
+    slug: string;
+    /** One of {@link ContentFieldType}, typed open so a newer CMS's type still reads. */
+    fieldType: string;
+    isRequired: boolean;
+    isLocalizable: boolean;
+    /** Order among the type's top-level fields. A sub-field orders by `groupPosition`. */
+    position: number;
+    config: Record<string, unknown> | null;
+    helpText: string | null;
+    scope: ContentFieldScope;
+    /** The `group` field this is a sub-field of, or null for a top-level field. */
+    groupId: string | null;
+    groupPosition: number;
+    /** A `group` field's own fields, ordered by `groupPosition`. Present on `types.get` only. */
+    subFields?: ContentField[];
+    createdAt: string;
+    updatedAt: string;
+    [extra: string]: unknown;
+}
+/**
+ * A content type: what the CMS calls a collection (blog posts, FAQs, a team page), with the
+ * fields its entries and its index page are made of.
+ */
+export interface ContentType {
+    id: string;
+    channelId: string;
+    name: string;
+    /** Unique within the store. Lowercase letters, digits and hyphens. */
+    slug: string;
+    description: string | null;
+    /** A singleton type holds exactly one entry (a settings page, a home page). */
+    isSingleton: boolean;
+    /**
+     * Where the type's entries live on the storefront: null for no URLs, `''` for the root,
+     * `/blog` for a prefix. Moving it re-paths every entry.
+     */
+    basePath: string | null;
+    isHierarchical: boolean;
+    /** The field whose value titles an entry; set only once the field exists. */
+    titleFieldSlug: string | null;
+    /**
+     * The type's top-level fields of both scopes, ordered by `position`, each `group` field with
+     * its `subFields`. Only `types.get` answers them: a list item and a `create` answer carry
+     * none, and an `update` answer carries them only when it moved `basePath`.
+     */
+    fields?: ContentField[];
+    createdAt: string;
+    updatedAt: string;
+    [extra: string]: unknown;
+}
+/**
+ * Exactly what `CreateCollectionDto` whitelists, less `titleFieldSlug`: the CMS refuses a title
+ * field on a type that has no fields yet, so it is set with `types.update` once they exist.
+ */
+export interface CreateContentTypeInput {
+    name: string;
+    slug: string;
+    description?: string;
+    isSingleton?: boolean;
+    basePath?: string | null;
+    isHierarchical?: boolean;
+}
+/**
+ * What `UpdateCollectionDto` whitelists. An absent key leaves the stored value alone; `null`
+ * clears `description`, `basePath` and `titleFieldSlug`.
+ */
+export interface UpdateContentTypeInput {
+    name?: string;
+    slug?: string;
+    description?: string | null;
+    isSingleton?: boolean;
+    basePath?: string | null;
+    isHierarchical?: boolean;
+    titleFieldSlug?: string | null;
+}
+/**
+ * Exactly what `CreateFieldDto` whitelists — not `Partial<ContentField>`: the CMS runs
+ * `forbidNonWhitelisted`, so handing a fetched field back (with its `id` and timestamps) is a
+ * 400 that fails the whole write.
+ */
+export interface CreateContentFieldInput {
+    name: string;
+    /** Lowercase letters, digits and underscores. */
+    slug: string;
+    fieldType: ContentFieldType;
+    isRequired?: boolean;
+    isLocalizable?: boolean;
+    /** Defaults to after the last field of its scope (of its group, for a sub-field). */
+    position?: number;
+    /** Stored verbatim; keys are the CMS's snake_case vocabulary. */
+    config?: Record<string, unknown>;
+    helpText?: string;
+    scope?: ContentFieldScope;
+    /** Makes this a sub-field of that `group` field. */
+    groupId?: string;
+}
+/**
+ * The members `fields.update` acts on. An absent key leaves the stored value alone; `null`
+ * clears `helpText` and `config`. A field's `scope` and `groupId` cannot move.
+ */
+export interface UpdateContentFieldInput {
+    name?: string;
+    slug?: string;
+    fieldType?: ContentFieldType;
+    isRequired?: boolean;
+    isLocalizable?: boolean;
+    /** For a sub-field, its position within the group. */
+    position?: number;
+    config?: Record<string, unknown> | null;
+    helpText?: string | null;
+}
+/** A type's index page: its `page` fields and their values. */
+export interface ContentPageValues {
+    /** The type's top-level `page` fields, ordered by `position`. */
+    fields: ContentField[];
+    /** Field slug → value, stored verbatim (the slugs are the merchant's own keys). */
+    values: Record<string, unknown>;
+    [extra: string]: unknown;
+}
+export interface GetContentPageValuesOptions extends Call {
+    /**
+     * The language to read: each field's value in that language, else its base value. Without
+     * one, the base values only — the client's tenant `language` is NOT applied here, so a read
+     * and the `set` that writes it back always name the same rows.
+     */
+    languageCode?: string;
+}
+export interface SetContentPageValuesInput {
+    /**
+     * Field slug → value for the slugs to write; a slug left out keeps its value. Every slug must
+     * be one of the type's `page` fields, or nothing is written.
+     */
+    values: Record<string, unknown>;
+    /** Writes the values for that language; without one, the base values. */
+    languageCode?: string;
+}
+/**
+ * Content types (CMS collections), read and written through the CMS.
+ *
+ * Reads need no permission: a type's schema is public, and storefronts read the same routes.
+ * 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 in this store.
+ * - `ConflictError` (409, `CONFLICT`): the slug is taken in this store.
+ * - `ValidationError` (400): `VALIDATION_FAILED` with one `details[]` entry per refused input
+ *   member; `VALIDATION_ERROR` for a value the CMS refuses on its own (a malformed `basePath`,
+ *   a `titleFieldSlug` naming no field, an id that is not a UUID).
+ * - `PermissionDeniedError` (403): the credential lacks the write's permission.
+ *
+ * No write here is deduplicated: an `idempotencyKey` is sent and acts on nothing, so a repeated
+ * `create` is a second write (refused `CONFLICT` on the same slug).
+ */
+export interface ContentTypesModule {
+    /**
+     * Every content type of the store, newest first, a page at a time. A list item carries no
+     * `fields`; read one with `get`.
+     *
+     * @effect read
+     */
+    list(options?: ListOptions): Promise<Page<ContentType>>;
+    /**
+     * One content type with its fields.
+     *
+     * @effect read
+     */
+    get(id: string, options?: Call): Promise<ContentType>;
+    /**
+     * @effect write
+     * @permission CreateCmsContent
+     */
+    create(input: CreateContentTypeInput, options?: Call): Promise<ContentType>;
+    /**
+     * Changing `basePath` re-paths every entry of the type on the storefront.
+     *
+     * @effect write
+     * @permission UpdateCmsContent
+     */
+    update(id: string, input: UpdateContentTypeInput, options?: Call): Promise<ContentType>;
+    /**
+     * Removes the type from the store: its entries and its index page stop being served, and
+     * nothing in the SDK brings it back.
+     *
+     * @effect destructive
+     * @permission DeleteCmsContent
+     */
+    delete(id: string, options?: Call): Promise<void>;
+}
+/**
+ * The fields of a content type. Every method takes the type's id first; a field of another
+ * type, or of another store's type, is `NotFoundError` (404). Refusals as on
+ * {@link ContentTypesModule}; a slug taken within the type's scope (or the group) is
+ * `ConflictError` (409).
+ */
+export interface ContentFieldsModule {
+    /**
+     * Adds a field; with `groupId`, a sub-field of that `group` field (only the types a group
+     * allows: a disallowed one is `ValidationError`).
+     *
+     * @effect write
+     * @permission CreateCmsContent
+     */
+    create(typeId: string, input: CreateContentFieldInput, options?: Call): Promise<ContentField>;
+    /**
+     * @effect write
+     * @permission UpdateCmsContent
+     */
+    update(typeId: string, fieldId: string, input: UpdateContentFieldInput, options?: Call): Promise<ContentField>;
+    /**
+     * Removes the field from the type. Entries keep no reachable value for it, and nothing in the
+     * SDK brings it back.
+     *
+     * @effect destructive
+     * @permission DeleteCmsContent
+     */
+    delete(typeId: string, fieldId: string, options?: Call): Promise<void>;
+    /**
+     * Gives each listed field the position of its index in `fieldIds`. Pass every top-level field
+     * of the scope, in the order wanted: an unlisted field keeps its old position, and an id that
+     * is not one of the type's fields is skipped without a refusal.
+     *
+     * @effect write
+     * @permission UpdateCmsContent
+     */
+    reorder(typeId: string, fieldIds: string[], options?: Call): Promise<void>;
+    /**
+     * Gives each listed sub-field of the `group` field the position of its index in `fieldIds`.
+     * Pass every sub-field, in the order wanted; an id outside the group is skipped.
+     *
+     * @effect write
+     * @permission UpdateCmsContent
+     */
+    reorderSubFields(typeId: string, groupFieldId: string, fieldIds: string[], options?: Call): Promise<void>;
+}
+/**
+ * The content of a type's own index page (its `page` fields): the blog's intro above the list
+ * of posts. Refusals as on {@link ContentTypesModule}.
+ */
+export interface ContentPageValuesModule {
+    /** @effect read */
+    get(typeId: string, options?: GetContentPageValuesOptions): Promise<ContentPageValues>;
+    /**
+     * Writes the given slugs' values in one transaction, and answers the language's values as
+     * stored afterwards. A slug that is not a `page` field is `ValidationError` and writes
+     * nothing.
+     *
+     * @effect write
+     * @permission UpdateCmsContent
+     */
+    set(typeId: string, input: SetContentPageValuesInput, options?: Call): Promise<{
+        values: Record<string, unknown>;
+        [extra: string]: unknown;
+    }>;
+}
+export declare function createContentTypesModule(transport: Transport): ContentTypesModule;
+export declare function createContentFieldsModule(transport: Transport): ContentFieldsModule;
+export declare function createContentPageValuesModule(transport: Transport): ContentPageValuesModule;

package/dist/content/types.js

@@ -0,0 +1,100 @@
+import { createPage, PLATFORM_PASSTHROUGH_KEYS, readRestPage, } from '@sixtyninecommerce/core';
+const COLLECTIONS = '/collections';
+/**
+ * `GET /collections` returns the WHOLE list unless `after` is sent; an empty `after` starts
+ * the cursor sequence, which then pages by `limit` (CMS default 50, at most 200).
+ */
+const FIRST_PAGE = '';
+/**
+ * `config` (a field's settings) is in the platform set. Page values add `values`, a bag keyed by
+ * the merchant's field slugs: `hero_title` must not come back as `heroTitle`. `values` is not
+ * in the platform set because content strings use the same name for a DTO array.
+ */
+const PAGE_VALUES_PASSTHROUGH = new Set([
+    ...PLATFORM_PASSTHROUGH_KEYS,
+    'values',
+]);
+function typePath(id) {
+    return `${COLLECTIONS}/${encodeURIComponent(id)}`;
+}
+function fieldsPath(typeId) {
+    return `${typePath(typeId)}/fields`;
+}
+function fieldPath(typeId, fieldId) {
+    return `${fieldsPath(typeId)}/${encodeURIComponent(fieldId)}`;
+}
+export function createContentTypesModule(transport) {
+    async function list(options) {
+        const body = await transport.rest('cms', {
+            method: 'GET',
+            path: COLLECTIONS,
+            query: { after: options?.after ?? FIRST_PAGE, limit: options?.limit },
+        }, { ...options, preserveKeys: PLATFORM_PASSTHROUGH_KEYS });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => list({ ...options, after: cursor }));
+    }
+    return {
+        list,
+        async get(id, options) {
+            const body = await transport.rest('cms', { method: 'GET', path: typePath(id) }, { ...options, preserveKeys: PLATFORM_PASSTHROUGH_KEYS });
+            return body.data;
+        },
+        async create(input, options) {
+            const body = await transport.rest('cms', { method: 'POST', path: COLLECTIONS, body: input }, { ...options, preserveKeys: PLATFORM_PASSTHROUGH_KEYS });
+            return body.data;
+        },
+        async update(id, input, options) {
+            const body = await transport.rest('cms', { method: 'PATCH', path: typePath(id), body: input }, { ...options, preserveKeys: PLATFORM_PASSTHROUGH_KEYS });
+            return body.data;
+        },
+        async delete(id, options) {
+            await transport.rest('cms', { method: 'DELETE', path: typePath(id), expect: 'void' }, options);
+        },
+    };
+}
+export function createContentFieldsModule(transport) {
+    return {
+        async create(typeId, input, options) {
+            const body = await transport.rest('cms', { method: 'POST', path: fieldsPath(typeId), body: input }, { ...options, preserveKeys: PLATFORM_PASSTHROUGH_KEYS });
+            return body.data;
+        },
+        async update(typeId, fieldId, input, options) {
+            const body = await transport.rest('cms', { method: 'PATCH', path: fieldPath(typeId, fieldId), body: input }, { ...options, preserveKeys: PLATFORM_PASSTHROUGH_KEYS });
+            return body.data;
+        },
+        async delete(typeId, fieldId, options) {
+            await transport.rest('cms', { method: 'DELETE', path: fieldPath(typeId, fieldId), expect: 'void' }, options);
+        },
+        async reorder(typeId, fieldIds, options) {
+            // The literal `reorder` segment: the CMS declares it before `:fieldId`, so it is never
+            // read as a field id.
+            await transport.rest('cms', { method: 'PATCH', path: `${fieldsPath(typeId)}/reorder`, body: { fieldIds } }, options);
+        },
+        async reorderSubFields(typeId, groupFieldId, fieldIds, options) {
+            await transport.rest('cms', {
+                method: 'PATCH',
+                path: `${fieldPath(typeId, groupFieldId)}/reorder-sub-fields`,
+                body: { fieldIds },
+            }, options);
+        },
+    };
+}
+export function createContentPageValuesModule(transport) {
+    return {
+        async get(typeId, options) {
+            const body = await transport.rest('cms', {
+                method: 'GET',
+                path: `${typePath(typeId)}/page-values`,
+                // Always sent, empty for the base values: the transport adds the tenant's `language`
+                // to any read that names none, and `set` (a write) never gets it, so a value read on
+                // an `nl` client and written back unchanged would land in the base rows.
+                query: { language_code: options?.languageCode ?? '' },
+            }, { ...options, preserveKeys: PAGE_VALUES_PASSTHROUGH });
+            return body.data;
+        },
+        async set(typeId, input, options) {
+            const body = await transport.rest('cms', { method: 'PATCH', path: `${typePath(typeId)}/page-values`, body: input }, { ...options, preserveKeys: PAGE_VALUES_PASSTHROUGH });
+            return body.data;
+        },
+    };
+}

package/dist/customers/age-verification.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A customer's date of birth and the age check on it (headless spec §9.2 `customers`; W10-33).
+ * A date of birth is a calendar DATE, sent and answered as `YYYY-MM-DD` with no time and no
+ * zone, so it reads the same wherever it is shown.
+ */
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** The age check of one customer, as the engine judges it today. */
+export interface CustomerAgeVerification {
+    /** Whether the store checks age at all (it has a minimum age). */
+    required: boolean;
+    /**
+     * The minimum age the store enforces, its organization's when the organization shares the age
+     * gate; null without one.
+     */
+    minimumAge: number | null;
+    /**
+     * With a minimum age: the customer has a date of birth that meets it. Without one: true.
+     */
+    verified: boolean;
+    /**
+     * `YYYY-MM-DD`, or null. It is the UTC date of the instant the engine stores, which is the
+     * date {@link CustomerDateOfBirthModule.set} was given.
+     */
+    dateOfBirth: string | null;
+    /**
+     * The customer's age in whole years today, as the engine counts it (the rule `verified` is
+     * judged by); null without a date of birth. "Today" is the STORE's calendar day, in its time
+     * zone (`admin.tenant.timeZone()`): the age and the verdict turn at the store's local
+     * midnight, never at midnight UTC or the reader's. A 29 February birthday counts from 1 March
+     * in a year without one.
+     */
+    age: number | null;
+    /**
+     * Set when the caller's customer-data level withheld the date of birth and the age (an app
+     * installation below `full`): null then means "not granted".
+     */
+    redacted?: true;
+}
+export interface CustomerDateOfBirthModule {
+    /**
+     * Record a customer's date of birth (`YYYY-MM-DD`), or clear it with `null`. Needs
+     * `UpdateCustomer`. Answers the age check as it stands afterwards.
+     *
+     * Refused before anything is sent: `INVALID_DATE_OF_BIRTH` (`ValidationError`, 400) for a
+     * value that is not a real calendar date written `YYYY-MM-DD`. Refused by the engine with its
+     * sentence (`ValidationError`, `USER_INPUT_ERROR`, 400): a date in the future, or before
+     * 1900. A customer this store does not hold is a `NotFoundError` (`ENTITY_NOT_FOUND`).
+     * Requires a platform release that answers the age: an older engine refuses the call as a
+     * whole (a `ValidationError`, 400), with nothing written.
+     *
+     * @effect write
+     */
+    set(customerId: string, dateOfBirth: string | null, options?: Call): Promise<CustomerAgeVerification>;
+}
+export declare const AGE_VERIFICATION_QUERY = "\n  query CustomerAgeVerification($customerId: ID!) {\n    customerAgeVerification(customerId: $customerId) {\n      \n  required\n  minimumAge\n  verified\n  dateOfBirth\n  age\n\n    }\n  }\n";
+export declare const SET_DATE_OF_BIRTH_MUTATION = "\n  mutation SetCustomerDateOfBirth($customerId: ID!, $dateOfBirth: DateTime) {\n    setCustomerDateOfBirth(customerId: $customerId, dateOfBirth: $dateOfBirth) {\n      \n  required\n  minimumAge\n  verified\n  dateOfBirth\n  age\n\n    }\n  }\n";
+/**
+ * The instant the engine stores for a calendar date: its UTC midnight. A value that is not a
+ * real date written `YYYY-MM-DD` is refused (`2026-02-30` is no date).
+ */
+export declare function dateOfBirthInstant(date: string): string;
+/** The calendar date of a stored instant: its UTC date. Null for no value or an unreadable one. */
+export declare function dateOfBirthDate(instant: string | null | undefined): string | null;
+export declare function readCustomerAgeVerification(transport: Transport, customerId: string, options?: Call): Promise<CustomerAgeVerification | null>;
+export declare function createCustomerDateOfBirthModule(transport: Transport): CustomerDateOfBirthModule;

package/dist/customers/age-verification.js

@@ -0,0 +1,79 @@
+/**
+ * A customer's date of birth and the age check on it (headless spec §9.2 `customers`; W10-33).
+ * A date of birth is a calendar DATE, sent and answered as `YYYY-MM-DD` with no time and no
+ * zone, so it reads the same wherever it is shown.
+ */
+import { ValidationError } from '@sixtyninecommerce/core';
+import { customerDataField } from './wire.js';
+const AGE_VERIFICATION_FIELDS = /* GraphQL */ `
+  required
+  minimumAge
+  verified
+  dateOfBirth
+  age
+`;
+export const AGE_VERIFICATION_QUERY = /* GraphQL */ `
+  query CustomerAgeVerification($customerId: ID!) {
+    customerAgeVerification(customerId: $customerId) {
+      ${AGE_VERIFICATION_FIELDS}
+    }
+  }
+`;
+export const SET_DATE_OF_BIRTH_MUTATION = /* GraphQL */ `
+  mutation SetCustomerDateOfBirth($customerId: ID!, $dateOfBirth: DateTime) {
+    setCustomerDateOfBirth(customerId: $customerId, dateOfBirth: $dateOfBirth) {
+      ${AGE_VERIFICATION_FIELDS}
+    }
+  }
+`;
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * The instant the engine stores for a calendar date: its UTC midnight. A value that is not a
+ * real date written `YYYY-MM-DD` is refused (`2026-02-30` is no date).
+ */
+export function dateOfBirthInstant(date) {
+    const match = typeof date === 'string' ? DATE_ONLY.exec(date) : null;
+    const instant = match ? new Date(`${date}T00:00:00.000Z`) : null;
+    if (instant === null ||
+        Number.isNaN(instant.getTime()) ||
+        instant.toISOString().slice(0, 10) !== date) {
+        throw new ValidationError({
+            code: 'INVALID_DATE_OF_BIRTH',
+            message: `A date of birth is a calendar date written YYYY-MM-DD; got ${JSON.stringify(date)}.`,
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    return instant.toISOString();
+}
+/** The calendar date of a stored instant: its UTC date. Null for no value or an unreadable one. */
+export function dateOfBirthDate(instant) {
+    if (typeof instant !== 'string' || instant === '')
+        return null;
+    const parsed = new Date(instant);
+    return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString().slice(0, 10);
+}
+function ageVerificationOf(wire) {
+    return {
+        required: wire.required,
+        minimumAge: wire.minimumAge ?? null,
+        verified: wire.verified,
+        dateOfBirth: dateOfBirthDate(wire.dateOfBirth),
+        age: wire.age ?? null,
+    };
+}
+export async function readCustomerAgeVerification(transport, customerId, options) {
+    const { value, mark } = await customerDataField(transport, AGE_VERIFICATION_QUERY, 'customerAgeVerification', { customerId }, options);
+    return value === null ? null : mark(ageVerificationOf(value));
+}
+export function createCustomerDateOfBirthModule(transport) {
+    return {
+        async set(customerId, dateOfBirth, options) {
+            const { value, mark } = await customerDataField(transport, SET_DATE_OF_BIRTH_MUTATION, 'setCustomerDateOfBirth', {
+                customerId,
+                dateOfBirth: dateOfBirth === null ? null : dateOfBirthInstant(dateOfBirth),
+            }, options);
+            return mark(ageVerificationOf(value));
+        },
+    };
+}