@luanpdd/kit-mcp 1.29.0 → 1.30.0

package/kit/skills/supabase-edge-functions/SKILL.md

@@ -1,242 +1,330 @@
 ---
 name: supabase-edge-functions
-description: Use ao escrever Edge Functions — Deno + imports npm:/jsr: (NUNCA bare), Deno.serve, env vars pre-populadas, file writes APENAS em /tmp, EdgeRuntime.waitUntil.
+description: Use ao escrever Edge Functions Supabase — Deno + imports versionados npm:/jsr:/node:, env vars 2026 (JSON dict SUPABASE_PUBLISHABLE_KEYS/SUPABASE_SECRET_KEYS), per-function deno.json, config.toml por função (verify_jwt, entrypoint, static_files), file writes APENAS em /tmp ou /s3/<bucket>, EdgeRuntime.waitUntil, CORS via @supabase/supabase-js/cors v2.95+.
 ---
 
-# Supabase — Edge Functions (Deno)
+# Supabase — Edge Functions (Deno) · 2026
 
 ## Quando usar
 
-LLM carrega esta skill quando criar, editar ou debugar Supabase Edge Functions (Deno runtime). Trigger phrases:
+LLM carrega esta skill quando criar, editar ou debugar Supabase Edge Functions. Trigger phrases:
 
 - "criar Edge Function", "Supabase functions"
-- "Deno + Supabase"
-- "supabase functions deploy"
-- "Edge Function background task"
-- "import npm: jsr: em Edge Function"
+- "Deno + Supabase", "supabase functions deploy/serve"
+- "Edge Function background task", "EdgeRuntime.waitUntil"
+- "import npm: jsr: node: em Edge Function"
+- "deno.json per function", "config.toml functions"
+
+> **Cross-refs canônicos v1.30:**
+> - Auth modes / `@supabase/server` → [`supabase-edge-functions-auth`](../supabase-edge-functions-auth/SKILL.md)
+> - Tests / Chrome DevTools debug → [`supabase-edge-functions-testing`](../supabase-edge-functions-testing/SKILL.md)
+> - `Supabase.ai.Session`, /s3, WebSockets, Wasm, regional → [`supabase-edge-runtime-builtins`](../supabase-edge-runtime-builtins/SKILL.md)
+> - Limits / status codes / `RateLimitError` → [`supabase-edge-functions-limits`](../supabase-edge-functions-limits/SKILL.md)
+> - MCP server pattern (mcp-lite) → [`supabase-edge-functions-mcp-server`](../supabase-edge-functions-mcp-server/SKILL.md)
+> - Glossário CLI → [`_shared-supabase/glossary.md`](../_shared-supabase/glossary.md)
 
 ## Regras absolutas
 
 - **Runtime é Deno**, não Node.js. Use APIs Deno (`Deno.serve`, `Deno.env`, `Deno.writeTextFile`).
-- **Imports SEMPRE com `npm:` ou `jsr:`** prefix. **NUNCA** bare specifiers (`import x from 'pkg'` falha em runtime).
-- **Use versão pinada** nos imports — `npm:hono@4.6.7`, `npm:@supabase/supabase-js@2`. Sem version, runtime resolve para latest e quebra em deploy.
-- **Env vars pre-populadas** (não definir manualmente):
+- **Imports SEMPRE com `npm:`, `jsr:` ou `node:`** prefix. **NUNCA** bare specifiers — falha em runtime.
+- **Versão pinada obrigatória** — `npm:hono@4.6.14`, `npm:@supabase/supabase-js@2.95.0`. Sem version, latest pode quebrar deploy.
+- **Env vars 2026 (JSON dict)** — pre-populadas no runtime hospedado:
   - `SUPABASE_URL`
