@palbase/backend 2.0.0 → 2.0.2

package/docs/llms.txt

@@ -0,0 +1,16 @@
+# 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.
+
+## Docs
+
+- [README](./README.md)
+- [getting-started](./getting-started.md)
+- [routing](./routing.md)
+- [endpoints](./endpoints.md)
+- [database](./database.md)
+- [schema](./schema.md)
+- [services](./services.md)
+- [errors](./errors.md)
+- [background](./background.md)
+- [events](./events.md)

package/docs/routing.md

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

package/docs/schema.md

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

package/docs/services.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Palbase Backend SDK — defineEndpoint, context types, schema DSL",
   "license": "MIT",
   "repository": {
@@ -45,7 +45,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "dependencies": {
     "@asteasolutions/zod-to-openapi": "^7.3.4",
@@ -65,6 +66,7 @@
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "docs:build": "node scripts/build-llms.mjs"
   }
 }