bunderstack 0.23.4 → 0.24.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bunderstack",
-  "version": "0.23.4",
-  "description": "Batteries-included backend framework for Bun: type-safe oRPC APIs, auth, storage, realtime, jobs, email, and validated env from one config.",
+  "version": "0.24.0",
+  "description": "Batteries-included backend framework for Bun: type-safe oRPC APIs, auth, storage, realtime, jobs, messaging, and validated env from one declaration.",
   "keywords": [
     "backend",
     "better-auth",
@@ -113,6 +113,10 @@
       "types": "./dist/email/smtp.d.ts",
       "default": "./dist/email/smtp.js"
     },
+    "./messaging": {
+      "types": "./dist/messaging/index.d.ts",
+      "default": "./dist/messaging/index.js"
+    },
     "./api": {
       "types": "./dist/api/types.d.ts",
       "default": "./dist/api/types.js"

package/skills/creating-bunderstack-apps/references/application-structure.md

@@ -3,9 +3,12 @@
 ## Separate declaration from runtime
 
 `src/bunderstack/backend.ts` synchronously constructs and exports `backend =
-bunderstack({...})`. It is pure: it validates the declaration and exposes
-`backend.manifest`, but it does not connect to infrastructure. The blueprint
-imports this declaration without starting the application.
+bunderstack({...})`. The declaration is one object; `database`, `storage`,
+`messaging`, and `realtime` also accept a function of the validated
+environment, and `auth` accepts a builder over `{ db, env }`. It is pure:
+`backend.inspect({ env })` resolves it and returns a manifest without
+connecting to infrastructure, and the blueprint imports this declaration
+without starting the application.
 
 `src/bunderstack/index.ts` owns the production runtime: it imports `backend`,
 calls `await backend.start()`, exports `app`, and calls `provision(app)` when the
@@ -122,7 +125,12 @@ const instrumentation = o.middleware(async ({ context, next, path }) => {
   }
 })
 
-bunderstack({ schema, database, middleware: [instrumentation], api })
+bunderstack({
+  schema,
+  database,
+  middleware: [instrumentation],
+  api,
+})
 ```
 
 Three rules apply to a graph-wide middleware. It runs before authentication, so
@@ -186,9 +194,10 @@ Commit `.env.example` with names and safe placeholders only. Keep production
 secrets, database URLs, storage credentials, and auth secrets in the runtime
 environment.
 
-Use local libSQL storage and console email for development when appropriate;
-declare production adapters and credentials through configuration and runtime
-environment rather than hard-coding them.
+Use local libSQL storage for development, and let a messaging channel without
+credentials capture instead of sending; declare production adapters and
+credentials through the declaration and the runtime environment rather than
+hard-coding them.
 
 ## Publish direct writes
 

package/skills/migrating-to-bunderstack/SKILL.md

@@ -8,6 +8,7 @@ description: Use when building, structuring, or migrating an application on Bund
 ## Overview
 
 Bunderstack is a batteries-included full-stack backend framework for Bun unifying:
+
 - **Drizzle ORM** (libSQL / SQLite / Postgres)
 - **Better Auth** (authentication & session management)
 - **oRPC v2** (unified type-safe RPC & OpenAPI/REST procedures with Standard Schema / Valibot)
@@ -31,11 +32,13 @@ import { schema } from './schema'
 import { access } from './access'
 import { api } from './api'
 
-// 1. Pure synchronous declaration (does NO I/O, no DB connection, exports static manifest)
+// 1. Pure synchronous declaration (does NO I/O, no DB connection)
+//    One object. `database`, `storage`, `messaging`, and `realtime` also take
+//    a function of the validated env when they need a key or a URL.
 export const backend = bunderstack({
   schema,
   access,
-  database: { adapter: libsql(), url: process.env.DATABASE_URL ?? 'file:./data.db' },
+  database: { adapter: libsql() }, // url defaults to DATABASE_URL
   api,
 })
 
@@ -44,7 +47,7 @@ export const app = await backend.start()
 export type App = typeof app
 ```
 
-- `backend.manifest` can be read statically by tools (such as blueprint generators) without starting the app or connecting to a database.
+- `backend.inspect({ env })` resolves the declaration and returns its manifest for tools (such as blueprint generators) without starting the app or connecting to a database.
 - `app = await backend.start()` explicitly boots the runtime.
 - `backend.test()` creates an isolated, lexically owned test fixture.
 
@@ -52,25 +55,25 @@ export type App = typeof app
 
 All Bunderstack capabilities are imported directly from single-segment subpaths of `bunderstack`:
 
-| Subpath Import | Purpose |
-| --- | --- |
-| `bunderstack` | Core backend builder (`bunderstack`, `defineApi`, `defineAccess`, `BunderstackError`) |
-| `bunderstack/libsql` | libSQL / SQLite database adapter |
-| `bunderstack/postgres-js` | postgres.js database adapter |
-| `bunderstack/bun-sql` | `Bun.sql` Postgres adapter |
-| `bunderstack/pglite` | PGlite in-memory / embedded Postgres adapter |
-| `bunderstack/client` | Framework-neutral typed client & `createLiveView` |
-| `bunderstack/client-react` | React LiveView hook (`useLiveView`) |
-| `bunderstack/client-rest` | Type-safe REST client |
-| `bunderstack/query` | TanStack Query integration (`createClient`, `syncRealtime`) |
-| `bunderstack/query-react` | React-specific query helpers |
-| `bunderstack/sync` | TanStack DB realtime sync collections |
-| `bunderstack/start` | TanStack Start integration (`createApiHandlers`) |
-| `bunderstack/start-auth` | Better Auth client for TanStack Start |
-| `bunderstack/provision` | Database schema provisioning (`provision(app)`) |
-| `bunderstack/testing` | Test fixture helpers |
-| `bunderstack/schema` | Internal system tables (`export * from 'bunderstack/schema'`) |
-| `bunderstack/typeid` | TypeID column types & generators |
+| Subpath Import             | Purpose                                                                               |
+| -------------------------- | ------------------------------------------------------------------------------------- |
+| `bunderstack`              | Core backend builder (`bunderstack`, `defineApi`, `defineAccess`, `BunderstackError`) |
+| `bunderstack/libsql`       | libSQL / SQLite database adapter                                                      |
+| `bunderstack/postgres-js`  | postgres.js database adapter                                                          |
+| `bunderstack/bun-sql`      | `Bun.sql` Postgres adapter                                                            |
+| `bunderstack/pglite`       | PGlite in-memory / embedded Postgres adapter                                          |
+| `bunderstack/client`       | Framework-neutral typed client & `createLiveView`                                     |
+| `bunderstack/client-react` | React LiveView hook (`useLiveView`)                                                   |
+| `bunderstack/client-rest`  | Type-safe REST client                                                                 |
+| `bunderstack/query`        | TanStack Query integration (`createClient`, `syncRealtime`)                           |
+| `bunderstack/query-react`  | React-specific query helpers                                                          |
+| `bunderstack/sync`         | TanStack DB realtime sync collections                                                 |
+| `bunderstack/start`        | TanStack Start integration (`createApiHandlers`)                                      |
+| `bunderstack/start-auth`   | Better Auth client for TanStack Start                                                 |
+| `bunderstack/provision`    | Database schema provisioning (`provision(app)`)                                       |
+| `bunderstack/testing`      | Test fixture helpers                                                                  |
+| `bunderstack/schema`       | Internal system tables (`export * from 'bunderstack/schema'`)                         |
+| `bunderstack/typeid`       | TypeID column types & generators                                                      |
 
 ---
 
@@ -79,6 +82,7 @@ All Bunderstack capabilities are imported directly from single-segment subpaths
 ### Scale Decision: Flat vs. Modular
 
 1. **Flat Layout (MVP / Small Service: < 5 tables, < 5 procedures, 1 job):**
+
    ```
    src/
    ├── bunderstack.ts   # backend declaration & app start
@@ -159,14 +163,16 @@ export const protectedProcedure = o.protected.use(async ({ context, next }) => {
   return next()
 })
 
-export const adminProcedure = protectedProcedure.use(async ({ context, next, errors }) => {
-  if (context.user.role !== 'admin') {
-    throw errors.FORBIDDEN({ message: 'Admin privileges required' })
-  }
-  return next()
-})
+export const adminProcedure = protectedProcedure.use(
+  async ({ context, next, errors }) => {
+    if (context.user.role !== 'admin') {
+      throw errors.FORBIDDEN({ message: 'Admin privileges required' })
+    }
+    return next()
+  },
+)
 
-// Graph-wide observability middleware (registered in bunderstack({ middleware: [instrumentation] }))
+// Graph-wide observability middleware (registered as `middleware: [instrumentation]`)
 export const instrumentation = o.middleware(async ({ context, next, path }) => {
   const startedAt = performance.now()
   try {
@@ -176,7 +182,9 @@ export const instrumentation = o.middleware(async ({ context, next, path }) => {
     const duration = Math.round(performance.now() - startedAt)
     // context.peekSession() reads resolved session without triggering forced auth on public/webhooks
     const userId = context.peekSession()?.user?.id
-    console.log(`[oRPC] ${path.join('.')} - ${duration}ms - User: ${userId ?? 'anon'}`)
+    console.log(
+      `[oRPC] ${path.join('.')} - ${duration}ms - User: ${userId ?? 'anon'}`,
+    )
   }
 })
 ```
@@ -184,6 +192,7 @@ export const instrumentation = o.middleware(async ({ context, next, path }) => {
 ### Rule: Circular Boot-Time Import Prevention
 
 `src/bunderstack/auth.ts` and `api/base.ts` must **NEVER** import `app` or `src/bunderstack/index.ts` at module top-level.
+
 - In `auth.ts`: Read `process.env` directly for secret keys. If an async hook (like email sending) needs the initialized app, use dynamic `import('./index')` inside the callback.
 - In `api/*.ts`: Consume `context.db`, `context.env`, `context.jobs`, `context.storage`, `context.auth` from handler parameters.
 
@@ -235,15 +244,16 @@ export const access = defineAccess(schema, {
   await client.posts.update.call({ id: 'post_1', title: 'Updated Title' })
   ```
 - **Custom List Procedures**: Use `listSpec` to give custom endpoints the same pagination and filtering behavior:
+
   ```ts
   import { listSpec } from 'bunderstack'
-  
+
   const logSpec = listSpec(schema.auditLogs, {
     filterable: ['level', 'userId'],
     sortable: ['createdAt'],
     defaultSort: { column: 'createdAt', order: 'desc' },
   })
-  
+
   export const logsProcedure = adminProcedure
     .input(logSpec.input)
     .handler(logSpec.handler)
@@ -251,7 +261,7 @@ export const access = defineAccess(schema, {
 
 ### 3.2 Authentication (`authConfig`)
 
-Export a clean Better Auth config and pass it into `bunderstack({ auth: authConfig })`:
+Export a clean Better Auth config and pass it as `auth: authConfig`; use the `({ db, env })` builder form when a hook needs the database or an env value:
 
 ```ts
 // src/bunderstack/auth.ts
@@ -277,12 +287,15 @@ import * as v from 'valibot'
 export const defineJobs = (jobs) =>
   jobs.define({
     sendWelcomeEmail: jobs.job({
-      input: v.object({ userId: v.string(), email: v.pipe(v.string(), v.email()) }),
+      input: v.object({
+        userId: v.string(),
+        email: v.pipe(v.string(), v.email()),
+      }),
       concurrency: 5,
       timeout: 30_000,
       retries: 3,
       handler: async ({ userId, email }, ctx) => {
-        await ctx.email.send({
+        await ctx.messaging.email.send({
           to: email,
           subject: 'Welcome!',
           html: '<h1>Welcome to our service</h1>',
@@ -360,6 +373,7 @@ Raise typed errors in procedures using `errors`:
 ```
 
 Outside procedures (e.g. in background jobs or domain services):
+
 ```ts
 import { BunderstackError } from 'bunderstack'
 
@@ -384,6 +398,7 @@ throw new BunderstackError('FORBIDDEN', 'Quota exceeded')
 
 > [!CAUTION]
 > **ALL MIGRATIONS MUST BE GENERATED EXCLUSIVELY VIA DRIZZLE-KIT CLI.**
+>
 > - Always run: `bunx drizzle-kit generate` (or `bun run db:generate`).
 > - **NEVER** hand-edit generated migration SQL files.
 > - **NEVER** let an LLM agent write or modify `.sql` files in `migrations/`.
@@ -410,7 +425,7 @@ export const Route = createFileRoute('/api/$')({
 })
 ```
 
-*Note: Remove any separate `/api/auth/$`, `/api/trpc/$`, or `/api/cron/*` route files.*
+_Note: Remove any separate `/api/auth/$`, `/api/trpc/$`, or `/api/cron/_` route files.\*
 
 ### Dedicated Production Worker (`src/worker.ts`)
 
@@ -429,6 +444,7 @@ await app.runWorker()
 ```
 
 Add worker script in `package.json`:
+
 ```json
 {
   "scripts": {
@@ -470,14 +486,17 @@ test('creates and retrieves a post', async () => {
   // Typed in-process oRPC client
   const client = t.client(identity)
 
-  const created = await client.posts.create({ title: 'New Post', content: 'Hello' })
+  const created = await client.posts.create({
+    title: 'New Post',
+    content: 'Hello',
+  })
   expect(created.title).toBe('New Post')
 
   // Run all queued background jobs deterministically
   await t.jobs.runUntilIdle()
 
   // Inspect sent emails
-  expect(t.email.sent).toHaveLength(0)
+  expect(t.messaging.email.sent).toHaveLength(0)
 })
 ```
 
@@ -515,6 +534,7 @@ Bunderhost monitors application deployment status via `GET /api/readiness`, whic
 ### Official Bunderstack Documentation for LLMs
 
 When working on Bunderstack projects, consult the dedicated LLM references:
+
 - **Web Documentation**: [https://bunderstack.kcrz.dev/docs](https://bunderstack.kcrz.dev/docs)
 - **Compact LLM Context (`llms.txt`)**: [https://bunderstack.kcrz.dev/docs/llms.txt](https://bunderstack.kcrz.dev/docs/llms.txt) (or local `node_modules/bunderstack/llms.txt`)
 - **Complete LLM Knowledge Base (`llms-full.txt`)**: [https://bunderstack.kcrz.dev/docs/llms-full.txt](https://bunderstack.kcrz.dev/docs/llms-full.txt)
@@ -524,10 +544,12 @@ When working on Bunderstack projects, consult the dedicated LLM references:
 Bunderhost provides a Model Context Protocol (MCP) server that allows coding agents to inspect, manage, and deploy projects.
 
 #### Connecting to Bunderhost MCP:
+
 1. Generate an Agent Access Token in Bunderhost: **Organization → Agent Access → Issue Token**.
 2. Connect your MCP client to `https://<bunderhost-host>/mcp` using the token as a `Bearer` credential.
 
 #### Key MCP Tools:
+
 - `list_projects`: List all projects in the organization.
 - `get_project`: Retrieve project configuration, active deployments, and blueprint status.
 - `get_project_readiness`: Check database reachability, migration state, and queue backlog.
@@ -537,6 +559,7 @@ Bunderhost provides a Model Context Protocol (MCP) server that allows coding age
 - `get_runtime_logs`: Stream runtime container logs.
 
 #### Agent Safety Rules for Bunderhost:
+
 1. **Secrets Are Never Exposed**: Database passwords, encryption keys, and environment values are never returned by MCP tools. When a new secret is needed, the agent must create a setup session (`create_setup_session`), and the user types the secret in the Bunderhost UI.
 2. **Mutations Require Confirmation**: Creating projects or deploying revisions require explicit user approval in the MCP client before execution.
 
@@ -544,15 +567,14 @@ Bunderhost provides a Model Context Protocol (MCP) server that allows coding age
 
 ## 9. Quick Reference & Common Mistakes
 
-| Anti-Pattern (Don't Do This) | Canonical Pattern (Do This) |
-| --- | --- |
-| Creating separate `/api/auth/$` and `/api/trpc/$` routes | Single catch-all `src/routes/api/$.ts` with `createApiHandlers(app)` |
-| Creating multiple Drizzle instances in `src/lib/db.ts` | Use `app.db` and `context.db`; export types with `BunderstackDb<typeof schema>` |
-| Constructing `ORPCError` manually | Use `errors.CODE({ message })` or `new BunderstackError('CODE', message)` |
-| Calling `getSession()` inside global middleware | Use `context.peekSession()` for non-blocking observability |
-| Editing `.sql` files in `migrations/` by hand | Always generate with `bunx drizzle-kit generate` and commit untouched |
-| Deploying to Bunderhost with schema push only | Generate and commit Drizzle migrations before deploying |
-| Starting workers inside the web server process in prod | Run dedicated `src/worker.ts` with `app.runWorker()` |
-| Hand-written HTTP `/api/cron/*` endpoints | Use `jobs.cron({ schedule, handler })` |
-| Top-level import of `app` inside `auth.ts` or `api/base.ts` | Consume `context` in handlers or use dynamic `import('./index')` in callbacks |
-
+| Anti-Pattern (Don't Do This)                                | Canonical Pattern (Do This)                                                     |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Creating separate `/api/auth/$` and `/api/trpc/$` routes    | Single catch-all `src/routes/api/$.ts` with `createApiHandlers(app)`            |
+| Creating multiple Drizzle instances in `src/lib/db.ts`      | Use `app.db` and `context.db`; export types with `BunderstackDb<typeof schema>` |
+| Constructing `ORPCError` manually                           | Use `errors.CODE({ message })` or `new BunderstackError('CODE', message)`       |
+| Calling `getSession()` inside global middleware             | Use `context.peekSession()` for non-blocking observability                      |
+| Editing `.sql` files in `migrations/` by hand               | Always generate with `bunx drizzle-kit generate` and commit untouched           |
+| Deploying to Bunderhost with schema push only               | Generate and commit Drizzle migrations before deploying                         |
+| Starting workers inside the web server process in prod      | Run dedicated `src/worker.ts` with `app.runWorker()`                            |
+| Hand-written HTTP `/api/cron/*` endpoints                   | Use `jobs.cron({ schedule, handler })`                                          |
+| Top-level import of `app` inside `auth.ts` or `api/base.ts` | Consume `context` in handlers or use dynamic `import('./index')` in callbacks   |

package/skills/migrating-to-bunderstack/references/audit-checklist.md

@@ -12,12 +12,12 @@ output or a file reference, not an assertion.
 | API mounting           | Hand-written handler maps; separate `/api/auth/$`, `/api/trpc/$`                     | `createApiHandlers(app)` on one `/api/$`                                             | Auth and oRPC requests succeed with only the catch-all present                                        | Shadowing route files deleted                                       |
 | Custom API routes      | Route files doing CRUD the framework can generate                                    | Generated CRUD plus `defineAccess`, or an `o.protected` procedure                    | Access rules cover each exposed table; a cross-owner request is denied                                | Route file has no client callers                                    |
 | Access control         | Per-endpoint session checks and hand-written SQL filters                             | `defineAccess(schema, rules)` with `scope.read` / `scope.write`                      | A test asserts a second user cannot read or write the first user's rows                               | Manual filter helpers unused                                        |
-| Jobs                   | BullMQ or a bespoke queue module                                                     | `jobs.define({ ... })` and `app.jobs.enqueue(...)`                                   | Job appears in `backend.manifest.background.jobs`                                                     | No queue library importer; package uninstalled                      |
+| Jobs                   | BullMQ or a bespoke queue module                                                     | `jobs.define({ ... })` and `app.jobs.enqueue(...)`                                   | Job appears in `backend.inspect().background.jobs`                                                    | No queue library importer; package uninstalled                      |
 | Cron                   | `/api/cron/*` guarded by a shared secret                                             | `jobs.cron({ schedule, handler })`                                                   | Cron task appears in the blueprint                                                                    | Cron route file and its secret removed from env                     |
 | Worker topology        | `startWorker()` or a queue bootstrap in the web entry                                | `src/worker.ts` calling `app.runWorker()`, run as its own process                    | Web entry starts no worker; the worker command exists in deployment config                            | Worker process is deployed before the embedded call is removed      |
 | Realtime               | Custom WebSocket server, manual pub/sub, channel-and-payload publishing              | `realtime` config plus `ctx.realtime.publish(table, event, row)` after commit        | A direct write reaches a subscriber with the complete row                                             | Custom transport deleted; shared Redis configured for multi-process |
 | Storage                | AWS or Tigris SDK wrapper, custom multipart upload route                             | Declared buckets and `app.storage`                                                   | Upload, signed URL, and delete work through the facade                                                | Wrapper deleted and SDK uninstalled                                 |
-| Email                  | Resend or SMTP SDK wrapper                                                           | `email` config and `app.email.send(...)`                                             | A send succeeds through the configured provider                                                       | Wrapper deleted and SDK uninstalled                                 |
+| Messaging              | Resend, SMTP, or Telegram SDK wrapper                                                | `messaging` channels and `app.messaging.<channel>.send(...)`                         | A send succeeds through the configured provider                                                       | Wrapper deleted and SDK uninstalled                                 |
 | Env                    | `createEnv()` beside the app, `dotenv`, unchecked `process.env` reads                | `env` schema in `bunderstack()`; source in `backend.start()`; `app.env` / `ctx.env`  | Boot fails with a clear message when a required variable is missing                                   | Legacy env module unused; `.env.example` lists names only           |
 | API declaration        | Router factories taking a bag of procedures; hand-written builder generics           | `defineApi({ schema, env })` bases in one module, plain router objects, `api` object | A router module imports its base and exports an object; no factory remains                            | `BunderstackApiBuilder<...>` and `os.$context<...>()` deleted       |
 | Observability          | Tracing or logging attached to an application procedure base                         | `middleware: [...]` in the config, which also reaches the generated CRUD             | A generated CRUD request produces a span or log line                                                  | Per-base instrumentation removed                                    |

package/skills/migrating-to-bunderstack/references/runtime-replacements.md

@@ -23,12 +23,14 @@ export const backend = bunderstack({
   schema,
   access,
   env: envSchema,
-  database: {
-    adapter: libsql(),
-    url: 'file:./data.db',
-  },
+  database: { adapter: libsql() },
   auth: authConfig,
-  email: { from: 'App <no-reply@example.com>' },
+  messaging: (env) => ({
+    email: resend({
+      apiKey: env.RESEND_API_KEY,
+      from: 'App <no-reply@example.com>',
+    }),
+  }),
   storage: {
     local: './uploads',
     defaultBucket: 'files',
@@ -69,7 +71,7 @@ await provision(app)
 
 The database adapter is imported explicitly; there is no implicit driver. Keep
 unrelated external side effects out of the backend import graph. The blueprint
-imports the declaration and reads `backend.manifest`; it never starts the app,
+imports the declaration and calls `backend.inspect({ env })`; it never starts the app,
 connects to a queue, or needs a special environment flag.
 
 Aggregate every domain, Better Auth, plugin, and internal table in the schema
@@ -230,19 +232,21 @@ access rules. Delete the AWS or Tigris wrapper and uninstall the SDK. A custom
 multipart upload route is replaced by the bucket's own upload route unless it
 performs domain work that cannot move into a job.
 
-## Email
+## Messaging
 
 ```ts
-await app.email.send({ to, subject, html })
+await app.messaging.email.send({ to, subject, html })
 ```
 
-Configure `email: { from, provider }`. `provider` defaults to `resend` when
-`RESEND_API_KEY` is set and `console` in development. The facade uses Web
-Standard `fetch`, so the `resend` package is uninstalled.
+Declare named channels: `messaging: (env) => ({ email: resend({ apiKey: env.RESEND_API_KEY, from }) })`. A
+channel whose credentials are absent or empty captures to the message journal
+instead of sending, and prints to the console locally. Telegram is a provider
+too, with its own message type. The facade uses Web Standard `fetch`, so the
+`resend` package is uninstalled.
 
 ## Env
 
-Pass `envSchema` to `bunderstack({ env: envSchema })` and read `app.env`
+Pass `envSchema` as the `env` key of the declaration and read `app.env`
 or `ctx.env`. Remove `@t3-oss/env-core` `createEnv()` calls and `dotenv`; Bun
 loads `.env` itself. Server variables must not use the `PUBLIC_` prefix, and
 browser-safe variables must. Declared env appears in the deployment blueprint,