-  - `SUPABASE_PUBLISHABLE_KEYS` (anon key — para client-side context)
-  - `SUPABASE_SECRET_KEYS` (service role — server-side only)
-  - `SUPABASE_DB_URL` (conexão direta ao Postgres)
-- Para outros secrets, set via `supabase secrets set --env-file path/to/.env`.
-- **`Deno.serve`** é o entry point canônico. **Nunca** `addEventListener('fetch')` (deprecated) ou `serve` de `https://deno.land/std@0.168.0/http/server.ts` (não usar).
-- **File writes APENAS em `/tmp`** — qualquer outro path é read-only.
-- Para tarefas em background após resposta, use **`EdgeRuntime.waitUntil(promise)`**. Sem isso, função termina antes da promise.
-- Multi-rota com Hono ou Express deve **prefixar** todas as rotas com `/<function-name>` (ex: `/my-function/users`) — sem prefix, request 404 quando deployada.
+  - `SUPABASE_PUBLISHABLE_KEYS` — **JSON dict**. `JSON.parse(...)['default']` para chave anon padrão.
+  - `SUPABASE_SECRET_KEYS` — **JSON dict** (service role). Idem. Server-side only.
+  - `SUPABASE_DB_URL` — Postgres direto.
+  - `SUPABASE_JWKS` — JWK Set para verificar JWTs.
+  - `SB_REGION`, `SB_EXECUTION_ID`, `DENO_DEPLOYMENT_ID` — runtime metadata.
+  - Legacy (ainda funcionam, evitar em código novo): `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`.
+- **Outros secrets:** `supabase secrets set --env-file path/to/.env` (max 100, 48 KiB cada, nome NÃO pode começar com `SUPABASE_`).
+- **`Deno.serve`** é o entry point canônico. **Nunca** `addEventListener('fetch')` (deprecated) ou `serve` legado de `deno.land/std`.
+- **File writes:** APENAS `/tmp` (ephemeral) ou `/s3/<bucket-name>/...` (persistent S3FS — ver [`supabase-edge-runtime-builtins`](../supabase-edge-runtime-builtins/SKILL.md)). Qualquer outro path é read-only.
+- **Background work:** `EdgeRuntime.waitUntil(promise)`. Sem isso, função termina antes da promise.
+- **Multi-rota:** prefixar todas as rotas com `/<function-name>` (Hono `basePath('/api')`). Sem prefix, request 404 em produção.
+- **CORS (v2.95.0+):** importar `corsHeaders` direto do SDK — `import { corsHeaders } from 'npm:@supabase/supabase-js@2.95.0/cors'`. Mantém-se sincronizado com novos headers do SDK automaticamente.
 
 ## Patterns canônicos
 
-### Função básica — Deno.serve + npm: import
+### Pattern 1 — Função básica com env vars 2026
 
 ```ts
 // supabase/functions/hello/index.ts
-// PT-BR: imports versionados sempre com npm:
-import { createClient } from 'npm:@supabase/supabase-js@2'
+// PT-BR: imports versionados + JSON dict de secret keys
+import { createClient } from 'npm:@supabase/supabase-js@2.95.0'
 
-Deno.serve(async (req) => {
-  const supabase = createClient(
-    Deno.env.get('SUPABASE_URL')!,
-    Deno.env.get('SUPABASE_SECRET_KEYS')!   // service role server-side
-  )
+const SUPABASE_SECRET_KEYS = JSON.parse(Deno.env.get('SUPABASE_SECRET_KEYS')!)
 
-  const { data, error } = await supabase
-    .from('tasks')
-    .select('id, title')
-    .limit(10)
+const supabase = createClient(
+  Deno.env.get('SUPABASE_URL')!,
+  // PT-BR: 'default' é a chave canônica; multi-key permite scoping (ex: 'automations')
+  SUPABASE_SECRET_KEYS['default'],
+)
 
+Deno.serve(async (req) => {
+  const { data, error } = await supabase.from('tasks').select('id, title').limit(10)
   if (error) {
     return new Response(JSON.stringify({ error: error.message }), {
       status: 500,
       headers: { 'Content-Type': 'application/json' },
     })
   }
-
-  return new Response(JSON.stringify(data), {
-    headers: { 'Content-Type': 'application/json' },
-  })
+  return Response.json(data)
 })
 ```
 
