@core / forms

1.1.0 ▾

1.1.0

verificadoMIT

Formularios y captación de leads: en código o desde el admin, antispam, consentimiento RGPD, avisos, webhooks firmados y CSV

Código11 archivosContexto~815 tokensescaneo superado

~815 tokens→ src/lib/forms/AGENTS.md→ .cursor/rules/genpm-core-forms.mdc

Esto es exactamente lo que lee tu IA cuando trabaja en src/lib/forms. No se añade nada más a su contexto.

@core/forms — rules for AI agents

Purpose

Contact and lead forms end to end: forms defined in code (defineForm with zod) or built by editors in the admin (forms content collection), anti-spam (@core/antispam), GDPR consent with a versioned text, stored submissions with source page and campaign parameters, and background processing (@core/jobs): team alert email, auto-reply, HMAC-signed webhook and onSubmission handlers. CSV export, retention and erasure helpers. Table: form_submissions.

Map

index.ts — public API: defineForm, submitForm, onSubmission, formsAdminResources, exportSubmissionsCsv, pruneSubmissions, deleteSubmissionsByEmail.
definitions.ts — code and admin-built definitions. submit.ts — submission and the forms.process job. admin.ts — admin, CSV, privacy.
react.ts — <Form formKey searchParams> (async server component; works without JavaScript).
adapters/hono.ts — formRoutes(). adapters/next.ts — formRoute (POST; HTML posts get a 303 back to the page).

Integration

Env: EMAIL_FROM (@core/email), optional FORMS_NOTIFY_TO (comma-separated default recipients) and FORMS_WEBHOOK_SECRET (≥ 32 chars, only with webhooks). Migrations as in src/lib/db/AGENTS.md; the @core/jobs cron must run.
Define code forms in a module imported at startup (e.g. src/genpm/forms.ts): defineForm({ key: 'contact', label: 'Contact', schema: z.object({ name: z.string().min(1), email: z.email(), message: z.string().min(5) }), emailField: 'email', consent: { required: true, version: '2026-10', text: '…' } }).
Mount formRoutes() or formRoute at /api/forms/<key> and render <Form formKey="contact" searchParams={await searchParams} />: it includes the anti-spam fields, the consent checkbox (never pre-checked) and shows the result after the 303. Custom markup: post to the same endpoint with honeypotProps, _ts and consent; JSON callers get { ok, reason, errors }. In Next.js Server Actions call submitForm(key, formData, { headers: await headers() }) instead.
Translate the messages with labels (keys: formLabels).
Add ...formsAdminResources() to src/genpm/admin.ts.
Verify: submit the form, run the cron, the team receives the email and the submission appears in the admin.

Conventions

Field names are the keys stored in data; keep them stable (exports and webhooks depend on them).
forms.process records each finished step in form_submissions.processed (notify, auto_reply, webhook, handler:<n>): a retry skips them, so emails and webhooks aren't repeated. Keep onSubmission handlers in a stable order.
Webhook receivers must verify x-genpm-signature (t=<unix>,v1=<hmac> over "<t>.<body>") and reject old timestamps.
Ask only for the data you need; define a retention period and schedule pruneSubmissions(days).
Permissions: submissions:read|update|delete|export, forms:* for admin-built forms.

Don't

Don't send emails or call webhooks inside the request; submitForm queues them.
Don't put submission values into HTML without escaping, or open CSV exports from other tools without the formula guard.
Don't add hidden fields that collect data the user didn't type.

# @core/forms — rules for AI agents

## Purpose
Contact and lead forms end to end: forms defined in code (`defineForm` with zod) or built by editors in the admin
(`forms` content collection), anti-spam (@core/antispam), GDPR consent with a versioned text, stored submissions with
source page and campaign parameters, and background processing (@core/jobs): team alert email, auto-reply,
HMAC-signed webhook and `onSubmission` handlers. CSV export, retention and erasure helpers. Table: `form_submissions`.

