vybekiit 0.7.25 → 0.7.27

package/dist/global-skills/neon-functions/references/function-triggers.md

@@ -0,0 +1,249 @@
+# Function Triggers
+
+A Function Trigger is a branch-scoped rule that POSTs to a Neon Function so recurring work does not need a separate scheduler. The request is a normal `fetch` invocation: same public URL, same 15-minute time-to-first-byte limit, same injected env (`DATABASE_URL`, …).
+
+Same regions as Functions: `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`. Needs Neon CLI 4.21 or newer to declare triggers in `neon.ts`.
+
+If `neon deploy` returns 404 `function triggers not available for this project`, the project does not have Function Triggers yet. Deploy the function without applying the trigger (`neon functions deploy <slug> --src <entry>`) and retry `neon deploy` once the project has them.
+
+## Supported types
+
+`triggers` is a keyed map on `defineConfig`. Types:
+
+| `type`                   | When it fires                                      | `neon.ts` fields                         | CLI create                                      |
+| ------------------------ | -------------------------------------------------- | ---------------------------------------- | ----------------------------------------------- |
+| `schedule`               | On a five-field UTC cron expression                | `function`, `cron`                       | `neon triggers create --cron '…'`               |
+| `storage_object_created` | When an object is created in a declared bucket     | `function`, `bucket`, optional `prefix`  | `neon triggers create --bucket <name>`          |
+
+`create` takes `--cron` or `--bucket`, not both. `@neon/functions` ≥ 0.11.0: `parseTriggerDelivery` accepts both types; `parseTriggerInvocation` and Hono `parseTrigger(c)` stay schedule-only (`storage_object_created` is `invalid_body` there).
+
+## Fields
+
+The trigger name is the `neon.ts` map key (CLI `--name`). It must be unique among every trigger visible on the branch, including other functions.
+
+| Field          | Required | Notes                                                                 |
+| -------------- | -------- | --------------------------------------------------------------------- |
+| `type`         | yes      | `"schedule"` or `"storage_object_created"`                            |
+| `function`     | yes      | Function slug. REST/MCP: `function_slug`                              |
+| `cron`         | schedule | Five-field UTC expression, e.g. `0 * * * *`, `*/15 * * * *`           |
+| `bucket`       | storage  | Bucket name. REST: `storage_object_created.bucket_name`               |
+| `prefix`       | no       | Object-key prefix filter. REST: `storage_object_created.prefix`       |
+| `functionPath` | no       | Path on the function. Default `/`. CLI: `--function-path`             |
+| `enabled`      | no       | Default `true`. CLI: `--enabled false` to create disabled             |
+
+## neon.ts (preferred)
+
+Declare `triggers` next to `functions` (and `buckets` when using storage). `neon deploy` applies triggers **after** the functions they target. Triggers that exist remotely but are omitted from `neon.ts` are left alone.
+
+```typescript
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  functions: {
+    ingest: { name: "Object ingest", source: "src/index.ts" },
+    cron: { name: "Cron", source: "src/cron.ts" },
+  },
+  buckets: { assets: { access: "public_read" } },
+  triggers: {
+    "on-upload": {
+      type: "storage_object_created",
+      function: "ingest",
+      bucket: "assets",
+      prefix: "logos/",
+      functionPath: "/object",
+    },
+    "every-minute": {
+      type: "schedule",
+      function: "cron",
+      cron: "* * * * *",
+      functionPath: "/cron",
+    },
+  },
+});
+```
+
+```bash
+neon deploy
+```
+
+Change the cron string, bucket, or prefix and deploy again to reschedule. Starter: `neon bootstrap --template cron-job`.
+
+## CLI
+
+Use when you are not applying `neon.ts`, or to list, enable, disable, or delete.
+
+```bash
+neon triggers create --function-slug cron --name hourly --cron '0 * * * *' --function-path /cron
+neon triggers create --function-slug ingest --name on-upload --bucket assets --prefix 'logos/' --function-path /object
+neon triggers list
+neon triggers list --output json
+neon triggers update <id> --branch <branch> --cron '*/30 * * * *'
+neon triggers update <id> --branch <branch> --bucket assets --prefix 'incoming/'
+neon triggers enable <id> --branch <branch>
+neon triggers disable <id> --branch <branch>
+neon triggers delete <id> --branch <branch>
+```
+
+`enable` / `disable` wrap `update --enabled`. Updating the cron recomputes `Next Run At`. Disabling clears `Next Run At`. Alias: `neon trigger`. `--cron` on a storage trigger, or `--bucket` / `--prefix` on a schedule trigger, is rejected.
+
+Inspect a trigger with `neon triggers list --output json`. Pass `--branch` on get/update/enable/disable/delete: without it the CLI resolves the trigger id as a branch name.
+
+Project and branch otherwise resolve from `--project-id` / `--branch`, then `.neon`, then a single-project auto-detect.
+
+## MCP backup
+
+The Neon MCP server (`?category=functions`) exposes `list_triggers`, `get_trigger`, `create_trigger`, `update_trigger`, and `delete_trigger`. `branch_id` is a `br-…` id, not a branch name (`list_branches` to resolve). Create a schedule trigger with snake_case:
+
+```json
+{
+  "type": "schedule",
+  "function_slug": "cron",
+  "name": "hourly",
+  "function_path": "/cron",
+  "schedule": { "cron": "0 * * * *" },
+  "enabled": true
+}
+```
+
+`create_trigger` required fields for schedule: `type`, `function_slug`, `name`, `schedule`. REST is the same payload at `POST /projects/{project_id}/branches/{branch_id}/triggers`. For `storage_object_created`, use CLI or REST with `"type": "storage_object_created"` and `storage_object_created: { "bucket_name": "assets", "prefix": "logos/" }`. CLI docs: https://neon.com/docs/cli/triggers.md.
+
+## Delivery payload
+
+Neon POSTs JSON. The Functions proxy drops client-supplied `x-neon-*` headers, so a present `x-neon-trigger-invocation-id` is from a trigger delivery. It must match `invocation_id` in the body.
+
+A Function that also serves app or public HTTP must not apply JWT or `X-Secret` middleware to the trigger path. Neon trigger POSTs do not send those. Caller shapes: [production-hardening.md](production-hardening.md).
+
+Schedule wire JSON (snake_case):
+
+```json
+{
+  "version": 1,
+  "invocation_id": "…",
+  "trigger": {
+    "type": "schedule",
+    "id": "trigger-…",
+    "name": "hourly"
+  },
+  "data": { "scheduled_at": "2026-09-15T23:35:00Z" }
+}
+```
+
+Storage-object-created wire JSON:
+
+```json
+{
+  "version": 1,
+  "invocation_id": "…",
+  "trigger": {
+    "type": "storage_object_created",
+    "id": "trigger-…",
+    "name": "on-upload"
+  },
+  "data": { "bucket_name": "uploads", "object_key": "smoke.txt" }
+}
+```
+
+Parsed (`@neon/functions` ≥ 0.11.0) is camelCase. `parseTriggerDelivery` also sets a top-level `type`. Schedule: `data.scheduledAt`. Storage: `data.bucketName`, `data.objectKey`. Narrow on `invocation.type` (or `isScheduleTriggerInvocation` / `isStorageObjectCreatedTriggerInvocation`) before reading `data` — a check on `trigger.type` does not narrow the sibling `data` field.
+
+### `parseTriggerDelivery` (both types)
+
+```typescript
+import { parseTriggerDelivery } from "@neon/functions/triggers";
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const parsed = await parseTriggerDelivery(request);
+    if (!parsed.ok) {
+      const status = parsed.error === "invalid_body" ? 400 : 401;
+      return new Response(parsed.error, { status });
+    }
+
+    const invocation = parsed.invocation;
+    if (invocation.type === "storage_object_created") {
+      return Response.json({
+        bucketName: invocation.data.bucketName,
+        objectKey: invocation.data.objectKey,
+      });
+    }
+
+    return Response.json({
+      scheduledAt: invocation.data.scheduledAt,
+    });
+  },
+};
+```
+
+`parseTriggerDelivery(request)` clones the Request before `json()`, so `request.json()` still works. If you already have the body: `parseTriggerDelivery({ headers, body })` (sync). `parsed.error` is `missing_header`, `invalid_body`, or `invocation_id_mismatch`. Unknown `trigger.type` values fail as `invalid_body`.
+
+Hono: `parseTriggerDelivery(c.req.raw)`.
+
+### `parseTrigger` (Hono, schedule only)
+
+Throws `HTTPException`. `c.req.json()` still works afterwards. Returns `ScheduleTriggerInvocation`. A `storage_object_created` delivery is `invalid_body`.
+
+| Failure                  | Status | Message                                       |
+| ------------------------ | ------ | --------------------------------------------- |
+| missing header           | 401    | `Missing x-neon-trigger-invocation-id header` |
+| header ≠ `invocation_id` | 401    | `Invocation id mismatch`                      |
+| invalid JSON or payload  | 400    | `Invalid trigger payload`                     |
+
+```typescript
+import { parseTrigger } from "@neon/functions/hono";
+
+app.post("/cron", async (c) => {
+  const invocation = await parseTrigger(c);
+  return c.json({ ok: true, invocationId: invocation.invocationId });
+});
+```
+
+### `parseTriggerInvocation` (`fetch`, schedule only)
+
+```typescript
+import { parseTriggerInvocation } from "@neon/functions/triggers";
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const parsed = await parseTriggerInvocation(request);
+    if (!parsed.ok) {
+      const status = parsed.error === "invalid_body" ? 400 : 401;
+      return new Response(parsed.error, { status });
+    }
+    return Response.json({
+      ok: true,
+      invocationId: parsed.invocation.invocationId,
+    });
+  },
+};
+```
+
+## Local `neon dev`
+
+`neon dev` forwards `x-neon-trigger-invocation-id`, so you can simulate a tick:
+
+```bash
+curl -X POST http://localhost:8787/cron \
+  -H 'content-type: application/json' \
+  -H 'x-neon-trigger-invocation-id: local-dev' \
+  -d '{
+    "version": 1,
+    "invocation_id": "local-dev",
+    "trigger": { "type": "schedule", "id": "trigger-local", "name": "hourly" },
+    "data": { "scheduled_at": "2026-09-15T00:00:00Z" }
+  }'
+```
+
+A public POST to the **deployed** function that includes that header still returns 401: the proxy strips client `x-neon-*` headers.
+
+## Inheritance
+
+Triggers are branch-scoped. A trigger created on a parent is visible on children (`inherited: true`, `source_branch_id` points at the origin) and starts disabled there.
+
+`neon deploy` of a `neon.ts` that declares the same trigger (default `enabled: true`) enables that inherited copy on the child. Omit it from `neon.ts` to leave the inherited trigger disabled. Enable without applying `neon.ts` with `neon triggers enable <id> --branch <branch>`.
+
+## Logs
+
+```bash
+neon logs query --source function --since 1h
+```
+
+Pass `--branch` when the function is not on the branch in `.neon`.

