@palbase/backend 2.0.0 → 3.0.0

package/docs/events.md

@@ -0,0 +1,67 @@
+# Hooks & Webhooks
+
+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)
+
+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, Database, Log } from "@palbase/backend";
+
+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 (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`,
+`documents.onDocumentDeleted`.
+
+## Webhooks (inbound provider events)
+
+Receive and verify webhooks from third-party providers. Files live under
+`webhooks/`.
+
+```ts
+// webhooks/stripe.ts
+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 (event, meta) => {
+      await Database.insert("orders", { status: "paid", data: event });
+    },
+    "payment_intent.payment_failed": async (event, meta) => {
+      Log.error("payment failed");
+      await Database.insert("payment_failures", { data: event });
+    },
+  },
+});
+```
+
+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

@@ -0,0 +1,65 @@
+# 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",
+    "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. 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
+
+A handler is one endpoint unit; a controller maps method+path to it. Create
+`handlers/hello.ts`:
+
+```ts
+import { defineHandler, z } from "@palbase/backend";
+
+export default defineHandler({
+  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,
+  }),
+});
+```
+
+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. See
+[routing.md](./routing.md) for the handler + controller model.