@palbase/backend 22.0.1 → 23.0.0

package/docs/config.md

@@ -1,147 +0,0 @@
-# Module Config (config-as-code)
-
-Beyond `db/schema.ts`, four more module surfaces are git-authoritative: storage
-buckets, notification providers, feature-flag definitions, and the outbound-HTTP
-allowlist. You declare them in `config/*.ts` files (typed, imported from
-`@palbase/backend`) and on `git push` the deploy creates/updates them. Secrets
-(certs, keys, API tokens) NEVER go in git — they live in a reserved encrypted env
-namespace, uploaded by the guided CLI.
-
-You normally author these with `palbase <module> add …` (the CLI writes the
-config file + uploads any secret); the files below are what it generates.
-
-## Storage buckets — `config/storage.ts`
-
-```ts
-import { defineStorage, bucket } from "@palbase/backend";
-
-export default defineStorage({
-  buckets: {
-    avatars: bucket({
-      public: true,                       // served without a signed URL
-      fileSizeLimit: "5MB",               // "5MB"/"20MB"/"1GB" or a byte number
-      allowedMimeTypes: ["image/png", "image/jpeg", "image/webp"],
-    }),
-    invoices: bucket({ public: false, fileSizeLimit: "20MB", allowedMimeTypes: ["application/pdf"] }),
-  },
-});
-```
-
-Author it: `palbase storage buckets add avatars --public --max-size 5MB --mime image/png,image/jpeg`.
-On deploy, the buckets are created/updated. A bucket REMOVED from the file is
-**never auto-deleted** (its files would be lost) — drop it explicitly in Studio.
-The files inside a bucket are runtime state, not config.
-
-## Notification providers — `config/notifications.ts`
-
-Providers carry secrets (APNs `.p8`, FCM service-account JSON, Twilio token).
-The config file is **structural** — it names the enabled providers + their
-non-secret fields; the secret is bound by convention to a reserved env key and
-NEVER appears in git.
-
-```ts
-import { defineNotifications } from "@palbase/backend";
-
-export default defineNotifications({
-  push: {
-    apns: { enabled: true, teamId: "A1B2C3D4E5", keyId: "XYZ123", bundleId: "net.example.app" },
-    // no p8 key here — it's in the reserved secret PB_NOTIFICATIONS_APNS_P8
-  },
-  sms: {
-    twilio: { enabled: true, accountSid: "AC...", messagingServiceSid: "MG..." },
-  },
-});
-```
-
-Author it with the guided CLI — it knows each provider's fields and uploads the
-secret for you, so you never type a secret-name string:
-
-```bash
-palbase notifications providers          # list the catalog + what's configured
-palbase notifications add apns \
-  --team-id A1B2C3D4E5 --key-id XYZ123 --bundle-id net.example.app \
-  --p8-file ./AuthKey_XYZ123.p8          # → uploads PB_NOTIFICATIONS_APNS_P8 (encrypted)
-palbase notifications add twilio --account-sid AC... --messaging-sid MG...
-                                          # prompts for the auth token (hidden)
-```
-
-The reserved secret env keys (`PB_NOTIFICATIONS_*`) are managed by these
-commands — `palbase secret set PB_*` is refused. Your own custom env
-(`MY_API_KEY` etc.) is unaffected and still flows via `.env.local`. On deploy,
-each enabled provider's reserved secret is resolved and the provider is
-configured; a provider whose secret is missing is skipped (warned, not fatal).
-
-## Feature flags — `config/flags.ts`
-
-Flag DEFINITIONS (key, type, default) are config; the value set for a specific
-user / an A/B assignment is runtime (set via the SDK/Studio, not git).
-
-```ts
-import { defineFlags, flag } from "@palbase/backend";
-
-export default defineFlags({
-  flags: {
-    new_checkout: flag({ type: "boolean", default: false, description: "Gate the redesigned checkout" }),
-    upload_limit: flag({ type: "number", default: 10 }),
-    theme:        flag({ type: "string", default: "system", variants: ["light", "dark", "system"] }),
-    limits:       flag({ type: "json", default: { daily: 10, burst: 50 } }),
-  },
-});
-```
-
-Four types: `boolean`, `number`, `string`, `json`. A `json` flag's default is an
-object (not an array, not a scalar) and nests at most 3 deep. `variants` is for
-`string` only — the flags service rejects it on every other type.
-
-Author it: `palbase flags add new_checkout --type boolean --default false`, or
-`palbase flags add limits --type json --default '{"daily":10}'`. On
-deploy, the definitions are upserted to the flags service (idempotent). A flag
-removed from the file is **not auto-deleted** (orphan definitions are harmless).
-
-## Outbound HTTP — `config/egress.ts`
-
-Your backend has **no ambient network**. A `fetch()` to an external host is
-refused unless the host is declared here, and with no `config/egress.ts` at all
-there is no outbound network whatsoever.
-
-```ts
-import { defineEgress } from "@palbase/backend";
-
-export default defineEgress({
-  hosts: ["api.openai.com", ".example.com"], // leading dot also covers subdomains
-  timeoutMs: 90_000,                         // per-call ceiling; omitted ⇒ 30_000
-});
-```
-
-Hosts are bare hostnames — https on :443 only, so no scheme, port, path or
-wildcard. `timeoutMs` is 1_000–300_000.
-
-Unlike the three above, this one is **fail-closed**: a malformed host or an
-out-of-range `timeoutMs` ABORTS the deploy rather than logging a warning. An
-allowlist that silently dropped an entry would be a broken feature, and one that
-silently widened would be a hole; an out-of-range timeout is rejected rather than
-clamped so your config file and the running system never disagree.
-
-### How long a call may take
-
-`timeoutMs` is a ceiling, not a grant — the call still ends when the invocation
-around it ends, and it covers the whole call including redirects (three hops do
-not get three budgets).
-
-| Where the fetch runs | What else bounds it |
-|---|---|
-| Job (`jobs/`) | Its own `@Job({ timeout })`, max 300s — the longest budget available. |
-| Endpoint / webhook | The gateway's request ceiling. Long work belongs in a job. |
-
-Responses are **buffered whole** (5 MB cap) before your `fetch()` resolves.
-Requesting a streaming response from an upstream (`stream: true`, SSE) therefore
-buys nothing: no partial output, no earlier first byte, and the entire stream
-must still finish inside `timeoutMs`.
-
-## How it's applied
-
-All four are evaluated + applied **on deploy**, the same place `db/schema.ts`
-migrations run, reaching each module through your project's gateway with a
-service-role key. Storage/notifications/flags are fail-soft — a config error logs
-a warning but never aborts the deploy of your code. `config/egress.ts` is the
-exception and is fail-closed, for the reason above.

