@elytracms/forms 0.0.0-stage → 0.0.95

package/dist/shared/kind.d.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import type { RecordEntryOf } from '@elytracms/core/persistence';
+/**
+ * EC-613 — the SUBMISSION record kind: every form post a site receives, one row in the
+ * engine's record store (EC-616), declared ONCE here and read by all three planes — the
+ * Convex functions that store it (`@elytracms/forms/convex`), the studio inbox that lists
+ * and edits it (`@elytracms/forms/studio`) and the site helpers that send it
+ * (`@elytracms/forms/next`).
+ *
+ * Its functions live in the Convex module `forms` — the consumer's ONE re-export file is
+ * `convex/forms.ts`: `export * from '@elytracms/forms/convex'`.
+ *
+ * Who writes what:
+ * - the SITE (through the ingest receiver's handler, `forms:ingest`): `form`, `payload`,
+ *   `files`, `sourceUrl`, `spam`, `submittedAt` — what the visitor sent and what the checks
+ *   said. Never edited afterwards;
+ * - the EDITOR (through the inbox): `status`, `assignee`, `notes` — the inbox lifecycle (the
+ *   SMB CRM of the ruling; a sales pipeline is the developer's structure, not this kind);
+ * - the DELIVERY (the scheduled `forms:deliver` action): `deliveryState`, `deliveryLog`.
+ *
+ * The payload is a LIST of `{ name, value }` (sorted by name), not an object keyed by field
+ * name: a visitor's field names never become stored object keys. Its display order is the
+ * FORM's (`labelPayload` over the form source's `fields`). A value is a string, a number, a
+ * boolean or a list of strings, so the stored depth is bounded by construction.
+ */
+/** The editor's inbox lifecycle. */
+export declare const SUBMISSION_STATUSES: readonly ["new", "open", "done", "spam"];
+export type SubmissionStatus = (typeof SUBMISSION_STATUSES)[number];
+/** What a submission's delivery is doing — see `@elytracms/forms` `applyDeliveryOutcome`. */
+export declare const DELIVERY_STATES: readonly ["pending", "sent", "partial", "failed", "skipped"];
+export type DeliveryState = (typeof DELIVERY_STATES)[number];
+/** What the spam checks said: nothing, or the form's honeypot was filled. */
+export declare const SPAM_VERDICTS: readonly ["clean", "honeypot"];
+export type SpamVerdict = (typeof SPAM_VERDICTS)[number];
+/** The longest text value one field may carry. */
+export declare const FORM_VALUE_MAX_LENGTH = 10000;
+/** One submitted value: a string, a number, a boolean, or a list of strings (a multi-select). */
+export declare const formValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+export type FormValue = z.infer<typeof formValueSchema>;
+/** One field of a submission's payload. */
+export declare const submissionFieldSchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+}, z.core.$strict>;
+export type SubmissionField = z.infer<typeof submissionFieldSchema>;
+/** One uploaded file a submission claimed (EC-617's upload intent, checked against the stored file). */
+export declare const submissionFileSchema: z.ZodObject<{
+    field: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    storageId: z.ZodString;
+    contentType: z.ZodString;
+    size: z.ZodNumber;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SubmissionFile = z.infer<typeof submissionFileSchema>;
+/** One line of the delivery log: one recipient (or the whole request) in one attempt. */
+export declare const deliveryEntrySchema: z.ZodObject<{
+    at: z.ZodString;
+    attempt: z.ZodNumber;
+    to: z.ZodOptional<z.ZodString>;
+    ok: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    retryAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type DeliveryEntry = z.infer<typeof deliveryEntrySchema>;
+/** The most log lines a row keeps (the oldest are dropped first). */
+export declare const DELIVERY_LOG_LIMIT = 100;
+export declare const submissionRecordKind: import("@elytracms/core/persistence").RecordKind<{
+    /** The form's key — the ingest `target` the site posted to (see `defineFormSource`'s `key`). */
+    form: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<{
+        new: "new";
+        open: "open";
+        done: "done";
+        spam: "spam";
+    }>>;
+    assignee: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    payload: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+    }, z.core.$strict>>;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        storageId: z.ZodString;
+        contentType: z.ZodString;
+        size: z.ZodNumber;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    sourceUrl: z.ZodOptional<z.ZodString>;
+    spam: z.ZodEnum<{
+        clean: "clean";
+        honeypot: "honeypot";
+    }>;
+    deliveryState: z.ZodEnum<{
+        pending: "pending";
+        sent: "sent";
+        partial: "partial";
+        failed: "failed";
+        skipped: "skipped";
+    }>;
+    deliveryLog: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        attempt: z.ZodNumber;
+        to: z.ZodOptional<z.ZodString>;
+        ok: z.ZodBoolean;
+        error: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
+        retryAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    submittedAt: z.ZodString;
+}>;
+export type SubmissionRecord = RecordEntryOf<typeof submissionRecordKind>;
+/** The columns the EDITOR owns — the only ones the inbox ever writes. */
+export declare const SUBMISSION_EDITOR_COLUMNS: readonly ["status", "assignee", "notes"];
+export type SubmissionEditorColumn = (typeof SUBMISSION_EDITOR_COLUMNS)[number];

package/dist/shared/kind.js

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import { defineRecordKind } from '@elytracms/core/persistence';
+/**
+ * EC-613 — the SUBMISSION record kind: every form post a site receives, one row in the
+ * engine's record store (EC-616), declared ONCE here and read by all three planes — the
+ * Convex functions that store it (`@elytracms/forms/convex`), the studio inbox that lists
+ * and edits it (`@elytracms/forms/studio`) and the site helpers that send it
+ * (`@elytracms/forms/next`).
+ *
+ * Its functions live in the Convex module `forms` — the consumer's ONE re-export file is
+ * `convex/forms.ts`: `export * from '@elytracms/forms/convex'`.
+ *
+ * Who writes what:
+ * - the SITE (through the ingest receiver's handler, `forms:ingest`): `form`, `payload`,
+ *   `files`, `sourceUrl`, `spam`, `submittedAt` — what the visitor sent and what the checks
+ *   said. Never edited afterwards;
+ * - the EDITOR (through the inbox): `status`, `assignee`, `notes` — the inbox lifecycle (the
+ *   SMB CRM of the ruling; a sales pipeline is the developer's structure, not this kind);
+ * - the DELIVERY (the scheduled `forms:deliver` action): `deliveryState`, `deliveryLog`.
+ *
+ * The payload is a LIST of `{ name, value }` (sorted by name), not an object keyed by field
+ * name: a visitor's field names never become stored object keys. Its display order is the
+ * FORM's (`labelPayload` over the form source's `fields`). A value is a string, a number, a
+ * boolean or a list of strings, so the stored depth is bounded by construction.
+ */
+/** The editor's inbox lifecycle. */
+export const SUBMISSION_STATUSES = ['new', 'open', 'done', 'spam'];
+/** What a submission's delivery is doing — see `@elytracms/forms` `applyDeliveryOutcome`. */
+export const DELIVERY_STATES = ['pending', 'sent', 'partial', 'failed', 'skipped'];
+/** What the spam checks said: nothing, or the form's honeypot was filled. */
+export const SPAM_VERDICTS = ['clean', 'honeypot'];
+/** The longest text value one field may carry. */
+export const FORM_VALUE_MAX_LENGTH = 10_000;
+/** One submitted value: a string, a number, a boolean, or a list of strings (a multi-select). */
+export const formValueSchema = z.union([
+    z.string().max(FORM_VALUE_MAX_LENGTH),
+    z.number(),
+    z.boolean(),
+    z.array(z.string().max(FORM_VALUE_MAX_LENGTH)).max(50),
+]);
+/** One field of a submission's payload. */
+export const submissionFieldSchema = z.strictObject({
+    name: z.string().min(1).max(200),
+    value: formValueSchema,
+});
+/** One uploaded file a submission claimed (EC-617's upload intent, checked against the stored file). */
+export const submissionFileSchema = z.strictObject({
+    /** The form field it was uploaded for. */
+    field: z.string().min(1).max(200),
+    /** The file name the visitor's browser reported (display only). */
+    name: z.string().max(300).optional(),
+    storageId: z.string().min(1),
+    contentType: z.string().min(1),
+    size: z.number().int().nonnegative(),
+    /** The storage URL (`https://<deployment>.convex.cloud/api/storage/<id>`), unguessable, valid while the file exists. */
+    url: z.string().optional(),
+});
+/** One line of the delivery log: one recipient (or the whole request) in one attempt. */
+export const deliveryEntrySchema = z.strictObject({
+    at: z.string().min(1),
+    attempt: z.number().int().positive(),
+    /** The recipient — absent for an entry about the whole attempt (unreachable site, refused request). */
+    to: z.string().optional(),
+    ok: z.boolean(),
+    /** Why it failed (truncated). */
+    error: z.string().optional(),
+    /** A note on a non-failure without a recipient (`no recipients`). */
+    note: z.string().optional(),
+    /** The transport's message id, when it reported one. */
+    id: z.string().optional(),
+    /** When the next automatic attempt runs, if one is scheduled. */
+    retryAt: z.string().optional(),
+});
+/** The most log lines a row keeps (the oldest are dropped first). */
+export const DELIVERY_LOG_LIMIT = 100;
+export const submissionRecordKind = defineRecordKind({
+    kind: 'submission',
+    module: 'forms',
+    keys: ['form', 'status'],
+    time: 'submittedAt',
+    fields: {
+        /** The form's key — the ingest `target` the site posted to (see `defineFormSource`'s `key`). */
+        form: z.string().min(1).max(200),
+        status: z.enum(SUBMISSION_STATUSES).default('new'),
+        assignee: z.string().max(200).optional(),
+        notes: z.string().max(20_000).optional(),
+        payload: z.array(submissionFieldSchema).max(200),
+        files: z.array(submissionFileSchema).max(20).optional(),
+        sourceUrl: z.string().max(2000).optional(),
+        spam: z.enum(SPAM_VERDICTS),
+        deliveryState: z.enum(DELIVERY_STATES),
+        deliveryLog: z.array(deliveryEntrySchema).max(DELIVERY_LOG_LIMIT).optional(),
+        submittedAt: z.string().min(1),
+    },
+});
+/** The columns the EDITOR owns — the only ones the inbox ever writes. */
+export const SUBMISSION_EDITOR_COLUMNS = ['status', 'assignee', 'notes'];
+//# sourceMappingURL=kind.js.map

package/dist/shared/kind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind.js","sourceRoot":"","sources":["../../src/shared/kind.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod'\nimport { defineRecordKind } from '@elytracms/core/persistence'\nimport type { RecordEntryOf } from '@elytracms/core/persistence'\n\n/**\n * EC-613 — the SUBMISSION record kind: every form post a site receives, one row in the\n * engine's record store (EC-616), declared ONCE here and read by all three planes — the\n * Convex functions that store it (`@elytracms/forms/convex`), the studio inbox that lists\n * and edits it (`@elytracms/forms/studio`) and the site helpers that send it\n * (`@elytracms/forms/next`).\n *\n * Its functions live in the Convex module `forms` — the consumer's ONE re-export file is\n * `convex/forms.ts`: `export * from '@elytracms/forms/convex'`.\n *\n * Who writes what:\n * - the SITE (through the ingest receiver's handler, `forms:ingest`): `form`, `payload`,\n *   `files`, `sourceUrl`, `spam`, `submittedAt` — what the visitor sent and what the checks\n *   said. Never edited afterwards;\n * - the EDITOR (through the inbox): `status`, `assignee`, `notes` — the inbox lifecycle (the\n *   SMB CRM of the ruling; a sales pipeline is the developer's structure, not this kind);\n * - the DELIVERY (the scheduled `forms:deliver` action): `deliveryState`, `deliveryLog`.\n *\n * The payload is a LIST of `{ name, value }` (sorted by name), not an object keyed by field\n * name: a visitor's field names never become stored object keys. Its display order is the\n * FORM's (`labelPayload` over the form source's `fields`). A value is a string, a number, a\n * boolean or a list of strings, so the stored depth is bounded by construction.\n */\n\n/** The editor's inbox lifecycle. */\nexport const SUBMISSION_STATUSES = ['new', 'open', 'done', 'spam'] as const\nexport type SubmissionStatus = (typeof SUBMISSION_STATUSES)[number]\n\n/** What a submission's delivery is doing — see `@elytracms/forms` `applyDeliveryOutcome`. */\nexport const DELIVERY_STATES = ['pending', 'sent', 'partial', 'failed', 'skipped'] as const\nexport type DeliveryState = (typeof DELIVERY_STATES)[number]\n\n/** What the spam checks said: nothing, or the form's honeypot was filled. */\nexport const SPAM_VERDICTS = ['clean', 'honeypot'] as const\nexport type SpamVerdict = (typeof SPAM_VERDICTS)[number]\n\n/** The longest text value one field may carry. */\nexport const FORM_VALUE_MAX_LENGTH = 10_000\n\n/** One submitted value: a string, a number, a boolean, or a list of strings (a multi-select). */\nexport const formValueSchema = z.union([\n  z.string().max(FORM_VALUE_MAX_LENGTH),\n  z.number(),\n  z.boolean(),\n  z.array(z.string().max(FORM_VALUE_MAX_LENGTH)).max(50),\n])\nexport type FormValue = z.infer<typeof formValueSchema>\n\n/** One field of a submission's payload. */\nexport const submissionFieldSchema = z.strictObject({\n  name: z.string().min(1).max(200),\n  value: formValueSchema,\n})\nexport type SubmissionField = z.infer<typeof submissionFieldSchema>\n\n/** One uploaded file a submission claimed (EC-617's upload intent, checked against the stored file). */\nexport const submissionFileSchema = z.strictObject({\n  /** The form field it was uploaded for. */\n  field: z.string().min(1).max(200),\n  /** The file name the visitor's browser reported (display only). */\n  name: z.string().max(300).optional(),\n  storageId: z.string().min(1),\n  contentType: z.string().min(1),\n  size: z.number().int().nonnegative(),\n  /** The storage URL (`https://<deployment>.convex.cloud/api/storage/<id>`), unguessable, valid while the file exists. */\n  url: z.string().optional(),\n})\nexport type SubmissionFile = z.infer<typeof submissionFileSchema>\n\n/** One line of the delivery log: one recipient (or the whole request) in one attempt. */\nexport const deliveryEntrySchema = z.strictObject({\n  at: z.string().min(1),\n  attempt: z.number().int().positive(),\n  /** The recipient — absent for an entry about the whole attempt (unreachable site, refused request). */\n  to: z.string().optional(),\n  ok: z.boolean(),\n  /** Why it failed (truncated). */\n  error: z.string().optional(),\n  /** A note on a non-failure without a recipient (`no recipients`). */\n  note: z.string().optional(),\n  /** The transport's message id, when it reported one. */\n  id: z.string().optional(),\n  /** When the next automatic attempt runs, if one is scheduled. */\n  retryAt: z.string().optional(),\n})\nexport type DeliveryEntry = z.infer<typeof deliveryEntrySchema>\n\n/** The most log lines a row keeps (the oldest are dropped first). */\nexport const DELIVERY_LOG_LIMIT = 100\n\nexport const submissionRecordKind = defineRecordKind({\n  kind: 'submission',\n  module: 'forms',\n  keys: ['form', 'status'],\n  time: 'submittedAt',\n  fields: {\n    /** The form's key — the ingest `target` the site posted to (see `defineFormSource`'s `key`). */\n    form: z.string().min(1).max(200),\n    status: z.enum(SUBMISSION_STATUSES).default('new'),\n    assignee: z.string().max(200).optional(),\n    notes: z.string().max(20_000).optional(),\n    payload: z.array(submissionFieldSchema).max(200),\n    files: z.array(submissionFileSchema).max(20).optional(),\n    sourceUrl: z.string().max(2000).optional(),\n    spam: z.enum(SPAM_VERDICTS),\n    deliveryState: z.enum(DELIVERY_STATES),\n    deliveryLog: z.array(deliveryEntrySchema).max(DELIVERY_LOG_LIMIT).optional(),\n    submittedAt: z.string().min(1),\n  },\n})\n\nexport type SubmissionRecord = RecordEntryOf<typeof submissionRecordKind>\n\n/** The columns the EDITOR owns — the only ones the inbox ever writes. */\nexport const SUBMISSION_EDITOR_COLUMNS = ['status', 'assignee', 'notes'] as const\nexport type SubmissionEditorColumn = (typeof SUBMISSION_EDITOR_COLUMNS)[number]\n"]}