package/dist/global-skills/neon-functions/references/mastra-studio.md

@@ -6,7 +6,7 @@ The shape mirrors any other Node integration (see [sentry.md](sentry.md)): insta
 
 ## 1. Define the agent against the Neon AI Gateway
 
-With `@mastra/core` 1.47+, use a `neon/<model>` magic string — Mastra reads `NEON_AI_GATEWAY_BASE_URL` and `NEON_AI_GATEWAY_TOKEN` from the environment (injected by `neon deploy` / `neon env pull` when `preview.aiGateway` is enabled in `neon.ts`). No manual `url`/`apiKey` or MLflow dialect swap is needed; Mastra routes each model to the correct gateway endpoint.
+With `@mastra/core` 1.47+, use a `neon/<model>` magic string — Mastra reads `NEON_AI_GATEWAY_BASE_URL` and `NEON_AI_GATEWAY_TOKEN` from the environment (injected by `neon deploy` / `neon env pull` when `aiGateway` is enabled in `neon.ts`). No manual `url`/`apiKey` or MLflow dialect swap is needed; Mastra routes each model to the correct gateway endpoint.
 
 ```typescript
 // src/mastra/agents/pricing.ts
@@ -102,8 +102,8 @@ functions: {
     name: "my app",
     source: "src/index.ts",
     env: {
-      MASTRA_PROJECT_ID: process.env.MASTRA_PROJECT_ID ?? "",
-      MASTRA_PLATFORM_ACCESS_TOKEN: process.env.MASTRA_PLATFORM_ACCESS_TOKEN ?? "",
+      MASTRA_PROJECT_ID: process.env.MASTRA_PROJECT_ID!,
+      MASTRA_PLATFORM_ACCESS_TOKEN: process.env.MASTRA_PLATFORM_ACCESS_TOKEN!,
     },
   },
 }

package/dist/global-skills/neon-functions/references/mcp.md

@@ -89,7 +89,7 @@ Key points:
 > [!WARNING]
 > A Neon Function has a **public HTTPS URL — anyone can reach it.** An unauthenticated MCP server hands every caller your tools (and the database behind them). Authenticate at the top of the handler before touching the transport, exactly as for [any client-facing function](../SKILL.md#functions-as-an-agent-backend-nextjs-and-similar-frameworks).
 
-[Better Auth](https://better-auth.com) (self-hostable, runs alongside your app) is a good fit, and it covers both common shapes. **Better Auth is evolving quickly** — the MCP plugin is moving out of `better-auth/plugins` into its own `@better-auth/mcp` package (built on the OAuth Provider plugin), which renames `withMcpAuth` → `requireMcpAuth` and `createMcpAuthClient` → `createMcpResourceClient`. Verify the current package and import paths against the [Better Auth MCP docs](https://better-auth.com/docs/plugins/mcp) before wiring it up.
+[Better Auth](https://better-auth.com) covers both common MCP shapes when you need an OAuth authorization server or API keys. Managed Auth does not. Keep existing app login (Clerk, Managed Auth, or Better Auth) unless the user asked to migrate it. Confirm the **installed** Better Auth version before copying imports: the MCP plugin is moving out of `better-auth/plugins` into `@better-auth/mcp` (`withMcpAuth` → `requireMcpAuth`, `createMcpAuthClient` → `createMcpResourceClient`). Docs: https://better-auth.com/docs/plugins/mcp
 
 ### Option 1 — OAuth via the Better Auth MCP plugin (best for third-party clients)
 

package/dist/global-skills/neon-functions/references/production-hardening.md

@@ -0,0 +1,340 @@
+# Production hardening for Neon Functions
+
+A Function has a public HTTPS URL. Authenticate the caller, then pick extra
+protection from who actually calls it. This file is the production path; JWT
+and trigger parsers stay in [SKILL.md](../SKILL.md) and
+[function-triggers.md](function-triggers.md).
+
+https://neon.com/docs/compute/functions/authentication.md
+
+## Choose the caller shape
+
+Pick a row before writing code. Mixed routes: apply the matching row per
+path, not one middleware for the whole Function.
+
+| Caller                                                                                                           | What to do                                                                                                                                                                                                                                        | Do not                                                                                                                                  |
+| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Trusted app server (Vercel/Netlify route, server action, queue worker) that finishes within that host's duration | The server calls the Function. Browser never sees the Function URL or the origin secret. Function returns 401 before any work.                                                                                                                    | Put the secret in client code. Proxy a long agent, WebSocket, or SSE stream through the app host without checking that host's duration. |
+| Function Triggers only                                                                                           | `parseTriggerDelivery` (both types). Keep this path outside JWT and `X-Secret` middleware.                                                                                                                                                        | Require a user JWT or `X-Secret` on the trigger path. Invent `x-neon-invocation-id`. Treat `invocation_id` as a secret.                 |
+| Public consumers (Open API, MCP, third-party HTTP)                                                               | A Cloudflare Worker Custom Domain you own, **not** registered as a Neon custom domain, proxies to the native invocation URL, sets `X-Secret`, and rate-limits at the edge. Function requires `X-Secret`, then the route's existing consumer auth. | Orange-cloud a Neon-registered custom-domain CNAME. Assume the native URL is closed. Put a human challenge in front of MCP.             |
+
+Browser-direct JWT agents stay on the client-direct path in SKILL.md. They
+are not the trusted-app-server row.
+
+## Native URL
+
+The native invocation URL stays reachable after you add a custom domain or a
+Worker. Application checks reject work; the request still occupies a Function
+invocation until the handler returns.
+
+Neon also enforces a default account-wide cap of 100 concurrent invocations
+(`429`, body `per-account concurrency limit reached`, `Retry-After` in
+seconds). That is not per-client DDoS protection.
+https://neon.com/docs/compute/functions/reference/runtime-limits.md
+
+Functions docs do not document a customer-configurable WAF, a switch to
+disable the native URL, or a Functions ingress IP allowlist. Do not invent
+those.
+
+## Trusted app server
+
+Keep the Function URL and origin secret in **server** env on the app host and
+in Function `env`. Authenticate the app route first. Then `fetch` the
+Function.
+
+Headers:
+
+```text
+X-Secret: <server-only origin secret>
+Authorization: <existing consumer credential, unchanged>
+```
+
+`X-Secret` is application-defined. Use it for the server hop when
+`Authorization` already carries a user or consumer bearer token.
+
+If the Function currently only checks `Authorization: Bearer <API_KEY>` and
+nothing forwards a user token, keep that check. Do not migrate that header.
+
+Compare `X-Secret` before parsing the body or touching Postgres. Missing
+`ORIGIN_SECRET` fails at startup. Do not add CORS if browsers must not call
+this Function.
+
+```typescript
+import { timingSafeEqual } from "node:crypto";
+
+const originSecret = process.env.ORIGIN_SECRET;
+if (!originSecret) throw new Error("ORIGIN_SECRET is required");
+const expected = Buffer.from(originSecret);
+
+function hasOriginSecret(request: Request): boolean {
+  const header = request.headers.get("x-secret");
+  if (header === null) return false;
+  const provided = Buffer.from(header);
+  if (provided.byteLength !== expected.byteLength) return false;
+  return timingSafeEqual(provided, expected);
+}
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    if (!hasOriginSecret(request)) {
+      return new Response("Unauthorized", { status: 401 });
+    }
+    return Response.json({ ok: true });
+  },
+};
+```
+
+Declare `ORIGIN_SECRET` in `neon.ts` `env` and on the app host.
+
+Buffer the incoming body on the app-server `fetch`. Node `fetch` throws
+`duplex option is required when sending a body` if you pass a streamed
+`request.body`. `duplex: "half"` is Node-only; this hop is short, so
+buffer instead. `redirect: "manual"` keeps `X-Secret` from following a
+cross-origin redirect.
+
+`NEON_FUNCTION_URL` is `invocation_url` from `neon functions get`. It ends
+with `/`. This example calls that root. For a Function path, concatenate
+onto that slash (`new URL("orders?limit=2", functionUrl)`). Do not copy the
+app request's host or pathname onto the Function; a Next.js `/api/...` route
+is not the Function path.
+
+```typescript
+const functionUrl = process.env.NEON_FUNCTION_URL;
+const originSecret = process.env.ORIGIN_SECRET;
+if (!functionUrl || !originSecret) {
+  throw new Error("NEON_FUNCTION_URL and ORIGIN_SECRET are required");
+}
+
+const headers = new Headers({ "x-secret": originSecret });
+const contentType = request.headers.get("content-type");
+if (contentType) headers.set("content-type", contentType);
+const authorization = request.headers.get("authorization");
+if (authorization) headers.set("authorization", authorization);
+
+return fetch(functionUrl, {
+  method: request.method,
+  headers,
+  body: request.body ? await request.arrayBuffer() : undefined,
+  redirect: "manual",
+});
+```
+
+## Function Triggers only
+
+Use the parsers in [function-triggers.md](function-triggers.md).
+`parseTriggerDelivery` covers `schedule` and `storage_object_created`.
+Hono `parseTrigger` and `parseTriggerInvocation` are schedule-only.
+
+Neon POSTs to the native URL and does not send `X-Secret` or a user JWT. A
+trigger path that requires those credentials drops real deliveries.
+
+`invocation_id` is a correlation id. Presence of `x-neon-trigger-invocation-id`
+after Neon strips client `x-neon-*` headers is the provenance check; matching
+the body is consistency. https://neon.com/docs/compute/functions/triggers/overview.md
+
+Local `neon dev` can send that header to simulate a tick. On the deployed
+Function a client-supplied `x-neon-*` header is stripped.
+
+## Public consumers through a Worker
+
+Consumers call a hostname you control. Volumetric filtering happens there.
+The Function still authenticates.
+
+DNS:
+
+- A Neon Function custom-domain CNAME must be DNS-only (grey cloud). A proxied
+  (orange-cloud) record blocks Neon domain validation.
+  https://neon.com/docs/compute/functions/custom-domains.md
+- Attach a [Cloudflare Worker Custom Domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/)
+  that is **not** registered with Neon. The Worker fetches the **native**
+  invocation URL.
+
+Worker:
+
+- Preserve method, pathname, query, body, and consumer `Authorization`.
+- Set `X-Secret`. Do not use it as the consumer credential.
+- Build the upstream URL from a fixed origin. Assign `pathname` and `search`
+  separately so a request path cannot change the authority.
+- Apply Cloudflare DDoS / WAF / rate-limiting rules on that Worker hostname.
+  The forwarding snippet does not configure those rules.
+- Disable the Worker's `workers.dev` route and Preview URLs. Hostname-scoped
+  rules do not apply to those endpoints, and they still run this forwarding
+  code. Inventory clients on those URLs first.
+  https://developers.cloudflare.com/workers/configuration/routing/workers-dev.md
+  Dashboard: Worker → Settings → Domains & Routes. A later Wrangler deploy
+  without `workers_dev: false` turns `workers.dev` back on.
+- Do not buffer a streaming body. Do not add a browser challenge MCP or API
+  clients cannot pass.
+
+Wrangler:
+
+```jsonc
+{
+  "workers_dev": false,
+  "preview_urls": false
+}
+```
+
+```typescript
+const FUNCTION_ORIGIN = "https://<invocation-host>"; // neon functions get
+
+export default {
+  async fetch(
+    request: Request,
+    env: { ORIGIN_SECRET: string },
+  ): Promise<Response> {
+    const incoming = new URL(request.url);
+    const upstream = new URL(FUNCTION_ORIGIN);
+    upstream.pathname = incoming.pathname;
+    upstream.search = incoming.search;
+
+    const headers = new Headers(request.headers);
+    headers.set("x-secret", env.ORIGIN_SECRET);
+    headers.delete("host");
+
+    return fetch(upstream, {
+      method: request.method,
+      headers,
+      body: request.body,
+      redirect: "manual",
+    });
+  },
+};
+```
+
+Function: require `X-Secret` first (same helper as above), then apply **that
+route's existing** consumer authentication. Browser preflight, OAuth
+discovery, and intentionally public routes keep their current behavior. An
+origin secret is not a user API key.
+
+Requiring `X-Secret` on the native URL is a migration. Move legitimate
+native-URL clients to the Worker first. Anyone who still hits the native URL
+without the secret gets 401 after the request has reached Function compute.
+
+HTTP-triggered Workers have no documented hard wall-clock duration while the
+client stays connected. Still verify WebSocket, SSE, and long agent streams
+against the chosen Worker before using this row for those workloads. If the
+edge cannot hold the stream, keep client-direct JWT.
+
+MCP: after switching consumers to the Worker hostname, confirm advertised
+resource URLs, token audiences, existing client registrations, and one live
+session as well as a fresh authorization. https://developers.cloudflare.com/workers/platform/limits/
+
+## Limit authenticated application work
+
+Edge rate limiting drops traffic before Neon. A limiter **inside** the
+Function runs after the request arrived. Use it to cap expensive work for a
+**verified** principal (user id, org id, API-key hash). Never use a
+caller-supplied id. A global budget can cap total capacity; one caller can
+consume it for everyone.
+
+Request-rate limits do not cap simultaneous long-running work. Bound in-flight
+expensive operations separately, in a shared store, not in module-scope
+counters (those are per-isolate and vanish on eviction).
+
+A query to Postgres on every anonymous request adds database work to a flood.
+Postgres can hold per-principal counters at low-to-moderate authenticated
+volume when you already have it; measure before relying on it. Prefer Redis
+or edge limits when a database round trip per request is too expensive.
+
+Optional Upstash quota after credential checks, before expensive work.
+`60` per minute and `timeout: 1_000` are example policy. `RATE_LIMIT_PREFIX`
+is the application + environment + quota name; `NEON_BRANCH` (a branch
+**name**) is appended so branches do not share counters.
+
+`Redis.fromEnv()` reads `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`.
+Upstash `reset` is milliseconds since epoch. Upstash can report a timeout as
+a successful `limit()` result; check `reason` before `success`. Await the
+admission decision; pass `pending` to `waitUntil` so background writes do not
+delay the response.
+
+```typescript
+import { waitUntil } from "@neon/functions";
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+
+const namespace = process.env.RATE_LIMIT_PREFIX;
+if (!namespace) throw new Error("RATE_LIMIT_PREFIX is required");
+
+const limiter = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(60, "1 m"),
+  prefix: `${namespace}:${process.env.NEON_BRANCH ?? "local"}`,
+  timeout: 1_000,
+  analytics: false,
+});
+
+export async function checkQuota(
+  authenticatedPrincipalId: string,
+): Promise<Response | null> {
+  let result: Awaited<ReturnType<typeof limiter.limit>>;
+  try {
+    result = await limiter.limit(authenticatedPrincipalId);
+  } catch (error) {
+    console.error("Rate-limit store failed", error);
+    return new Response("Rate limiter unavailable", {
+      status: 503,
+      headers: { "Retry-After": "1" },
+    });
+  }
+
+  waitUntil(result.pending);
+
+  if (result.reason === "timeout") {
+    console.error("Rate-limit store timed out");
+    return new Response("Rate limiter unavailable", {
+      status: 503,
+      headers: { "Retry-After": "1" },
+    });
+  }
+
+  if (result.success) return null;
+
+  const retryAfterSeconds = Math.max(
+    1,
+    Math.ceil((result.reset - Date.now()) / 1000),
+  );
+  return new Response("Too Many Requests", {
+    status: 429,
+    headers: {
+      "Retry-After": String(retryAfterSeconds),
+      "RateLimit-Limit": String(result.limit),
+      "RateLimit-Remaining": String(result.remaining),
+      "RateLimit-Reset": String(retryAfterSeconds),
+    },
+  });
+}
+```
+
+Preserve CORS headers on these responses when the route already sets them.
+Do not relabel limiter failures as `401` or as quota exhaustion. `Retry-After`
+is required on `429`. `RateLimit-*` is optional metadata; `RateLimit-Reset`
+here is seconds until the window renews.
+
+Do not rate-limit in the Function by `X-Forwarded-For`. That header is not a
+documented trustworthy client-IP on Functions. IP limits belong at the edge.
+
+## Preserve existing clients
+
+- Direct-client JWT agents keep their token, JWKS, issuer, and audience.
+  Do not require `X-Secret` on those routes.
+- CORS still has to succeed for legitimate browser origins, including on
+  401/429. CORS is not authentication.
+- Inventory production and preview origins before tightening an allowlist.
+- WebSocket and SSE handshake, heartbeat, and reconnect stay as documented
+  in SKILL.md.
+- MCP OAuth discovery, tokens, methods, and streaming stay as documented in
+  [mcp.md](mcp.md). Authenticate before the transport.
+- Adding a Worker does not by itself change the API's consumer credentials.
+- Stored rows stay authorized by the verified identity, not by a quota key.
+
+## Reject these
+
+- Orange-cloud proxying a **Neon-registered** custom-domain CNAME.
+- Shipping a server origin secret to the browser.
+- Putting a long stream behind a host or Worker whose duration or transport
+  cannot hold it.
+- Treating header/body equality as trigger provenance outside Neon's edge.
+- In-memory counters as a cross-isolate quota.
+- A Postgres lookup on every anonymous request as DDoS protection.
+- Treating a native-URL `401` as traffic blocked before Function compute.

package/dist/global-skills/neon-functions/references/sse.md

@@ -17,17 +17,20 @@ export default {
     const url = new URL(request.url);
     if (url.pathname !== "/events") return new Response("ok");
 
+    let timer: ReturnType<typeof setInterval>;
     const stream = new ReadableStream<Uint8Array>({
       start(controller) {
         // An SSE frame is `data: <payload>\n\n`. A line starting with `:` is a
         // comment — used here as a heartbeat to keep the stream from going idle.
         controller.enqueue(encoder.encode("data: hello\n\n"));
-        const timer = setInterval(
+        timer = setInterval(
           () => controller.enqueue(encoder.encode(": ping\n\n")),
           25_000,
         );
-        // cancel() fires when the client disconnects.
-        return () => clearInterval(timer);
+      },
+      // cancel() fires when the client disconnects.
+      cancel() {
+        clearInterval(timer);
       },
     });
 
@@ -42,7 +45,7 @@ export default {
 };
 ```
 
-> `cancel()` is returned from `start()` here for brevity; you can also declare it as a separate `cancel()` method on the stream's underlying source. Either way, use it to drop the client from any broadcast set and clear timers.
+> `cancel()` is a method on the stream's underlying source; it fires when the client disconnects. Use it to drop the client from any broadcast set and clear timers. A cleanup function returned from `start()` is ignored, so it has to be a real `cancel()` method.
 
 ## With Hono
 
@@ -91,7 +94,7 @@ const CHANNEL = "events";
 // One dedicated DIRECT connection per isolate to receive events (LISTEN needs a
 // real session — use DATABASE_URL_UNPOOLED, not the pooled URL).
 // Don't call attachDatabasePool here: it would silence the idle drop that killed the feed.
-// An error listener keeps the isolate alive; the feed stays down until the isolate restarts.
+// The error listener keeps the process alive; reconnect the client on error in production (omitted here).
 const listener = new Client({
   connectionString: process.env.DATABASE_URL_UNPOOLED,
 });