@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/dist/content/forms.d.ts

@@ -1,5 +1,12 @@
 import { type Page, type Transport } from '@sixtyninecommerce/core';
 import type { Call, ListOptions } from '../types.js';
+/**
+ * The field types the CMS accepts on a new field (`CreateFormFieldDto.field_type`), pinned
+ * against the CMS's published `openapi.json` by `content-coverage.spec.ts`. The members that
+ * carry a field's type stay `string` so a type a newer CMS adds still reads, and so code that
+ * already passes a `string` keeps compiling; `fieldTypes()` answers each type's rules at runtime.
+ */
+export type FormFieldType = 'text' | 'textarea' | 'email' | 'phone' | 'number' | 'select' | 'checkbox' | 'radio' | 'date' | 'file' | 'hidden';
 /**
  * Everything a visitor reads is TRANSLATED, per language, in its own row:
  * `forms_translations` and `form_fields_translations`. `name` and `slug` are
@@ -70,21 +77,40 @@ export interface Form {
     /** Free-form JSONB the CMS stores verbatim — never case-converted. */
     settings: Record<string, unknown> | null;
     translations?: FormTranslation[];
+    /**
+     * The form's fields, REMOVED ones included (each with its `removedAt`): see
+     * {@link FormField.removedAt}. Not on `list`.
+     */
     fields?: FormField[];
+    /** How many submissions the form holds, deleted ones not counted. On `list` only. */
+    submissionCount?: number;
     createdAt: string;
     updatedAt: string;
     [extra: string]: unknown;
 }
 export interface FormField {
     id: string;
+    formId: string;
     name: string;
+    /** The key a submission's answer for this field is stored under. */
     slug: string;
+    /** One of {@link FormFieldType}. */
     fieldType: string;
     isRequired: boolean;
+    /** The field's place in the form, lowest first. */
     position: number;
     config: Record<string, unknown> | null;
     validation: Record<string, unknown> | null;
     translations?: FormFieldTranslation[];
+    /**
+     * When the field was removed from the form, or `null` for a live field. Every answer that
+     * carries a form's `fields` includes its removed ones (storefronts never see them), so the
+     * answers older submissions hold under a removed field's slug can still be labelled: filter
+     * on this to show the form a visitor fills in.
+     */
+    removedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
     [extra: string]: unknown;
 }
 /**
@@ -96,14 +122,38 @@ export interface FormField {
  */
 export interface FormFieldInput {
     name: string;
+    /**
+     * Lowercase letters and digits in words joined by single UNDERSCORES (`first_name`), unlike
+     * a form's hyphenated slug; unique among the form's live fields. A submission sends the
+     * field's answer under it.
+     */
     slug: string;
+    /** One of {@link FormFieldType}. */
     fieldType: string;
     isRequired?: boolean;
+    /** Defaults to after the form's last live field. */
     position?: number;
     config?: Record<string, unknown>;
     validation?: Record<string, unknown>;
     translations?: FormFieldTranslationInput[];
 }