package/dist/shared/mail.d.ts

@@ -0,0 +1,35 @@
+import type { LocalizedString } from '@elytracms/core/cms-core';
+import type { FormFieldLabel } from './source.js';
+import type { SubmissionField } from './kind.js';
+/**
+ * EC-613 — a submission LABELLED by its form (pure): the studio inbox shows it, the site's
+ * delivery route writes it into the mail. A payload field the form does not (or no longer)
+ * declares keeps its submitted name — what the visitor sent is never hidden.
+ */
+/** One payload line with the label an editor reads. */
+export interface LabelledField {
+    name: string;
+    label: LocalizedString;
+    value: SubmissionField['value'];
+}
+/**
+ * The payload in the FORM's order (its declared fields first, as declared), then any field
+ * the form does not declare, in submitted order.
+ */
+export declare function labelPayload(payload: readonly SubmissionField[], fields?: readonly FormFieldLabel[]): LabelledField[];
+/** A label as plain text for a mail (a localized label in `locale`, else its first entry). */
+export declare function plainLabel(label: LocalizedString, locale?: string): string;
+/** The plain-text mail body of a submission. */
+export declare function submissionMailText(input: {
+    formTitle?: string;
+    fields: readonly LabelledField[];
+    files: readonly {
+        field: string;
+        name?: string;
+        url: string;
+        size: number;
+    }[];
+    sourceUrl?: string;
+    submittedAt: string;
+    locale?: string;
+}): string;

