includio-cms 0.20.0 → 0.22.0

package/dist/core/errors.js

@@ -0,0 +1,179 @@
+/**
+ * Base error class for CMS runtime failures. Carries a stable `code` and a
+ * `context` bag so callers (and clients) can branch on the failure mode without
+ * string-matching on `message`.
+ *
+ * `code` is a SCREAMING_SNAKE_CASE constant; see callers for the canonical list
+ * (`ENTRY_NOT_FOUND`, `ENTRY_VERSION_NOT_FOUND`, `INVALID_DATA`,
+ * `MISSING_REQUIRED_PARAM`, `CONFIG_VALIDATION_FAILED`).
+ *
+ * @public
+ * @example
+ * ```ts
+ * try { await resolveEntry({ id }); }
+ * catch (e) {
+ *   if (e instanceof CmsError && e.code === 'ENTRY_NOT_FOUND') { ... }
+ * }
+ * ```
+ */
+export class CmsError extends Error {
+    code;
+    context;
+    constructor(code, message, context = {}, options) {
+        super(message, options);
+        this.name = 'CmsError';
+        this.code = code;
+        this.context = context;
+    }
+    toString() {
+        const ctx = Object.entries(this.context)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => `${k}=${formatContextValue(v)}`)
+            .join(', ');
+        return ctx
+            ? `[${this.code}] ${this.message} (${ctx})`
+            : `[${this.code}] ${this.message}`;
+    }
+}
+function formatContextValue(v) {
+    if (v === null)
+        return 'null';
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * Thrown by {@link defineConfig} when the runtime config fails Zod validation.
+ * Aggregates ALL issues (not just the first) so the user can fix everything in
+ * one pass.
+ *
+ * @public
+ */
+export class ConfigValidationError extends CmsError {
+    issues;
+    constructor(issues) {
+        const header = `CMSConfig validation failed (${issues.length} issue${issues.length === 1 ? '' : 's'}):`;
+        const body = issues
+            .map((i) => {
+            const hint = i.hint ? ` — Hint: ${i.hint}` : '';
+            return `  - ${i.path}: ${i.message}${hint}`;
+        })
+            .join('\n');
+        super('CONFIG_VALIDATION_FAILED', `${header}\n${body}`, { issueCount: issues.length });
+        this.name = 'ConfigValidationError';
+        this.issues = issues;
+    }
+}
+/**
+ * Render a Zod issue path (`(string | number)[]`) into JS-style notation:
+ * - string segments → `.foo`
+ * - numeric segments → `[3]`
+ * - leading string segment has no leading dot.
+ */
+export function formatIssuePath(path) {
+    if (path.length === 0)
+        return '<root>';
+    let out = '';
+    for (let i = 0; i < path.length; i++) {
+        const seg = path[i];
+        if (typeof seg === 'number') {
+            out += `[${seg}]`;
+        }
+        else if (i === 0) {
+            out += seg;
+        }
+        else {
+            out += `.${seg}`;
+        }
+    }
+    return out;
+}
+/**
+ * Maps a config validation issue to a human-readable hint based on its path
+ * prefix and Zod issue `code`. Returns `undefined` when no specific hint
+ * applies (the bare message is good enough).
+ */
+function hintFor(path, code, message) {
+    const root = path[0];
+    const last = path[path.length - 1];
+    // languages[i].code — must be ISO-639-1 (with optional region)
+    if (root === 'languages' && last === 'code') {
+        return "use a 2-letter ISO code, optionally with region — e.g. 'en' or 'pl-PL'";
+    }
+    if (root === 'languages' && code === 'too_small') {
+        return 'CMSConfig.languages must contain at least one language';
+    }
+    if (root === 'languages' && code === 'invalid_type') {
+        return 'CMSConfig.languages must be an array of { code, label, default? }';
+    }
+    // adapters
+    if (root === 'db') {
+        return 'pass a DatabaseAdapter (e.g. import { postgresAdapter } from "includio-cms/db-postgres")';
+    }
+    if (root === 'files') {
+        return 'pass a FilesAdapter (e.g. import { localFilesAdapter } from "includio-cms/files-local")';
+    }
+    if (root === 'email') {
+        return 'pass an EmailAdapter or omit `email` (notifications will be skipped)';
+    }
+    if (root === 'ai') {
+        return 'pass an AIAdapter or omit `ai` (AI features will be disabled)';
+    }
+    // duplicate slugs / cross-field invariants surface as `custom` issues
+    if (code === 'custom' && /duplicate/i.test(message)) {
+        return 'each collection/single/form must have a unique `slug`';
+    }
+    if (code === 'custom' && /default locale/i.test(message)) {
+        return 'mark exactly one language with `default: true`, or rely on languages[0]';
+    }
+    if (code === 'custom' && /relation target/i.test(message)) {
+        return 'the relation field references a collection slug that is not declared in `collections`';
+    }
+    if (code === 'custom' && /apiKeys/i.test(message)) {
+        return 'apiKeys[].permissions must reference declared collection slugs';
+    }
+    // Field-level issues — recurse hint for known shapes
+    if (last === 'slug' && code === 'invalid_string') {
+        return 'slug must be a non-empty string of [a-z0-9-]';
+    }
+    if (last === 'type' && code === 'invalid_enum_value') {
+        return 'check field.type against the supported list (text, content, number, boolean, date, datetime, file, media, select, radio, checkboxes, relation, object, array, blocks, slug, seo, shop, url, custom)';
+    }
+    return undefined;
+}
+/**
+ * Render a `ZodError` from entry/form data validation as a list of
+ * `path: message` lines (one per issue). Used by data-write operations to give
+ * callers a readable dump instead of `JSON.stringify(error.flatten())`.
+ *
+ * @public
+ */
+export function formatZodDataIssues(error) {
+    if (error.issues.length === 0)
+        return '<no issues>';
+    return error.issues
+        .map((i) => {
+        const path = formatIssuePath(i.path);
+        return `${path}: ${i.message}`;
+    })
+        .join('\n');
+}
+/**
+ * Convert a `ZodError` into a {@link ConfigValidationError} with friendly,
+ * path-prefixed messages and per-issue hints.
+ */
+export function formatConfigError(error) {
+    const issues = error.issues.map((issue) => ({
+        path: formatIssuePath(issue.path),
+        message: issue.message,
+        hint: hintFor(issue.path, issue.code, issue.message)
+    }));
+    return new ConfigValidationError(issues);
+}

package/dist/core/server/consentLogs/operations/create.d.ts

@@ -1,6 +1,18 @@
 import type { ConsentLogData } from '../../../../types/consent.js';
 /**
- * Persists a CMP consent log entry via the database adapter.
+ * Persists a CMP consent log entry via the database adapter. Used by the CMP
+ * banner to record user consent decisions.
+ *
+ * @param data - The consent payload (categories accepted/rejected + audit metadata).
+ * @returns A `Promise` that resolves once the row is written.
  * @public
+ * @example
+ * ```ts
+ * await createConsentLog({
+ *   sessionId: 'abc',
+ *   categories: { necessary: true, analytics: false },
+ *   ip: '203.0.113.42'
+ * });
+ * ```
  */
 export declare const createConsentLog: (data: ConsentLogData) => Promise<void>;

package/dist/core/server/consentLogs/operations/create.js

@@ -1,7 +1,19 @@
 import { getCMS } from '../../../cms.js';
 /**
- * Persists a CMP consent log entry via the database adapter.
+ * Persists a CMP consent log entry via the database adapter. Used by the CMP
+ * banner to record user consent decisions.
+ *
+ * @param data - The consent payload (categories accepted/rejected + audit metadata).
+ * @returns A `Promise` that resolves once the row is written.
  * @public
+ * @example
+ * ```ts
+ * await createConsentLog({
+ *   sessionId: 'abc',
+ *   categories: { necessary: true, analytics: false },
+ *   ip: '203.0.113.42'
+ * });
+ * ```
  */
 export const createConsentLog = async (data) => {
     await getCMS().databaseAdapter.createConsentLog(data);

package/dist/core/server/entries/operations/create.js

@@ -5,6 +5,7 @@ import z from 'zod';
 import { _getDbEntryOrThrow as getDbEntryOrThrow } from './get.js';
 import { generateZodSchemaFromFields } from '../../../fields/fieldSchemaToTs.js';
 import { getFieldsFromConfig } from '../../../fields/layoutUtils.js';
+import { CmsError, formatZodDataIssues } from '../../../errors.js';
 export const createEntrySchema = z.object({
     slug: z.string(),
     type: z.enum(entryTypes)
@@ -42,7 +43,11 @@ export const createEntryVersion = async (data, options) => {
         });
         const parsedData = schema.safeParse(data.data);
         if (!parsedData.success) {
-            throw Error('Invalid data: ' + JSON.stringify(parsedData.error.flatten()));
+            throw new CmsError('INVALID_DATA', `Invalid data for entry version:\n${formatZodDataIssues(parsedData.error)}`, {
+                collection: entry.slug,
+                entryId: data.entryId,
+                lang: data.lang
+            });
         }
         validatedData = parsedData.data;
     }

package/dist/core/server/entries/operations/get.js

@@ -1,5 +1,6 @@
 import { getCMS } from '../../../cms.js';
 import { getAtPath } from '../../../../admin/utils/objectPath.js';
+import { CmsError } from '../../../errors.js';
 import { getFieldsFromConfig } from '../../../fields/layoutUtils.js';
 import { getEntrySlugPath, getSlugFromEntryData, getEntryPath } from '../../fields/slugResolver.js';
 export const _getDbEntries = async (options) => {
@@ -19,7 +20,10 @@ export const _getDbEntry = async (options) => {
 export const _getDbEntryOrThrow = async (options) => {
     const entry = await _getDbEntry(options);
     if (!entry) {
-        throw new Error('Entry not found');
+        throw new CmsError('ENTRY_NOT_FOUND', 'Entry not found', {
+            collection: options.slug,
+            id: options.id
+        });
     }
     return entry;
 };
@@ -84,7 +88,10 @@ export const _getRawEntry = async (options) => {
 export const _getRawEntryOrThrow = async (options) => {
     const entry = await _getRawEntry(options);
     if (!entry) {
-        throw new Error('Entry not found');
+        throw new CmsError('ENTRY_NOT_FOUND', 'Entry not found', {
+            collection: options.slug,
+            id: options.id
+        });
     }
     return entry;
 };
@@ -156,7 +163,11 @@ export const _getDbEntryVersion = async (options) => {
 export const _getDbEntryVersionOrThrow = async (options) => {
     const version = await _getDbEntryVersion(options);
     if (!version) {
-        throw new Error('Entry version not found');
+        throw new CmsError('ENTRY_VERSION_NOT_FOUND', 'Entry version not found', {
+            versionId: options.id,
+            entryId: options.entryId,
+            lang: options.lang
+        });
     }
     return version;
 };

package/dist/core/server/entries/operations/resolveEntry.d.ts

@@ -73,7 +73,15 @@ export type CountEntriesOptions = Omit<ResolveEntriesOptions, 'limit' | 'offset'
  * - `status` defaults to `'published'`. See {@link ResolveStatus}.
  * - `populate` controls relation depth + per-field opt-out. See {@link PopulateConfig}.
  *
+ * @param opts - At minimum, an `id` or a `collection` slug.
+ * @returns The populated `Entry`, or `null` when nothing matches.
+ * @throws {CmsError} with `code: 'MISSING_REQUIRED_PARAM'` when neither `id`
+ *   nor `collection` is provided.
  * @public
+ * @example
+ * ```ts
+ * const post = await resolveEntry({ collection: 'posts', locale: 'en' });
+ * ```
  */
 export declare function resolveEntry(opts: ResolveEntryOptions): Promise<Entry | null>;
 /**
@@ -84,11 +92,34 @@ export declare function resolveEntry(opts: ResolveEntryOptions): Promise<Entry |
  * - `filter.{dataValues, dataLike, dataILikeOr}` map onto adapter `getEntryVersions` filters.
  * - `limit`/`offset` applied after status pick.
  *
+ * @param opts - Must include `collection`. See {@link ResolveEntriesOptions}.
+ * @returns Array of populated `Entry` objects in the requested order.
+ * @throws {CmsError} with `code: 'MISSING_REQUIRED_PARAM'` when `collection`
+ *   is omitted.
  * @public
+ * @example
+ * ```ts
+ * const posts = await resolveEntries({
+ *   collection: 'posts',
+ *   locale: 'en',
+ *   limit: 10,
+ *   orderBy: { column: 'createdAt', direction: 'desc' }
+ * });
+ * ```
  */
 export declare function resolveEntries(opts: ResolveEntriesOptions): Promise<Entry[]>;
 /**
- * Count entries matching the same filters as `resolveEntries`, without populating.
+ * Count entries matching the same filters as `resolveEntries`, without
+ * fetching or populating their data.
+ *
+ * @param opts - Must include `collection`. See {@link CountEntriesOptions}.
+ * @returns The number of entries matching the filters.
+ * @throws {CmsError} with `code: 'MISSING_REQUIRED_PARAM'` when `collection`
+ *   is omitted.
  * @public
+ * @example
+ * ```ts
+ * const total = await countEntries({ collection: 'posts', locale: 'en' });
+ * ```
  */
 export declare function countEntries(opts: CountEntriesOptions): Promise<number>;

package/dist/core/server/entries/operations/resolveEntry.js

@@ -1,6 +1,7 @@
 import { getCMS } from '../../../cms.js';
 import { getFieldsFromConfig } from '../../../fields/layoutUtils.js';
 import { getEntrySlugPath, getSlugFromEntryData, getEntryPath } from '../../fields/slugResolver.js';
+import { CmsError } from '../../../errors.js';
 function pickVersion(versions, status) {
     const sorted = versions.slice().sort((a, b) => b.versionNumber - a.versionNumber);
     const now = new Date();
@@ -51,11 +52,19 @@ async function buildEntry(dbEntry, version, ctx) {
  * - `status` defaults to `'published'`. See {@link ResolveStatus}.
  * - `populate` controls relation depth + per-field opt-out. See {@link PopulateConfig}.
  *
+ * @param opts - At minimum, an `id` or a `collection` slug.
+ * @returns The populated `Entry`, or `null` when nothing matches.
+ * @throws {CmsError} with `code: 'MISSING_REQUIRED_PARAM'` when neither `id`
+ *   nor `collection` is provided.
  * @public
+ * @example
+ * ```ts
+ * const post = await resolveEntry({ collection: 'posts', locale: 'en' });
+ * ```
  */
 export async function resolveEntry(opts) {
     if (!opts.id && !opts.collection) {
-        throw new Error('resolveEntry: must provide id or collection');
+        throw new CmsError('MISSING_REQUIRED_PARAM', 'resolveEntry: must provide id or collection', { op: 'resolveEntry', missing: 'id|collection' });
     }
     const cms = getCMS();
     const locale = opts.locale ?? cms.languages[0];
@@ -99,11 +108,24 @@ export async function resolveEntry(opts) {
  * - `filter.{dataValues, dataLike, dataILikeOr}` map onto adapter `getEntryVersions` filters.
  * - `limit`/`offset` applied after status pick.
  *
+ * @param opts - Must include `collection`. See {@link ResolveEntriesOptions}.
+ * @returns Array of populated `Entry` objects in the requested order.
+ * @throws {CmsError} with `code: 'MISSING_REQUIRED_PARAM'` when `collection`
+ *   is omitted.
  * @public
+ * @example
+ * ```ts
+ * const posts = await resolveEntries({
+ *   collection: 'posts',
+ *   locale: 'en',
+ *   limit: 10,
+ *   orderBy: { column: 'createdAt', direction: 'desc' }
+ * });
+ * ```
  */
 export async function resolveEntries(opts) {
     if (!opts.collection) {
-        throw new Error('resolveEntries: collection is required');
+        throw new CmsError('MISSING_REQUIRED_PARAM', 'resolveEntries: collection is required', { op: 'resolveEntries', missing: 'collection' });
     }
     const cms = getCMS();
     const locale = opts.locale ?? cms.languages[0];
@@ -169,12 +191,22 @@ export async function resolveEntries(opts) {
     return results;
 }
 /**
- * Count entries matching the same filters as `resolveEntries`, without populating.
+ * Count entries matching the same filters as `resolveEntries`, without
+ * fetching or populating their data.
+ *
+ * @param opts - Must include `collection`. See {@link CountEntriesOptions}.
+ * @returns The number of entries matching the filters.
+ * @throws {CmsError} with `code: 'MISSING_REQUIRED_PARAM'` when `collection`
+ *   is omitted.
  * @public
+ * @example
+ * ```ts
+ * const total = await countEntries({ collection: 'posts', locale: 'en' });
+ * ```
  */
 export async function countEntries(opts) {
     if (!opts.collection) {
-        throw new Error('countEntries: collection is required');
+        throw new CmsError('MISSING_REQUIRED_PARAM', 'countEntries: collection is required', { op: 'countEntries', missing: 'collection' });
     }
     const cms = getCMS();
     const locale = opts.locale ?? cms.languages[0];

package/dist/core/server/entries/operations/update.js

@@ -4,6 +4,7 @@ import { getFieldsFromConfig } from '../../../fields/layoutUtils.js';
 import z from 'zod';
 import { _getDbEntryOrThrow as getDbEntryOrThrow, _getDbEntryVersionOrThrow as getDbEntryVersionOrThrow, _getDbEntryVersions as getDbEntryVersions } from './get.js';
 import { createEntryVersion } from './create.js';
+import { CmsError, formatZodDataIssues } from '../../../errors.js';
 export const updateEntrySchema = z.object({
     archivedAt: z.date().nullable().optional(),
     sortOrder: z.number().int().nullable().optional()
@@ -53,7 +54,10 @@ export const updateEntryVersion = async (id, data) => {
         });
         const parsedData = schema.safeParse(filteredData.data);
         if (!parsedData.success) {
-            throw Error('Invalid data: ' + parsedData.error.flatten());
+            throw new CmsError('INVALID_DATA', `Invalid data for entry version:\n${formatZodDataIssues(parsedData.error)}`, {
+                collection: entry.slug,
+                versionId: id
+            });
         }
         dataToUpdate.data = parsedData.data;
     }

package/dist/core/server/fields/utils/resolveMedia.d.ts

@@ -1,15 +1,32 @@
 import type { ImageFieldStyle } from '../../../../types/fields.js';
 import type { ImageStyle, MediaFile } from '../../../../types/media.js';
 /**
+ * Resolved media file plus its image styles + blur placeholder. Returned by
+ * {@link resolveMediaWithStyles}.
  * @public
  */
 export interface ResolvedMedia {
+    /** The original media file row (URL, MIME, dimensions, focal point, ...). */
     data: MediaFile;
+    /** Generated image styles keyed by style name. */
     styles: Record<string, ImageStyle>;
+    /** Tiny base64 blur placeholder, or `null` for non-image media. */
     blurDataUrl: string | null;
 }
 /**
- * Resolve media files by IDs and generate image styles. Useful for plugins resolving media references (e.g. photo-grid).
+ * Resolve media files by IDs and generate image styles. Useful for plugins or
+ * custom resolvers that hold raw media references (e.g. photo-grid blocks).
+ *
+ * @param mediaIds - The media file UUIDs to resolve.
+ * @param styles - Optional list of `ImageFieldStyle` to generate for each file.
+ * @returns A map keyed by media id, each entry is a {@link ResolvedMedia}.
  * @public
+ * @example
+ * ```ts
+ * const resolved = await resolveMediaWithStyles(
+ *   ['uuid-1', 'uuid-2'],
+ *   [{ name: 'thumb', width: 400 }]
+ * );
+ * ```
  */
 export declare function resolveMediaWithStyles(mediaIds: string[], styles?: ImageFieldStyle[]): Promise<Record<string, ResolvedMedia>>;

package/dist/core/server/fields/utils/resolveMedia.js

@@ -1,8 +1,20 @@
 import { getCMS } from '../../../cms.js';
 import { getImageStyles } from './imageStyles.js';
 /**
- * Resolve media files by IDs and generate image styles. Useful for plugins resolving media references (e.g. photo-grid).
+ * Resolve media files by IDs and generate image styles. Useful for plugins or
+ * custom resolvers that hold raw media references (e.g. photo-grid blocks).
+ *
+ * @param mediaIds - The media file UUIDs to resolve.
+ * @param styles - Optional list of `ImageFieldStyle` to generate for each file.
+ * @returns A map keyed by media id, each entry is a {@link ResolvedMedia}.
  * @public
+ * @example
+ * ```ts
+ * const resolved = await resolveMediaWithStyles(
+ *   ['uuid-1', 'uuid-2'],
+ *   [{ name: 'thumb', width: 400 }]
+ * );
+ * ```
  */
 export async function resolveMediaWithStyles(mediaIds, styles) {
     if (!mediaIds.length)

package/dist/core/server/forms/submissions/operations/create.d.ts

@@ -1,14 +1,34 @@
 /**
+ * Options for {@link createFormSubmission}.
  * @public
  */
 export interface CreateFormSubmissionOptions {
+    /** Form slug as declared in `defineConfig({ forms })`. */
     slug: string;
+    /** Submission payload. Validated against the form's field Zod schema. */
     data: Record<string, unknown>;
+    /** Optional remote IP for audit / rate-limit attribution. */
     ip?: string;
+    /** Optional user-agent string. */
     userAgent?: string;
 }
 /**
- * Persists a form submission and triggers best-effort notification email. Returns `true` if the row was written (email failures are logged, do not affect return).
+ * Persists a form submission and triggers a best-effort notification email.
+ *
+ * Validates `data` against the form's field schema and throws a `CmsError`
+ * with `code: 'INVALID_DATA'` listing every issue when invalid. Email failures
+ * are logged but do not affect the return value.
+ *
+ * @param options - See {@link CreateFormSubmissionOptions}.
+ * @returns `true` if the row was written, `false` if the DB insert failed.
+ * @throws {CmsError} with `code: 'INVALID_DATA'` when validation fails.
  * @public
+ * @example
+ * ```ts
+ * await createFormSubmission({
+ *   slug: 'contact',
+ *   data: { email: 'user@example.com', message: 'Hi' }
+ * });
+ * ```
  */
 export declare const createFormSubmission: (options: CreateFormSubmissionOptions) => Promise<boolean>;

package/dist/core/server/forms/submissions/operations/create.js

@@ -1,9 +1,25 @@
 import { getLocalizedLabel } from '../../../../../admin/utils/collectionLabel.js';
 import { getCMS } from '../../../../cms.js';
 import { generateZodSchemaFromFormFields } from '../../../../fields/formFieldSchemaToTs.js';
+import { CmsError, formatZodDataIssues } from '../../../../errors.js';
 /**
- * Persists a form submission and triggers best-effort notification email. Returns `true` if the row was written (email failures are logged, do not affect return).
+ * Persists a form submission and triggers a best-effort notification email.
+ *
+ * Validates `data` against the form's field schema and throws a `CmsError`
+ * with `code: 'INVALID_DATA'` listing every issue when invalid. Email failures
+ * are logged but do not affect the return value.
+ *
+ * @param options - See {@link CreateFormSubmissionOptions}.
+ * @returns `true` if the row was written, `false` if the DB insert failed.
+ * @throws {CmsError} with `code: 'INVALID_DATA'` when validation fails.
  * @public
+ * @example
+ * ```ts
+ * await createFormSubmission({
+ *   slug: 'contact',
+ *   data: { email: 'user@example.com', message: 'Hi' }
+ * });
+ * ```
  */
 export const createFormSubmission = async (options) => {
     const { slug, data, ip, userAgent } = options;
@@ -11,7 +27,7 @@ export const createFormSubmission = async (options) => {
     const schema = await generateZodSchemaFromFormFields(config.fields);
     const parsedData = schema.safeParse(data);
     if (!parsedData.success) {
-        throw new Error('Invalid data: ' + JSON.stringify(parsedData.error.flatten()));
+        throw new CmsError('INVALID_DATA', `Invalid data for form submission:\n${formatZodDataIssues(parsedData.error)}`, { formSlug: slug });
     }
     try {
         await getCMS().databaseAdapter.createFormSubmission({

package/dist/core/server/forms/submissions/utils/parseMultipart.d.ts

@@ -1,6 +1,20 @@
 import type { FormField } from '../../../../../types/formFields.js';
 /**
- * Parses multipart `FormData` into a typed record of field values, handling file uploads via the configured files adapter.
+ * Parses multipart `FormData` into a typed record of field values, handling
+ * file uploads via the configured `FilesAdapter`.
+ *
+ * @param formData - The request's `FormData` (e.g. `await request.formData()`).
+ * @param fields - The form's `FormField[]` definitions.
+ * @returns A plain `Record<string, unknown>` keyed by field slug, with files
+ *   replaced by their persisted URL/identifier.
  * @public
+ * @example
+ * ```ts
+ * const data = await parseFormDataForSubmission(
+ *   await request.formData(),
+ *   formConfig.fields
+ * );
+ * await createFormSubmission({ slug: formConfig.slug, data });
+ * ```
  */
 export declare function parseFormDataForSubmission(formData: FormData, fields: FormField[]): Promise<Record<string, unknown>>;

package/dist/core/server/forms/submissions/utils/parseMultipart.js

@@ -26,8 +26,22 @@ function validateMagicBytes(buffer, declaredMime) {
     return false;
 }
 /**
- * Parses multipart `FormData` into a typed record of field values, handling file uploads via the configured files adapter.
+ * Parses multipart `FormData` into a typed record of field values, handling
+ * file uploads via the configured `FilesAdapter`.
+ *
+ * @param formData - The request's `FormData` (e.g. `await request.formData()`).
+ * @param fields - The form's `FormField[]` definitions.
+ * @returns A plain `Record<string, unknown>` keyed by field slug, with files
+ *   replaced by their persisted URL/identifier.
  * @public
+ * @example
+ * ```ts
+ * const data = await parseFormDataForSubmission(
+ *   await request.formData(),
+ *   formConfig.fields
+ * );
+ * await createFormSubmission({ slug: formConfig.slug, data });
+ * ```
  */
 export async function parseFormDataForSubmission(formData, fields) {
     const result = {};

package/dist/core/server/media/operations/uploadFile.js

@@ -4,6 +4,7 @@ import { generateAdminThumbnail } from '../utils/generateAdminThumbnail.js';
 import { generateDefaultStylesInBackground } from '../styles/operations/generateDefaultStyles.js';
 import { generateDefaultVideoStylesInBackground } from '../styles/operations/generateDefaultVideoStyles.js';
 import sharp from 'sharp';
+import { withTimeout, sharpTimeoutMs } from '../../../../server/utils/withTimeout.js';
 async function maybeDownscale(file) {
     const cms = getCMS();
     const { maxOriginalWidth, maxOriginalHeight } = cms.mediaConfig;
@@ -14,19 +15,19 @@ async function maybeDownscale(file) {
         return file;
     try {
         const buffer = Buffer.from(await file.arrayBuffer());
-        const metadata = await sharp(buffer).metadata();
+        const metadata = await withTimeout(sharp(buffer).metadata(), sharpTimeoutMs(), 'sharp.metadata');
         const w = metadata.width || 0;
         const h = metadata.height || 0;
         const exceedsWidth = maxOriginalWidth && w > maxOriginalWidth;
         const exceedsHeight = maxOriginalHeight && h > maxOriginalHeight;
         if (!exceedsWidth && !exceedsHeight)
             return file;
-        const resized = await sharp(buffer)
+        const resized = await withTimeout(sharp(buffer)
             .resize(maxOriginalWidth, maxOriginalHeight, {
             fit: 'inside',
             withoutEnlargement: true
         })
-            .toBuffer();
+            .toBuffer(), sharpTimeoutMs(), 'sharp.resize');
         return new File([new Uint8Array(resized)], file.name, { type: file.type });
     }
     catch (e) {