## Map
- `index.ts` — public API: `defineForm`, `submitForm`, `onSubmission`, `formsAdminResources`, `exportSubmissionsCsv`, `pruneSubmissions`, `deleteSubmissionsByEmail`.
- `definitions.ts` — code and admin-built definitions. `submit.ts` — submission and the `forms.process` job. `admin.ts` — admin, CSV, privacy.
- `react.ts` — `<Form formKey searchParams>` (async server component; works without JavaScript).
- `adapters/hono.ts` — `formRoutes()`. `adapters/next.ts` — `formRoute` (POST; HTML posts get a 303 back to the page).

## Integration
1. Env: `EMAIL_FROM` (@core/email), optional `FORMS_NOTIFY_TO` (comma-separated default recipients) and `FORMS_WEBHOOK_SECRET` (≥ 32 chars, only with webhooks). Migrations as in `src/lib/db/AGENTS.md`; the @core/jobs cron must run.
2. Define code forms in a module imported at startup (e.g. `src/genpm/forms.ts`):
   `defineForm({ key: 'contact', label: 'Contact', schema: z.object({ name: z.string().min(1), email: z.email(), message: z.string().min(5) }), emailField: 'email', consent: { required: true, version: '2026-10', text: '…' } })`.
3. Mount `formRoutes()` or `formRoute` at `/api/forms/<key>` and render `<Form formKey="contact" searchParams={await searchParams} />`:
   it includes the anti-spam fields, the consent checkbox (never pre-checked) and shows the result after the 303.
   Custom markup: post to the same endpoint with `honeypotProps`, `_ts` and `consent`; JSON callers get `{ ok, reason, errors }`.
   In Next.js Server Actions call `submitForm(key, formData, { headers: await headers() })` instead.
4. Translate the messages with `labels` (keys: `formLabels`).
5. Add `...formsAdminResources()` to `src/genpm/admin.ts`.
6. Verify: submit the form, run the cron, the team receives the email and the submission appears in the admin.

## Conventions
- Field names are the keys stored in `data`; keep them stable (exports and webhooks depend on them).
- `forms.process` records each finished step in `form_submissions.processed` (`notify`, `auto_reply`, `webhook`,
  `handler:<n>`): a retry skips them, so emails and webhooks aren't repeated. Keep `onSubmission` handlers in a stable order.
- Webhook receivers must verify `x-genpm-signature` (`t=<unix>,v1=<hmac>` over `"<t>.<body>"`) and reject old timestamps.
- Ask only for the data you need; define a retention period and schedule `pruneSubmissions(days)`.
- Permissions: `submissions:read|update|delete|export`, `forms:*` for admin-built forms.

## Don't
- Don't send emails or call webhooks inside the request; `submitForm` queues them.
- Don't put submission values into HTML without escaping, or open CSV exports from other tools without the formula guard.
- Don't add hidden fields that collect data the user didn't type.

El árbol exacto que se inyectará, tras aplicar .genpmignore. Anclado a

src/lib/forms/schema.tssolo lectura · 76db1c0

// Tablas de @core/forms. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { index, jsonb, pgTable, text } from 'drizzle-orm/pg-core';
import { primaryId, timestamps } from '../db/index.ts';

export const formSubmissions = pgTable(
  'form_submissions',
  {
    id: primaryId('sub'),
    formKey: text('form_key').notNull(),
    data: jsonb('data').$type<Record<string, unknown>>().notNull(),
    /** Versión del texto de consentimiento aceptado (prueba RGPD), si el formulario lo pide. */
    consentVersion: text('consent_version'),
    /** Página desde la que se envió (sin query) y parámetros de campaña capturados. */
    sourcePath: text('source_path'),
    utm: jsonb('utm').$type<Record<string, string>>(),
    /** Pasos de `forms.process` ya hechos (`notify`, `auto_reply`, `webhook`, `handler:<n>`): un reintento no los repite. */
    processed: jsonb('processed').$type<string[]>().notNull().default([]),
    status: text('status', { enum: ['new', 'read', 'archived', 'spam'] })
      .notNull()
      .default('new'),
    ...timestamps,
  },
  (t) => [index('form_submissions_form_idx').on(t.formKey, t.createdAt)],
);

export type FormSubmission = typeof formSubmissions.$inferSelect;