@cogenta/forms 0.2.4

package/dist/rows.js

@@ -0,0 +1,72 @@
+import { CogentaError } from '@cogenta/core';
+/**
+ * Reading rows back out of three databases that disagree about them — the
+ * same trouble `@cogenta/commerce`'s `rows.ts` documents, restated here
+ * because this package owns its own tables and does not depend on commerce.
+ */
+export function toText(value, what) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'bigint')
+        return String(value);
+    throw new CogentaError({
+        code: 'INTERNAL',
+        message: `The stored value of ${what} is not text.`,
+        hint: 'This row was not written by this package.',
+        details: { column: what, type: typeof value },
+    });
+}
+export function toNullableText(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    if (typeof value === 'string')
+        return value;
+    return String(value);
+}
+export function toInt(value, what) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return Math.trunc(value);
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return Math.trunc(parsed);
+    }
+    throw new CogentaError({
+        code: 'INTERNAL',
+        message: `The stored value of ${what} is not a usable integer.`,
+        hint: 'This row was not written by this package, or the column type was changed by hand.',
+        details: { column: what, type: typeof value },
+    });
+}
+export function toBool(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value !== 0;
+    if (typeof value === 'bigint')
+        return value !== 0n;
+    if (typeof value === 'string')
+        return value !== '' && value !== '0' && value !== 'false';
+    return false;
+}
+/** Postgres wants a real boolean; MySQL/SQLite want 0/1. */
+export function fromBool(value, dialect) {
+    return dialect === 'postgres' ? value : value ? 1 : 0;
+}
+export function toJson(value, what) {
+    const text = toText(value, what);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CogentaError({
+            code: 'INTERNAL',
+            message: `The stored value of ${what} is not valid JSON.`,
+            hint: 'This row was not written by this package.',
+            details: { column: what },
+        });
+    }
+}
+//# sourceMappingURL=rows.js.map

