@ciromaciel/contract 1.2.0 → 1.4.0

package/README.md

@@ -133,6 +133,22 @@ Both return `{ ok: true, subject, email, name, scopes, claims }` or
 the `riligar-auth` issuer only. `jose` (5 or 6) is an **optional** peer, needed
 only by this entrypoint.
 
+### `@ciromaciel/contract/outbox`
+
+```js
+import { OUTBOX_SQL, envelope, enqueueEvent, deliverDue, releaseHeld, retryDelivery } from '@ciromaciel/contract/outbox'
+```
+
+The delivery queue every product shares. Each event is a row in `outbox` before it leaves, one per subscribed endpoint, signed with `./webhooks`. A 2xx is `sent`; 401 and 403 are `held` (probed hourly, released at once by `releaseHeld` when the secret changes); 410 is `failed`; anything else retries after 1 min, 5 min, 30 min, 2 h and 12 h. `OUTBOX_SQL` is the schema to put in the product's first migration. The product supplies a D1-shaped `db` and `decryptSecret(ciphertext)`.
+
+### `@ciromaciel/contract/feedback`
+
+```js
+import { createFeedback, FEEDBACK_SQL } from '@ciromaciel/contract/feedback'
+```
+
+"Sugerir ou relatar", the corner button of every panel (`FeedbackWidget` in `@ciromaciel/dashboard-kit`), on the worker side. `createFeedback({ product, prefix, error, requirePerson, locate, fields })` returns `handleRoutes` (`GET`/`POST /api/feedback`, behind the login), `handleHooks` (the Tasks' signed answers at `/feedback/tasks` and the build job's news at `/feedback/build`) and `runCron` (resend what the Tasks did not take; resend and then report what the triage never took). A request carries `<prefix>-<6 hex>` (`DK-1A2B3C`) and its thread is `<product>:<ref>`. `FEEDBACK_SQL` is the table; the product adds its own columns (`deck_id`) and names them in `locate().columns`. Only a person sends, and `locate` names only the account's own things. Env: `FEEDBACK_URL`, `FEEDBACK_SECRET`, `TASKS_WEBHOOK_SECRET`, `BUILD_SECRET`.
+
 ## Links
 
 - [Website](https://ciromaciel.click)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ciromaciel/contract",
-    "version": "1.2.0",
+    "version": "1.4.0",
     "license": "MIT",
     "type": "module",
     "description": "A single response envelope, a closed catalogue of error codes, and helpers that make answering outside it impossible.",
@@ -15,7 +15,9 @@
         "./schemas": "./src/schemas.js",
         "./plan": "./src/plan/index.js",
         "./webhooks": "./src/webhooks.js",
-        "./token": "./src/token.js"
+        "./token": "./src/token.js",
+        "./outbox": "./src/outbox.js",
+        "./feedback": "./src/feedback.js"
     },
     "scripts": {
         "test": "bun test tests/"

package/src/feedback.js

@@ -0,0 +1,417 @@
+// ============================================================================
+// @ciromaciel/contract/feedback — "Sugerir ou relatar", the same in every product
+// ============================================================================
+//
+//     import { createFeedback, FEEDBACK_SQL } from '@ciromaciel/contract/feedback'
+//
+//     const feedback = createFeedback({
+//         product: 'decks', prefix: 'DK',
+//         error: (code, message, details) => new ContractError(code, message, details),
+//         requirePerson: auth => requirePerson(auth, ContractError, CODES, 'Mandar uma sugestão'),
+//         locate: async ({ db, auth, body }) => ({ columns: { deck_id: … }, where: { deckTitle: … } }),
+//         fields: row => ({ deckId: row.deck_id }),
+//     })
+//
+// The panel's corner button (dashboard-kit FeedbackWidget) is the door to the improvement agent
+// (manager/docs/2026-10-11-AGENTE-DE-MELHORIAS.html). Blogs was the pilot, 11/10/2026; this module
+// is its routes/feedback.js with the product's pieces passed in, so the second product is a config
+// and not a copy.
+//
+//     POST /api/feedback   { kind: problem|idea, happens, wish?, context, …the product's ids }
+//     GET  /api/feedback   the account's own, newest first, with where each one is
+//     POST /feedback/tasks the Tasks' signed request.created / request.answered (the way back)
+//     POST /feedback/build the build job's signed news: building, review (with the preview), live
+//
+// The person writes only what happens and what they would like. WHERE comes from the panel
+// (`context`: the screen, the address, the browser, the window) and from the product (`locate`:
+// the names of its own things, only when they are the account's): the agent starts knowing the
+// place, not asking.
+//
+// The row is the record. When FEEDBACK_URL and FEEDBACK_SECRET are set (the Tasks' source
+// "Melhorias dos produtos"), a signed `feedback.created` goes there after the answer; a failed
+// send is tried again by the product's cron (`forwardPending`), and a feedback the triage never
+// took is sent once more and then reported stuck (`watchTriage`). Only a person sends.
+//
+// ENV the product's worker reads: FEEDBACK_URL, FEEDBACK_SECRET (the source), TASKS_WEBHOOK_SECRET
+// (the Tasks' outgoing webhook, the way back), BUILD_SECRET (the build job's news).
+
+import { CODES } from './codes.js'
+import { collection, created, ok, page } from './responses.js'
+import { envelope, sendSigned } from './outbox.js'
+import { verifyWebhook } from './webhooks.js'
+
+/**
+ * The table every product keeps. A product adds its own columns for its things (Blogs: blog_id,
+ * post_id; Decks: deck_id) in its migration, and names them in `locate().columns`.
+ */
+export const FEEDBACK_SQL = `
+CREATE TABLE IF NOT EXISTS feedback (
+    id TEXT PRIMARY KEY,
+    account_id TEXT NOT NULL,
+    number INTEGER NOT NULL,
+    kind TEXT NOT NULL,
+    happens TEXT NOT NULL,
+    wish TEXT NOT NULL DEFAULT '',
+    context TEXT NOT NULL DEFAULT '{}',
+    reporter_name TEXT NOT NULL DEFAULT '',
+    reporter_email TEXT NOT NULL DEFAULT '',
+    status TEXT NOT NULL DEFAULT 'received',
+    status_note TEXT NOT NULL DEFAULT '',
+    forwarded_at INTEGER,
+    forward_status INTEGER,
+    retries INTEGER NOT NULL DEFAULT 0,
+    retried_at INTEGER,
+    stuck_at INTEGER,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    UNIQUE (account_id, number)
+);
+CREATE INDEX IF NOT EXISTS idx_feedback_account ON feedback (account_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_feedback_forward ON feedback (forwarded_at, created_at);
+`
+
+export const FEEDBACK_KINDS = ['problem', 'idea']
+
+export const FEEDBACK_STATUS_LABELS = {
+    received: 'Recebido',
+    triaged: 'Em análise',
+    approved: 'Aprovado',
+    building: 'Em construção',
+    review: 'Em revisão',
+    live: 'No ar',
+    declined: 'Não vamos fazer',
+    needs_info: 'Precisa de mais detalhes',
+}
+
+/** How long a feedback may sit in "Recebido" after the Tasks took it before the next step. */
+export const STUCK_AFTER = 15 * 60
+
+/** Requests about a feedback that are not its triage: their creation moves nothing. */
+const FOLLOW_UP = / · (Revisar|A construção parou|A sugestão travou)\b/
+
+/** The Ciro's choice in the Tasks, as the status the person sees. */
+const OPTION_STATUS = { 'Aprovar e construir': 'approved', 'Pedir mais detalhes à pessoa': 'needs_info', 'Não vamos fazer': 'declined' }
+
+/** The choices that start the build job: the first approval builds; "Tentar de novo" answers a build that stopped. */
+const OPTION_JOB = { 'Aprovar e construir': 'build', 'Tentar de novo': 'build' }
+const RESEND_OPTION = 'Mandar de novo ao agente'
+
+/** The review's native answers (Tasks: kind review), as the job they start. */
+const REVIEW_JOB = { approved: 'ship', changes: 'revise', refused: 'discard' }
+
+const TRIAGE_PHASE = 'Triagem'
+const BUILD_STATUSES = ['building', 'review', 'live', 'approved', 'declined']
+const MAX_TEXT = 4000
+const CONTEXT_KEYS = { screen: 80, section: 40, path: 500, url: 1000, viewport: 20, browser: 300, language: 20, panelVersion: 40, timezone: 60 }
+const COLUMN = /^[a-z][a-z0-9_]{0,40}$/
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+const text = (value, max) =>
+    String(value ?? '')
+        .replace(/\r\n?/g, '\n')
+        .trim()
+        .slice(0, max)
+const parse = (value, fallback) => {
+    try {
+        return value ? JSON.parse(value) : fallback
+    } catch {
+        return fallback
+    }
+}
+const isOk = status => status >= 200 && status < 300
+export const isUuid = value => typeof value === 'string' && UUID.test(value)
+
+/** What the panel says about where it happened, kept to the known keys and sizes. */
+export function cleanContext(value) {
+    const input = value && typeof value === 'object' ? value : {}
+    return Object.fromEntries(
+        Object.entries(CONTEXT_KEYS)
+            .map(([key, max]) => [key, text(input[key], max)])
+            .filter(([, v]) => v)
+    )
+}
+
+/**
+ * The feedback of one product.
+ *
+ *   product        'blogs' — the event's product, the thread's key (`blogs:BL-…`), the machines' groups
+ *   prefix         'BL' — the code a request carries across systems: BL- and the first 6 hex of the id
+ *   error          (code, message, details) => Error the product's worker turns into its failure()
+ *   requirePerson  auth => void, throws when it is not a person (a key or an agent never sends)
+ *   locate         async ({ db, auth, body }) => { columns, where }: the product's columns of the row
+ *                  and the names added to the context; only what is the account's (never another's name)
+ *   fields         row => object: the product's ids in the API and in the events ({ blogId, postId })
+ *   userAgent      of the signed sends
+ *   fetch          for the tests; the global one by default
+ */
+export function createFeedback({ product, prefix, error, requirePerson, locate = async () => ({}), fields = () => ({}), userAgent = `ciromaciel-${product}/1.0`, fetch: fetchImpl }) {
+    if (!/^[a-z][a-z0-9-]{0,30}$/.test(String(product))) throw new Error('createFeedback: product is a lowercase key, like "decks".')
+    if (!/^[A-Z]{2,4}$/.test(String(prefix))) throw new Error('createFeedback: prefix is 2 to 4 capital letters, like "DK".')
+    const fail = (code, message, details) => error(code, message, details)
+
+    const refOf = id => `${prefix}-${String(id).replace(/-/g, '').slice(0, 6).toUpperCase()}`
+    const REF = new RegExp(`^${prefix}-([0-9A-F]{6})\\b`)
+    const WORK_KEY = new RegExp(`^${product}:(${prefix}-[0-9A-F]{6})$`)
+    const workKeyOf = id => `${product}:${refOf(id)}`
+    const byRef = (db, hex) => db.prepare('SELECT * FROM feedback WHERE id LIKE ?').bind(`${hex.toLowerCase()}%`).first()
+
+    function serialize(row) {
+        return {
+            id: row.id,
+            number: row.number,
+            ref: refOf(row.id),
+            kind: row.kind,
+            happens: row.happens,
+            wish: row.wish,
+            ...fields(row),
+            context: parse(row.context, {}),
+            status: row.status,
+            statusLabel: FEEDBACK_STATUS_LABELS[row.status] ?? row.status,
+            statusNote: row.status_note,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        }
+    }
+
+    /** The event the Tasks receives: everything the triage needs, in one piece. A resend is another event id. */
+    function eventOf(row, type = 'feedback.created', attempt = 0, extra = {}, eventId = null) {
+        return {
+            eventId: eventId ?? `${row.id}.${type}${attempt ? `.retry${attempt}` : ''}`,
+            body: envelope({
+                type,
+                at: row.created_at,
+                channel: 'panel',
+                person: { email: row.reporter_email || null, name: row.reporter_name || null },
+                properties: { product, id: row.id, ref: refOf(row.id), number: row.number, accountId: row.account_id, kind: row.kind, happens: row.happens, wish: row.wish, ...fields(row), ...parse(row.context, {}), ...extra },
+            }),
+        }
+    }
+
+    const isWired = env => Boolean(env.FEEDBACK_URL && env.FEEDBACK_SECRET)
+
+    /** One signed event to the Tasks' source; the HTTP status (0 when it did not answer). */
+    async function send(env, event) {
+        try {
+            const answer = await sendSigned({ url: env.FEEDBACK_URL, secret_ciphertext: env.FEEDBACK_SECRET }, event, { decryptSecret: async secret => secret, userAgent, ...(fetchImpl ? { fetch: fetchImpl } : {}) })
+            return answer?.status ?? 0
+        } catch {
+            return 0
+        }
+    }
+
+    async function forward(env, db, row, now) {
+        if (!isWired(env)) return false
+        const status = await send(env, eventOf(row))
+        await db
+            .prepare('UPDATE feedback SET forwarded_at = ?, forward_status = ? WHERE id = ?')
+            .bind(isOk(status) ? now : null, status, row.id)
+            .run()
+        return isOk(status)
+    }
+
+    /** Each status a feedback reaches, once (`feedback.status`): the Tasks' boards count the funnel from it. */
+    async function announceStatus(env, row, status, now) {
+        if (!isWired(env) || status === row.status) return
+        await send(env, eventOf({ ...row, created_at: now }, 'feedback.status', 0, { status, statusLabel: FEEDBACK_STATUS_LABELS[status] ?? status }, `${row.id}.feedback.status.${status}`))
+    }
+
+    async function resend(env, db, row, now) {
+        const attempt = (row.retries ?? 0) + 1
+        const status = await send(env, eventOf(row, 'feedback.created', attempt))
+        if (isOk(status)) await db.prepare('UPDATE feedback SET retries = ?, retried_at = ?, stuck_at = NULL WHERE id = ?').bind(attempt, now, row.id).run()
+        return isOk(status)
+    }
+
+    /**
+     * The cron's watch over the triage: taken by the Tasks and still "Recebido", after 15 minutes
+     * it goes to the agent once more; 15 minutes after that, `feedback.stuck`, which a rule in the
+     * Tasks turns into a request to the Ciro ("A sugestão travou").
+     */
+    async function watchTriage(env, db, now) {
+        if (!isWired(env)) return { resent: 0, stuck: 0 }
+        const { results } = await db
+            .prepare("SELECT * FROM feedback WHERE status = 'received' AND forwarded_at IS NOT NULL AND stuck_at IS NULL AND created_at > ? ORDER BY created_at LIMIT 20")
+            .bind(now - 3 * 86_400)
+            .all()
+        let resent = 0
+        let stuck = 0
+        for (const row of results) {
+            if (!row.retries && row.forwarded_at <= now - STUCK_AFTER) {
+                if (await resend(env, db, row, now)) resent++
+            } else if (row.retries && row.retried_at <= now - STUCK_AFTER) {
+                if (isOk(await send(env, eventOf(row, 'feedback.stuck', row.retries)))) {
+                    await db.prepare('UPDATE feedback SET stuck_at = ? WHERE id = ?').bind(now, row.id).run()
+                    stuck++
+                }
+            }
+        }
+        return { resent, stuck }
+    }
+
+    /** The cron's second chance: rows of the last 3 days the Tasks did not take yet. */
+    async function forwardPending(env, db, now) {
+        if (!isWired(env)) return 0
+        const { results } = await db
+            .prepare('SELECT * FROM feedback WHERE forwarded_at IS NULL AND created_at > ? ORDER BY created_at LIMIT 20')
+            .bind(now - 3 * 86_400)
+            .all()
+        let sent = 0
+        for (const row of results) if (await forward(env, db, row, now)) sent++
+        return sent
+    }
+
+    /** Both cron chores at once, for the product's scheduled(). */
+    async function runCron(env, db, now) {
+        return { sent: await forwardPending(env, db, now), ...(await watchTriage(env, db, now)) }
+    }
+
+    /**
+     * Starts the build job on the Tasks' machines: a signed `feedback.job` to the source, whose rule
+     * "Construir melhorias · <product>" runs the product's improvement job. `group` keeps two jobs of
+     * one group from running at once: the ships share one (two deploys never overlap), each
+     * improvement's build, revise and discard share another.
+     */
+    async function startJob(env, job, row, props) {
+        if (!isWired(env)) return 0
+        const feedback = { id: row.id, ref: refOf(row.id), number: row.number, kind: row.kind, happens: row.happens, wish: row.wish, context: parse(row.context, {}) }
+        const group = job === 'ship' ? `${product}-deploy` : `${product}-${feedback.ref.toLowerCase()}`
+        const payload = { feedback, workKey: workKeyOf(row.id), requestId: String(props.requestId ?? ''), note: String(props.note ?? '').slice(0, 2000), group }
+        const event = {
+            eventId: `${row.id}.feedback.job.${job}.${payload.requestId || Date.now()}`,
+            body: envelope({ type: 'feedback.job', at: Math.floor(Date.now() / 1000), channel: 'panel', person: { email: null, name: null }, properties: { product, ref: feedback.ref, job, ...payload } }),
+        }
+        return send(env, event)
+    }
+
+    async function readSigned(request, secret, maxBytes, now) {
+        const body = await request.text()
+        if (body.length > maxBytes) throw fail(CODES.PAYLOAD_TOO_LARGE, 'Evento grande demais.')
+        const check = await verifyWebhook([secret], { id: request.headers.get('x-ccm-id'), timestamp: request.headers.get('x-ccm-timestamp'), signature: request.headers.get('x-ccm-signature'), body }, now)
+        if (!check.ok) throw fail(CODES.UNAUTHORIZED, 'Assinatura inválida.')
+        return parse(body, {})
+    }
+
+    /**
+     * POST /feedback/tasks — public, signed with TASKS_WEBHOOK_SECRET. A request whose thread key
+     * (or, before the threads, whose title code) names a feedback moves it: created in the triage →
+     * Em análise; answered → the option the Ciro chose; refused → Não vamos fazer. Any other request
+     * of the Ciro's Tasks is acknowledged and ignored.
+     */
+    async function handleTasksHook({ request, env, db, pathname, method, now }) {
+        if (pathname !== '/feedback/tasks' || method !== 'POST') return null
+        if (!env.TASKS_WEBHOOK_SECRET) return null
+        const event = await readSigned(request, env.TASKS_WEBHOOK_SECRET, 64 * 1024, now)
+        const props = event?.data?.properties ?? {}
+        const fromWork = WORK_KEY.exec(String(props.workKey ?? ''))
+        const match = fromWork ? REF.exec(fromWork[1]) : REF.exec(String(props.title ?? ''))
+        if (!match || !['request.created', 'request.answered'].includes(event.type)) return ok({ accepted: 0 })
+        const row = await byRef(db, match[1])
+        if (!row) return ok({ accepted: 0 })
+        let status = row.status
+        let note = ''
+        let job = null
+        const isTriage = props.workKey ? props.phase === TRIAGE_PHASE : !FOLLOW_UP.test(String(props.title))
+        if (event.type === 'request.created' && row.status === 'received' && isTriage) status = 'triaged'
+        if (event.type === 'request.answered' && props.outcome === 'answered' && props.option === RESEND_OPTION) {
+            const sent = await resend(env, db, row, now)
+            return ok({ accepted: 1, status: row.status, resent: sent })
+        }
+        if (event.type === 'request.answered' && props.kind === 'review' && props.decision) {
+            // The review, answered natively: approve ships, changes rebuilds on the same branch with
+            // the note (meant for whoever redoes it, not for the person), refuse discards.
+            job = REVIEW_JOB[props.decision] ?? null
+            if (props.decision === 'refused') status = 'declined'
+            note = props.decision === 'changes' ? '' : String(props.note ?? '').slice(0, 500)
+        } else if (event.type === 'request.answered') {
+            if (props.outcome === 'refused') status = 'declined'
+            else if (props.outcome === 'answered') {
+                status = OPTION_STATUS[props.option] ?? status
+                job = OPTION_JOB[props.option] ?? null
+            }
+            note = String(props.note ?? '').slice(0, 500)
+        }
+        // "Pôr no ar" keeps "Em revisão" until the deploy is over: the job itself says "No ar".
+        const keepsNote = event.type !== 'request.answered' || props.decision === 'changes'
+        const isChanged = status !== row.status || (note && !keepsNote)
+        if (isChanged) {
+            await db
+                .prepare('UPDATE feedback SET status = ?, status_note = ?, updated_at = ? WHERE id = ?')
+                .bind(status, keepsNote ? row.status_note : note, now, row.id)
+                .run()
+            await announceStatus(env, row, status, now)
+        }
+        const dispatched = job ? await startJob(env, job, row, props) : null
+        if (!isChanged && !job) return ok({ accepted: 0 })
+        return ok({ accepted: 1, status, ...(job ? { job, dispatched } : {}) })
+    }
+
+    /** POST /feedback/build — public, signed with BUILD_SECRET: { ref, status, note? }, the job's news. */
+    async function handleBuildHook({ request, env, db, pathname, method, now }) {
+        if (pathname !== '/feedback/build' || method !== 'POST') return null
+        if (!env.BUILD_SECRET) return null
+        const input = await readSigned(request, env.BUILD_SECRET, 16 * 1024, now)
+        const match = REF.exec(String(input.ref ?? ''))
+        if (!match) throw fail(CODES.VALIDATION_ERROR, `Falta o código (${prefix}-…).`, { field: 'ref' })
+        if (!BUILD_STATUSES.includes(input.status)) throw fail(CODES.VALIDATION_ERROR, `O status é ${BUILD_STATUSES.join(', ')}.`, { field: 'status' })
+        const row = await byRef(db, match[1])
+        if (!row) return ok({ accepted: 0 })
+        await db
+            .prepare('UPDATE feedback SET status = ?, status_note = ?, updated_at = ? WHERE id = ?')
+            .bind(input.status, text(input.note, 500), now, row.id)
+            .run()
+        await announceStatus(env, row, input.status, now)
+        return ok({ accepted: 1, status: input.status })
+    }
+
+    /** The open hooks, in one call for the product's public chain. */
+    async function handleHooks(context) {
+        return (await handleTasksHook(context)) ?? (await handleBuildHook(context))
+    }
+
+    /** GET and POST /api/feedback, behind the product's login. */
+    async function handleRoutes(context) {
+        const { request, env, db, auth, pathname, method, now, ctx } = context
+        if (pathname !== '/api/feedback') return null
+
+        if (method === 'GET') {
+            const { results } = await db.prepare('SELECT * FROM feedback WHERE account_id = ? ORDER BY created_at DESC LIMIT 50').bind(auth.accountId).all()
+            return collection(results.map(serialize), page({ limit: 50, offset: 0, total: results.length }))
+        }
+
+        if (method === 'POST') {
+            requirePerson(auth)
+            const body = await readBody(request)
+            const kind = String(body.kind ?? '')
+            if (!FEEDBACK_KINDS.includes(kind)) throw fail(CODES.VALIDATION_ERROR, 'Escolha se é um problema ou uma melhoria.', { field: 'kind' })
+            const happens = text(body.happens, MAX_TEXT)
+            if (happens.length < 5) throw fail(CODES.VALIDATION_ERROR, kind === 'problem' ? 'Conte o que aconteceu.' : 'Conte a sua ideia.', { field: 'happens' })
+            const wish = text(body.wish, MAX_TEXT)
+            const located = (await locate({ db, auth, body })) ?? {}
+            const columns = Object.entries(located.columns ?? {}).filter(([name]) => COLUMN.test(name))
+            const where = { ...cleanContext(body.context), ...(located.where ?? {}) }
+            const id = crypto.randomUUID()
+            const number = ((await db.prepare('SELECT MAX(number) AS n FROM feedback WHERE account_id = ?').bind(auth.accountId).first())?.n ?? 0) + 1
+            const names = ['id', 'account_id', 'number', ...columns.map(([name]) => name), 'kind', 'happens', 'wish', 'context', 'reporter_name', 'reporter_email', 'created_at', 'updated_at']
+            const values = [id, auth.accountId, number, ...columns.map(([, value]) => value ?? null), kind, happens, wish, JSON.stringify(where), text(auth.name, 120), text(auth.email, 200), now, now]
+            await db
+                .prepare(`INSERT INTO feedback (${names.join(', ')}) VALUES (${names.map(() => '?').join(', ')})`)
+                .bind(...values)
+                .run()
+            const row = await db.prepare('SELECT * FROM feedback WHERE id = ?').bind(id).first()
+            // To the Tasks after the answer: the person never waits for the triage's door.
+            if (ctx?.waitUntil) ctx.waitUntil(forward(env, db, row, now).catch(() => {}))
+            return created(serialize(row))
+        }
+        return null
+    }
+
+    async function readBody(request) {
+        const raw = await request.text()
+        if (raw.length > 64 * 1024) throw fail(CODES.PAYLOAD_TOO_LARGE, 'Texto grande demais.')
+        const body = parse(raw, null)
+        if (!body || typeof body !== 'object' || Array.isArray(body)) throw fail(CODES.VALIDATION_ERROR, 'O corpo é um objeto JSON.')
+        return body
+    }
+
+    return { product, prefix, refOf, workKeyOf, serialize, handleRoutes, handleHooks, handleTasksHook, handleBuildHook, forwardPending, watchTriage, runCron }
+}

package/src/outbox.js

@@ -0,0 +1,237 @@
+// ============================================================================
+// @ciromaciel/contract/outbox — the delivery queue every product shares
+// ============================================================================
+//
+//     import { OUTBOX_SQL, enqueueEvent, deliverDue, releaseHeld } from '@ciromaciel/contract/outbox'
+//
+// Every event a product emits leaves through webhook endpoints the account
+// registers, signed with `./webhooks`. WRITTEN BEFORE IT LEAVES: each delivery
+// is a row in `outbox` first (one per endpoint); trying it right away is a
+// courtesy, and the cron is the guarantee.
+//
+// WHAT HAPPENS TO AN ATTEMPT:
+//
+//     2xx              sent
+//     401, 403         held: almost always a rotated secret or a revoked key on
+//                      the other side. Retrying five times would only kill the
+//                      delivery in 14 hours, while the fix is one paste away.
+//                      It waits, probed once an hour, and leaves on its own
+//                      when the endpoint answers 2xx again — or at once when
+//                      the secret is replaced here (`releaseHeld`).
+//     410              failed: the receiver said this address is gone.
+//     anything else    retried after 1 min, 5 min, 30 min, 2 h and 12 h, then
+//                      failed — visible on the screen and resendable by hand.
+//
+// WHY IT LIVES HERE. Videos wrote it, Community copied it, and four products
+// were about to copy it again. One fix should not become six.
+//
+// IT ASKS THE PRODUCT FOR TWO THINGS ONLY: a D1-shaped `db` (prepare, bind,
+// first, all, run, batch) and a `decryptSecret(ciphertext)` that returns the
+// endpoint's `whsec_`. Envelopes are built by the product with `envelope()`.
+
+import { webhookHeaders } from './webhooks.js'
+
+/** Seconds before each retry of an ordinary failure. */
+export const RETRY_DELAYS = [60, 300, 1800, 7200, 43_200]
+
+/** How often a held delivery is probed, in seconds. */
+export const HOLD_PROBE_SECONDS = 3600
+
+const DELIVERY_TIMEOUT_MS = 10_000
+
+/**
+ * The two tables, as products put them in their first migration. Same columns
+ * as Videos' `0002_webhook_endpoints.sql`, plus the `held` status.
+ */
+export const OUTBOX_SQL = `
+CREATE TABLE webhook_endpoints (
+    id                 TEXT PRIMARY KEY,
+    account_id         TEXT NOT NULL,
+    url                TEXT NOT NULL,
+    description        TEXT,
+    events             TEXT NOT NULL DEFAULT '["*"]',      -- JSON array of types, or ["*"]
+    secret_ciphertext  TEXT NOT NULL,
+    secret_prefix      TEXT NOT NULL,
+    secret_source      TEXT NOT NULL DEFAULT 'generated',  -- generated | provided
+    is_active          INTEGER NOT NULL DEFAULT 1,
+    last_status        INTEGER,
+    last_at            INTEGER,
+    created_at         INTEGER NOT NULL,
+    updated_at         INTEGER NOT NULL
+);
+CREATE INDEX idx_webhook_endpoints_account ON webhook_endpoints (account_id, created_at);
+
+CREATE TABLE outbox (
+    id           TEXT PRIMARY KEY,
+    account_id   TEXT NOT NULL,
+    target       TEXT NOT NULL,                           -- webhook_endpoints.id
+    event_id     TEXT NOT NULL,                           -- x-ccm-id: resending is a no-op on the other side
+    type         TEXT NOT NULL,
+    subject_id   TEXT,                                    -- what the event is about (a response, a link), to list deliveries per item
+    body         TEXT NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'pending',         -- pending | sent | held | failed
+    attempts     INTEGER NOT NULL DEFAULT 0,
+    next_at      INTEGER NOT NULL,
+    last_status  INTEGER,
+    last_error   TEXT,
+    created_at   INTEGER NOT NULL,
+    sent_at      INTEGER,
+    UNIQUE (target, event_id)
+);
+CREATE INDEX idx_outbox_due ON outbox (status, next_at);
+CREATE INDEX idx_outbox_account ON outbox (account_id, created_at DESC);
+CREATE INDEX idx_outbox_target ON outbox (target, created_at DESC);
+CREATE INDEX idx_outbox_subject ON outbox (account_id, subject_id);
+`
+
+/** Whether an endpoint's subscription covers `type`. */
+export function subscribes(endpoint, type) {
+    let events
+    try {
+        events = JSON.parse(endpoint.events ?? '["*"]')
+    } catch {
+        events = ['*']
+    }
+    return events.includes('*') || events.includes(type)
+}
+
+/**
+ * The envelope People reads from any source: `{type, timestamp, data}`, the
+ * person in `data.person`, where they came through in `data.channel`, the rest
+ * in `data.properties`. Empty person fields are dropped.
+ */
+export function envelope({ type, at, channel = 'web', person = null, properties = {} }) {
+    const data = { channel, properties }
+    if (person) {
+        const clean = Object.fromEntries(Object.entries(person).filter(([, value]) => value !== undefined && value !== null && value !== ''))
+        if (Object.keys(clean).length) data.person = clean
+    }
+    return JSON.stringify({ type, timestamp: new Date(at * 1000).toISOString(), data })
+}
+
+/**
+ * What one attempt turns into. `attempts` counts this one.
+ *
+ * @returns {{status: 'sent'|'pending'|'held'|'failed', nextIn: number|null}}
+ */
+export function classifyAttempt({ ok, status }, attempts) {
+    if (ok) return { status: 'sent', nextIn: null }
+    if (status === 401 || status === 403) return { status: 'held', nextIn: HOLD_PROBE_SECONDS }
+    if (status === 410) return { status: 'failed', nextIn: null }
+    if (attempts > RETRY_DELAYS.length) return { status: 'failed', nextIn: null }
+    return { status: 'pending', nextIn: RETRY_DELAYS[attempts - 1] }
+}
+
+/**
+ * Queues one event for every active endpoint of the account subscribed to its
+ * type. Returns the outbox ids, so the caller can try them at once.
+ *
+ * @param {object} db D1 or anything shaped like it
+ * @param {{accountId: string, eventId: string, type: string, body: string, at: number, subjectId?: string}} event
+ */
+export async function enqueueEvent(db, { accountId, eventId, type, body, at, subjectId = null }) {
+    const { results: active } = await db.prepare('SELECT id, events FROM webhook_endpoints WHERE account_id = ? AND is_active = 1').bind(accountId).all()
+    const targets = active.filter(endpoint => subscribes(endpoint, type))
+    if (!targets.length) return []
+    const ids = []
+    const statements = targets.map(endpoint => {
+        const id = crypto.randomUUID()
+        ids.push(id)
+        return db
+            .prepare('INSERT OR IGNORE INTO outbox (id, account_id, target, event_id, type, subject_id, body, next_at, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)')
+            .bind(id, accountId, endpoint.id, eventId, type, subjectId, body, at, at)
+    })
+    await db.batch(statements)
+    return ids
+}
+
+async function post(fetchImpl, url, headers, body, userAgent) {
+    const started = Date.now()
+    try {
+        const response = await fetchImpl(url, { method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': userAgent, ...headers }, body, signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS) })
+        return { status: response.status, ok: response.ok, ms: Date.now() - started, error: response.ok ? null : (await response.text()).slice(0, 300) }
+    } catch (error) {
+        return { status: 0, ok: false, ms: Date.now() - started, error: error?.name === 'TimeoutError' ? 'Sem resposta em 10 s.' : 'Não foi possível conectar.' }
+    }
+}
+
+/**
+ * One signed POST to an endpoint: a delivery, or the "Enviar teste" button.
+ *
+ * @param {object} endpoint a `webhook_endpoints` row
+ * @param {{eventId: string, body: string}} delivery
+ * @param {{decryptSecret: (ciphertext: string) => Promise<string>, fetch?: typeof fetch, userAgent?: string}} options
+ */
+export async function sendSigned(endpoint, { eventId, body }, { decryptSecret, fetch: fetchImpl = fetch, userAgent = 'ciromaciel-webhooks/1.0' }) {
+    const secret = await decryptSecret(endpoint.secret_ciphertext)
+    return post(fetchImpl, endpoint.url, await webhookHeaders(secret, { id: eventId, body }), body, userAgent)
+}
+
+/**
+ * Delivers due rows: those `ids`, or every pending or held row whose time has
+ * come. Returns counts for the cron's log.
+ *
+ * @param {object} db
+ * @param {{now: number, ids?: string[]|null, limit?: number, decryptSecret: Function, fetch?: typeof fetch, userAgent?: string}} options
+ */
+export async function deliverDue(db, { now, ids = null, limit = 50, decryptSecret, fetch: fetchImpl = fetch, userAgent }) {
+    const rows = ids
+        ? ids.length
+            ? (
+                  await db
+                      .prepare(`SELECT * FROM outbox WHERE status IN ('pending', 'held') AND id IN (${ids.map(() => '?').join(',')})`)
+                      .bind(...ids)
+                      .all()
+              ).results
+            : []
+        : (await db.prepare("SELECT * FROM outbox WHERE status IN ('pending', 'held') AND next_at <= ? ORDER BY next_at LIMIT ?").bind(now, limit).all()).results
+    const endpoints = new Map()
+    const counts = { due: rows.length, sent: 0, held: 0, failed: 0, retrying: 0 }
+    for (const row of rows) {
+        if (!endpoints.has(row.target)) endpoints.set(row.target, await db.prepare('SELECT * FROM webhook_endpoints WHERE id = ? AND account_id = ?').bind(row.target, row.account_id).first())
+        const endpoint = endpoints.get(row.target)
+        if (!endpoint || !endpoint.is_active) {
+            await db
+                .prepare("UPDATE outbox SET status = 'failed', last_error = ? WHERE id = ?")
+                .bind(endpoint ? 'Endpoint desligado.' : 'Endpoint removido.', row.id)
+                .run()
+            counts.failed++
+            continue
+        }
+        const result = await sendSigned(endpoint, { eventId: row.event_id, body: row.body }, { decryptSecret, fetch: fetchImpl, userAgent })
+        // A held row probing again does not spend the ordinary retries.
+        const attempts = row.status === 'held' ? row.attempts : row.attempts + 1
+        const next = classifyAttempt(result, Math.max(attempts, 1))
+        if (next.status === 'sent') {
+            await db.prepare("UPDATE outbox SET status = 'sent', attempts = ?, last_status = ?, last_error = NULL, sent_at = ? WHERE id = ?").bind(row.attempts + 1, result.status, now, row.id).run()
+            counts.sent++
+        } else if (next.status === 'failed') {
+            await db.prepare("UPDATE outbox SET status = 'failed', attempts = ?, last_status = ?, last_error = ? WHERE id = ?").bind(row.attempts + 1, result.status, result.error, row.id).run()
+            counts.failed++
+        } else {
+            await db
+                .prepare('UPDATE outbox SET status = ?, attempts = ?, last_status = ?, last_error = ?, next_at = ? WHERE id = ?')
+                .bind(next.status, attempts, result.status, result.error, now + next.nextIn, row.id)
+                .run()
+            if (next.status === 'held') counts.held++
+            else counts.retrying++
+        }
+        await db.prepare('UPDATE webhook_endpoints SET last_status = ?, last_at = ? WHERE id = ?').bind(result.status, now, endpoint.id).run()
+    }
+    return counts
+}
+
+/**
+ * Lets held deliveries of an endpoint go now — called when its secret or URL
+ * changes here, so the fix is felt at once instead of at the next probe.
+ */
+export async function releaseHeld(db, { accountId, endpointId, now }) {
+    const result = await db.prepare("UPDATE outbox SET status = 'pending', next_at = ? WHERE account_id = ? AND target = ? AND status = 'held'").bind(now, accountId, endpointId).run()
+    return result?.meta?.changes ?? 0
+}
+
+/** Puts one failed or held delivery back in line, for the "Reenviar" button. */
+export async function retryDelivery(db, { accountId, id, now }) {
+    const result = await db.prepare("UPDATE outbox SET status = 'pending', attempts = 0, next_at = ? WHERE id = ? AND account_id = ? AND status IN ('failed', 'held')").bind(now, id, accountId).run()
+    return (result?.meta?.changes ?? 0) > 0
+}