-### Background task com `EdgeRuntime.waitUntil`
+### Pattern 2 — CORS canônico (v2.95+)
 
 ```ts
-// supabase/functions/audit-log/index.ts
-// PT-BR: responde rápido, processa pesado em background
+// PT-BR: import corsHeaders do SDK — auto-sync com novos headers em releases futuras
+import { corsHeaders } from 'npm:@supabase/supabase-js@2.95.0/cors'
 
 Deno.serve(async (req) => {
-  const body = await req.json()
+  if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders })
 
-  // PT-BR: `waitUntil` mantém runtime alive até promise resolver
-  EdgeRuntime.waitUntil((async () => {
-    // PT-BR: file write apenas em /tmp
-    await Deno.writeTextFile(
-      `/tmp/audit-${Date.now()}.log`,
-      JSON.stringify(body)
-    )
-    // PT-BR: pode chamar APIs externas, gerar embeddings, etc.
-    await fetch('https://example.com/audit', {
-      method: 'POST',
-      body: JSON.stringify(body),
+  try {
+    const { name } = await req.json()
+    return new Response(JSON.stringify({ message: `Hello ${name}!` }), {
+      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
     })
-  })())
-
-  // PT-BR: response volta imediatamente
-  return new Response('accepted', { status: 202 })
+  } catch (error) {
+    return new Response(JSON.stringify({ error: error.message }), {
+      status: 400,
+      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+    })
+  }
 })
 ```
 
-### Multi-rota com Hono
+### Pattern 3 — Background task com `waitUntil` + `beforeunload`
 
 ```ts
-// supabase/functions/api/index.ts
-// PT-BR: rotas prefixadas com /api (nome da function)
-import { Hono } from 'npm:hono@4.6.7'
-
-const app = new Hono().basePath('/api')
+addEventListener('beforeunload', (ev) => {
+  // PT-BR: log antes do isolate desligar — registra qual deadline foi atingido
+  console.log('Function will shutdown:', (ev as CustomEvent).detail?.reason)
+})
 
-app.get('/users', (c) => c.json({ users: [] }))
-app.get('/users/:id', (c) => c.json({ id: c.req.param('id') }))
-app.post('/users', async (c) => {
-  const body = await c.req.json()
-  return c.json({ created: body }, 201)
+addEventListener('unhandledrejection', (ev) => {
+  console.log('unhandledrejection', (ev as PromiseRejectionEvent).reason)
+  ev.preventDefault()
 })
 
-Deno.serve(app.fetch)
+Deno.serve(async (req) => {
+  const body = await req.json()
+  EdgeRuntime.waitUntil((async () => {
+    try {
+      await Deno.writeTextFile(`/tmp/audit-${Date.now()}.log`, JSON.stringify(body))
+      await fetch('https://example.com/audit', { method: 'POST', body: JSON.stringify(body) })
+    } catch (err) {
+      console.error('background task failed', err)
+    }
+  })())
+  return new Response('accepted', { status: 202 })
+})
 ```
 
-### Função usando JSR e Node built-in
+### Pattern 4 — Per-function `deno.json` (recomendado 2026)
 
-```ts
-// supabase/functions/hash/index.ts
-// PT-BR: imports do JSR + Node built-in (precisa node: prefix)
-import { encodeHex } from 'jsr:@std/encoding/hex'
-import { createHash } from 'node:crypto'
+Cada função tem seu próprio `deno.json` para isolamento de dependências:
 
-Deno.serve(async (req) => {
-  const { text } = await req.json()
-  const hash = createHash('sha256').update(text).digest('hex')
-  return new Response(JSON.stringify({ hash }), {
-    headers: { 'Content-Type': 'application/json' },
-  })
-})
+```
+supabase/functions/
+├── orders/
+│   ├── index.ts
+│   └── deno.json          # PT-BR: dependencies isoladas por função
+├── shipments/
+│   ├── index.ts
+│   └── deno.json
+└── _shared/
+    ├── cors.ts            # legacy — preferir 'npm:@supabase/supabase-js/cors'
+    └── supabase-admin.ts
 ```
 
-### Auth — service-role server-side
+```json
+// supabase/functions/orders/deno.json
+{
+  "imports": {
+    "hono": "npm:hono@4.6.14",
+    "supabase": "npm:@supabase/supabase-js@2.95.0",
+    "zod": "npm:zod@3.23.8"
+  }
+}
+```
 
-```ts
-// supabase/functions/admin-action/index.ts
-// PT-BR: service-role bypassa RLS — apenas server-side
-import { createClient } from 'npm:@supabase/supabase-js@2'
+Após criar `deno.json`, imports usam alias direto: `import { Hono } from 'hono'`. **Não use `import_map.json` global** — é legacy; prefira per-function. CLI 1.207.9+.
 
