bunderstack 0.15.2 → 0.17.0-beta.0

package/src/index.ts

@@ -1,25 +1,45 @@
+import type { AnyRouter as AnyORPCRouter } from '@orpc/server'
 // src/index.ts
-import type { AnyRouter } from '@trpc/server'
-import type { Hono as HonoType } from 'hono'
 
-import { fetchRequestHandler } from '@trpc/server/adapters/fetch'
+import { OpenAPIGenerator, OpenAPIGeneratorError } from '@orpc/openapi'
+import { OpenAPIHandler } from '@orpc/openapi/fetch'
+import { RPCHandler } from '@orpc/server/fetch'
+import { ValibotToJsonSchemaConverter } from '@orpc/valibot'
 
 import type { TableAccessInput } from './access'
+import type {
+  CrudApiRouterFor,
+  ExposedApiTables,
+  MergeApiRouterTypes,
+  UnifiedApiRouter,
+} from './api/types'
+import type { RealtimeApiRouter } from './api/realtime-router'
 import type { DbFor } from './db'
 import type {
   BunderstackJobsBuilder,
   EnqueueOptions,
   JobsDefs,
   JobsFacade,
-  LocalCronScheduler,
-  LocalCronSchedulerOptions,
   StartWorkerOptions,
   WorkerHandle,
 } from './jobs/index'
 import type { StorageConfigInput } from './storage/buckets'
 import type { StorageAdapter } from './storage/index'
 
