Serverless Function Development on Butterbase

Guide for developing and deploying serverless functions on Butterbase's Deno runtime. Covers handler signatures, trigger types, database access, environment variables, and testing.

---

1. Handler Signature

Every function exports a single handler function with this signature:

export async function handler(
  request: Request,
  context: {
    db: PostgresClient,                                  // RLS-aware DB client
    env: Record<string, string>,                         // env vars set on the function
    user: { id: string } | null,                         // present for HTTP+auth:required; null for cron
    waitUntil: (p: Promise<unknown>) => void,            // background work after Response (≤30s)
    idempotency: {
      claim: (key: string, opts?: { scope?: string; ttlSeconds?: number }) => Promise<boolean>
    }                                                    // atomic dedup for webhook retries
  }
): Promise<Response>

CRITICAL: The handler MUST return new Response() (Web API standard). Do NOT return plain objects.

Correct:

return new Response(JSON.stringify({ message: "ok" }), {
  status: 200,
  headers: { "Content-Type": "application/json" }
});

Wrong (will fail):

return { status: 200, body: "ok" };  // NOT a Response object!

---

2. Trigger Types

HTTP Trigger

Invoke the function via an HTTP request.

{
  "trigger": {
    "type": "http",
    "config": { "method": "POST", "path": "/my-endpoint", "auth": "required" }
  }
}

Auth options:

• "required", request must include a valid JWT; ctx.user is always set
• "optional", JWT is parsed if present; ctx.user may be null
• "none", public endpoint; no auth needed; ctx.user is always null

---

Cron Trigger

Execute the function on a schedule.