@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

package/docs/examples/intake-hooks.md

@@ -1,237 +0,0 @@
----
-description: A public intake form with a Turnstile bot check as the Procedure's guard and a staff email from an after hook.
----
-# Intake form with bot check and notification
-
-[Examples hub](./README.md) · Without the bot check and email, this is [Intake form](./intake.md).
-
-Anonymous visitors submit a request. A Cloudflare Turnstile token is verified
-before anything is written, and staff get an email after the row is committed.
-The write stays one SQL statement; two small `ref` handlers carry the
-integrations.
-
-## Problem
-
-The public write must reject automated submissions before anything is stored.
-A new row should email the team, without making the visitor wait for the email
-or fail when email is not configured. Submissions are records, so the Schema is
-`operational`.
-
-## Manifest
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: requests }
-spec:
-  title: Requests
-  description: Requests submitted through the public intake form.
-  lifecycle: operational
-  schema:
-    type: object
-    additionalProperties: false
-    required: [name, email, message]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 120 }
-      email: { type: string, format: email }
-      message: { type: string, minLength: 1, maxLength: 2000 }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: recent-requests }
-spec:
-  title: Recent requests
-  surface: staff
-  requires: { auth: { all: [{ ctx.staff: [owner, editor, contributor] }] } }
-  sql: |
-    SELECT id, name, email, message, created_at FROM requests
-    ORDER BY created_at DESC LIMIT 50
----
-# The guard runs first, with this Procedure's validated input, token included. The INSERT never stores the token.
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: submit-request }
-spec:
-  title: Submit request
-  description: Create a new public request after a Turnstile check.
-  requires: { guard: { procedure: verify-turnstile } }
-  input:
-    type: object
-    additionalProperties: false
-    required: [name, email, message]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 120 }
-      email: { type: string, format: email }
-      message: { type: string, minLength: 1, maxLength: 2000 }
-      turnstileToken: { type: string }
-  output: { type: object }
-  handler:
-    sql: |
-      INSERT INTO requests (name, email, message)
-      VALUES (input.name, input.email, input.message)
-      RETURNING id
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: verify-turnstile }
-spec:
-  input:
-    type: object
-    properties:
-      turnstileToken: { type: string }
-  output: { type: object }
-  handler: { ref: verifyTurnstile }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: notify-requests }
-spec:
-  input: { type: object }
-  output: { type: object }
-  handler: { ref: notifyRequests }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: submit-request-http }
-spec:
-  source: { kind: http, method: POST, path: /api/requests }
-  target: { procedure: submit-request }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: submit-request-mcp }
-spec:
-  source: { kind: mcp, surface: public }
-  target: { procedure: submit-request }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: requests-notify }
-spec:
-  source: { kind: lifecycle, schema: requests, on: [after_create] }
-  target: { procedure: notify-requests }
-```
-
-Why each check sits where it does:
-
-- **The bot check is a guard, not a before hook.** A guard receives the target
-  Procedure's validated input, so it can read `turnstileToken`. A before hook
-  receives only the row about to be written (`ctx.cause.rows`), and the token is
-  never part of the row. A guard belongs to one Procedure, which is right here:
-  staff creating a row through Admin are not asked for a token.
-- **The guard's input schema leaves `additionalProperties` open.** It receives
-  `name`, `email` and `message` too.
-- **The email is an after hook.** It runs only after the commit, and a failure
-  never undoes the row. One statement can write many rows, so the handler loops
-  over `ctx.cause.rows`.
-
-## Handlers
-
-```ts
-// src/handlers.ts
-import { DiagnosticError, runtimeDiagnostic } from "@aotter/mantle";
-import type { MantleHandlers } from "../.mantle/generated/mantle.js";
-import type { Env } from "./service.js";
-
-const reject = (message: string, value?: unknown): never => {
-  throw new DiagnosticError(runtimeDiagnostic({ code: "AUTH_DENIED", severity: "error", path: "/turnstileToken", value, message }));
-};
-
-export const handlers: MantleHandlers<Env> = {
-  verifyTurnstile: async (input, ctx) => {
-    const secret = ctx.env.TURNSTILE_SECRET_KEY?.trim();
-    if (!secret) return {}; // fails open until the secret exists; see below
-    const token = (input as { turnstileToken?: string }).turnstileToken?.trim();
-    if (!token) reject("Turnstile verification is required.");
-    const body = new FormData();
-    body.set("secret", secret);
-    body.set("response", token!);
-    const response = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", { method: "POST", body });
-    const result = response.ok ? ((await response.json().catch(() => null)) as { success?: boolean; "error-codes"?: string[] } | null) : null;
-    if (!result?.success) reject("Turnstile verification failed.", result?.["error-codes"]);
-    return {};
-  },
-
-  // an after hook gets every row the statement wrote: loop, never rows[0]
-  notifyRequests: async (_input, ctx) => {
-    const { EMAIL, INTAKE_NOTIFY_TO, INTAKE_NOTIFY_FROM } = ctx.env;
-    if (ctx.cause.kind !== "lifecycle" || !EMAIL || !INTAKE_NOTIFY_TO || !INTAKE_NOTIFY_FROM) return {};
-    for (const row of ctx.cause.rows) {
-      await EMAIL.send({
-        to: INTAKE_NOTIFY_TO,
-        from: INTAKE_NOTIFY_FROM,
-        subject: `New request from ${String(row.name)}`,
-        text: [`Name: ${String(row.name)}`, `Email: ${String(row.email)}`, "", String(row.message)].join("\n"),
-        replyTo: String(row.email),
-      });
-    }
-    return {};
-  },
-};
-```
-
-`src/service.ts` is the application's own file after the first
-`mantle generate`. Add the bindings to its `Env`:
-
-```ts
-interface EmailBinding {
-  send(message: { to: string; from: string; subject: string; text?: string; replyTo?: string }): Promise<unknown>;
-}
-
-export interface Env {
-  readonly DB: D1Database;
-  // ...the generated fields...
-  readonly TURNSTILE_SECRET_KEY?: string;
-  readonly EMAIL?: EmailBinding;
-  readonly INTAKE_NOTIFY_TO?: string;
-  readonly INTAKE_NOTIFY_FROM?: string;
-}
-```
-
-Put `send_email` (`[{ "name": "EMAIL" }]`) and the two `vars` in
-`wrangler.jsonc`, and set the secret with
-`wrangler secret put TURNSTILE_SECRET_KEY`.
-
-A handler throws `DiagnosticError` to answer with that code's status
-(`AUTH_DENIED` is 403). Any other throw is logged and answered as 500
-`INTERNAL_ERROR`. Import it from `@aotter/mantle`, not `@aotter/mantle/spec`:
-the root carries no SQL parser, while `/spec` bundles it into the Worker.
-
-Two policies are deliberate:
-
-- **The bot check fails open while the secret is unset,** so a first deploy
-  still accepts submissions. To fail closed, make the missing secret a
-  `reject(...)`.
-- **The notification fails soft.** After hooks are best effort: a throw is
-  logged and the row stays. `ctx.cause.id` is stable across a replay, so a
-  handler that must not send twice can deduplicate on it.
-
-## Try it
-
-```sh
-curl -sS -X POST http://127.0.0.1:8787/api/requests \
-  -H 'content-type: application/json' \
-  -d '{"name":"Ada","email":"ada@example.test","message":"Please call me back.","turnstileToken":"<token>"}'
-```
-
-The answer is `{ "results": [[{ "id": "…" }]] }`. With the secret set, a bad
-token is HTTP 403 with `{ "error": { "code": "AUTH_DENIED", … } }`, and no row
-exists. A missing `name` is HTTP 400 `INPUT_VALIDATION_FAILED` before the guard
-runs.
-
-An agent calling `submit_request` on `/mcp` has no browser widget. With the
-secret set, it is refused unless it brings a valid token. Keep or remove
-`submit-request-mcp` deliberately.
-
-## What this leaves out
-
-- **Deduplication.** Add a `uniqueIndexes` tuple and `ON CONFLICT DO NOTHING`
-  if duplicates matter.
-- **Rate limiting beyond Turnstile.** Put a quota in the service's own `fetch`.
-- **Reliable delivery.** After hooks run inline after the commit. A CRM sync
-  that must not be lost needs the service's own queue or outbox.
-
-## Source
-
-- [Writes: Procedures, Triggers and hooks](../handbook/concepts/procedures-and-triggers.md)
-- [Authorization reference](../handbook/reference/authorization.md): guards

package/docs/examples/intake.md

@@ -1,127 +0,0 @@
----
-description: A public intake form that inserts operational request rows with one SQL statement. No bot check or email hooks.
----
-# Intake form
-
-[Examples hub](./README.md) · Bot checks and staff email are [Intake with bot check and notification](./intake-hooks.md).
-
-Anonymous visitors submit a request, and staff list recent submissions. The
-only Procedure is one SQL `INSERT`; there is no handler code. Use this shape for
-any form that anonymous visitors submit.
-
-## Problem
-
-Visitors send a name, an email address and a message. Staff read recent
-submissions through Admin's API or the staff MCP surface. Submissions are
-records, not authored content, so the Schema is `operational`: a row is live as
-soon as it is written.
-
-## Manifest
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: requests }
-spec:
-  title: Requests
-  description: Requests submitted through the public intake form.
-  lifecycle: operational
-  schema:
-    type: object
-    additionalProperties: false
-    required: [name, email, message]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 120 }
-      email: { type: string, format: email }
-      message: { type: string, minLength: 1, maxLength: 2000 }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: recent-requests }
-spec:
-  title: Recent requests
-  surface: staff
-  requires: { auth: { all: [{ ctx.staff: [owner, editor, contributor] }] } }
-  sql: |
-    SELECT id, name, email, message, created_at FROM requests
-    ORDER BY created_at DESC LIMIT 50
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: submit-request }
-spec:
-  title: Submit request
-  description: Create a new public request.
-  input:
-    type: object
-    additionalProperties: false
-    required: [name, email, message]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 120 }
-      email: { type: string, format: email }
-      message: { type: string, minLength: 1, maxLength: 2000 }
-  output: { type: object }
-  handler:
-    sql: |
-      INSERT INTO requests (name, email, message)
-      VALUES (input.name, input.email, input.message)
-      RETURNING id
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: submit-request-http }
-spec:
-  source: { kind: http, method: POST, path: /api/requests }
-  target: { procedure: submit-request }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: submit-request-mcp }
-spec:
-  source: { kind: mcp, surface: public }
-  target: { procedure: submit-request }
-```
-
-The submission time is the native `created_at` column, which Store fills; a
-write can never set it. A column the SQL does not name keeps its default, so a
-caller cannot add fields: the `INSERT` lists exactly what is stored.
-
-## Handlers
-
-None. The plan has no `ref`, so the generated `src/handlers.ts` is an empty map.
-
-## Try it
-
-```sh
-curl -sS -X POST http://127.0.0.1:8787/api/requests \
-  -H 'content-type: application/json' \
-  -d '{"name":"Ada","email":"ada@example.test","message":"Please call me back."}'
-```
-
-An inline SQL Procedure answers `{ "results": [...] }`, one array of
-`RETURNING` rows per statement, here `[[{ "id": "…" }]]`. A missing `name` is
-HTTP 400 `INPUT_VALIDATION_FAILED`.
-
-Staff read the queue at `GET /admin/api/views/recent-requests?limit=50` with a
-staff session; the response is `{ rows, nextCursor? }`.
-
-| MCP surface | Tool | From |
-|---|---|---|
-| `/mcp` | `submit_request` | the `submit-request-mcp` Trigger |
-| `/mcp/staff` | `recent_requests` | the staff View |
-
-A Schema is never an MCP tool. Staff edit rows in Admin's API
-(`/admin/api/entries`), not through generated record tools.
-
-## What this leaves out
-
-- **Bot check and notification.** They are `ref` lifecycle hooks in
-  [Intake with bot check and notification](./intake-hooks.md).
-- **Deduplication.** Two identical submissions are two rows.
-- **Rate limiting.** Put a per-form quota in the service's own `fetch`, in
-  front of the REST surface.
-
-## Source
-
-- [Procedure reference](../handbook/reference/procedure.md)
-- [View reference](../handbook/reference/view.md)

