@palbase/backend 1.0.0 → 2.0.2

package/dist/test/index.d.ts

@@ -1,4 +1,4 @@
-import { D as DBClient, l as PBRequest, d as PalbaseModuleClients, L as Logger, C as CacheClient, Q as QueueClient, U as User } from '../endpoint-knNIeovM.js';
+import { D as DBClient, l as PBRequest, d as PalbaseModuleClients, L as Logger, C as CacheClient, Q as QueueClient, U as User } from '../endpoint-Djk5L6G2.js';
 import 'zod';
 import '../schema-BqfEhIC0.js';
 

package/dist/test/index.js

@@ -1,6 +1,6 @@
 import {
   __setRuntime
-} from "../chunk-7N5ICXCB.js";
+} from "../chunk-L36JLUPO.js";
 
 // src/test/mock-db.ts
 function createMockDB() {

package/docs/README.md

@@ -0,0 +1,51 @@
+# 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)).

package/docs/background.md

@@ -0,0 +1,56 @@
+# 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`);
+  },
+});
+```

package/docs/database.md

@@ -0,0 +1,60 @@
+# 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).

package/docs/endpoints.md

@@ -0,0 +1,116 @@
+# 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 }),
+});
+```

package/docs/errors.md

@@ -0,0 +1,48 @@
+# 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.

package/docs/events.md

@@ -0,0 +1,59 @@
+# 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.

package/docs/getting-started.md

@@ -0,0 +1,49 @@
+# 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.