+/**
+ * The members `fields.update` acts on: those of {@link FormFieldInput}, each optional. An absent
+ * key leaves the stored value alone; `null` clears `config` or `validation`, each of which is
+ * replaced whole, never merged. `translations` writes the languages it names and keeps the
+ * others. A new `position` is written as given and moves no other field: give each field its
+ * number to reorder a form.
+ */
+export interface UpdateFormFieldInput {
+    name?: string;
+    slug?: string;
+    fieldType?: string;
+    isRequired?: boolean;
+    position?: number;
+    config?: Record<string, unknown> | null;
+    validation?: Record<string, unknown> | null;
+    translations?: FormFieldTranslationInput[];
+}
 /**
  * Exactly what `UpsertFormDto` whitelists. `slug` is NOT here on purpose: it
  * comes from the URL, and sending it is a 400 under `forbidNonWhitelisted`.
@@ -123,11 +173,292 @@ export interface FormInput {
     translations?: FormTranslationInput[];
     fields?: FormFieldInput[];
 }
+/**
+ * Exactly what `CreateFormDto` whitelists. A new form has no fields: add them with
+ * `fields.create`, or write a form and its fields in one call with `upsertBySlug`.
+ */
+export interface CreateFormInput {
+    name: string;
+    /**
+     * Lowercase letters and digits in words joined by single hyphens (`contact-us`); unique among
+     * the store's forms. What a storefront reads the form by.
+     */
+    slug: string;
+    /** Comma-separated addresses each submission is e-mailed to. */
+    notificationEmails?: string | null;
+    /** Where a storefront sends the visitor after a submission. */
+    redirectUrlOnSuccess?: string | null;
+    /** What a submission does; the CMS's default is `store`. */
+    submitAction?: string;
+    /** Stored verbatim. */
+    settings?: Record<string, unknown> | null;
+    translations?: FormTranslationInput[];
+}
+/**
+ * What `UpdateFormDto` whitelists. An absent key leaves the stored value alone; `null` clears
+ * `notificationEmails`, `redirectUrlOnSuccess` and `settings`. `settings` is replaced whole,
+ * never merged: read the form, change the bag, write it back. `translations` writes the
+ * languages it names and keeps the others. A new `slug` changes what storefronts read the form
+ * by.
+ */
+export interface UpdateFormInput {
+    name?: string;
+    slug?: string;
+    notificationEmails?: string | null;
+    redirectUrlOnSuccess?: string | null;
+    submitAction?: string;
+    settings?: Record<string, unknown> | null;
+    translations?: FormTranslationInput[];
+}
+/** A form as a reference to it shows it: what a picker lists and a chosen form's label reads. */
+export interface FormReference {
+    id: string;
+    name: string;
+    /** What a storefront reads the form by. */
+    slug: string;
+    /**
+     * How many submissions the form holds, on `references` only and only for a caller with
+     * `ReadCmsForm` (the storefront projection has no count).
+     */
+    submissionCount?: number;
+}
+export interface FormListOptions extends ListOptions {
+    /** Forms whose name contains this, ignoring case. */
+    search?: string;
+    /**
+     * `name`, `created_at` or `updated_at`, with a leading `-` for descending. Anything else (and
+     * no sort) is newest first.
+     */
+    sort?: string;
+}
+/** One rule a field type honours on a submission, read from `validation` first, then `config`. */
+export interface FormFieldConstraint {
+    /** The key in the field's `validation` (or `config`): `min_length`, `pattern`, `options`, … */
+    key: string;
+    valueType: string;
+    description: string;
+}
+/** One field type as `GET /forms/field-types` describes it. */
+export interface FormFieldTypeDescriptor {
+    /** One of {@link FormFieldType}. */
+    type: string;
+    label: string;
+    description: string;
+    /** The shape of the answer a submission sends for a field of this type. */
+    valueType: string;
+    constraints: FormFieldConstraint[];
+    notes?: string;
+    [extra: string]: unknown;
+}
+/** The shape a form slug or a field slug must have. */
+export interface FormSlugRule {
+    /** The regular expression's source. */
+    pattern: string;
+    maxLength: number;
+    description: string;
+    validExamples: string[];
+    invalidExamples: string[];
+    [extra: string]: unknown;
+}
+export interface FormFieldTypeRegistry {
+    fieldTypes: FormFieldTypeDescriptor[];
+    slugRules: {
+        form: FormSlugRule;
+        field: FormSlugRule;
+    };
+}
+/**
+ * One visitor's submission of a form. PERSONAL DATA: `data` is whatever the visitor typed (a
+ * name, an address, a message), and `ipAddress` / `userAgent` identify their device.
+ */
+export interface FormSubmission {
+    id: string;
+    formId: string;
+    channelId: string;
+    /**
+     * The visitor's answers, keyed by field slug EXACTLY as stored (`first_name` stays
+     * `first_name`): never case-converted. Keys of removed fields stay in older submissions.
+     */
+    data: Record<string, unknown>;
+    /** The language the visitor submitted in, when the storefront named one. */
+    localeCode: string | null;
+    ipAddress: string | null;
+    userAgent: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+    [extra: string]: unknown;
+}
+/**
+ * A form's fields. Every method takes the form's id first; a form of another store, a removed
+ * form, or a field of another form is `NotFoundError` (404). A field write records the form's
+ * change exactly like a form write.
+ */
+export interface FormFieldsModule {
+    /**
+     * Adds a field. A slug taken by a live field of the form is `ConflictError` (409); an unknown
+     * `fieldType` or a slug of the wrong shape is `ValidationError` (`VALIDATION_FAILED`). Answers
+     * the field as stored, with its translations (a CMS before 2026-10-15 answers it without
+     * them).
+     *
+     * @effect write
+     * @permission CreateCmsForm
+     */
+    create(formId: string, input: FormFieldInput, options?: Call): Promise<FormField>;
+    /**
+     * Writes what the input names. Answers the field with its translations.
+     *
+     * @effect write
+     * @permission UpdateCmsForm
+     */
+    update(formId: string, fieldId: string, input: UpdateFormFieldInput, options?: Call): Promise<FormField>;
+    /**
+     * Removes the field from the form: storefronts stop rendering it and a new submission may no
+     * longer answer it, its slug is free again, and nothing in the SDK brings it back. Submissions
+     * keep what they answered under it, and the form's `fields` keep it with its `removedAt`.
+     *
+     * @effect destructive
+     * @permission DeleteCmsForm
+     */
+    delete(formId: string, fieldId: string, options?: Call): Promise<void>;
+}
+/**
+ * A form's submissions: PERSONAL DATA (see {@link FormSubmission}). A form of another store is
+ * `NotFoundError` (404).
+ */
+export interface FormSubmissionsModule {
+    /**
+     * The form's submissions, newest first, a page at a time, with `Page.total`.
+     *
+     * Without `after`, pages follow the CMS's cursor: a walk (`for await`) sees every submission
+     * once, even while visitors submit or others are deleted. `after: offsetCursor(n)` opens the
+     * page that starts at offset `n` (a table's page `n`), and the pages after it go by offset, so
+     * a submission that arrives or is deleted meanwhile can push a row onto the next page twice or
+     * past it. A page's `nextCursor`, passed back as `after`, continues in the page's own mode.
+     * The CMS answers at most 200 a page in cursor mode, whatever `limit` asks.
+     *
+     * An app installation below `customerData: full` is refused: `PermissionDeniedError` with
+     * code `CUSTOMER_DATA_NOT_GRANTED` (free text cannot be partly withheld). A staff member or a
+     * personal API token needs only the permission.
+     *
+     * @effect read
+     * @permission ReadCmsForm
+     */
+    list(formId: string, options?: ListOptions): Promise<Page<FormSubmission>>;
+    /**
+     * Removes the submission from every read and from the form's `submissionCount`; nothing in
+     * the SDK brings it back. It is NOT an erasure: the CMS keeps the row, marked removed, until
+     * the store itself is purged.
+     *
+     * @effect destructive
+     * @permission DeleteCmsForm
+     */
+    delete(formId: string, submissionId: string, options?: Call): Promise<void>;
+}
+/**
+ * The store's forms (a contact form, a newsletter sign-up), their fields and their submissions,
+ * through the CMS.
+ *
+ * Every method needs the permission it names (`@permission`). The form reads are public CMS
+ * routes that answer anyone without `ReadCmsForm` on the store the storefront projection, which
+ * these methods refuse with `AdminProjectionError` instead of returning half a form.
+ *
+ * Refusals are the CMS's problem+json, mapped by status:
+ * - `NotFoundError` (404, `NOT_FOUND`): no such form, field or submission in this store.
+ * - `ConflictError` (409, `CONFLICT`): the slug is taken (a form's in the store, a field's in its
+ *   form).
+ * - `ValidationError` (400): `VALIDATION_FAILED` with one `details[]` entry per refused input
+ *   member (a slug of the wrong shape, an unknown field type, an address that is not one in
+ *   `notificationEmails`, an id that is not a UUID).
+ * - `PermissionDeniedError` (403): the credential lacks the method's permission.
+ *
+ * Every form or field write records the store's site-content change (`content.site_content_changed`
+ * with kind `form_definition`) and `form.changed`; deleting a submission records neither.
+ * `create` and `upsertBySlug` honour an `idempotencyKey` (the CMS replays the first answer);
+ * every other write sends it and it acts on nothing.
+ */
 export interface FormsModule {
-    list(options?: ListOptions): Promise<Page<Form>>;
+    /**
+     * The store's forms, a page at a time, newest first unless `sort` says otherwise; each with
+     * its `submissionCount`, none with its fields. Pages are offset-based (`Page.total` counts the
+     * matches), so `after: offsetCursor((n - 1) * size)` opens page `n`.
+     *
+     * @effect read
+     * @permission ReadCmsForm
+     */
+    list(options?: FormListOptions): Promise<Page<Form>>;
+    /**
+     * One form with its translations and its fields, removed ones included.
+     *
+     * @effect read
+     * @permission ReadCmsForm
+     */
     get(id: string, options?: Call): Promise<Form>;
+    /**
+     * One form by its slug, as {@link FormsModule.get}.
+     *
+     * @effect read
+     * @permission ReadCmsForm
+     */
     getBySlug(slug: string, options?: Call): Promise<Form>;
+    /**
+     * The store's forms as references (id, name, slug), a page at a time, in `list`'s order and
+     * with its `search` and `sort`. Unlike `list` it needs no permission: it reads what a
+     * storefront reads, so a caller without `ReadCmsForm` (a content editor choosing the form a
+     * page shows) can still name and pick one.
+     *
+     * @effect read
+     */
+    references(options?: FormListOptions): Promise<Page<FormReference>>;
+    /**
+     * One form as a reference (id, name, slug), for any caller: `NotFoundError` for a form this
+     * store does not hold.
+     *
+     * @effect read
+     */
+    reference(id: string, options?: Call): Promise<FormReference>;
+    /**
+     * The field types a form can hold, the rules each honours, and the shapes a form slug and a
+     * field slug must have. The same for every store.
+     *
+     * @effect read
+     */
+    fieldTypes(options?: Call): Promise<FormFieldTypeRegistry>;
+    /**
+     * Adds a form without fields. Answers it as stored, with its translations (a CMS before
+     * 2026-10-15 answers it without them).
+     *
+     * @effect write
+     * @permission CreateCmsForm
+     */
+    create(input: CreateFormInput, options?: Call): Promise<Form>;
+    /**
+     * Writes what the input names. Answers the form as it now is, with its translations and its
+     * fields (a CMS before 2026-10-15 answers the translations as they were BEFORE this write).
+     *
+     * @effect write
+     * @permission UpdateCmsForm
+     */
+    update(id: string, input: UpdateFormInput, options?: Call): Promise<Form>;
+    /**
+     * Creates the form when its slug is free in the store, or updates it, and upserts each listed
+     * field by slug in the same transaction; fields not listed are left alone. Creating needs
+     * `CreateCmsForm`, updating `UpdateCmsForm`.
+     *
+     * @effect write
+     * @permission CreateCmsForm
+     * @permission UpdateCmsForm
+     */
     upsertBySlug(slug: string, input: FormInput, options?: Call): Promise<Form>;
+    /**
+     * Removes the form: storefronts reading it get `NotFoundError`, its slug is free again, its
+     * submissions can no longer be listed, and nothing in the SDK brings it back.
+     *
+     * @effect destructive
+     * @permission DeleteCmsForm
+     */
     delete(id: string, options?: Call): Promise<void>;
+    fields: FormFieldsModule;
+    submissions: FormSubmissionsModule;
 }
 export declare function createFormsModule(transport: Transport): FormsModule;