package/dist/rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.js","sourceRoot":"","sources":["../src/rows.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5C;;;;GAIG;AAEH,MAAM,UAAU,MAAM,CAAC,KAAc,EAAE,IAAY;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;IAChF,MAAM,IAAI,YAAY,CAAC;QACrB,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,uBAAuB,IAAI,eAAe;QACnD,IAAI,EAAE,2CAA2C;QACjD,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,KAAK,EAAE;KAC9C,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAA;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC3C,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;AACtB,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,KAAc,EAAE,IAAY;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IACjF,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QAC5B,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IACxD,CAAC;IACD,MAAM,IAAI,YAAY,CAAC;QACrB,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,uBAAuB,IAAI,2BAA2B;QAC/D,IAAI,EAAE,mFAAmF;QACzF,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,KAAK,EAAE;KAC9C,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,KAAK,CAAC,CAAA;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,KAAK,EAAE,CAAA;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,KAAK,EAAE,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,OAAO,CAAA;IACxF,OAAO,KAAK,CAAA;AACd,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,QAAQ,CAAC,KAAc,EAAE,OAAe;IACtD,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AACvD,CAAC;AAED,MAAM,UAAU,MAAM,CAAI,KAAc,EAAE,IAAY;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IAChC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,YAAY,CAAC;YACrB,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,uBAAuB,IAAI,qBAAqB;YACzD,IAAI,EAAE,2CAA2C;YACjD,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE;SAC1B,CAAC,CAAA;IACJ,CAAC;AACH,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,71 @@
+import { type DatabaseHandle } from '@cogenta/core';
+import type { CreateFormDefinitionInput, FormDefinition, FormSubmission, FormSubmissionNote, FormSubmissionStatus, UpdateFormDefinitionInput } from './types.js';
+export interface SubmitOptions {
+    readonly ip?: string | null;
+    readonly referrer?: string | null;
+    readonly userAgent?: string | null;
+}
+export interface ListSubmissionsOptions {
+    readonly formId?: string;
+    readonly status?: FormSubmissionStatus;
+    readonly limit?: number;
+    readonly cursor?: string;
+    /** Task 7 — an ISO instant; only submissions at or after it. Applied in SQL, same as `cursor`. */
+    readonly from?: string;
+    /** Task 7 — an ISO instant; only submissions at or before it. */
+    readonly to?: string;
+    /**
+     * Task 7 — free text, matched case-insensitively against a submission's
+     * own field values and consent text. Applied in application code after the
+     * SQL filters above narrow the scan (see `MAX_QUERY_SCAN_ROWS`'s own
+     * comment) — the honest cost of a form whose values are free-form JSON
+     * with no dialect-portable full-text index.
+     */
+    readonly query?: string;
+}
+export interface ListSubmissionsResult {
+    readonly items: readonly FormSubmission[];
+    readonly nextCursor: string | null;
+}
+export interface PurgeReport {
+    readonly purged: number;
+}
+export interface FormDefinitionStore {
+    create(input: CreateFormDefinitionInput): Promise<FormDefinition>;
+    read(id: string): Promise<FormDefinition | null>;
+    readByName(name: string): Promise<FormDefinition | null>;
+    list(): Promise<readonly FormDefinition[]>;
+    update(id: string, input: UpdateFormDefinitionInput): Promise<FormDefinition>;
+    remove(id: string): Promise<void>;
+    /** Task 11 — a real, independent copy: its own id, an available name derived from the original's, inactive by default so a duplicate never starts silently accepting submissions, and no submissions carried over. */
+    duplicate(id: string): Promise<FormDefinition>;
+}
+export interface FormSubmissionStore {
+    /** Full server-side validation happens here — `validateSubmission` — never trusting whatever the client already checked. */
+    submit(formName: string, rawValues: Readonly<Record<string, unknown>>, options?: SubmitOptions): Promise<FormSubmission>;
+    read(id: string): Promise<FormSubmission | null>;
+    list(options?: ListSubmissionsOptions): Promise<ListSubmissionsResult>;
+    markStatus(id: string, status: FormSubmissionStatus): Promise<FormSubmission>;
+    bulkMarkStatus(ids: readonly string[], status: FormSubmissionStatus): Promise<number>;
+    remove(id: string): Promise<void>;
+    bulkRemove(ids: readonly string[]): Promise<number>;
+    unreadCount(): Promise<number>;
+    /** GDPR task 7's minimum: an e-mail-based search across submissions, for export/deletion requests. */
+    searchByEmail(email: string): Promise<readonly FormSubmission[]>;
+    /** GDPR erasure: every submission naming this e-mail address, gone. */
+    deleteByEmail(email: string): Promise<number>;
+    /** Removes submissions older than each form's own `retainDays` (ADR-0022's `purgeExpired` model, applied to submissions rather than content). */
+    purgeExpired(): Promise<PurgeReport>;
+    /** Task 8 — an operator's own note. Never shown to the visitor, never included in a CSV export. */
+    addNote(submissionId: string, body: string, author: {
+        id: string | null;
+        label: string;
+    }): Promise<FormSubmissionNote>;
+    listNotes(submissionId: string): Promise<readonly FormSubmissionNote[]>;
+}
+export interface FormStore {
+    readonly definitions: FormDefinitionStore;
+    readonly submissions: FormSubmissionStore;
+}
+export declare function createFormStore(db: DatabaseHandle, now?: () => number): FormStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAMpB,MAAM,eAAe,CAAA;AAGtB,OAAO,KAAK,EAEV,yBAAyB,EAEzB,cAAc,EAKd,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EAEpB,yBAAyB,EAC1B,MAAM,YAAY,CAAA;AAmKnB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAA;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,kGAAkG;IAClG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAA;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IACjE,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAA;IAChD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAA;IACxD,IAAI,IAAI,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAAA;IAC1C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC7E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,sNAAsN;IACtN,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,mBAAmB;IAClC,4HAA4H;IAC5H,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC5C,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,cAAc,CAAC,CAAA;IAC1B,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAA;IAChD,IAAI,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAA;IACtE,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC7E,cAAc,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACrF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,UAAU,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnD,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAC9B,sGAAsG;IACtG,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAAA;IAChE,uEAAuE;IACvE,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC7C,iJAAiJ;IACjJ,YAAY,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IACpC,mGAAmG;IACnG,OAAO,CACL,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAC9B,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAAA;CACxE;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAA;IACzC,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAA;CAC1C;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,GAAE,MAAM,MAAiB,GAAG,SAAS,CAmc3F"}