package/dist/shared/mail.js

@@ -0,0 +1,47 @@
+import { formatFormValue } from './submission.js';
+/**
+ * The payload in the FORM's order (its declared fields first, as declared), then any field
+ * the form does not declare, in submitted order.
+ */
+export function labelPayload(payload, fields = []) {
+    const byName = new Map(payload.map((field) => [field.name, field]));
+    const out = [];
+    const used = new Set();
+    for (const declared of fields) {
+        const field = byName.get(declared.name);
+        if (!field || used.has(declared.name))
+            continue;
+        used.add(declared.name);
+        out.push({ name: field.name, label: declared.label ?? field.name, value: field.value });
+    }
+    for (const field of payload) {
+        if (used.has(field.name))
+            continue;
+        used.add(field.name);
+        out.push({ name: field.name, label: field.name, value: field.value });
+    }
+    return out;
+}
+/** A label as plain text for a mail (a localized label in `locale`, else its first entry). */
+export function plainLabel(label, locale) {
+    if (typeof label === 'string')
+        return label;
+    return (locale ? label[locale] : undefined) ?? Object.values(label)[0] ?? '';
+}
+/** The plain-text mail body of a submission. */
+export function submissionMailText(input) {
+    const lines = [];
+    for (const field of input.fields)
+        lines.push(`${plainLabel(field.label, input.locale)}: ${formatFormValue(field.value)}`);
+    if (input.files.length > 0) {
+        lines.push('', 'Files:');
+        for (const file of input.files) {
+            lines.push(`- ${file.name ?? file.field} (${Math.max(1, Math.round(file.size / 1024))} KB): ${file.url}`);
+        }
+    }
+    lines.push('', `Submitted: ${input.submittedAt}`);
+    if (input.sourceUrl)
+        lines.push(`Page: ${input.sourceUrl}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=mail.js.map

package/dist/shared/mail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail.js","sourceRoot":"","sources":["../../src/shared/mail.ts"],"names":[],"mappings":"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","sourcesContent":["import type { LocalizedString } from '@elytracms/core/cms-core'\nimport type { FormFieldLabel } from './source'\nimport type { SubmissionField } from './kind'\nimport { formatFormValue } from './submission'\n\n/**\n * EC-613 — a submission LABELLED by its form (pure): the studio inbox shows it, the site's\n * delivery route writes it into the mail. A payload field the form does not (or no longer)\n * declares keeps its submitted name — what the visitor sent is never hidden.\n */\n\n/** One payload line with the label an editor reads. */\nexport interface LabelledField {\n  name: string\n  label: LocalizedString\n  value: SubmissionField['value']\n}\n\n/**\n * The payload in the FORM's order (its declared fields first, as declared), then any field\n * the form does not declare, in submitted order.\n */\nexport function labelPayload(payload: readonly SubmissionField[], fields: readonly FormFieldLabel[] = []): LabelledField[] {\n  const byName = new Map(payload.map((field) => [field.name, field]))\n  const out: LabelledField[] = []\n  const used = new Set<string>()\n  for (const declared of fields) {\n    const field = byName.get(declared.name)\n    if (!field || used.has(declared.name)) continue\n    used.add(declared.name)\n    out.push({ name: field.name, label: declared.label ?? field.name, value: field.value })\n  }\n  for (const field of payload) {\n    if (used.has(field.name)) continue\n    used.add(field.name)\n    out.push({ name: field.name, label: field.name, value: field.value })\n  }\n  return out\n}\n\n/** A label as plain text for a mail (a localized label in `locale`, else its first entry). */\nexport function plainLabel(label: LocalizedString, locale?: string): string {\n  if (typeof label === 'string') return label\n  return (locale ? label[locale] : undefined) ?? Object.values(label)[0] ?? ''\n}\n\n/** The plain-text mail body of a submission. */\nexport function submissionMailText(input: {\n  formTitle?: string\n  fields: readonly LabelledField[]\n  files: readonly { field: string; name?: string; url: string; size: number }[]\n  sourceUrl?: string\n  submittedAt: string\n  locale?: string\n}): string {\n  const lines: string[] = []\n  for (const field of input.fields) lines.push(`${plainLabel(field.label, input.locale)}: ${formatFormValue(field.value)}`)\n  if (input.files.length > 0) {\n    lines.push('', 'Files:')\n    for (const file of input.files) {\n      lines.push(`- ${file.name ?? file.field} (${Math.max(1, Math.round(file.size / 1024))} KB): ${file.url}`)\n    }\n  }\n  lines.push('', `Submitted: ${input.submittedAt}`)\n  if (input.sourceUrl) lines.push(`Page: ${input.sourceUrl}`)\n  return lines.join('\\n')\n}\n"]}

package/dist/shared/source.d.ts

@@ -0,0 +1,70 @@
+import type { LocalizedString } from '@elytracms/core/cms-core';
+import type { SubmissionField } from './kind.js';
+/**
+ * EC-613 — the FORM SOURCE: how the addon reads the consumer's own form documents, declared
+ * ONCE by the consumer and read by the two planes that know the project — the studio inbox
+ * (a submission's field labels, the form's title) and the site's delivery route (the
+ * recipients, the labels in the mail). Convex never reads it: the deployment stays
+ * data-only (EC-585 1e), and the recipients are resolved from the PUBLISHED form document on
+ * the site — never from anything a visitor sent (a recipient from the payload would make the
+ * site an open mail relay).
+ *
+ * The form collection, its field types and the renderer stay the consumer's (the ruling):
+ * this declaration only says where in a form document the addon finds what it needs.
+ *
+ * ```ts
+ * // cms/forms.ts — anywhere; the studio config and the site's delivery route import it
+ * export const contactForms = defineFormSource({
+ *   collection: 'form',
+ *   key: 'internalId', // the site posts this value as the submission's target
+ *   title: (form) => form.title,
+ *   recipients: (form) => [form.recipient],
+ *   fields: (form) => form.fields.map((field) => ({ name: field.name, label: field.label })),
+ * })
+ * ```
+ */
+/** One field of a form, as the addon labels a submission's payload with it. */
+export interface FormFieldLabel {
+    /** The submitted name (the input's `name`). */
+    name: string;
+    /** What an editor reads instead of the name; a plain string or `{ en, de, … }`. */
+    label?: LocalizedString;
+}
+/** A form document as the addon sees it: its id and its values (the consumer's shape). */
+export interface FormDocument<V = Record<string, unknown>> {
+    id: string;
+    values: V;
+}
+export interface FormSourceConfig<V = Record<string, unknown>> {
+    /** The collection that holds the forms. */
+    collection: string;
+    /**
+     * How a site addresses a form — the submission's `target` and the row's `form` column: the
+     * name of a text field of the form document (`'internalId'`), or a function. Default: the
+     * document's id.
+     */
+    key?: string | ((form: FormDocument<V>) => string | undefined);
+    /** The form's display title (the inbox column, the mail subject). */
+    title?: (values: V) => string | undefined;
+    /** Who receives a submission's mail. An empty list delivers nothing (an inbox-only form). */
+    recipients: (values: V) => readonly (string | undefined | null)[];
+    /** The form's fields, in order, for labelling a payload. Absent → the submitted names. */
+    fields?: (values: V) => readonly FormFieldLabel[];
+    /** The address a reply goes to (default: the first payload value of a field named like `email`). */
+    replyTo?: (payload: readonly SubmissionField[]) => string | undefined;
+}
+/** A declared form source (see the module header). */
+export interface FormSource<V = Record<string, unknown>> extends FormSourceConfig<V> {
+    /** The key of one form document — `key` applied, else its id. */
+    keyOf(form: FormDocument<V>): string | undefined;
+    /** The form among `forms` a submission's `form` column names. */
+    find(forms: readonly FormDocument<V>[], key: string): FormDocument<V> | undefined;
+    /** The recipients of one form: trimmed, valid addresses only, each once. */
+    recipientsOf(form: FormDocument<V>): string[];
+}
+/** Is this a deliverable address (the same shape both consumers' routes check)? */
+export declare function isEmailAddress(value: unknown): value is string;
+/** Declare how the addon reads your form documents (see the module header). */
+export declare function defineFormSource<V = Record<string, unknown>>(config: FormSourceConfig<V>): FormSource<V>;
+/** The default reply-to: the first payload value of a field named like `email`, if it is an address. */
+export declare function defaultReplyTo(payload: readonly SubmissionField[]): string | undefined;

package/dist/shared/source.js

@@ -0,0 +1,40 @@
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/** Is this a deliverable address (the same shape both consumers' routes check)? */
+export function isEmailAddress(value) {
+    return typeof value === 'string' && EMAIL.test(value.trim());
+}
+/** Declare how the addon reads your form documents (see the module header). */
+export function defineFormSource(config) {
+    if (!config.collection)
+        throw new Error('defineFormSource: `collection` is required.');
+    const keyOf = (form) => {
+        if (config.key === undefined)
+            return form.id;
+        if (typeof config.key === 'function')
+            return config.key(form);
+        const value = form.values[config.key];
+        return typeof value === 'string' && value.length > 0 ? value : undefined;
+    };
+    return {
+        ...config,
+        keyOf,
+        find: (forms, key) => forms.find((form) => keyOf(form) === key),
+        recipientsOf: (form) => {
+            const seen = new Set();
+            for (const entry of config.recipients(form.values)) {
+                if (isEmailAddress(entry))
+                    seen.add(entry.trim());
+            }
+            return [...seen];
+        },
+    };
+}
+/** The default reply-to: the first payload value of a field named like `email`, if it is an address. */
+export function defaultReplyTo(payload) {
+    for (const field of payload) {
+        if (/e-?mail/i.test(field.name) && isEmailAddress(field.value))
+            return field.value.trim();
+    }
+    return undefined;
+}
+//# sourceMappingURL=source.js.map

package/dist/shared/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/shared/source.ts"],"names":[],"mappings":"AAsEA,MAAM,KAAK,GAAG,4BAA4B,CAAA;AAE1C,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;AAC9D,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAA8B,MAA2B;IACvF,IAAI,CAAC,MAAM,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IACtF,MAAM,KAAK,GAAG,CAAC,IAAqB,EAAsB,EAAE;QAC1D,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,EAAE,CAAA;QAC5C,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,UAAU;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC7D,MAAM,KAAK,GAAI,IAAI,CAAC,MAAkC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAClE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1E,CAAC,CAAA;IACD,OAAO;QACL,GAAG,MAAM;QACT,KAAK;QACL,IAAI,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC;QAC/D,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE;YACrB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;YAC9B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACnD,IAAI,cAAc,CAAC,KAAK,CAAC;oBAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;YACnD,CAAC;YACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;QAClB,CAAC;KACF,CAAA;AACH,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,cAAc,CAAC,OAAmC;IAChE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,OAAQ,KAAK,CAAC,KAAgB,CAAC,IAAI,EAAE,CAAA;IACvG,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC","sourcesContent":["import type { LocalizedString } from '@elytracms/core/cms-core'\nimport type { SubmissionField } from './kind'\n\n/**\n * EC-613 — the FORM SOURCE: how the addon reads the consumer's own form documents, declared\n * ONCE by the consumer and read by the two planes that know the project — the studio inbox\n * (a submission's field labels, the form's title) and the site's delivery route (the\n * recipients, the labels in the mail). Convex never reads it: the deployment stays\n * data-only (EC-585 1e), and the recipients are resolved from the PUBLISHED form document on\n * the site — never from anything a visitor sent (a recipient from the payload would make the\n * site an open mail relay).\n *\n * The form collection, its field types and the renderer stay the consumer's (the ruling):\n * this declaration only says where in a form document the addon finds what it needs.\n *\n * ```ts\n * // cms/forms.ts — anywhere; the studio config and the site's delivery route import it\n * export const contactForms = defineFormSource({\n *   collection: 'form',\n *   key: 'internalId', // the site posts this value as the submission's target\n *   title: (form) => form.title,\n *   recipients: (form) => [form.recipient],\n *   fields: (form) => form.fields.map((field) => ({ name: field.name, label: field.label })),\n * })\n * ```\n */\n\n/** One field of a form, as the addon labels a submission's payload with it. */\nexport interface FormFieldLabel {\n  /** The submitted name (the input's `name`). */\n  name: string\n  /** What an editor reads instead of the name; a plain string or `{ en, de, … }`. */\n  label?: LocalizedString\n}\n\n/** A form document as the addon sees it: its id and its values (the consumer's shape). */\nexport interface FormDocument<V = Record<string, unknown>> {\n  id: string\n  values: V\n}\n\nexport interface FormSourceConfig<V = Record<string, unknown>> {\n  /** The collection that holds the forms. */\n  collection: string\n  /**\n   * How a site addresses a form — the submission's `target` and the row's `form` column: the\n   * name of a text field of the form document (`'internalId'`), or a function. Default: the\n   * document's id.\n   */\n  key?: string | ((form: FormDocument<V>) => string | undefined)\n  /** The form's display title (the inbox column, the mail subject). */\n  title?: (values: V) => string | undefined\n  /** Who receives a submission's mail. An empty list delivers nothing (an inbox-only form). */\n  recipients: (values: V) => readonly (string | undefined | null)[]\n  /** The form's fields, in order, for labelling a payload. Absent → the submitted names. */\n  fields?: (values: V) => readonly FormFieldLabel[]\n  /** The address a reply goes to (default: the first payload value of a field named like `email`). */\n  replyTo?: (payload: readonly SubmissionField[]) => string | undefined\n}\n\n/** A declared form source (see the module header). */\nexport interface FormSource<V = Record<string, unknown>> extends FormSourceConfig<V> {\n  /** The key of one form document — `key` applied, else its id. */\n  keyOf(form: FormDocument<V>): string | undefined\n  /** The form among `forms` a submission's `form` column names. */\n  find(forms: readonly FormDocument<V>[], key: string): FormDocument<V> | undefined\n  /** The recipients of one form: trimmed, valid addresses only, each once. */\n  recipientsOf(form: FormDocument<V>): string[]\n}\n\nconst EMAIL = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/\n\n/** Is this a deliverable address (the same shape both consumers' routes check)? */\nexport function isEmailAddress(value: unknown): value is string {\n  return typeof value === 'string' && EMAIL.test(value.trim())\n}\n\n/** Declare how the addon reads your form documents (see the module header). */\nexport function defineFormSource<V = Record<string, unknown>>(config: FormSourceConfig<V>): FormSource<V> {\n  if (!config.collection) throw new Error('defineFormSource: `collection` is required.')\n  const keyOf = (form: FormDocument<V>): string | undefined => {\n    if (config.key === undefined) return form.id\n    if (typeof config.key === 'function') return config.key(form)\n    const value = (form.values as Record<string, unknown>)[config.key]\n    return typeof value === 'string' && value.length > 0 ? value : undefined\n  }\n  return {\n    ...config,\n    keyOf,\n    find: (forms, key) => forms.find((form) => keyOf(form) === key),\n    recipientsOf: (form) => {\n      const seen = new Set<string>()\n      for (const entry of config.recipients(form.values)) {\n        if (isEmailAddress(entry)) seen.add(entry.trim())\n      }\n      return [...seen]\n    },\n  }\n}\n\n/** The default reply-to: the first payload value of a field named like `email`, if it is an address. */\nexport function defaultReplyTo(payload: readonly SubmissionField[]): string | undefined {\n  for (const field of payload) {\n    if (/e-?mail/i.test(field.name) && isEmailAddress(field.value)) return (field.value as string).trim()\n  }\n  return undefined\n}\n"]}

package/dist/shared/submission.d.ts

@@ -0,0 +1,83 @@
+import type { IngestPayload } from '@elytracms/core/ingest';
+import type { FormValue, SpamVerdict, SubmissionField } from './kind.js';
+/**
+ * EC-613 — the FORMS WIRE inside the ingest envelope (EC-617): what a site's `submission`
+ * payload carries for this addon, and the ONE reader the receiver's handler turns it into a
+ * row with. Pure (no Convex), so the rules are unit-tested on their own.
+ *
+ * `data` holds the form's fields by name, plus RESERVED keys the addon's site helpers fill,
+ * in the `elytra:` namespace:
+ *
+ * - `elytra:source` — the page the form was submitted from (the row's `sourceUrl`);
+ * - `elytra:honeypot` — the value of the form's honeypot field (a real visitor leaves it empty).
+ *
+ * Any other `elytra:` key is refused — never silently dropped. Empty values (`''`, `[]`) are
+ * not answers and are not stored; a submission with no answer and no file is refused.
+ *
+ * A field NAME follows ONE rule ({@link formFieldNameProblem}): the ingest envelope's — a name
+ * Convex can store (`convexFieldNameProblem`, `@elytracms/core/ingest`: printable ASCII, no
+ * leading `$`, at most 1024 characters; the route and the receiver refuse anything else with
+ * 400) — plus the forms addon's own cap of 200 characters (the stored payload's `name`). The
+ * site helpers refuse a name before sending, with the same reason the envelope would give.
+ */
+/** The reserved namespace of the forms wire. */
+export declare const FORMS_RESERVED_PREFIX = "elytra:";
+/** The page a submission came from. */
+export declare const FORMS_SOURCE_KEY = "elytra:source";
+/** The honeypot's value. */
+export declare const FORMS_HONEYPOT_KEY = "elytra:honeypot";
+/**
+ * The hidden input a native (no-JS) form post names its form with — read by the `./next`
+ * form-post route, never sent on: it becomes the ingest payload's `target`.
+ */
+export declare const FORMS_TARGET_FIELD = "elytra:form";
+/** The forms addon's own cap on a field name (the stored payload's `name`) — below Convex's 1024. */
+export declare const FORM_FIELD_NAME_MAX = 200;
+/**
+ * Why a form field may not be named `name`, or `undefined` when it may: the ingest envelope's
+ * rule first (`convexFieldNameProblem` — the ONE rule, read, never restated), then the forms
+ * addon's own limits (not empty, at most {@link FORM_FIELD_NAME_MAX} characters). Phrased to
+ * follow `The field name “<name>” …`, exactly as the envelope's 400 issue reads.
+ */
+export declare function formFieldNameProblem(name: string): string | undefined;
+/** The issue message for a refused field name — the envelope's wording (`@elytracms/core/ingest`). */
+export declare function formFieldNameMessage(name: string, problem: string): string;
+/** The honeypot field both consumers' forms already render (overridable in the site helpers). */
+export declare const DEFAULT_HONEYPOT_FIELD = "website";
+/**
+ * The file types a form upload may have — documents and raster images. Anything that a
+ * browser would run when opened from the deployment's storage URL (HTML, SVG, scripts) is
+ * refused by the receiver's handler (415), and so is every type not listed.
+ */
+export declare const FORMS_UPLOAD_CONTENT_TYPES: readonly string[];
+/** What a site's submission becomes in the row (the visitor's part — see the kind's header). */
+export interface SubmissionColumns {
+    form: string;
+    payload: SubmissionField[];
+    sourceUrl?: string;
+    spam: SpamVerdict;
+}
+export type SubmissionRead = {
+    ok: true;
+    columns: SubmissionColumns;
+} | {
+    ok: false;
+    status: 422;
+    message: string;
+    issues: {
+        path: (string | number)[];
+        message: string;
+    }[];
+};
+/**
+ * Read a `submission` payload into the row's visitor columns (fields sorted by name). Refuses (422, with the issues)
+ * a value that is not a form value, an unknown reserved key, an over-long source URL, and a
+ * submission with no answer — unless it carries files (`hasFiles`).
+ */
+export declare function readSubmissionPayload(payload: Extract<IngestPayload, {
+    kind: 'submission';
+}>, options?: {
+    hasFiles?: boolean;
+}): SubmissionRead;
+/** The display text of one value (a list joined by commas, a boolean as yes/no). */
+export declare function formatFormValue(value: FormValue): string;