package/dist/content/forms.js

@@ -1,6 +1,7 @@
-import { createPage, offsetCursor, PLATFORM_PASSTHROUGH_KEYS, readOffsetCursor, } from '@sixtyninecommerce/core';
+import { createPage, offsetCursor, PLATFORM_PASSTHROUGH_KEYS, readOffsetCursor, snakeToCamelKeys, } from '@sixtyninecommerce/core';
 import { AdminProjectionError } from '../errors.js';
 const DEFAULT_PAGE_SIZE = 25;
+const DEFAULT_SUBMISSION_PAGE_SIZE = 50;
 /**
  * A form carries three bags the CMS stores verbatim: `settings`, and each
  * field's `config` and `validation` (whose constraint keys are snake_case —
@@ -9,6 +10,18 @@ const DEFAULT_PAGE_SIZE = 25;
  * `Transport.rest` preserves nothing that is not named.
  */
 const FORM_PASSTHROUGH = PLATFORM_PASSTHROUGH_KEYS;
+/**
+ * A submission's answers are keyed by the merchant's field slugs (`first_name`), which the
+ * transport would rename (`firstName`) on the way in. `data` cannot join the shared set: it is
+ * also the CMS's list envelope. So the list keeps the envelope's rows verbatim and camelises
+ * each row here, its `data` excepted (`PLATFORM_PASSTHROUGH_KEYS` header in
+ * `@sixtyninecommerce/core`'s `case.ts`). Both paging modes answer the rows under `data`; the
+ * `items` copy a cursor page also carries is not read.
+ */
+const SUBMISSION_ENVELOPE = new Set(['data']);
+const SUBMISSION_ROW = new Set([...PLATFORM_PASSTHROUGH_KEYS, 'data']);
+/** The cursor-mode opener: `after` present and empty starts the CMS's keyset walk. */
+const FIRST_CURSOR_PAGE = '';
 /**
  * `GET /forms*` is a PUBLIC CMS route with OPTIONAL auth: a token the CMS does
  * not accept for this channel is not rejected — the route answers 200 with the
@@ -23,9 +36,42 @@ function assertAdminProjection(form, what) {
         return form;
     throw new AdminProjectionError(what);
 }
+/** The reference members: the same under the admin and the storefront projection, but the count. */
+function toReference(form) {
+    return {
+        id: form.id,
+        name: form.name,
+        slug: form.slug,
+        ...(typeof form.submissionCount === 'number' ? { submissionCount: form.submissionCount } : {}),
+    };
+}
+function formPath(id) {
+    return `/forms/${encodeURIComponent(id)}`;
+}
+function fieldPath(formId, fieldId) {
+    return `${formPath(formId)}/fields/${encodeURIComponent(fieldId)}`;
+}
+function submissionsPath(formId) {
+    return `${formPath(formId)}/submissions`;
+}
+/** The offset an `offsetCursor` names, or null for any other cursor (the CMS's own). */
+function offsetOf(cursor) {
+    try {
+        return readOffsetCursor(cursor);
+    }
+    catch {
+        return null;
+    }
+}
 export function createFormsModule(transport) {
     async function listPage(offset, limit, options) {
-        const body = await transport.rest('cms', { method: 'GET', path: '/forms', query: { limit, offset } }, { ...options, preserveKeys: FORM_PASSTHROUGH });
+        const body = await transport.rest('cms', {
+            method: 'GET',
+            path: '/forms',
+            // `offset` is always sent: it keeps the CMS out of its keyset mode, which cannot resume
+            // a `sort` and cannot open page n.
+            query: { limit, offset, search: options?.search, sort: options?.sort },
+        }, { ...options, preserveKeys: FORM_PASSTHROUGH });
         const items = body.data ?? [];
         // `GET /forms` is `@Public()` exactly like the two single reads, so a
         // credential the CMS will not accept for this channel is answered 200 with
@@ -40,6 +86,73 @@ export function createFormsModule(transport) {
         const hasNext = advanced < total;
         return createPage(items, { nextCursor: hasNext ? offsetCursor(advanced) : null, hasNext, total }, (cursor) => listPage(readOffsetCursor(cursor), limit, options));
     }
+    async function referencePage(offset, limit, options) {
+        // The bags are dropped below, so nothing in them needs preserving.
+        const body = await transport.rest('cms', {
+            method: 'GET',
+            path: '/forms',
+            query: { limit, offset, search: options?.search, sort: options?.sort },
+        }, options);
+        const items = (body.data ?? []).map(toReference);
+        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) => referencePage(readOffsetCursor(cursor), limit, options));
+    }
+    async function writeForm(method, path, input, options) {
+        const body = await transport.rest('cms', { method, path, body: input }, { ...options, preserveKeys: FORM_PASSTHROUGH });
+        return body.data;
+    }
+    async function submissionPage(formId, limit, position, options) {
+        const body = await transport.rest('cms', {
+            method: 'GET',
+            path: submissionsPath(formId),
+            query: 'offset' in position ? { limit, offset: position.offset } : { limit, ...position },
+        }, { ...options, preserveKeys: SUBMISSION_ENVELOPE });
+        const rows = body.data ?? [];
+        const items = rows.map((row) => snakeToCamelKeys(row, { preserveKeys: SUBMISSION_ROW }));
+        const total = body.pagination?.total;
+        if ('offset' in position) {
+            // An offset page echoes no offset: the next one is built from what THIS call asked for,
+            // advancing by the limit past an empty page so a walk always ends.
+            const advanced = position.offset + (items.length > 0 ? items.length : limit);
+            const hasNext = advanced < (total ?? items.length);
+            return createPage(items, { nextCursor: hasNext ? offsetCursor(advanced) : null, hasNext, total }, (cursor) => submissionPage(formId, limit, { offset: readOffsetCursor(cursor) }, options));
+        }
+        const nextCursor = typeof body.nextCursor === 'string' && body.nextCursor !== '' ? body.nextCursor : null;
+        const hasNext = body.hasNext === true && nextCursor !== null;
+        return createPage(items, { nextCursor: hasNext ? nextCursor : null, hasNext, total }, (cursor) => submissionPage(formId, limit, { after: cursor }, options));
+    }
+    const fields = {
+        async create(formId, input, options) {
+            const body = await transport.rest('cms', { method: 'POST', path: `${formPath(formId)}/fields`, body: input }, { ...options, preserveKeys: FORM_PASSTHROUGH });
+            return body.data;
+        },
+        async update(formId, fieldId, input, options) {
+            const body = await transport.rest('cms', { method: 'PATCH', path: fieldPath(formId, fieldId), body: input }, { ...options, preserveKeys: FORM_PASSTHROUGH });
+            return body.data;
+        },
+        async delete(formId, fieldId, options) {
+            await transport.rest('cms', { method: 'DELETE', path: fieldPath(formId, fieldId), expect: 'void' }, options);
+        },
+    };
+    const submissions = {
+        list(formId, options) {
+            const limit = options?.limit ?? DEFAULT_SUBMISSION_PAGE_SIZE;
+            if (options?.after === undefined) {
+                return submissionPage(formId, limit, { after: FIRST_CURSOR_PAGE }, options);
+            }
+            const offset = offsetOf(options.after);
+            return submissionPage(formId, limit, offset === null ? { after: options.after } : { offset }, options);
+        },
+        async delete(formId, submissionId, options) {
+            await transport.rest('cms', {
+                method: 'DELETE',
+                path: `${submissionsPath(formId)}/${encodeURIComponent(submissionId)}`,
+                expect: 'void',
+            }, options);
+        },
+    };
     return {
         list(options) {
             const limit = options?.limit ?? DEFAULT_PAGE_SIZE;
@@ -47,19 +160,42 @@ export function createFormsModule(transport) {
             return listPage(offset, limit, options);
         },
         async get(id, options) {
-            const body = await transport.rest('cms', { method: 'GET', path: `/forms/${encodeURIComponent(id)}` }, { ...options, preserveKeys: FORM_PASSTHROUGH });
+            const body = await transport.rest('cms', { method: 'GET', path: formPath(id) }, { ...options, preserveKeys: FORM_PASSTHROUGH });
             return assertAdminProjection(body.data, `form "${id}"`);
         },
         async getBySlug(slug, options) {
             const body = await transport.rest('cms', { method: 'GET', path: `/forms/by-slug/${encodeURIComponent(slug)}` }, { ...options, preserveKeys: FORM_PASSTHROUGH });
             return assertAdminProjection(body.data, `form "${slug}"`);
         },
+        references(options) {
+            const limit = options?.limit ?? DEFAULT_PAGE_SIZE;
+            const offset = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+            return referencePage(offset, limit, options);
+        },
+        async reference(id, options) {
+            const body = await transport.rest('cms', { method: 'GET', path: formPath(id) }, options);
+            return toReference(body.data);
+        },
+        async fieldTypes(options) {
+            // Every key of this answer is the CMS's own camelCase vocabulary; the constraint keys a
+            // field's bags use (`min_length`) are VALUES here, which the conversion never touches.
+            const body = await transport.rest('cms', { method: 'GET', path: '/forms/field-types' }, options);
+            return { fieldTypes: body.data, slugRules: body.meta.slugRules };
+        },
+        create(input, options) {
+            return writeForm('POST', '/forms', input, options);
+        },
+        update(id, input, options) {
+            return writeForm('PATCH', formPath(id), input, options);
+        },
         async upsertBySlug(slug, input, options) {
             const body = await transport.rest('cms', { method: 'PUT', path: `/forms/by-slug/${encodeURIComponent(slug)}`, body: input }, { ...options, preserveKeys: FORM_PASSTHROUGH });
             return body.data;
         },
         async delete(id, options) {
-            await transport.rest('cms', { method: 'DELETE', path: `/forms/${encodeURIComponent(id)}`, expect: 'void' }, options);
+            await transport.rest('cms', { method: 'DELETE', path: formPath(id), expect: 'void' }, options);
         },
+        fields,
+        submissions,
     };
 }

