@palbase/backend 1.0.0 → 2.0.2

package/docs/llms-full.txt

@@ -0,0 +1,713 @@
+# Palbase Backend SDK (`@palbase/backend`)
+
+> File-based TypeScript backend SDK. Endpoints use `req` (PBRequest) + imported service singletons (`Database`, `Cache`, …). Workers/jobs/hooks/webhooks use a `ctx` object. Not Express, not Supabase Edge Functions.
+
+
+
+<!-- ===== README.md ===== -->
+
+# Palbase Backend SDK (`@palbase/backend`)
+
+Write your backend as TypeScript files. Palbase discovers them by path, runs
+them inside the managed backend runtime, and exposes them as a typed HTTP API.
+
+This is **not** Express, Fastify, or a Supabase Edge Function. There is no
+`app.get(...)`, no manual route registration, no `import express`. You export
+definitions; the runtime wires them up.
+
+## The two mental models (important)
+
+| You are writing… | Handler receives | Services come from |
+|------------------|------------------|--------------------|
+| **Endpoints** (`endpoints/**`) | a single `req` ([PBRequest](./endpoints.md)) | imported singletons: `import { Database } from "@palbase/backend"` |
+| **Workers, Jobs, Hooks, Webhooks** | a `ctx` object | `ctx.db`, `ctx.log`, `ctx.cache`, `ctx.queue` |
+
+Endpoints use `req` + imported singletons. Everything else uses `ctx`. Do not
+mix them: there is no `ctx` inside an endpoint handler, and no imported
+`Database` singleton call inside a worker (use `ctx.db`).
+
+## Project shape
+
+```
+my-backend/
+├── package.json            # depends on @palbase/backend
+├── endpoints/              # HTTP endpoints (file-based routing)
+│   └── hello/get.ts        # → GET /hello
+├── db/schema.ts            # table definitions (optional, enables typed DB)
+├── workers/                # background job handlers (optional)
+├── jobs/                   # cron-scheduled jobs (optional)
+├── hooks/                  # auth/storage/document event hooks (optional)
+├── webhooks/               # inbound provider webhooks (optional)
+└── middleware/             # cross-cutting request middleware (optional)
+```
+
+## Documentation
+
+| Topic | File |
+|-------|------|
+| Getting started | [getting-started.md](./getting-started.md) |
+| File-based routing | [routing.md](./routing.md) |
+| Endpoints & `req` | [endpoints.md](./endpoints.md) |
+| Database & transactions | [database.md](./database.md) |
+| Schema & typed DB | [schema.md](./schema.md) |
+| Services (Cache, Queue, Storage, …) | [services.md](./services.md) |
+| Errors | [errors.md](./errors.md) |
+| Workers & Jobs | [background.md](./background.md) |
+| Hooks & Webhooks | [events.md](./events.md) |
+
+For AI coding tools: a single concatenated corpus is generated at
+[`llms-full.txt`](./llms-full.txt) (and an index at [`llms.txt`](./llms.txt)).
+
+
+
+<!-- ===== getting-started.md ===== -->
+
+# Getting started
+
+There is no CLI init command. A starter project is created for you when your
+Palbase project is provisioned. You then edit the files locally and deploy them.
+
+## package.json
+
+Your project depends on the SDK and uses the Palbase CLI for the dev loop:
+
+```json
+{
+  "name": "my-backend",
+  "private": true,
+  "scripts": {
+    "dev": "palbase serve",
+    "deploy": "palbase push",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": { "@palbase/backend": "latest" },
+  "devDependencies": { "@types/node": "^22", "typescript": "^5" }
+}
+```
+
+## Local dev loop
+
+- `palbase serve` — run your backend locally with hot reload.
+- `palbase push` — deploy the current directory to your project's backend runtime.
+- `palbase push --branch <name>` — deploy to a branch instead of `main`.
+
+## Your first endpoint
+
+Create `endpoints/hello/get.ts`:
+
+```ts
+import { defineEndpoint, z } from "@palbase/backend";
+
+export default defineEndpoint({
+  method: "GET",
+  input: z.object({ name: z.string().optional() }),
+  output: z.object({ message: z.string(), user: z.string().nullable() }),
+  handler: async (req) => ({
+    message: `hello, ${req.input.name ?? "world"}!`,
+    user: req.user?.id ?? null,
+  }),
+});
+```
+
+This is served at `GET /hello`. The Zod `input` schema validates the request and
+flows into `req.input`; the `output` schema validates your return value.
+
+
+
+<!-- ===== routing.md ===== -->
+
+# File-based routing
+
+The path of a file under `endpoints/` plus its filename determine the route.
+The filename is the HTTP method.
+
+| File | Route |
+|------|-------|
+| `endpoints/hello/get.ts` | `GET /hello` |
+| `endpoints/items/post.ts` | `POST /items` |
+| `endpoints/posts/[id]/get.ts` | `GET /posts/:id` |
+| `endpoints/posts/[id]/patch.ts` | `PATCH /posts/:id` |
+| `endpoints/rooms/[id]/sessions/post.ts` | `POST /rooms/:id/sessions` |
+
+Rules:
+
+- The method file name is one of `get`, `post`, `put`, `patch`, `delete` (`.ts`).
+- A `[segment]` directory becomes a `:segment` path param, read via `req.params.segment`.
+- Each method file `export default defineEndpoint({...})` — one endpoint per file.
+- There is no central router file and no manual registration. Adding a file adds a route.
+
+```ts
+// endpoints/posts/[id]/get.ts  → GET /posts/:id
+import { defineEndpoint, z, Database, HttpError } from "@palbase/backend";
+
+export default defineEndpoint({
+  method: "GET",
+  output: z.object({ id: z.string(), title: z.string() }),
+  handler: async (req) => {
+    const post = await Database.findById("posts", req.params.id!);
+    if (!post) throw new HttpError(404, "post_not_found", "No such post");
+    return { id: post.id as string, title: post.title as string };
+  },
+});
+```
+
+
+
+<!-- ===== endpoints.md ===== -->
+
+# Endpoints
+
+An endpoint is `export default defineEndpoint({...})` in a method file. The
+handler receives **one argument**, `req` (a `PBRequest`). Services are NOT on
+`req` — import them as singletons (see [services.md](./services.md)).
+
+## `defineEndpoint` config
+
+```ts
+defineEndpoint({
+  method: "POST",                    // required: GET | POST | PUT | PATCH | DELETE
+  auth: { required: true },          // optional; see Auth below. Omitted → public.
+  rateLimit: { max: 100, window: 60 }, // optional: max requests per window seconds
+  input: z.object({ ... }),          // optional Zod schema → validates & types req.input
+  output: z.object({ ... }),         // optional Zod schema → validates the return value
+  errors: { ... },                   // optional declared errors (see errors.md)
+  middleware: [ ... ],               // optional Middleware[] (see below)
+  handler: async (req) => { ... },   // required
+});
+```
+
+## `req` (PBRequest)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `req.input` | inferred from `input` schema | request body for POST/PUT/PATCH; `{}` otherwise |
+| `req.params` | `Record<string,string>` | route params, e.g. `req.params.id` |
+| `req.query` | `Record<string,string>` | parsed query string |
+| `req.headers` | `Record<string,string>` | lowercase keys |
+| `req.user` | `User` when authenticated; `User \| null` when `auth` is omitted or `required: false` | see Auth below |
+| `req.client` | `ClientInfo` | calling SDK/app/platform/os version (all nullable) |
+| `req.file` | `FileContext \| null` | uploaded file, if any |
+| `req.method` | `string` | the HTTP method |
+| `req.requestId` / `req.traceId` / `req.spanId` | `string` | correlation ids |
+| `req.errors` | typed throwers | present when `errors` is declared (see errors.md) |
+
+`User` is `{ id: string; email: string; role: string; metadata: Record<string, unknown> }`.
+
+## Auth
+
+```ts
+auth: { required: true }                // require any authenticated user → req.user is non-null User
+auth: { required: true, role: "admin" } // require a specific role
+auth: { required: false }               // public → req.user may be null
+// auth omitted entirely                 // also public → req.user is User | null
+```
+
+Whether `req.user` is non-null is computed from the `auth` config at the type
+level:
+
+| `auth` value | `req.user` type |
+|--------------|-----------------|
+| omitted | `User \| null` |
+| `true` | `User` |
+| `false` | `User \| null` |
+| `{ required: true }` | `User` |
+| `{ required: false }` | `User \| null` |
+| `{ role: "admin" }` (object, no `required`) | `User` |
+
+To enforce authentication, set `auth: { required: true }` (or `auth: true`). An
+object with a `role` but no `required` key is treated as authenticated. When
+`auth` is omitted, the endpoint is public and `req.user` may be null.
+
+## Typed input/output
+
+```ts
+import { defineEndpoint, z, Database } from "@palbase/backend";
+
+export default defineEndpoint({
+  method: "POST",
+  auth: { required: true },
+  input: z.object({ name: z.string().min(1).max(100), capacity: z.number().int().positive().optional() }),
+  output: z.object({ id: z.string(), name: z.string(), capacity: z.number().nullable() }),
+  handler: async (req) => {
+    const room = await Database.insert("rooms", {
+      name: req.input.name,
+      capacity: req.input.capacity ?? null,
+    });
+    return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
+  },
+});
+```
+
+## Middleware
+
+A middleware wraps a request. Define one in `middleware/<name>.ts`:
+
+```ts
+// middleware/logger.ts
+import { defineMiddleware } from "@palbase/backend";
+
+export default defineMiddleware(async (ctx, next) => {
+  ctx.log.info(`start ${ctx.requestId}`);
+  await next();
+  ctx.log.info(`done ${ctx.requestId}`);
+});
+```
+
+The middleware handler receives `(ctx, next)` — call `await next()` to run the
+rest of the chain (other middleware, then the endpoint handler). Note this uses
+the `ctx` model, not `req`.
+
+To attach middleware to a specific endpoint, import it and list it in the
+endpoint's `middleware` array:
+
+```ts
+import { defineEndpoint, z } from "@palbase/backend";
+import logger from "../../middleware/logger.js";
+
+export default defineEndpoint({
+  method: "GET",
+  middleware: [logger],
+  output: z.object({ ok: z.boolean() }),
+  handler: async (req) => ({ ok: true }),
+});
+```
+
+
+
+<!-- ===== database.md ===== -->
+
+# Database
+
+In **endpoints**, import the `Database` singleton:
+
+```ts
+import { Database } from "@palbase/backend";
+```
+
+In **workers, jobs, hooks, and webhooks**, use `ctx.db` — the same surface,
+reached via the context object (see [background.md](./background.md) and
+[events.md](./events.md)).
+
+## Operations
+
+| Method | Returns |
+|--------|---------|
+| `Database.insert(table, data)` | the inserted row (`Record<string, unknown>`) |
+| `Database.update(table, id, data)` | the updated row |
+| `Database.delete(table, id)` | `void` |
+| `Database.findById(table, id)` | the row or `null` |
+| `Database.findMany(table, query?)` | matching rows (array) |
+| `Database.query(sql, params?)` | rows from a read-only SQL query (runs in a READ ONLY transaction) |
+| `Database.transaction(fn)` | runs `fn(tx)` in a transaction |
+
+```ts
+const row = await Database.insert("todos", { title: "buy milk", done: false });
+const one = await Database.findById("todos", row.id as string);
+const open = await Database.findMany("todos", { done: false });
+await Database.update("todos", row.id as string, { done: true });
+await Database.delete("todos", row.id as string);
+```
+
+`findMany`'s `query` is an equality filter: keys are ANDed together. For
+anything richer (ranges, ordering, joins) use `Database.query`.
+
+`Database.query` is **read-only** — use it for selects/joins the helpers don't
+cover. Writes must go through `insert`/`update`/`delete` or a transaction.
+
+```ts
+const rows = await Database.query(
+  "SELECT id, title FROM todos WHERE done = $1 ORDER BY created_at DESC LIMIT $2",
+  [false, 20],
+);
+```
+
+## Transactions
+
+`transaction(fn)` gives you a `tx` with the same DB ops (no nested
+transaction). Returning commits; throwing rolls back.
+
+```ts
+await Database.transaction(async (tx) => {
+  const order = await tx.insert("orders", { amount: 1000, status: "pending" });
+  await tx.insert("order_items", { order_id: order.id, sku: "ABC" });
+  // throw here → both inserts roll back
+});
+```
+
+For a typed `.tables.*` API instead of string table names, see
+[schema.md](./schema.md).
+
+
+
+<!-- ===== schema.md ===== -->
+
+# Schema & typed database access
+
+Declare your tables in `db/schema.ts` with `defineSchema`. This drives
+migrations and, via `typedDatabase`, a fully-typed `.tables.*` API.
+
+## Defining a schema
+
+```ts
+import {
+  defineSchema, table,
+  uuid, text, integer, boolean, timestamp, jsonb, enumType,
+} from "@palbase/backend";
+
+export default defineSchema({
+  rooms: table("rooms", {
+    id: uuid().primaryKey().defaultRandom(),
+    name: text().notNull(),
+    capacity: integer().nullable(),
+    is_active: boolean().default(true),
+    created_at: timestamp().defaultNow(),
+  }),
+  sessions: table("sessions", {
+    id: uuid().primaryKey().defaultRandom(),
+    room_id: uuid().notNull().references("rooms", "id").onDelete("cascade"),
+    user_id: uuid().notNull(),
+    data: jsonb().nullable(),
+    started_at: timestamp().defaultNow(),
+  }),
+  orders: table("orders", {
+    id: uuid().primaryKey().defaultRandom(),
+    status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
+    amount: integer().notNull(),
+  }),
+});
+```
+
+## Column builders
+
+| Builder | Postgres type |
+|---------|---------------|
+| `uuid()` | `uuid` |
+| `text()` | `text` |
+| `integer()` | `integer` |
+| `boolean()` | `boolean` |
+| `timestamp()` | `timestamptz` |
+| `jsonb()` | `jsonb` |
+| `enumType(name, values)` | a Postgres enum |
+
+Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
+`.default(value)`, `.defaultRandom()` (uuid → `gen_random_uuid()`),
+`.defaultNow()` (timestamp → `now()`), `.references(table, column)`,
+`.onDelete("cascade" | "set null" | "restrict" | "no action")`.
+
+## Typed DB access
+
+`typedDatabase(schema)` returns a typed facade. `insert` demands the right
+columns; rows come back typed; nullable columns are `T | null`.
+
+```ts
+import { defineEndpoint, z, typedDatabase } from "@palbase/backend";
+import schema from "../../db/schema.js";
+
+const Db = typedDatabase(schema);
+
+export default defineEndpoint({
+  method: "POST",
+  input: z.object({ name: z.string() }),
+  output: z.object({ id: z.string(), name: z.string() }),
+  handler: async (req) => {
+    const room = await Db.tables.rooms.insert({ name: req.input.name });
+    return { id: room.id, name: room.name };
+  },
+});
+```
+
+Note the `.js` extension on `../../db/schema.js` even though the file is
+`db/schema.ts` — this is standard ESM module resolution; you still author the
+file as `.ts`.
+
+`Db.tables.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
+`findById(id)`, `findMany(query?)`, and `Db.transaction(fn)` mirrors the
+untyped transaction with typed tables.
+
+
+
+<!-- ===== services.md ===== -->
+
+# Services
+
+In **endpoints**, import service singletons from `@palbase/backend`. In
+**workers/jobs/hooks/webhooks**, the equivalents live on `ctx` (`ctx.cache`,
+`ctx.queue`, `ctx.log`, `ctx.db`).
+
+Available singletons: `Database`, `Documents`, `Storage`, `Cache`, `Queue`,
+`Log`, `Notifications`, `Flags`.
+
+**Not available to backend handlers** (do not import them here): Realtime,
+Functions, CMS, Links, Analytics, and Auth. Auth runs on the client SDK; the
+others are out of scope for backend endpoints.
+
+## Cache
+
+JSON-typed key/value cache.
+
+```ts
+import { Cache } from "@palbase/backend";
+
+await Cache.set("k", { hits: 1 }, 60);     // value + TTL seconds
+const v = await Cache.get<{ hits: number }>("k"); // typed, null on miss
+await Cache.incr("counter");
+await Cache.del("k");
+
+// Stampede-safe read-through: only one caller across all pods runs fn.
+const profile = await Cache.getOrSet("user:42", 300, async () => {
+  return Database.findById("users", "42");
+});
+```
+
+`getOrSet` caches whatever `fn` returns, including `null` — return a sentinel or
+guard upstream if you don't want misses cached.
+
+## Queue
+
+Enqueue work for a worker (see [background.md](./background.md)).
+
+```ts
+import { Queue } from "@palbase/backend";
+const { jobId } = await Queue.push("process-order", { orderId: "ord_1", amount: 1000 });
+```
+
+## Log
+
+```ts
+import { Log } from "@palbase/backend";
+Log.info("created order", { orderId });
+Log.warn("retrying");
+Log.error("failed", err);
+Log.debug("detail");
+```
+
+## Storage
+
+Bucket-scoped file operations.
+
+```ts
+import { Storage } from "@palbase/backend";
+const bucket = Storage.bucket("avatars");
+const { data, error } = await bucket.upload("u/42.png", file);
+const { data: signed } = await bucket.createSignedUrl("u/42.png", 3600);
+const pub = bucket.getPublicUrl("u/42.png");        // sync, no network
+await bucket.remove(["u/42.png"]);
+```
+
+All Storage calls return `{ data, error }` — check `error` before using `data`.
+
+## Documents
+
+Firestore-like document store.
+
+```ts
+import { Documents } from "@palbase/backend";
+const col = Documents.collection("rooms");
+const { data: ref } = await col.add({ name: "Lobby" });
+const snap = await col.where("active", "==", true).orderBy("name").limit(10).get();
+const { data: doc } = await Documents.doc("rooms/abc").get();
+```
+
+## Notifications
+
+```ts
+import { Notifications } from "@palbase/backend";
+await Notifications.email.send({ /* PalbaseEmailSendParams */ });
+await Notifications.push.send({ /* PalbasePushSendParams */ });
+await Notifications.sms.send({ /* PalbaseSmsSendParams */ });
+```
+
+## Flags
+
+```ts
+import { defineEndpoint, z, Flags } from "@palbase/backend";
+
+export default defineEndpoint({
+  method: "GET",
+  auth: { required: true },           // req.user is non-null here
+  output: z.object({ enabled: z.boolean() }),
+  handler: async (req) => {
+    const { data: enabled } = await Flags.isEnabled("new-checkout", { userId: req.user.id });
+    const { data: variant } = await Flags.getVariant("button-color", { userId: req.user.id });
+    return { enabled: enabled ?? false };
+  },
+});
+```
+
+
+
+<!-- ===== errors.md ===== -->
+
+# Errors
+
+Two ways to fail a request. Both serialize to the standard Palbase error
+envelope:
+
+```json
+{ "error": "todo_not_found", "error_description": "No such todo", "status": 404, "request_id": "req_…" }
+```
+
+## 1. `HttpError` (ad-hoc)
+
+```ts
+import { HttpError } from "@palbase/backend";
+throw new HttpError(404, "todo_not_found", "No such todo");
+// optional structured payload (4th arg) rides along under `data`:
+throw new HttpError(423, "todo_locked", "Locked", { retryAfter: 30 });
+```
+
+`new HttpError(status, code, description, data?)`.
+
+## 2. Declared errors (typed)
+
+Declare them on the endpoint; throw via `req.errors.<name>(...)`. Declared
+errors are described in the endpoint's OpenAPI and codegen'd into a typed enum
+for iOS callers.
+
+```ts
+import { defineEndpoint, z, Database } from "@palbase/backend";
+
+export default defineEndpoint({
+  method: "POST",
+  input: z.object({ id: z.string() }),
+  output: z.object({ ok: z.boolean() }),
+  errors: {
+    notFound: { status: 404, code: "todo_not_found", description: "No such todo" },
+    locked: { status: 423, code: "todo_locked", data: z.object({ retryAfter: z.number() }) },
+  },
+  handler: async (req) => {
+    const todo = await Database.findById("todos", req.input.id);
+    if (!todo) throw req.errors.notFound();              // no data → no args
+    if (todo.locked) throw req.errors.locked({ retryAfter: 30 }); // data schema → required arg
+    return { ok: true };
+  },
+});
+```
+
+A declared error with a `data` Zod schema requires that payload as an argument;
+one without `data` takes no arguments. This is enforced by the types.
+
+
+
+<!-- ===== background.md ===== -->
+
+# Workers & Jobs
+
+Workers and jobs use the **`ctx` model**: their handler receives a context
+object with `ctx.db`, `ctx.log`, `ctx.cache`, `ctx.queue`, `ctx.env`. They do
+**not** receive a `req`, and you do **not** import the `Database` singleton
+inside them — use `ctx.db`.
+
+## Workers (queue consumers)
+
+A worker processes jobs pushed via `Queue.push(name, payload)`. File lives under
+`workers/`.
+
+```ts
+// workers/process-order.ts
+import { defineWorker } from "@palbase/backend";
+
+interface OrderPayload { orderId: string; amount: number; }
+
+export default defineWorker<OrderPayload>({
+  name: "process-order",       // must match the Queue.push() name
+  retry: 5,                    // optional, default 3
+  timeout: 60,                 // optional, seconds
+  backoff: "exponential",      // "exponential" | "linear" | "fixed", default exponential
+  handler: async (ctx, payload) => {
+    ctx.log.info(`processing ${payload.orderId} for $${payload.amount}`);
+    await ctx.db.update("orders", payload.orderId, { status: "processed" });
+  },
+});
+```
+
+Enqueue from an endpoint:
+
+```ts
+import { Queue } from "@palbase/backend";
+await Queue.push("process-order", { orderId: "ord_1", amount: 1000 });
+```
+
+## Jobs (cron-scheduled)
+
+A job runs on a cron schedule. File lives under `jobs/`.
+
+```ts
+// jobs/cleanup.ts
+import { defineJob } from "@palbase/backend";
+
+export default defineJob({
+  name: "cleanup-expired",
+  schedule: "0 3 * * *",       // standard cron
+  timeout: 120,                // optional, seconds
+  handler: async (ctx) => {
+    const expired = await ctx.db.findMany("sessions", { expired: true });
+    for (const s of expired) await ctx.db.delete("sessions", s.id as string);
+    ctx.log.info(`cleaned ${expired.length} sessions`);
+  },
+});
+```
+
+
+
+<!-- ===== events.md ===== -->
+
+# Hooks & Webhooks
+
+Like workers/jobs, hooks and webhooks use the **`ctx` model** (`ctx.db`,
+`ctx.log`, `ctx.cache`, `ctx.queue`, `ctx.env`) — not `req`, and not imported
+singletons.
+
+## Hooks (platform events)
+
+React to auth, storage, and document events. Files live under `hooks/`. Builders
+are imported from `@palbase/backend`: `auth`, `storage`, `documents`.
+
+```ts
+// hooks/auth.ts
+import { auth } from "@palbase/backend";
+
+export const onUserCreated = auth.onUserCreated(async (ctx, event) => {
+  ctx.log.info(`new user: ${event.user.email}`);
+  await ctx.db.insert("profiles", {
+    user_id: event.user.id,
+    email: event.user.email,
+  });
+});
+
+export const onSignIn = auth.onSignIn(async (ctx, event) => {
+  ctx.log.info(`sign in: ${event.user.email} via ${event.provider}`);
+});
+```
+
+Available hook builders: `auth.onUserCreated`, `auth.onSignIn`, `auth.onSignOut`,
+`auth.onPasswordReset`, `storage.onFileUploaded`, `storage.onFileDeleted`,
+`documents.onDocumentCreated`, `documents.onDocumentUpdated`,
+`documents.onDocumentDeleted`.
+
+## Webhooks (inbound provider events)
+
+Receive and verify webhooks from third-party providers. Files live under
+`webhooks/`.
+
+```ts
+// webhooks/stripe.ts
+import { defineWebhook } from "@palbase/backend";
+
+export default defineWebhook({
+  provider: "stripe",
+  secret: { env: "STRIPE_WEBHOOK_SECRET" },   // signing secret resolved from env
+  events: {
+    "checkout.session.completed": async (ctx, event) => {
+      await ctx.db.insert("orders", { status: "paid", data: event });
+    },
+    "payment_intent.payment_failed": async (ctx, event) => {
+      ctx.log.error("payment failed");
+      await ctx.db.insert("payment_failures", { data: event });
+    },
+  },
+});
+```
+
+The signing secret is read from the project's env/secrets (`{ env: "NAME" }`);
+the runtime verifies the signature before dispatching to your event handlers.