@palbase/backend 2.0.2 → 3.0.0

package/docs/events.md

@@ -1,8 +1,10 @@
 # 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.
+Like workers/jobs, hooks and webhooks use the **singleton model** — the same
+imported service singletons as endpoints (`import { Database, Log } from
+"@palbase/backend"`). They do **not** receive a `req`. A second `meta` argument
+carries the non-service data (`env`, `projectId`, `environmentId`; webhooks also
+get `requestId`).
 
 ## Hooks (platform events)
 
@@ -11,21 +13,24 @@ are imported from `@palbase/backend`: `auth`, `storage`, `documents`.
 
 ```ts
 // hooks/auth.ts
-import { auth } from "@palbase/backend";
+import { auth, Database, Log } from "@palbase/backend";
 
-export const onUserCreated = auth.onUserCreated(async (ctx, event) => {
-  ctx.log.info(`new user: ${event.user.email}`);
-  await ctx.db.insert("profiles", {
+export const onUserCreated = auth.onUserCreated(async (event, meta) => {
+  Log.info(`new user: ${event.user.email}`);
+  await Database.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}`);
+export const onSignIn = auth.onSignIn(async (event, meta) => {
+  Log.info(`sign in: ${event.user.email} via ${event.provider}`);
 });
 ```
 
+`meta` shape: `{ env, projectId, environmentId }`. Branch env vars are in
+`meta.env`; services come from the imported singletons.
+
 Available hook builders: `auth.onUserCreated`, `auth.onSignIn`, `auth.onSignOut`,
 `auth.onPasswordReset`, `storage.onFileUploaded`, `storage.onFileDeleted`,
 `documents.onDocumentCreated`, `documents.onDocumentUpdated`,
@@ -38,22 +43,25 @@ Receive and verify webhooks from third-party providers. Files live under
 
 ```ts
 // webhooks/stripe.ts
-import { defineWebhook } from "@palbase/backend";
+import { defineWebhook, Database, Log } 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 });
+    "checkout.session.completed": async (event, meta) => {
+      await Database.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 });
+    "payment_intent.payment_failed": async (event, meta) => {
+      Log.error("payment failed");
+      await Database.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.
+The signing secret is resolved by the runtime from `secret: { env: "NAME" }`;
+your handlers access branch env vars via `meta.env`. The runtime verifies the
+signature before dispatching to your event handlers.
+
+`meta` shape: `{ env, requestId, projectId, environmentId }`.

package/docs/getting-started.md

@@ -13,7 +13,6 @@ Your project depends on the SDK and uses the Palbase CLI for the dev loop:
   "private": true,
   "scripts": {
     "dev": "palbase serve",
-    "deploy": "palbase push",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": { "@palbase/backend": "latest" },
@@ -23,19 +22,24 @@ Your project depends on the SDK and uses the Palbase CLI for the dev loop:
 
 ## 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`.
+- `palbase serve` — run your backend locally with hot reload. It runs your
+  `controllers/` locally but proxies `Database`/`ctx.*` to the **deployed**
+  branch, so the branch must already be deployed (serve tells you to push first
+  if it isn't). See [migrations.md](./migrations.md) for the schema/migration
+  side of this.
+- **Deploy is GitHub-native** — there is no `palbase push`. Commit and
+  `git push` to your project's repo; the push triggers a deploy of the backend
+  runtime. Push a **branch** to deploy that branch instead of `main`.
 
 ## Your first endpoint
 
-Create `endpoints/hello/get.ts`:
+A handler is one endpoint unit; a controller maps method+path to it. Create
+`handlers/hello.ts`:
 
 ```ts
-import { defineEndpoint, z } from "@palbase/backend";
+import { defineHandler, z } from "@palbase/backend";
 
-export default defineEndpoint({
-  method: "GET",
+export default defineHandler({
   input: z.object({ name: z.string().optional() }),
   output: z.object({ message: z.string(), user: z.string().nullable() }),
   handler: async (req) => ({
@@ -45,5 +49,17 @@ export default defineEndpoint({
 });
 ```
 
+Then mount it in `controllers/hello.controller.ts`:
+
+```ts
+import { defineController, route } from "@palbase/backend";
+import hello from "../handlers/hello.js";
+
+export default defineController("/hello", {
+  hello: route.get("/", hello),
+});
+```
+
 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.
+flows into `req.input`; the `output` schema validates your return value. See
+[routing.md](./routing.md) for the handler + controller model.