package/dist/content/items.d.ts

@@ -73,6 +73,29 @@ export interface ContentItemWithFields {
     fieldValues: Record<string, unknown>;
     [extra: string]: unknown;
 }
+/** One named item's outcome in `items.bulkSetStatus`. */
+export interface ContentItemStatusOutcome {
+    id: string;
+    /** `OK`, or `FAILED` (a string on the wire: read anything else as not done). */
+    status: 'OK' | 'FAILED' | (string & {});
+    /**
+     * When FAILED: `VALIDATION_ERROR` (publishing an item that leaves a required field empty, the
+     * refusal `publish` answers) or `NOT_FOUND` (no live item of the type in this store).
+     */
+    code: string | null;
+    /** When FAILED: the CMS's sentence; for an empty required field it names the fields. */
+    message: string | null;
+}
+/** What `items.bulkSetStatus` answers. */
+export interface ContentItemBulkStatusResult {
+    /** How many items now have the status. */
+    updated: number;
+    /**
+     * One outcome per id named, in the order named, each id once. Null when the CMS answering
+     * predates per-item outcomes; such a CMS also publishes without the required-field check.
+     */
+    results: ContentItemStatusOutcome[] | null;
+}
 export interface ContentItemListOptions extends ListOptions {
     /**
      * Only items in this status. Honoured for a credential holding `ReadCmsContent` on the
@@ -222,16 +245,16 @@ export interface ContentItemsModule {
      */
     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.
+     * Sets one status on several items of the type in one transaction, and reports each item on its
+     * own (`results`). Publishing refuses an item that leaves a required field empty, as `publish`
+     * does: that item keeps its status (`FAILED`, `VALIDATION_ERROR`) and the others still change.
+     * An id that is not a live item of this type in this store changes nothing (`NOT_FOUND`). The
+     * call itself fails only for the whole selection (an unknown type, a malformed id or status).
      *
      * @effect write
      * @permission UpdateCmsContent
      */
-    bulkSetStatus(typeId: string, itemIds: readonly string[], status: ContentItemStatus, options?: Call): Promise<{
-        updated: number;
-    }>;
+    bulkSetStatus(typeId: string, itemIds: readonly string[], status: ContentItemStatus, options?: Call): Promise<ContentItemBulkStatusResult>;
     /**
      * 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
@@ -248,8 +271,8 @@ export interface ContentItemsModule {
      * 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.
+     * error. An id that is not a UUID is absent too (a CMS before 2026-10-14 refused the whole batch
+     * with it, `ValidationError` `INVALID_DATA`).
      *
      * 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

package/dist/content/items.js

@@ -138,7 +138,7 @@ export function createContentItemsModule(transport) {
                 path: `${itemsPath(typeId)}/bulk-status`,
                 body: { itemIds: [...itemIds], status },
             }, options);
-            return { updated: body.data.updated };
+            return { updated: body.data.updated, results: body.data.results ?? null };
         },
         async bulkDelete(typeId, itemIds, options) {
             const body = await transport.rest('cms', {