package/docs/examples/legal-documents.md

@@ -1,218 +0,0 @@
----
-description: Localized Terms and Privacy documents with immutable revisions, a public lookup and signed-in acceptance records.
----
-# Legal documents and consent
-
-[Examples hub](./README.md)
-
-A portable shape for Terms of Use, a Privacy Policy and consent receipts. Each
-`(kind, revision, locale)` row is one legal artifact. Every Procedure is SQL.
-Core does not install this or own the public pages.
-
-## Problem
-
-Staff add reviewed legal text as new revisions and publish them; a published
-revision that users accepted is never rewritten. The public reads the current
-revision for a kind and a locale. A signed-in user records acceptance of one
-published revision, and the receipt names who and when without trusting the
-caller.
-
-## Manifest
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: legal-documents }
-spec:
-  title:
-    en: Legal documents
-    zh-TW: 法律文件
-  description:
-    en: Supply the site's complete, reviewed legal text. Never create empty, placeholder, or agent-invented terms. Create a new revision instead of rewriting a published document accepted by users.
-    zh-TW: 請填入網站已審閱的完整法律正文。不得建立空白、佔位或由 agent 虛構的條款；已有使用者同意的已發佈文件應建立新修訂，不得覆寫。
-  localized: true
-  lifecycle: publishing
-  uniqueIndexes: [[kind, revision, locale]]
-  indexes: [[kind, locale, effectiveAt]]
-  searchableFields: [title, revision]
-  schema:
-    type: object
-    readOnly: true
-    additionalProperties: false
-    required: [kind, revision, locale, title, body, effectiveAt]
-    properties:
-      kind: { type: string, enum: [terms, privacy] }
-      revision: { type: string, minLength: 1, maxLength: 100 }
-      locale: { type: string }
-      title: { type: string, minLength: 1, maxLength: 200 }
-      body:
-        type: string
-        minLength: 1
-        x-mcp-hint: markdown
-        description:
-          en: Complete reviewed legal text in Markdown; placeholders are not acceptable.
-          zh-TW: 已審閱的完整 Markdown 法律正文，不得使用佔位文字。
-      effectiveAt: { type: string, format: date-time }
----
-# Public over a publishing Schema: drafts are never visible here.
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: current-legal-document }
-spec:
-  title:
-    en: Current legal document
-    zh-TW: 現行法律文件
-  description: The newest published revision of one legal document in one locale.
-  surface: public
-  input:
-    type: object
-    additionalProperties: false
-    required: [kind, locale]
-    properties:
-      kind: { type: string, enum: [terms, privacy] }
-      locale: { type: string }
-  sql: |
-    SELECT id, kind, revision, locale, title, body, effectiveAt, updated_at
-    FROM "legal-documents"
-    WHERE kind = input.kind AND locale = input.locale AND effectiveAt <= now()
-    ORDER BY effectiveAt DESC LIMIT 1
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: create-legal-document }
-spec:
-  title:
-    en: Create legal document revision
-    zh-TW: 建立法律文件修訂
-  description:
-    en: Supply the site's complete, reviewed legal text. Never create empty, placeholder, or agent-invented terms. Create a new revision instead of rewriting a published document accepted by users.
-    zh-TW: 請填入網站已審閱的完整法律正文。不得建立空白、佔位或由 agent 虛構的條款；已有使用者同意的已發佈文件應建立新修訂，不得覆寫。
-  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
-  input:
-    type: object
-    additionalProperties: false
-    required: [kind, revision, locale, title, body, effectiveAt]
-    properties:
-      kind: { type: string, enum: [terms, privacy] }
-      revision: { type: string, minLength: 1, maxLength: 100 }
-      locale: { type: string }
-      title: { type: string, minLength: 1, maxLength: 200 }
-      body:
-        type: string
-        minLength: 1
-        x-mcp-hint: markdown
-        description:
-          en: Complete reviewed legal text in Markdown; placeholders are not acceptable.
-          zh-TW: 已審閱的完整 Markdown 法律正文，不得使用佔位文字。
-      effectiveAt: { type: string, format: date-time }
-  output: { type: object }
-  handler:
-    sql: |
-      INSERT INTO "legal-documents" (kind, revision, locale, title, body, effectiveAt)
-      VALUES (input.kind, input.revision, input.locale, input.title, input.body, input.effectiveAt)
-      RETURNING id, revision
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: create-legal-document-staff }
-spec:
-  source: { kind: mcp, surface: staff }
-  target: { procedure: create-legal-document }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: legal-acceptances }
-spec:
-  title:
-    en: Legal acceptances
-    zh-TW: 法律文件同意紀錄
-  description:
-    en: Append-only receipts bound by the server to the signed-in user and acceptance time.
-    zh-TW: 由伺服器綁定登入使用者與同意時間的唯增紀錄。
-  lifecycle: operational
-  uniqueIndexes: [[documentId, userId]]
-  indexes: [[userId]]
-  schema:
-    type: object
-    readOnly: true
-    additionalProperties: false
-    required: [documentId, userId]
-    properties:
-      documentId: { type: string, x-mantle-ref: legal-documents }
-      userId: { type: string }
----
-# A conditional INSERT ... SELECT: it writes a receipt only for a published revision, and a repeat acceptance is ignored.
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: accept-legal-document }
-spec:
-  title:
-    en: Accept legal document
-    zh-TW: 同意法律文件
-  description:
-    en: Record the signed-in user's acceptance of one published legal document revision.
-    zh-TW: 記錄登入使用者對一份已發佈法律文件修訂的同意。
-  requires: { auth: { all: [ctx.user] } }
-  input:
-    type: object
-    additionalProperties: false
-    required: [documentId]
-    properties:
-      documentId: { type: string, x-mantle-ref: legal-documents }
-  output: { type: object }
-  handler:
-    sql: |
-      INSERT INTO "legal-acceptances" (documentId, userId)
-      SELECT d.id, auth.uid() FROM "legal-documents" d
-      WHERE d.id = input.documentId AND d.status = 'published'
-      ON CONFLICT (documentId, userId) DO NOTHING
-      RETURNING id
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: accept-legal-document-http }
-spec:
-  source: { kind: http, method: POST, path: /api/legal/acceptances }
-  target: { procedure: accept-legal-document }
-```
-
-How the guarantees are made:
-
-- **Who and when are the server's.** `accept-legal-document` writes
-  `auth.uid()` as `userId`, and the acceptance time is the native
-  `created_at`. The input carries only `documentId`.
-- **Only a published revision can be accepted.** The `INSERT … SELECT` writes
-  a row only when the document exists and is published. It is a set op, so
-  writing nothing is a normal result: `results` is `[[]]` for a draft, an
-  unknown id or a repeat acceptance. The client checks for a returned `id`.
-- **Revisions are immutable through generic surfaces.** The root
-  `readOnly: true` keeps Admin from offering generic edits, and the unique
-  `(kind, revision, locale)` index makes a new revision a new row. It is not a
-  storage lock: host code with `runtime.store` can still rewrite a row, so do
-  not write to this Schema from your own code.
-- **Agents are told not to invent terms.** The English Procedure description
-  is the staff MCP tool's description.
-- **`effectiveAt <= now()`** lets staff publish a revision ahead of the day it
-  takes effect.
-
-Do not add an MCP Trigger for `accept-legal-document`: accepting terms is an
-explicit action in the application's own interface.
-
-## Handlers
-
-None.
-
-## Serving the pages
-
-Serve `/terms` and `/privacy` from the service's own `fetch`: with the caller
-your `CallerResolver` returned, call
-`runtime.store.as(caller).view("current-legal-document", { input: { kind, locale } })`
-for the requested locale, fall back to the site's default
-locale, and render the Markdown as sanitized HTML. Answer with a clear
-unavailable page when no revision is published. The application owns the
-consent checkbox, sign-in, retention and export policy.
-
-## Source
-
-- [Publication](./publication.md): the localized publishing pattern
-- [Authorization](../handbook/concepts/authorization.md): server-bound identity