package/dist/store.js

@@ -0,0 +1,509 @@
+import { CogentaError, identifier, newId, sql, unsafeRaw, } from '@cogenta/core';
+import { fromBool, toBool, toInt, toJson, toNullableText, toText } from './rows.js';
+import { TABLES } from './tables.js';
+import { emailValueOf, FORM_FIELD_KINDS } from './types.js';
+import { validateCaptchaConfig, validateDefinitionFields, validateFormSteps, validateNotifyChannels, validateSubmission, } from './validate.js';
+// Reserved: `forms-router.ts` mounts submission management under
+// `/api/forms/submissions/*`, so a form literally named "submissions" would
+// make `GET /api/forms/submissions` ambiguous between "the definition named
+// submissions" and "every submission across every form".
+const RESERVED_NAMES = new Set(['submissions']);
+const DEFAULT_RETAIN_DAYS = 180;
+const DEFAULT_CONFIRMATION = 'Thank you — your message has been received.';
+const DEFAULT_AUTORESPONDER = { enabled: false };
+const DEFAULT_CAPTCHA = { enabled: false };
+const SUBMISSION_STATUSES = ['new', 'read', 'archived', 'spam'];
+const DAY_MS = 24 * 60 * 60 * 1000;
+// Fiche 47 task 7: a text search across `values_json`/`consents_json` is a
+// full application-side scan (the same honest tradeoff `searchByEmail`
+// already makes) rather than a dialect-specific `LIKE`, whose case
+// sensitivity differs across SQLite/Postgres/MySQL. Bounded so an
+// operator-triggered search on a very large form cannot become an unbounded
+// read — this route is never a hot path.
+const MAX_QUERY_SCAN_ROWS = 5_000;
+function slugName(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '-')
+        .replace(/^-+|-+$/gu, '');
+}
+function toJsonOrDefault(value, what, fallback) {
+    if (value === null || value === undefined || value === '')
+        return fallback;
+    return toJson(value, what);
+}
+function decodeDefinition(row) {
+    return {
+        id: toText(row.id, 'form.id'),
+        name: toText(row.name, 'form.name'),
+        label: toText(row.label, 'form.label'),
+        fields: toJson(row.fields, 'form.fields'),
+        active: toBool(row.active),
+        confirmationMessage: toText(row.confirmation_message, 'form.confirmation_message'),
+        redirectTo: toNullableText(row.redirect_to),
+        notifyEmails: toJson(row.notify_emails, 'form.notify_emails'),
+        autoresponder: toJson(row.autoresponder, 'form.autoresponder'),
+        retainDays: toInt(row.retain_days, 'form.retain_days'),
+        steps: toJsonOrDefault(row.steps, 'form.steps', []),
+        notifyChannels: toJsonOrDefault(row.notify_channels, 'form.notify_channels', []),
+        captcha: toJsonOrDefault(row.captcha, 'form.captcha', DEFAULT_CAPTCHA),
+        createdAt: toText(row.created_at, 'form.created_at'),
+        updatedAt: toText(row.updated_at, 'form.updated_at'),
+    };
+}
+function decodeSubmission(row) {
+    return {
+        id: toText(row.id, 'submission.id'),
+        formId: toText(row.form_id, 'submission.form_id'),
+        formName: toText(row.form_name, 'submission.form_name'),
+        values: toJson(row.values_json, 'submission.values_json'),
+        consents: toJson(row.consents_json, 'submission.consents_json'),
+        status: toText(row.status, 'submission.status'),
+        ipHash: toNullableText(row.ip_hash),
+        referrer: toNullableText(row.referrer),
+        userAgent: toNullableText(row.user_agent),
+        submittedAt: toText(row.submitted_at, 'submission.submitted_at'),
+    };
+}
+function decodeNote(row) {
+    return {
+        id: toText(row.id, 'note.id'),
+        submissionId: toText(row.submission_id, 'note.submission_id'),
+        authorId: toNullableText(row.author_id),
+        authorLabel: toText(row.author_label, 'note.author_label'),
+        body: toText(row.body, 'note.body'),
+        createdAt: toText(row.created_at, 'note.created_at'),
+    };
+}
+function formUnknown(name) {
+    return new CogentaError({
+        code: 'FORM_UNKNOWN',
+        message: `No form named "${name}".`,
+        hint: 'Check the form name, or create it first.',
+    });
+}
+/** A submission value as plain text — a file field contributes its filename, never its bytes. */
+function submissionValueText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.join(' ');
+    return value.filename;
+}
+/** Task 7's text search: every value and every consent's recorded wording, matched case-insensitively. */
+function submissionMatchesQuery(submission, needleLower) {
+    for (const value of Object.values(submission.values)) {
+        if (submissionValueText(value).toLowerCase().includes(needleLower))
+            return true;
+    }
+    for (const consent of submission.consents) {
+        if (consent.text.toLowerCase().includes(needleLower))
+            return true;
+    }
+    return false;
+}
+export function createFormStore(db, now = Date.now) {
+    const d = db.dialect;
+    const definitionsTable = identifier(TABLES.definitions, d);
+    const submissionsTable = identifier(TABLES.submissions, d);
+    const notesTable = identifier(TABLES.submissionNotes, d);
+    async function readDefinitionRow(id) {
+        const result = await db.query(sql `select * from ${definitionsTable} where id = ${id}`);
+        const row = result.rows[0];
+        return row === undefined ? null : decodeDefinition(row);
+    }
+    async function readDefinitionByNameRow(name) {
+        const result = await db.query(sql `select * from ${definitionsTable} where name = ${name}`);
+        const row = result.rows[0];
+        return row === undefined ? null : decodeDefinition(row);
+    }
+    const definitions = {
+        create: async (input) => {
+            const name = slugName(input.name);
+            if (name === '') {
+                throw new CogentaError({
+                    code: 'FORM_DEFINITION_INVALID',
+                    message: 'A form needs a usable name.',
+                    hint: 'Give the form a label with at least one letter or digit.',
+                });
+            }
+            if (RESERVED_NAMES.has(name)) {
+                throw new CogentaError({
+                    code: 'FORM_NAME_TAKEN',
+                    message: `"${name}" is a reserved name and cannot be used for a form.`,
+                    hint: 'Choose a different name.',
+                });
+            }
+            for (const field of input.fields) {
+                if (!FORM_FIELD_KINDS.includes(field.kind)) {
+                    throw new CogentaError({
+                        code: 'FORM_DEFINITION_INVALID',
+                        message: `"${field.kind}" is not a form field kind.`,
+                        hint: `Use one of: ${FORM_FIELD_KINDS.join(', ')}.`,
+                    });
+                }
+            }
+            validateDefinitionFields(input.fields);
+            validateFormSteps(input.fields, input.steps ?? []);
+            validateNotifyChannels(input.notifyChannels ?? []);
+            validateCaptchaConfig(input.captcha ?? DEFAULT_CAPTCHA);
+            if ((await readDefinitionByNameRow(name)) !== null) {
+                throw new CogentaError({
+                    code: 'FORM_NAME_TAKEN',
+                    message: `A form named "${name}" already exists.`,
+                    hint: 'Choose a different name, or edit the existing form.',
+                });
+            }
+            const id = newId(now);
+            const at = new Date(now()).toISOString();
+            await db.query(sql `
+        insert into ${definitionsTable}
+          (id, name, label, fields, active, confirmation_message, redirect_to,
+           notify_emails, autoresponder, retain_days, steps, notify_channels, captcha,
+           created_at, updated_at)
+        values (${id}, ${name}, ${input.label}, ${JSON.stringify(input.fields)},
+                ${fromBool(input.active ?? true, d)}, ${input.confirmationMessage ?? DEFAULT_CONFIRMATION},
+                ${input.redirectTo ?? null}, ${JSON.stringify(input.notifyEmails ?? [])},
+                ${JSON.stringify(input.autoresponder ?? DEFAULT_AUTORESPONDER)},
+                ${input.retainDays ?? DEFAULT_RETAIN_DAYS}, ${JSON.stringify(input.steps ?? [])},
+                ${JSON.stringify(input.notifyChannels ?? [])},
+                ${JSON.stringify(input.captcha ?? DEFAULT_CAPTCHA)}, ${at}, ${at})`);
+            const created = await readDefinitionRow(id);
+            if (created === null) {
+                throw new CogentaError({
+                    code: 'INTERNAL',
+                    message: 'The form was not stored.',
+                    hint: 'Check that the forms tables exist (ensureFormsTables).',
+                });
+            }
+            return created;
+        },
+        read: readDefinitionRow,
+        readByName: readDefinitionByNameRow,
+        list: async () => {
+            const result = await db.query(sql `select * from ${definitionsTable} order by created_at desc`);
+            return result.rows.map(decodeDefinition);
+        },
+        update: async (id, input) => {
+            const existing = await readDefinitionRow(id);
+            if (existing === null) {
+                throw new CogentaError({
+                    code: 'FORM_UNKNOWN',
+                    message: `No form with id "${id}".`,
+                    hint: 'It may have been deleted.',
+                });
+            }
+            const nextFields = input.fields ?? existing.fields;
+            if (input.fields !== undefined) {
+                for (const field of nextFields) {
+                    if (!FORM_FIELD_KINDS.includes(field.kind)) {
+                        throw new CogentaError({
+                            code: 'FORM_DEFINITION_INVALID',
+                            message: `"${field.kind}" is not a form field kind.`,
+                            hint: `Use one of: ${FORM_FIELD_KINDS.join(', ')}.`,
+                        });
+                    }
+                }
+                validateDefinitionFields(nextFields);
+            }
+            const nextSteps = input.steps ?? existing.steps;
+            if (input.steps !== undefined || input.fields !== undefined) {
+                validateFormSteps(nextFields, nextSteps);
+            }
+            const nextNotifyChannels = input.notifyChannels ?? existing.notifyChannels;
+            if (input.notifyChannels !== undefined)
+                validateNotifyChannels(nextNotifyChannels);
+            const nextCaptcha = input.captcha ?? existing.captcha;
+            if (input.captcha !== undefined)
+                validateCaptchaConfig(nextCaptcha);
+            let nextName = existing.name;
+            if (input.name !== undefined) {
+                nextName = slugName(input.name);
+                if (RESERVED_NAMES.has(nextName)) {
+                    throw new CogentaError({
+                        code: 'FORM_NAME_TAKEN',
+                        message: `"${nextName}" is a reserved name and cannot be used for a form.`,
+                        hint: 'Choose a different name.',
+                    });
+                }
+                const clash = await readDefinitionByNameRow(nextName);
+                if (clash !== null && clash.id !== id) {
+                    throw new CogentaError({
+                        code: 'FORM_NAME_TAKEN',
+                        message: `A form named "${nextName}" already exists.`,
+                        hint: 'Choose a different name.',
+                    });
+                }
+            }
+            const at = new Date(now()).toISOString();
+            await db.query(sql `
+        update ${definitionsTable} set
+          name = ${nextName},
+          label = ${input.label ?? existing.label},
+          fields = ${JSON.stringify(nextFields)},
+          active = ${fromBool(input.active ?? existing.active, d)},
+          confirmation_message = ${input.confirmationMessage ?? existing.confirmationMessage},
+          redirect_to = ${input.redirectTo === undefined ? existing.redirectTo : input.redirectTo},
+          notify_emails = ${JSON.stringify(input.notifyEmails ?? existing.notifyEmails)},
+          autoresponder = ${JSON.stringify(input.autoresponder ?? existing.autoresponder)},
+          retain_days = ${input.retainDays ?? existing.retainDays},
+          steps = ${JSON.stringify(nextSteps)},
+          notify_channels = ${JSON.stringify(nextNotifyChannels)},
+          captcha = ${JSON.stringify(nextCaptcha)},
+          updated_at = ${at}
+        where id = ${id}`);
+            const updated = await readDefinitionRow(id);
+            if (updated === null) {
+                throw new CogentaError({
+                    code: 'FORM_UNKNOWN',
+                    message: `No form with id "${id}".`,
+                    hint: 'It may have been deleted.',
+                });
+            }
+            return updated;
+        },
+        remove: async (id) => {
+            await db.query(sql `delete from ${submissionsTable} where form_id = ${id}`);
+            await db.query(sql `delete from ${definitionsTable} where id = ${id}`);
+        },
+        duplicate: async (id) => {
+            const existing = await readDefinitionRow(id);
+            if (existing === null) {
+                throw new CogentaError({
+                    code: 'FORM_UNKNOWN',
+                    message: `No form with id "${id}".`,
+                    hint: 'It may have been deleted.',
+                });
+            }
+            let candidate = `${existing.name}-copy`;
+            let suffix = 2;
+            while ((await readDefinitionByNameRow(candidate)) !== null) {
+                candidate = `${existing.name}-copy-${suffix}`;
+                suffix += 1;
+            }
+            return definitions.create({
+                name: candidate,
+                label: `${existing.label} (copy)`,
+                fields: existing.fields,
+                // Never active: a duplicate must not start accepting real
+                // submissions before an operator has reviewed the copy (its route,
+                // its notifications, its CAPTCHA secret) — the same caution
+                // `active: true` by default elsewhere would defeat.
+                active: false,
+                confirmationMessage: existing.confirmationMessage,
+                redirectTo: existing.redirectTo,
+                notifyEmails: existing.notifyEmails,
+                autoresponder: existing.autoresponder,
+                retainDays: existing.retainDays,
+                steps: existing.steps,
+                notifyChannels: existing.notifyChannels,
+                captcha: existing.captcha,
+            });
+        },
+    };
+    async function readSubmissionRow(id) {
+        const result = await db.query(sql `select * from ${submissionsTable} where id = ${id}`);
+        const row = result.rows[0];
+        return row === undefined ? null : decodeSubmission(row);
+    }
+    const submissions = {
+        submit: async (formName, rawValues, options = {}) => {
+            const name = slugName(formName);
+            const definition = await readDefinitionByNameRow(name);
+            if (definition === null)
+                throw formUnknown(formName);
+            const validated = validateSubmission(definition, rawValues, now);
+            const id = newId(now);
+            const at = new Date(now()).toISOString();
+            await db.query(sql `
+        insert into ${submissionsTable}
+          (id, form_id, form_name, values_json, consents_json, status, ip_hash, referrer, user_agent, submitted_at)
+        values (${id}, ${definition.id}, ${definition.name}, ${JSON.stringify(validated.values)},
+                ${JSON.stringify(validated.consents)}, ${'new'},
+                ${options.ip ?? null}, ${options.referrer ?? null}, ${options.userAgent ?? null}, ${at})`);
+            const created = await readSubmissionRow(id);
+            if (created === null) {
+                throw new CogentaError({
+                    code: 'INTERNAL',
+                    message: 'The submission was not stored.',
+                    hint: 'Check that the forms tables exist (ensureFormsTables).',
+                });
+            }
+            return created;
+        },
+        read: readSubmissionRow,
+        list: async (options = {}) => {
+            const limit = Math.min(options.limit ?? 50, 200);
+            const clauses = [];
+            if (options.formId !== undefined)
+                clauses.push(sql `form_id = ${options.formId}`);
+            if (options.status !== undefined)
+                clauses.push(sql `status = ${options.status}`);
+            if (options.cursor !== undefined)
+                clauses.push(sql `submitted_at < ${options.cursor}`);
+            if (options.from !== undefined)
+                clauses.push(sql `submitted_at >= ${options.from}`);
+            if (options.to !== undefined)
+                clauses.push(sql `submitted_at <= ${options.to}`);
+            let where = unsafeRaw('');
+            for (const [index, clause] of clauses.entries()) {
+                where = index === 0 ? sql `where ${clause}` : sql `${where} and ${clause}`;
+            }
+            const needle = options.query?.trim().toLowerCase() ?? '';
+            const hasQuery = needle !== '';
+            // With a text query, the row count after filtering is not knowable in
+            // SQL, so the cheap `limit + 1` "is there another page" trick is
+            // replaced by pulling a bounded superset and filtering/paginating in
+            // memory (see `MAX_QUERY_SCAN_ROWS`'s own comment above).
+            const sqlLimit = hasQuery ? MAX_QUERY_SCAN_ROWS : limit + 1;
+            const result = await db.query(sql `select * from ${submissionsTable} ${where} order by submitted_at desc limit ${sqlLimit}`);
+            let rows = result.rows.map(decodeSubmission);
+            if (hasQuery)
+                rows = rows.filter((submission) => submissionMatchesQuery(submission, needle));
+            const hasMore = rows.length > limit;
+            const items = hasMore ? rows.slice(0, limit) : rows;
+            return { items, nextCursor: hasMore ? (items[items.length - 1]?.submittedAt ?? null) : null };
+        },
+        markStatus: async (id, status) => {
+            if (!SUBMISSION_STATUSES.includes(status)) {
+                throw new CogentaError({
+                    code: 'FORM_SUBMISSION_INVALID',
+                    message: `"${status}" is not a submission status.`,
+                    hint: `Use one of: ${SUBMISSION_STATUSES.join(', ')}.`,
+                });
+            }
+            await db.query(sql `update ${submissionsTable} set status = ${status} where id = ${id}`);
+            const updated = await readSubmissionRow(id);
+            if (updated === null) {
+                throw new CogentaError({
+                    code: 'FORM_SUBMISSION_NOT_FOUND',
+                    message: `No submission with id "${id}".`,
+                    hint: 'It may already have been deleted.',
+                });
+            }
+            return updated;
+        },
+        bulkMarkStatus: async (ids, status) => {
+            if (!SUBMISSION_STATUSES.includes(status)) {
+                throw new CogentaError({
+                    code: 'FORM_SUBMISSION_INVALID',
+                    message: `"${status}" is not a submission status.`,
+                    hint: `Use one of: ${SUBMISSION_STATUSES.join(', ')}.`,
+                });
+            }
+            let count = 0;
+            for (const id of ids) {
+                const result = await db.query(sql `update ${submissionsTable} set status = ${status} where id = ${id}`);
+                count += result.rowsAffected;
+            }
+            return count;
+        },
+        remove: async (id) => {
+            await db.query(sql `delete from ${notesTable} where submission_id = ${id}`);
+            await db.query(sql `delete from ${submissionsTable} where id = ${id}`);
+        },
+        bulkRemove: async (ids) => {
+            let count = 0;
+            for (const id of ids) {
+                await db.query(sql `delete from ${notesTable} where submission_id = ${id}`);
+                const result = await db.query(sql `delete from ${submissionsTable} where id = ${id}`);
+                count += result.rowsAffected;
+            }
+            return count;
+        },
+        unreadCount: async () => {
+            const result = await db.query(sql `select count(*) as n from ${submissionsTable} where status = ${'new'}`);
+            return toInt(result.rows[0]?.n ?? 0, 'unread count');
+        },
+        searchByEmail: async (email) => {
+            const normalised = email.trim().toLowerCase();
+            // The e-mail lives inside `values_json`, one key per form's own `email`
+            // field — there is no dedicated column to index it under, since a form
+            // is not required to collect an e-mail at all. A full scan is the
+            // honest cost of that flexibility; this route is an operator-triggered
+            // GDPR request, never a hot path.
+            const result = await db.query(sql `select * from ${submissionsTable}`);
+            const definitionsById = new Map();
+            const matches = [];
+            for (const row of result.rows) {
+                const submission = decodeSubmission(row);
+                let definition = definitionsById.get(submission.formId);
+                if (definition === undefined) {
+                    const found = await readDefinitionRow(submission.formId);
+                    if (found !== null) {
+                        definition = found;
+                        definitionsById.set(submission.formId, found);
+                    }
+                }
+                const value = definition === undefined ? null : emailValueOf(submission, definition.fields);
+                if (value === normalised)
+                    matches.push(submission);
+            }
+            return matches;
+        },
+        deleteByEmail: async (email) => {
+            const matches = await submissions.searchByEmail(email);
+            let count = 0;
+            for (const match of matches) {
+                await db.query(sql `delete from ${notesTable} where submission_id = ${match.id}`);
+                const result = await db.query(sql `delete from ${submissionsTable} where id = ${match.id}`);
+                count += result.rowsAffected;
+            }
+            return count;
+        },
+        purgeExpired: async () => {
+            const forms = await definitions.list();
+            let purged = 0;
+            for (const form of forms) {
+                const cutoff = new Date(now() - form.retainDays * DAY_MS).toISOString();
+                const expiredResult = await db.query(sql `select id from ${submissionsTable} where form_id = ${form.id} and submitted_at < ${cutoff}`);
+                for (const row of expiredResult.rows) {
+                    await db.query(sql `delete from ${notesTable} where submission_id = ${row.id}`);
+                }
+                const result = await db.query(sql `delete from ${submissionsTable} where form_id = ${form.id} and submitted_at < ${cutoff}`);
+                purged += result.rowsAffected;
+            }
+            return { purged };
+        },
+        addNote: async (submissionId, body, author) => {
+            const submission = await readSubmissionRow(submissionId);
+            if (submission === null) {
+                throw new CogentaError({
+                    code: 'FORM_SUBMISSION_NOT_FOUND',
+                    message: `No submission with id "${submissionId}".`,
+                    hint: 'It may have been deleted.',
+                });
+            }
+            const trimmed = body.trim();
+            if (trimmed === '') {
+                throw new CogentaError({
+                    code: 'FORM_SUBMISSION_INVALID',
+                    message: 'A note needs some text.',
+                    hint: 'Write something before saving the note.',
+                });
+            }
+            const id = newId(now);
+            const at = new Date(now()).toISOString();
+            await db.query(sql `
+        insert into ${notesTable} (id, submission_id, author_id, author_label, body, created_at)
+        values (${id}, ${submissionId}, ${author.id}, ${author.label}, ${trimmed}, ${at})`);
+            const result = await db.query(sql `select * from ${notesTable} where id = ${id}`);
+            const row = result.rows[0];
+            if (row === undefined) {
+                throw new CogentaError({
+                    code: 'INTERNAL',
+                    message: 'The note was not stored.',
+                    hint: 'Check that the forms tables exist (ensureFormsTables).',
+                });
+            }
+            return decodeNote(row);
+        },
+        listNotes: async (submissionId) => {
+            const result = await db.query(sql `select * from ${notesTable} where submission_id = ${submissionId} order by created_at asc`);
+            return result.rows.map(decodeNote);
+        },
+    };
+    return { definitions, submissions };
+}
+//# sourceMappingURL=store.js.map