package/docs/resources.md

@@ -1,97 +0,0 @@
-# Resources
-
-A `Resource` models one external connection — a pooled datastore, a stateless
-API client, or a per-user factory. You put it in `resources/`, export an
-instance, and **do not register it**: the framework discovers it and sets it up
-once at boot. On top of that lifecycle you expose your own clean facade.
-
-```ts
-import { Resource } from "@palbase/backend";
-```
-
-## Lifecycle (boot scope — not per request)
-
-A resource is created once at process boot — NOT per request. The framework:
-
-1. calls `init(env)` **once**, with only the secrets the resource declared.
-
-That is the whole lifecycle — there is no teardown counterpart. The runtime
-recycles an environment by disposing its isolate outright, with no signal
-delivered into your code first, so a `shutdown()` you declare is **never
-called**. Do not buffer in memory intending to flush on the way out; treat a
-write as durable when the call that made it returns. The optional `shutdown()`
-member survives in the type because the older process-based runtime did invoke
-it on SIGTERM.
-
-The instance lives for the whole process; your facade methods are called
-per-request. This makes "reconnect on every request" structurally impossible.
-
-## Pooled datastore
-
-```ts
-import { Resource } from "@palbase/backend";
-import neo4j, { type Driver, type Session } from "neo4j-driver";
-
-export class Neo4jResource extends Resource {
-  static secrets = ["NEO4J_URL", "NEO4J_USER", "NEO4J_PASSWORD"] as const;
-  private driver!: Driver;
-  async init(env: { NEO4J_URL: string; NEO4J_USER: string; NEO4J_PASSWORD: string }) {
-    this.driver = neo4j.driver(env.NEO4J_URL, neo4j.auth.basic(env.NEO4J_USER, env.NEO4J_PASSWORD));
-  }
-  session(): Session {
-    return this.driver.session();
-  }
-}
-
-export const graph = new Neo4jResource();
-```
-
-## Stateless API client — `init` only
-
-```ts
-import { Resource } from "@palbase/backend";
-import { Client } from "@googlemaps/google-maps-services-js";
-
-export class GoogleResource extends Resource {
-  static secrets = ["GOOGLE_MAPS_KEY"] as const;
-  private client = new Client();
-  private key = "";
-  init(env: { GOOGLE_MAPS_KEY: string }) {
-    this.key = env.GOOGLE_MAPS_KEY;
-  }
-  nearby(lat: number, lng: number) {
-    return this.client.placesNearby({ params: { location: { lat, lng }, radius: 1500, key: this.key } });
-  }
-}
-
-export const google = new GoogleResource();
-```
-
-A per-user (OAuth) resource adds a factory method on the base, e.g.
-`github.forUser(token)` — the same single model covers pooled, stateless, and
-per-user.
-
-## Secrets
-
-`static secrets` is the contract:
-
-- It **types** the `env` passed to `init` — only the declared names are
-  present, each a `string`. An undeclared key is a compile error.
-- A declared secret that is **missing at boot fails the deploy**, naming the
-  secret. Secrets are Environment-scoped; set them with
-  `palbase secret set NAME ...` or in Studio. A resource is initialised once at
-  boot, so rotating a secret needs a redeploy/restart.
-
-`secrets` is optional — a resource that needs none simply omits it and gets an
-empty `env`.
-
-## Using a resource
-
-Import the singleton and call your facade — services and handlers reach
-resources the same way they reach `Database`:
-
-```ts
-import { google } from "../resources/google.js";
-
-const results = (await google.nearby(41.0, 29.0)).data.results;
-```

package/template/config/secrets.ts

@@ -1,24 +0,0 @@
-import { defineSecrets, secret } from "@palbase/backend";
-
-// The secrets this backend needs, declared next to the code that needs them.
-//
-// This file holds NAMES, never values. A value lives only in the environment's
-// vault and reaches the process through `Secrets.get("NAME")`; nothing here —
-// and nothing in the repository this is committed to — ever holds one.
-//
-// Declaring the requirement is what makes a missing secret a sentence on your
-// terminal instead of a 500 on the first request that touches it: `push`
-// compares this list against the target environment's vault and refuses,
-// naming what is missing, before anything ships.
-//
-// `required` defaults to true. The example below is optional because the
-// backend genuinely runs without it — a required secret in a fresh scaffold
-// would just block your first deploy. Delete it and declare your own.
-export default defineSecrets({
-  secrets: [
-    secret("SENTRY_DSN", {
-      required: false,
-      description: "crash reporting endpoint — errors go unreported without it",
-    }),
-  ],
-});