-Deno.serve(async (req) => {
-  // PT-BR: extrair JWT do header Authorization e validar
-  const authHeader = req.headers.get('Authorization')
-  if (!authHeader?.startsWith('Bearer ')) {
-    return new Response('unauthorized', { status: 401 })
-  }
+### Pattern 5 — Per-function `config.toml`
 
-  // PT-BR: client com service-role para operação privilegiada
-  const supabase = createClient(
-    Deno.env.get('SUPABASE_URL')!,
-    Deno.env.get('SUPABASE_SECRET_KEYS')!
-  )
+```toml
+# supabase/config.toml
+[functions.stripe-webhook]
+verify_jwt = false                                          # webhook externo: signature-based
 
-  // PT-BR: validar JWT e extrair user
-  const { data: { user }, error } = await supabase.auth.getUser(
-    authHeader.replace('Bearer ', '')
-  )
-  if (!user || error) return new Response('unauthorized', { status: 401 })
+[functions.image-processor]
+import_map = "./functions/image-processor/import_map.json"  # apenas se ainda em import_map legacy
 
-  // PT-BR: agora pode operar com privilégios de service_role
-  await supabase.from('audit_log').insert({ user_id: user.id, action: 'admin_view' })
+[functions.legacy-js]
+entrypoint = "./functions/legacy-js/index.js"               # JS puro (CLI 1.215.0+)
 
-  return new Response('ok')
-})
+[functions.wasm-add]
+static_files = ["./functions/wasm-add/add-wasm/pkg/*"]      # bundle Wasm com a função (CLI 2.7.0+)
+
+[edge_runtime]
+policy = "per_worker"                                       # mantém isolate alive — required p/ WebSocket + background task local
+deno_version = 2
 ```
 
-## Anti-patterns
+`policy = "per_worker"` é OBRIGATÓRIO para testar localmente **background tasks** e **WebSockets** — caso contrário o isolate é terminado após request. Caveat: hot-reload é desativado; restart manual via `supabase functions serve`.
 
-### Anti-pattern 1: Bare specifier sem `npm:`/`jsr:`
+### Pattern 6 — Imports JSR + Node built-in
 
-**Errado:**
 ```ts
-import { createClient } from '@supabase/supabase-js'      // ⚠ bare specifier
+import { encodeHex } from 'jsr:@std/encoding@1.0.8/hex'
+import { createHash } from 'node:crypto'         // PT-BR: node: prefix obrigatório
+import process from 'node:process'
 ```
 
-**Por quê:** Deno não resolve bare specifiers. Runtime falha em startup com erro `Module not found`.
+### Pattern 7 — Custom NPM registry / private packages
+
+```bash
+# Custom registry corporativa
+NPM_CONFIG_REGISTRY=https://npm.corp.com/ supabase functions deploy my-fn
+
+# Private package via .npmrc (per-function)
+# supabase/functions/my-fn/.npmrc
+@myorg:registry=https://npm.registryhost.com
+//npm.registryhost.com/:_authToken=VALID_AUTH_TOKEN
+```
+
+```ts
+import pkg from 'npm:@myorg/private-package@1.0.1'
+```
+
+CLI 1.207.9+ para `.npmrc` per-function; CLI 2.2.8+ para `NPM_CONFIG_REGISTRY`.
+
+## Anti-patterns
+
+### A1 — Bare specifier
 
-**Certo:**
 ```ts
-import { createClient } from 'npm:@supabase/supabase-js@2'
+// ⚠ Errado — Module not found
+import { createClient } from '@supabase/supabase-js'
+// ✓ Certo
+import { createClient } from 'npm:@supabase/supabase-js@2.95.0'
 ```
 
-### Anti-pattern 2: `Deno.writeTextFile` fora de `/tmp`
+### A2 — Tratar `SUPABASE_SECRET_KEYS` como string (regressão 2025 → 2026)
 
-**Errado:**
 ```ts
-await Deno.writeTextFile('/data/audit.log', data)         // ⚠ filesystem read-only
-await Deno.writeTextFile('./local/x.log', data)           // ⚠ idem
+// ⚠ Errado — em 2026 é JSON dict; passar como string quebra createClient
+const supabase = createClient(URL, Deno.env.get('SUPABASE_SECRET_KEYS')!)
+
+// ✓ Certo
+const SECRET_KEYS = JSON.parse(Deno.env.get('SUPABASE_SECRET_KEYS')!)
+const supabase = createClient(URL, SECRET_KEYS['default'])
 ```
 
-**Por quê:** Edge Functions runtime tem filesystem read-only exceto `/tmp`. Writes fora de `/tmp` falham com `EACCES`.
+### A3 — `Deno.writeTextFile` fora de `/tmp` ou `/s3/<bucket>`
 
-**Certo:**
 ```ts
+await Deno.writeTextFile('/data/audit.log', data)   // ⚠ EACCES — read-only
+await Deno.writeTextFile('./local/x.log', data)     // ⚠ idem
+// ✓
 await Deno.writeTextFile(`/tmp/audit-${Date.now()}.log`, data)
+await Deno.writeTextFile(`/s3/my-bucket/audit.log`, data)  // S3FS_* env vars necessários
 ```
 
-### Anti-pattern 3: Trabalho pesado inline na response
+### A4 — Trabalho pesado inline (cliente espera)
 
-**Errado:**
 ```ts
+// ⚠ Errado — bloqueia response até 30s+; client timeout
 Deno.serve(async (req) => {
-  const body = await req.json()
-  await processHeavyJob(body)        // ⚠ trava response 30s+
-  await sendEmail(body)              // ⚠ idem
+  await processHeavyJob(await req.json())
   return new Response('done')
 })
-```
-
-**Por quê:** cliente espera resposta. Edge Functions têm timeout (default 60s). Falhas pontuais quebram UX.
 
-**Certo:** use `EdgeRuntime.waitUntil` para liberar resposta:
-```ts
+// ✓ Certo — waitUntil libera response
 Deno.serve(async (req) => {
   const body = await req.json()
-  EdgeRuntime.waitUntil((async () => {
-    await processHeavyJob(body)
-    await sendEmail(body)
-  })())
+  EdgeRuntime.waitUntil(processHeavyJob(body))
   return new Response('accepted', { status: 202 })
 })
 ```
 
-### Anti-pattern 4: Multi-rota sem prefix
+### A5 — Multi-rota sem `basePath`
 
-**Errado:**
 ```ts
-const app = new Hono()                  // ⚠ sem basePath
+const app = new Hono()                  // ⚠ /users em produção = 404
 app.get('/users', handler)
-Deno.serve(app.fetch)                   // request a /users → 404 em produção
+// ✓ basePath com o nome canônico da função
+const app = new Hono().basePath('/api')
 ```
 
-**Por quê:** quando deployado, URL é `https://<ref>.supabase.co/functions/v1/<name>/...`. Sem `basePath('/<name>')` no router, request a `/users` não casa.
+### A6 — Import map global em `supabase/functions/import_map.json`
+
+Legacy, ainda suportado mas **não recomendado**. Cada update em uma função pode quebrar outras (deps acopladas). Prefira `deno.json` per-function.
+
+### A7 — Custom CORS string hard-coded
 
-**Certo:**
 ```ts
-const app = new Hono().basePath('/api')   // PT-BR: prefix com nome da function
+// ⚠ Errado — desatualiza quando SDK adiciona novos headers (drift silencioso)
+const corsHeaders = { 'Access-Control-Allow-Headers': 'authorization, apikey, content-type' }
+
+// ✓ Certo (v2.95.0+) — import sincronizado com releases
+import { corsHeaders } from 'npm:@supabase/supabase-js@2.95.0/cors'
+```
+
+### A8 — Confundir `Authorization` (JWT) vs `apikey` (API key)
+
+`Authorization: Bearer <user-jwt>` — JWT do usuário Supabase Auth.
+`apikey: sb_publishable_... | sb_secret_...` — API key do projeto.
+
+Enviar `sb_publishable_*` como Bearer = 401. Ver [`supabase-edge-functions-auth`](../supabase-edge-functions-auth/SKILL.md).
+
+## Estrutura recomendada
+
+```
+supabase/
+├── config.toml
+└── functions/
+    ├── _shared/                     # shared (underscore prefix evita deploy)
+    │   ├── supabase-admin.ts
+    │   └── supabase-client.ts
+    ├── orders/
+    │   ├── index.ts
+    │   ├── deno.json                # per-function (2026)
+    │   └── .npmrc                   # opcional — private NPM
+    └── tests/
+        ├── orders-test.ts
+        └── shipments-test.ts
 ```
 
+Diretrizes:
+- **"Fat functions":** combine endpoints relacionados em uma função (reduz cold start). Multi-rota com Hono/Oak/Express.
+- **Hyphens em nomes:** URL-friendly.
+- **`_shared/` underscore:** não é deployado, importado relativamente.
+- **`tests/` separado:** sufixo `-test.ts`. Ver [`supabase-edge-functions-testing`](../supabase-edge-functions-testing/SKILL.md).
+
+## Limits & quotas (resumo — detalhe em [`supabase-edge-functions-limits`](../supabase-edge-functions-limits/SKILL.md))
+
+| Recurso | Free | Pro/Team |
+|---|---|---|
+| Memory | 256 MB | 256 MB |
+| CPU (per request) | 2s | 2s |
+| Wall clock (isolate lifetime) | 150s | 400s |
+| Request idle timeout | 150s | 150s |
+| Max function size (bundled) | 20 MB | 20 MB |
+| Max functions/project | 100 | 500 / 1000 |
+| Nested function calls | ~5000/min/chain | ~5000/min/chain |
+
+Outgoing ports `25` e `587` bloqueados (use Resend/SendGrid HTTP API).
+
 ## Ver também
 
-- [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md) — clients usam `npm:@supabase/supabase-js`
-- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — service-role server-side bypassa RLS
-- [supabase-cron-queues](../supabase-cron-queues/SKILL.md) — Edge Functions invocadas por `pg_net.http_post`
-- [glossário](../_shared-supabase/glossary.md) — comandos CLI (`supabase functions deploy`)
+- [`supabase-edge-functions-auth`](../supabase-edge-functions-auth/SKILL.md) — `@supabase/server`, withSupabase, 4 auth modes, verify_jwt
+- [`supabase-edge-functions-testing`](../supabase-edge-functions-testing/SKILL.md) — Deno test, supabase functions serve, Chrome DevTools
+- [`supabase-edge-runtime-builtins`](../supabase-edge-runtime-builtins/SKILL.md) — `Supabase.ai.Session`, /s3 persistent, WebSockets, Wasm, regional
+- [`supabase-edge-functions-limits`](../supabase-edge-functions-limits/SKILL.md) — limits, status codes, RateLimitError
+- [`supabase-edge-functions-mcp-server`](../supabase-edge-functions-mcp-server/SKILL.md) — mcp-lite pattern
+- [`supabase-cron-queues`](../supabase-cron-queues/SKILL.md) — pattern `cron → pgmq → Edge Function`
+- [`supabase-auth-ssr`](../supabase-auth-ssr/SKILL.md) — clients SSR
+- [`_shared-supabase/glossary.md`](../_shared-supabase/glossary.md) — CLI + termos canônicos