-import { resolveAccessUser, validateAndResolveAccess } from './access'
+import { validateAndResolveAccess } from './access'
+import { createApiBuilder } from './api/builder'
+import { createApiContext } from './api/context'
+import { buildCrudApiRouter } from './api/crud-router'
+import { mergeOpenAPISpecs } from './api/openapi'
+import { buildRealtimeApiRouter } from './api/realtime-router'
+import { buildApiRouter } from './api/router'
+import { buildStorageApiRouter } from './api/storage-router'
+import {
+  buildApiRegistry,
+  mergeApiRoutersStrict,
+  normalizeApiPath,
+  normalizeForeignOpenAPISpec,
+} from './api/registry'
 import {
   createAuth,
   toAuthSessionResolver,
@@ -27,20 +47,17 @@ import {
 } from './auth'
 import { resolveConfig, type BunderstackConfig } from './config'
 import { resolveRealtimeRedisUrl } from './config'
-import { buildCrudRouter } from './crud'
 import { createDb } from './db'
 import { detectDialect } from './dialect'
 import { createEmail, emailProviderTag, type EmailFacade } from './email'
 import { validateEnv, type EnvConfigInput, type ValidatedEnv } from './env'
+import { BUNDERSTACK_ERROR_STATUS_MAP } from './errors'
 import { buildHandler } from './handler'
 import { withInternalTables } from './internal-tables'
 import {
   createJobsBuilder,
   createJobRunner,
-  buildCronRouter,
   enqueueJob,
-  runCronSlot,
-  startLocalCronScheduler,
   startJobWorker,
   validateJobsDefs,
 } from './jobs/index'
@@ -55,16 +72,17 @@ import {
   type RealtimeFacade,
   type RealtimeTransport,
 } from './realtime/facade'
-import { createRealtimeBroker, buildRealtimeRouter } from './realtime/index'
-import { createRedisRealtimeBroker } from './realtime/redis'
+import {
+  createMemoryRealtimePublisher,
+  createRedisRealtimePublisher,
+} from './realtime/publisher'
 import { deleteFileWithDerivatives } from './storage/delete'
 import { deleteFileMetaRow, insertReadyFile } from './storage/file-meta'
 import { createBucketStorages } from './storage/registry'
-import { buildBucketStorageRouter } from './storage/router'
+import { createStorageOperations } from './storage/operations'
 import { sweepOrphans } from './storage/sweep'
-import { createTRPC, type BunderstackTRPC } from './trpc'
 
-type AuthInstance = ReturnType<typeof createAuth>
+export type AuthInstance = ReturnType<typeof createAuth>
 
 function waitForWorkerShutdown(
   signal: AbortSignal,
@@ -138,11 +156,6 @@ export type AppRunWorkerOptions = AppStartWorkerOptions & {
    */
   allowProcessLocalRealtime?: boolean
 }
-export type AppStartCronSchedulerOptions = Pick<
-  LocalCronSchedulerOptions,
-  'onError'
->
-
 /** Bucket names declared in a storage config; `string` when unknowable. */
 export type BucketNamesOf<TStorage> = TStorage extends {
   buckets: infer B extends Record<string, unknown>
@@ -155,16 +168,13 @@ export type BunderstackApp<
   TAccess extends Record<string, TableAccessInput> | undefined = undefined,
   TBuckets extends string = string,
   TEnv extends EnvConfigInput | undefined = undefined,
-  TRouter = undefined,
   TJobsDefs extends JobsDefs | undefined = undefined,
+  TCustomApiRouter extends AnyORPCRouter | undefined = undefined,
 > = {
   handler: (req: Request) => Promise<Response>
   db: DbFor<TSchema>
   auth: AuthInstance
   storage: StorageFacade
-  router: HonoType
-  /** Raw tRPC router when the config declared one — escape hatch. */
-  trpcRouter?: AnyRouter
   /** Validated env: bunderstack's base vars plus the config's `env` extension. */
   env: ValidatedEnv<TEnv>
   /** Email facade; always present — send() throws when email isn't configured. */
@@ -178,11 +188,9 @@ export type BunderstackApp<
   startWorker(options?: AppStartWorkerOptions): Promise<WorkerHandle>
   /** Run a queue worker until aborted, then close the application. */
   runWorker(options?: AppRunWorkerOptions): Promise<void>
-  /** Start local delivery for declared cron tasks (for development only). */
-  startCronScheduler(
-    options?: AppStartCronSchedulerOptions,
-  ): Promise<LocalCronScheduler>
   close(): Promise<void>
+  /** True when this process is running the background tick loop. */
+  readonly backgroundRunning: boolean
   readonly status: LifecycleStatus
   readonly signal: AbortSignal
   /** Deploy-time introspection: what this app needs provisioned. */
@@ -195,129 +203,40 @@ export type BunderstackApp<
     schema: TSchema
     access: TAccess
     buckets: TBuckets
-    trpc: TRouter
+    api: MergeApiRouterTypes<
+      UnifiedApiRouter<CrudApiRouterFor<TSchema, TAccess>, TCustomApiRouter>,
+      RealtimeApiRouter
+    >
   }
 }
 
-// Overloads: the builder-callback form and the prebuilt-router/none form are
-// separate signatures so the callback's `t` parameter gets contextual typing
-// and the router type lands on `$inferClient` without conditional-type
-// inference (which breaks under contextual return types). `jobs` needs the
-// same split against BOTH trpc forms — a union parameter type (`TJobsDefs |
-// (callback => TJobsDefs)`) defeats inference (TS widens TJobsDefs to its
-// constraint when a function literal could match either union arm) — hence
-// four overloads covering the trpc × jobs option cross product.
 export function createBunderstack<
   TSchema extends Record<string, unknown>,
-  const TAccess extends Record<string, TableAccessInput> | undefined =
-    undefined,
+  const TAccess extends Record<string, TableAccessInput> | undefined = undefined,
   const TStorage extends StorageConfigInput | undefined = undefined,
   const TEnv extends EnvConfigInput | undefined = undefined,
-  TRouter extends AnyRouter = AnyRouter,
   const TJobsDefs extends JobsDefs | undefined = undefined,
+  TCustomApiRouter extends AnyORPCRouter | undefined = undefined,
 >(
-  options: BunderstackConfig<TSchema, TAccess, TStorage, TEnv> & {
-    /** Builder callback receiving the pre-wired `t` instance. */
-    trpc: (t: BunderstackTRPC<TSchema, ValidatedEnv<TEnv>>) => TRouter
-    /** Builder callback receiving the pre-wired `j` instance. */
-    jobs: (j: BunderstackJobsBuilder<TSchema, ValidatedEnv<TEnv>>) => TJobsDefs
+  options: BunderstackConfig<TSchema, TAccess, TStorage, TEnv, TCustomApiRouter> & {
+    jobs?: TJobsDefs | ((j: BunderstackJobsBuilder<TSchema, ValidatedEnv<TEnv>>) => TJobsDefs)
   },
-): Promise<
-  BunderstackApp<
-    TSchema,
-    TAccess,
-    BucketNamesOf<TStorage>,
-    TEnv,
-    TRouter,
-    TJobsDefs
-  >
->
-export function createBunderstack<
-  TSchema extends Record<string, unknown>,
-  const TAccess extends Record<string, TableAccessInput> | undefined =
-    undefined,
-  const TStorage extends StorageConfigInput | undefined = undefined,
-  const TEnv extends EnvConfigInput | undefined = undefined,
-  TRouter extends AnyRouter = AnyRouter,
-  const TJobsDefs extends JobsDefs | undefined = undefined,
->(
-  options: BunderstackConfig<TSchema, TAccess, TStorage, TEnv> & {
-    /** Builder callback receiving the pre-wired `t` instance. */
-    trpc: (t: BunderstackTRPC<TSchema, ValidatedEnv<TEnv>>) => TRouter
-    /** Prebuilt job definitions (escape hatch for multi-file setups). */
-    jobs?: TJobsDefs
-  },
-): Promise<
-  BunderstackApp<
-    TSchema,
-    TAccess,
-    BucketNamesOf<TStorage>,
-    TEnv,
-    TRouter,
-    TJobsDefs
-  >
->
-export function createBunderstack<
-  TSchema extends Record<string, unknown>,
-  const TAccess extends Record<string, TableAccessInput> | undefined =
-    undefined,
-  const TStorage extends StorageConfigInput | undefined = undefined,
-  const TEnv extends EnvConfigInput | undefined = undefined,
-  TRouter extends AnyRouter | undefined = undefined,
-  const TJobsDefs extends JobsDefs | undefined = undefined,
->(
-  options: BunderstackConfig<TSchema, TAccess, TStorage, TEnv> & {
-    /** Prebuilt tRPC router (escape hatch for multi-file setups). */
-    trpc?: TRouter
-    /** Builder callback receiving the pre-wired `j` instance. */
-    jobs: (j: BunderstackJobsBuilder<TSchema, ValidatedEnv<TEnv>>) => TJobsDefs
-  },
-): Promise<
-  BunderstackApp<
-    TSchema,
-    TAccess,
-    BucketNamesOf<TStorage>,
-    TEnv,
-    TRouter,
-    TJobsDefs
-  >
->
-export function createBunderstack<
+): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TJobsDefs, TCustomApiRouter>>
+export async function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
     undefined,
   const TStorage extends StorageConfigInput | undefined = undefined,
   const TEnv extends EnvConfigInput | undefined = undefined,
-  TRouter extends AnyRouter | undefined = undefined,
-  const TJobsDefs extends JobsDefs | undefined = undefined,
+  TCustomApiRouter extends AnyORPCRouter | undefined = undefined,
 >(
-  options: BunderstackConfig<TSchema, TAccess, TStorage, TEnv> & {
-    /** Prebuilt tRPC router (escape hatch for multi-file setups). */
-    trpc?: TRouter
-    /** Prebuilt job definitions (escape hatch for multi-file setups). */
-    jobs?: TJobsDefs
-  },
-): Promise<
-  BunderstackApp<
+  options: BunderstackConfig<
     TSchema,
     TAccess,
-    BucketNamesOf<TStorage>,
+    TStorage,
     TEnv,
-    TRouter,
-    TJobsDefs
-  >
->
-export async function createBunderstack<
-  TSchema extends Record<string, unknown>,
-  const TAccess extends Record<string, TableAccessInput> | undefined =
-    undefined,
-  const TStorage extends StorageConfigInput | undefined = undefined,
-  const TEnv extends EnvConfigInput | undefined = undefined,
->(
-  options: BunderstackConfig<TSchema, TAccess, TStorage, TEnv> & {
-    trpc?:
-      | AnyRouter
-      | ((t: BunderstackTRPC<TSchema, ValidatedEnv<TEnv>>) => AnyRouter)
+    TCustomApiRouter
+  > & {
     jobs?:
       | JobsDefs
       | ((j: BunderstackJobsBuilder<TSchema, ValidatedEnv<TEnv>>) => JobsDefs)
@@ -328,8 +247,8 @@ export async function createBunderstack<
     TAccess,
     BucketNamesOf<TStorage>,
     TEnv,
-    AnyRouter | undefined,
-    JobsDefs | undefined
+    JobsDefs | undefined,
+    TCustomApiRouter
   >
 > {
   const dialect = detectDialect(options.schema)
@@ -340,16 +259,14 @@ export async function createBunderstack<
     : undefined
   if (jobsDefs) validateJobsDefs(jobsDefs)
   // Env is validated FIRST: the app refuses to boot on missing/invalid vars,
-  // and everything downstream (config, email, trpc ctx) consumes the result.
+  // and everything downstream consumes the result.
   const env = validateEnv(options.env, {
     emailProvider: emailProviderTag(options.email),
     defaultDatabaseUrl:
       dialect === 'pg' ? 'file:./data.pglite' : 'file:./data.db',
-    // Storage orphan cleanup is also a signed platform schedule, so every
-    // production app has scheduled delivery even without user-defined cron.
-    cronConfigured: true,
+    source: options.processEnv,
   })
-  const config = resolveConfig(options, env)
+  const config = resolveConfig(options, env, options.processEnv)
   // Adapters use Drizzle mocks during deployment introspection, so the database
   // and Redis below never touch external services.
   const introspect = process.env.BUNDERSTACK_INTROSPECT === '1'
@@ -394,81 +311,51 @@ export async function createBunderstack<
       typeof config.realtime === 'object'
         ? config.realtime.bufferSize
         : undefined
+    const realtimeResumeSeconds =
+      typeof config.realtime === 'object'
+        ? config.realtime.resumeSeconds
+        : undefined
     const configuredRedisUrl = config.realtime
       ? resolveRealtimeRedisUrl(config.realtime, env)
       : undefined
-    const configuredRealtimeTransport: RealtimeTransport = !config.realtime
-      ? 'disabled'
-      : configuredRedisUrl
-        ? 'redis'
-        : 'memory'
     const redisUrl = introspect ? undefined : configuredRedisUrl
-    const broker = config.realtime
+    const publisher = config.realtime
       ? redisUrl
-        ? createRedisRealtimeBroker({
-            access: resolvedAccess,
-            channel: process.env.BUNDERSTACK_REALTIME_CHANNEL || undefined,
-            redis: () => {
-              // Redis pub/sub requires a dedicated connection (subscribe puts the client into
-              // a restricted state). We use one client for commands and a second for subscribe.
-              const cmdClient = new Bun.RedisClient(redisUrl)
-              const subClient = new Bun.RedisClient(redisUrl)
-              return {
-                incr: (key: string) => cmdClient.incr(key),
-                publish: (channel: string, message: string) =>
-                  cmdClient.publish(channel, message),
-                subscribe: (channel: string, listener: (msg: string) => void) =>
-                  subClient.subscribe(channel, listener),
-                lpush: (key: string, value: string) =>
-                  cmdClient.lpush(key, value),
-                ltrim: (key: string, start: number, stop: number) =>
-                  cmdClient.ltrim(key, start, stop),
-                lrange: (key: string, start: number, stop: number) =>
-                  cmdClient.lrange(key, start, stop),
-                close: () => {
-                  cmdClient.close()
-                  subClient.close()
-                },
-              }
-            },
-            bufferSize: realtimeBufferSize,
-          })
-        : createRealtimeBroker({
-            access: resolvedAccess,
-            bufferSize: realtimeBufferSize,
+        ? (() => {
+            const redis = new Bun.RedisClient(redisUrl)
+            const subscriber = redis.duplicate()
+            lifecycle.add(async () => {
+              redis.close()
+              ;(await subscriber).close()
+            })
+            return createRedisRealtimePublisher(redis, subscriber, {
+              prefix:
+                process.env.BUNDERSTACK_REALTIME_PREFIX ?? 'bunderstack:',
+              maxBufferedEvents: realtimeBufferSize,
+              resumeSeconds: realtimeResumeSeconds,
+            })
+          })()
+        : createMemoryRealtimePublisher({
+            maxBufferedEvents: realtimeBufferSize,
+            resumeSeconds: realtimeResumeSeconds,
           })
       : undefined
-    const runtimeRealtimeTransport: RealtimeTransport = !broker
+    const runtimeRealtimeTransport: RealtimeTransport = !publisher
       ? 'disabled'
       : redisUrl
         ? 'redis'
         : 'memory'
     const realtime = createRealtimeFacade<TSchema>(
-      broker,
+      publisher,
       runtimeRealtimeTransport,
     )
-    const crudRouter = buildCrudRouter(options.schema, userDb, {
-      auth: authResolver,
-      access: resolvedAccess,
-      idempotency: options.idempotency,
-      realtime,
-    })
-    const realtimeRouter = broker
-      ? buildRealtimeRouter(broker, {
-          auth: authResolver,
-          keepaliveMs:
-            typeof config.realtime === 'object'
-              ? config.realtime.keepaliveMs
-              : undefined,
-        })
-      : undefined
     const registry = createBucketStorages(config.storage)
-    if (broker) lifecycle.add(() => broker.close())
-    const storageRouter = buildBucketStorageRouter({
+    const storageOperations = createStorageOperations({
       registry,
       db,
-      auth: authResolver,
     })
+    const storageApiRouter = buildStorageApiRouter(registry, storageOperations)
+    const realtimeApiRouter = buildRealtimeApiRouter(publisher, resolvedAccess)
     const storage: StorageFacade = {
       async delete(fileId) {
         const bucketName = fileId.split('/')[0] ?? ''
@@ -518,25 +405,43 @@ export async function createBunderstack<
         })
       },
     }
-    const jobRunner = jobsDefs
+    const storageConfigured = Boolean(options.storage)
+    // The storage sweep used to be a hardcoded maintenance route. It is an
+    // ordinary cron now, so it inherits retries, timeout and onFailed.
+    const resolvedDefs: JobsDefs | undefined = storageConfigured
+      ? {
+          ...(jobsDefs ?? {}),
+          'bunderstack:storage-sweep': {
+            kind: 'cron',
+            schedule: '0 4 * * *',
+            handler: async () => {
+              await storage.sweep()
+            },
+          },
+        }
+      : jobsDefs
+
+    const jobRunner = resolvedDefs
       ? createJobRunner({
           db,
-          defs: jobsDefs,
+          defs: resolvedDefs,
           ctx: { db: userDb, env, email, storage, realtime },
         })
       : undefined
     const jobs = {
       async enqueue(name: string, input?: unknown, opts?: EnqueueOptions) {
-        if (!jobsDefs) {
+        if (!resolvedDefs) {
           throw new Error(
             '[bunderstack] no jobs configured — add a `jobs` key to createBunderstack',
           )
         }
-        const result = await enqueueJob(db, jobsDefs, name, input, opts)
+        const result = await enqueueJob(db, resolvedDefs, name, input, opts)
         return result
       },
       tick(now?: number) {
-        return jobRunner ? jobRunner.tick(now) : Promise.resolve()
+        return jobRunner
+          ? jobRunner.tick(now)
+          : Promise.resolve({ claimed: 0, ran: 0, failed: 0 })
       },
     }
     if (jobRunner) jobRunner.setJobsFacade(jobs)
@@ -558,54 +463,16 @@ export async function createBunderstack<
       const handle = startJobWorker({
         ...options,
         signal,
-        tick: (now) => jobRunner.tick(now),
+        // The runtime loop only cares that a tick completed; TickResult is for
+        // callers that invoke tick() directly.
+        tick: async (now) => {
+          await jobRunner.tick(now)
+        },
       })
       const unregister = lifecycle.add(() => handle.close())
       void handle.closed.finally(unregister)
       return handle
     }
-    const startCronScheduler = async (
-      options: AppStartCronSchedulerOptions = {},
-    ): Promise<LocalCronScheduler> => {
-      if (introspect) {
-        return { tick: async () => {}, close: async () => {} }
-      }
-      const cron = Object.entries(jobsDefs ?? {}).flatMap(
-        ([name, definition]) =>
-          definition.kind === 'cron'
-            ? [{ name, schedule: definition.schedule }]
-            : [],
-      )
-      if (cron.length === 0) {
-        throw new Error('[bunderstack] no cron tasks configured')
-      }
-      if (lifecycle.status !== 'ready') {
-        throw new Error('[bunderstack] application lifecycle is closed')
-      }
-      const scheduler = startLocalCronScheduler({
-        cron,
-        onError: options.onError,
-        runSlot: async (name, slot) => {
-          await runCronSlot({
-            db,
-            defs: jobsDefs!,
-            ctx: { db: userDb, env, email, storage, realtime },
-            name,
-            slot,
-            now: Date.now(),
-          })
-        },
-      })
-      const unregister = lifecycle.add(() => scheduler.close())
-      try {
-        await scheduler.tick()
-      } catch (error) {
-        unregister()
-        await scheduler.close()
-        throw error
-      }
-      return scheduler
-    }
     const runWorker = async (
       options: AppRunWorkerOptions = {},
     ): Promise<void> => {
@@ -633,61 +500,173 @@ export async function createBunderstack<
         await lifecycle.close()
       }
     }
-    const trpcRouter: AnyRouter | undefined =
-      typeof options.trpc === 'function'
-        ? options.trpc(createTRPC<TSchema, ValidatedEnv<TEnv>>())
-        : options.trpc
-    const trpcHandler = trpcRouter
-      ? (req: Request) =>
-          fetchRequestHandler({
-            endpoint: '/api/trpc',
-            req,
-            router: trpcRouter,
-            createContext: async () => ({
-              db: userDb,
-              user: await resolveAccessUser(authResolver, req.headers),
-              env,
-              email,
-              jobs,
-              realtime,
-              storage,
-              req,
-            }),
-          })
+    const crudApiRouter = buildCrudApiRouter(options.schema, userDb, {
+      access: resolvedAccess,
+      idempotency: options.idempotency,
+      realtime,
+    })
+
+    const customApiRouter = options.api
+      ? options.api(createApiBuilder<TSchema, ValidatedEnv<TEnv>>())
       : undefined
-    const cronRouter = env.BUNDERSTACK_CRON_SECRET
-      ? buildCronRouter({
-          db,
-          defs: jobsDefs ?? {},
-          ctx: { db: userDb, env, email, storage, realtime },
-          secret: env.BUNDERSTACK_CRON_SECRET,
-          storage,
+
+    const nativeRouter = buildApiRouter({
+      crud: crudApiRouter as Record<string, unknown>,
+      storage: storageApiRouter as Record<string, unknown>,
+      realtime: realtimeApiRouter as Record<string, unknown> | undefined,
+      custom: customApiRouter as Record<string, unknown> | undefined,
+    }) as any
+
+    const authOpenAPISpecRaw =
+      options.openapi &&
+      auth.api &&
+      'generateOpenAPISchema' in auth.api &&
+      typeof auth.api.generateOpenAPISchema === 'function'
+        ? await auth.api.generateOpenAPISchema()
+        : undefined
+
+    const authOpenAPISpec = authOpenAPISpecRaw
+      ? normalizeForeignOpenAPISpec(authOpenAPISpecRaw, {
+          prefix: '/api/auth',
+          source: 'auth',
         })
       : undefined
-    const { handler, router } = buildHandler({
-      crudRouter,
+
+    await buildApiRegistry({
+      nativeRouter,
+      foreignSpecs: authOpenAPISpec ? [authOpenAPISpec] : [],
+      reservedCoreHandles: new Set([
+        'health',
+        ...(publisher ? ['realtime.changes'] : []),
+        ...[...registry.keys()].flatMap((name) =>
+          ['prepareUpload', 'upload', 'confirmUpload', 'download', 'delete'].map(
+            (operation) => `files.${name}.${operation}`,
+          ),
+        ),
+      ]),
+    })
+
+    const combinedOpenAPISpec = options.openapi
+      ? mergeOpenAPISpecs({
+          nativeSpec: await new OpenAPIGenerator({
+            converters: [
+              new ValibotToJsonSchemaConverter(),
+              {
+                condition: (schema: any) =>
+                  Boolean(
+                    schema?.['~standard'] &&
+                      !schema['~standard'].jsonSchema,
+                  ),
+                convert: (schema: any) => {
+                  const vendor = schema?.['~standard']?.vendor ?? 'unknown'
+                  throw new OpenAPIGeneratorError(
+                    `No JSON Schema converter is configured for Standard Schema vendor "${vendor}"`,
+                  )
+                },
+              },
+            ],
+          }).generate(nativeRouter),
+          authSpec: authOpenAPISpec,
+        })
+      : undefined
+
+    const openapiHandler = new OpenAPIHandler(nativeRouter, {
+      errorStatusMap: BUNDERSTACK_ERROR_STATUS_MAP,
+      customErrorResponseBodyEncoder: (error: any) => ({
+        error: error.message,
+        code: error.data?.code ?? error.code,
+        ...(error.data?.details !== undefined
+          ? { details: error.data.details }
+          : {}),
+      }),
+      fetchInterceptors: [
+        async (options) => {
+          const res = await options.next()
+          if (res.matched && options.context.resHeaders) {
+            options.context.resHeaders.forEach((v: string, k: string) =>
+              res.response.headers.set(k, v),
+            )
+          }
+          return res
+        },
+      ],
+    })
+    const rpcHandler = new RPCHandler(nativeRouter)
+
+    const apiHandler = async (req: Request): Promise<Response | null> => {
+      const urlString = typeof req === 'string' ? (req as string) : req.url
+      if (!urlString) return null
+      const url = new URL(urlString, 'http://localhost')
+      if (
+        combinedOpenAPISpec &&
+        url.pathname === '/api/openapi.json' &&
+        req.method === 'GET'
+      ) {
+        return new Response(JSON.stringify(combinedOpenAPISpec), {
+          headers: { 'Content-Type': 'application/json' },
+        })
+      }
+
+      const apiCtx = createApiContext(
+        {
+          db: userDb,
+          env,
+          storage,
+          email,
+          jobs,
+          realtime,
+          auth,
+          authResolver,
+        },
+        req,
+      )
+
+      if (url.pathname.startsWith('/api/rpc')) {
+        const res = await rpcHandler.handle(req, {
+          prefix: '/api/rpc',
+          context: apiCtx,
+        })
+        if (res.matched) return res.response
+      }
+
+      const openapiRes = await openapiHandler.handle(req, { context: apiCtx })
+      if (openapiRes.matched) return openapiRes.response
+
+      return null
+    }
+
+    const handler = buildHandler({
       authHandler: (req) => auth.handler(req),
-      storageRouter,
-      realtimeRouter,
-      trpcHandler,
-      cronRouter,
+      apiHandler,
       rateLimit: options.rateLimit,
     })
 
+    // Topology is a deployment concern: the role decides whether this process
+    // runs background work, so application code never has to.
+    const roleWantsWorker =
+      env.BUNDERSTACK_ROLE === 'all' || env.BUNDERSTACK_ROLE === 'worker'
+    const autoStart =
+      options.background?.autoStart ??
+      (roleWantsWorker && !introspect && resolvedDefs !== undefined)
+    let backgroundRunning = false
+    if (autoStart) {
+      await startWorker()
+      backgroundRunning = true
+    }
+
     const app: BunderstackApp<
       TSchema,
       TAccess,
       BucketNamesOf<TStorage>,
       TEnv,
-      AnyRouter | undefined,
-      JobsDefs | undefined
+      JobsDefs | undefined,
+      TCustomApiRouter
     > = {
       handler,
       // Internal tables live on the runtime db but stay out of the public type.
       db: userDb,
       auth,
       storage,
-      router,
       env,
       email,
       realtime,
@@ -697,13 +676,12 @@ export async function createBunderstack<
       jobs: jobs as never,
       startWorker,
       runWorker,
-      startCronScheduler,
       close: () => lifecycle.close(),
+      backgroundRunning,
       get status() {
         return lifecycle.status
       },
       signal: lifecycle.signal,
-      trpcRouter,
       manifest: buildManifest({
         schema: options.schema,
         dialect,
@@ -712,7 +690,7 @@ export async function createBunderstack<
         envConfig: options.env as EnvConfigInput | undefined,
         emailProvider: emailProviderTag(options.email),
         realtime: Boolean(config.realtime),
-        jobs: jobsDefs,
+        jobs: resolvedDefs,
       }),
     }
 
@@ -744,6 +722,8 @@ export async function createBunderstack<
 }
 
 export { MAX_LIST_LIMIT } from './list-query'
+export { BunderstackError } from './errors'
+export type { BunderstackErrorCode } from './errors'
 export { resolveConfig } from './config'
 export type {
   BetterAuthConfig,
@@ -761,13 +741,7 @@ export type {
   EmailConfigInput,
   EmailFacade,
 } from './email'
-export { createTRPC } from './trpc'
-export type { BunderstackTRPC, TRPCContext } from './trpc'
-export {
-  createJobsBuilder,
-  signScheduleRequest,
-  verifyScheduleRequest,
-} from './jobs/index'
+export { createJobsBuilder } from './jobs/index'
 export type {
   BunderstackJobContext,
   BunderstackJobsBuilder,
@@ -783,8 +757,6 @@ export type {
   JobsRuntimeFacade,
   QueueJobDefinition,
   QueueJobKeys,
-  LocalCronScheduler,
-  LocalCronSchedulerOptions,
   RunWorkerOptions,
   StartWorkerOptions,
   WorkerHandle,
@@ -824,10 +796,27 @@ export type {
 export type { TransformSpec } from './storage/thumbnails'
 export { mockAuthSession } from './testing'
 
-export type { RealtimeAction } from './realtime/index'
+export type { RealtimeAction } from './realtime/publisher'
 export { createRealtimeFacade } from './realtime/facade'
 export type {
   RealtimeFacade,
   RealtimeTransport,
   SchemaTable,
 } from './realtime/facade'
+
+export { createApiBuilder } from './api/builder'
+export type { BunderstackApiBuilder, ApiFactory } from './api/builder'
+export type {
+  CrudApiRouterFor,
+  ExposedApiTables,
+  MergeApiRouterTypes,
+  UnifiedApiRouter,
+} from './api/types'
+export type { TableCrudProcedures } from './api/crud-router'
+export {
+  buildApiRegistry,
+  mergeApiRoutersStrict,
+  normalizeApiPath,
+  normalizeForeignOpenAPISpec,
+} from './api/registry'
+export { mergeOpenAPISpecs } from './api/openapi'