@palbase/backend 22.1.0 → 23.0.0

package/docs/llms-full.txt

@@ -32,8 +32,8 @@ db/schema.ts                        # config-as-code Postgres schema (tables, co
 ```
 
 The four folders above are the daily surface. These also exist (own docs, linked
-below): `resources/` (external connections — [resources.md](./resources.md)),
-`seeds/` (seed data), `jobs/` (background — [background.md](./background.md)),
+below): `resources/` (plain modules a controller imports — a client, a
+formatter, anything shared), `seeds/` (seed data), `jobs/` (background — [background.md](./background.md)),
 `webhooks/` + `hooks/` (events — [events.md](./events.md)), `middleware/`.
 
 ### The 7 rules (checklist)
@@ -211,9 +211,11 @@ generated client surface) changes; the verb/path do not affect it.
   secrets in its environment. There is no `.env` file: nothing writes one and
   nothing reads one, so the values live in one child process and are gone when it
   exits.
-- `config/secrets.ts` — `defineSecrets({ secrets: [secret("NAME")] })` declares
-  WHICH secrets the backend needs (never a value). `push` refuses the deploy when
-  a required one is missing from the target Environment, naming it.
+- Secrets are written to the stack (`palbase secret set NAME --stdin`) and read
+  with `Secrets.get(name)`. The NAME is typed: `palbase-stack.d.ts` is generated
+  from the stack, so a secret it does not hold cannot be spelled — a compile
+  error rather than a 500. There is no `config/secrets.ts`: it asked you to
+  restate names the vault already had, and the deploy compared the two lists.
 - `tsconfig.json` needs `"experimentalDecorators": true` (the scaffold sets it).
 
 ## Mental model
@@ -274,7 +276,6 @@ HTTP endpoints are **not** file-path routed. You author a class controller
 | Schema & typed DB | [schema.md](./schema.md) |
 | Migrations (additive vs type-change + drift-gate) | [migrations.md](./migrations.md) |
 | Services (Cache, Queue, Storage, …) | [services.md](./services.md) |
-| Resources (external connections) | [resources.md](./resources.md) |
 | Errors | [errors.md](./errors.md) |
 | Workers & Jobs | [background.md](./background.md) |
 | Hooks & Webhooks | [events.md](./events.md) |
@@ -1685,108 +1686,6 @@ to drive live chat, presence, dashboards, and other push features.
 
 
 
-<!-- ===== resources.md ===== -->
-
-# 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;
-```
-
-
-
 <!-- ===== errors.md ===== -->
 
 # Errors
@@ -1973,155 +1872,3 @@ handlers access Environment variables via `meta.env`. The runtime verifies the
 signature before dispatching to your event handlers.
 
 `meta` shape: `{ env, requestId, environmentId }`.
-
-
-
-<!-- ===== config.md ===== -->
-
-# 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/llms.txt

@@ -13,8 +13,6 @@
 - [schema](./schema.md)
 - [migrations](./migrations.md)
 - [services](./services.md)
-- [resources](./resources.md)
 - [errors](./errors.md)
 - [background](./background.md)
 - [events](./events.md)
-- [config](./config.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "22.1.0",
+  "version": "23.0.0",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
@@ -53,14 +53,14 @@
         "default": "./dist/db/env.cjs"
       }
     },
-    "./purchases": {
+    "./stack": {
       "import": {
-        "types": "./dist/purchases/keys.d.ts",
-        "default": "./dist/purchases/keys.js"
+        "types": "./dist/stack.d.ts",
+        "default": "./dist/stack.js"
       },
       "require": {
-        "types": "./dist/purchases/keys.d.cts",
-        "default": "./dist/purchases/keys.cjs"
+        "types": "./dist/stack.d.cts",
+        "default": "./dist/stack.cjs"
       }
     },
     "./engine": {

package/template/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@palbase/backend": "^22.0.0"
+    "@palbase/backend": "^23.0.0"
   },
   "devDependencies": {
     "@types/node": "^22",