bunderstack 0.9.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Batteries-included backend framework for Bun: CRUD APIs, auth, file storage, realtime, tRPC, email, and validated env from a single Drizzle schema and config object.",
   "keywords": [
     "backend",

package/src/access.ts

@@ -311,7 +311,13 @@ export function validateAndResolveAccess<
       columns.includes('userId')
 
     if (!hasExplicitRules && !hasConventionOwner) continue
-    if (!ownerColumn && input?.crud !== true && !input?.scope?.read && !input?.scope?.write) continue
+    if (
+      !ownerColumn &&
+      input?.crud !== true &&
+      !input?.scope?.read &&
+      !input?.scope?.write
+    )
+      continue
 
     if (input?.ownerColumn && !columns.includes(input.ownerColumn)) {
       throw new Error(
@@ -483,7 +489,7 @@ export function sanitizeWriteBody(
 export type AuthSessionResolver = {
   api: {
     getSession: (opts: { headers: Headers }) => Promise<{
-      user: { id: string; email: string; name?: string } | null
+      user: { id: string; email: string; name?: string; role?: string } | null
       session?: { activeOrganizationId?: string | null } | null
     } | null>
   }
@@ -500,6 +506,7 @@ export async function resolveAccessUser(
     id: session.user.id,
     email: session.user.email,
     name: session.user.name,
+    role: session.user.role,
   }
 }
 
@@ -515,6 +522,7 @@ export async function resolveSession(
       id: session.user.id,
       email: session.user.email,
       name: session.user.name,
+      role: session.user.role,
     },
     activeOrganizationId: session.session?.activeOrganizationId ?? null,
   }

package/src/auth.ts

@@ -2,16 +2,22 @@
 import { betterAuth } from 'better-auth'
 import { drizzleAdapter } from 'better-auth/adapters/drizzle'
 
-import type { BetterAuthConfig } from './config'
 import type { AuthSessionResolver } from './access'
+import type { BetterAuthConfig } from './config'
 import type { AnyDb, Dialect } from './dialect'
 import type { EmailFacade } from './email'
 
-export function createAuth(db: AnyDb, cfg: BetterAuthConfig, dialect: Dialect) {
+export function createAuth(
+  db: AnyDb,
+  cfg: BetterAuthConfig,
+  dialect: Dialect,
+  userSchema?: Record<string, unknown>,
+) {
   return betterAuth({
     ...cfg,
     database: drizzleAdapter(db as Parameters<typeof drizzleAdapter>[0], {
       provider: dialect === 'pg' ? 'pg' : 'sqlite',
+      ...(userSchema ? { schema: userSchema } : {}),
     }),
   })
 }
@@ -39,15 +45,18 @@ export function toAuthSessionResolver(
             typeof session.activeOrganizationId === 'string'
               ? session.activeOrganizationId
               : null
+          const role =
+            'role' in result.user && typeof result.user.role === 'string'
+              ? result.user.role
+              : undefined
           return {
             user: {
               id: result.user.id,
               email: result.user.email,
               name: result.user.name,
+              ...(role ? { role } : {}),
             },
-            session: session
-              ? { activeOrganizationId }
-              : null,
+            session: session ? { activeOrganizationId } : null,
           }
         }
         return null
@@ -70,7 +79,10 @@ export function withEmailAuthDefaults(
   if (!emailConfigured) return cfg
   const out: BetterAuthConfig = { ...cfg }
 
-  if (cfg.emailAndPassword?.enabled && !cfg.emailAndPassword.sendResetPassword) {
+  if (
+    cfg.emailAndPassword?.enabled &&
+    !cfg.emailAndPassword.sendResetPassword
+  ) {
     out.emailAndPassword = {
       ...cfg.emailAndPassword,
       sendResetPassword: async ({ user, url }) => {

package/src/config.ts

@@ -2,7 +2,7 @@
 import { betterAuth } from 'better-auth'
 import { z } from 'zod'
 
-import type { TableAccessInput } from './access'
+import type { AuthSessionResolver, TableAccessInput } from './access'
 import type { DatabaseAdapter } from './database/adapter'
 import type { EmailConfigInput } from './email'
 import type { IdempotencyConfig } from './idempotency'
@@ -86,6 +86,7 @@ export type BunderstackConfig<
   | 'schema'
   | 'access'
   | 'auth'
+  | 'authResolver'
   | 'storage'
   | 'env'
   | 'email'
@@ -102,6 +103,11 @@ export type BunderstackConfig<
     migrations?: string
   }
   auth?: BetterAuthConfig
+  /**
+   * Reuse an application-owned session reader for CRUD, realtime, storage,
+   * and tRPC while keeping Bunderstack's auth handler available.
+   */
+  authResolver?: AuthSessionResolver
   storage?: TStorage
   env?: TEnv
   email?: EmailConfigInput

package/src/index.ts

@@ -107,6 +107,14 @@ export interface StorageFacade {
    * the count reaped.
    */
   sweep(olderThanMs?: number): Promise<number>
+  /**
+   * Get a public or presigned download URL for a file key.
+   * Returns a presigned S3 URL when S3 is configured, or local proxy route `/api/files/...` in development.
+   */
+  getUrl(
+    key: string,
+    opts?: { bucket?: string; expiresIn?: number },
+  ): Promise<string>
 }
 
 export type AppStartWorkerOptions = Omit<StartWorkerOptions, 'tick'>
@@ -362,10 +370,11 @@ export async function createBunderstack<
       db,
       withEmailAuthDefaults(config.auth, email, Boolean(options.email)),
       dialect,
+      options.schema as Record<string, unknown>,
     )
     // Internal routers consume the narrow AuthSessionResolver contract, not the
     // raw better-auth instance. app.auth still exposes `auth` unchanged.
-    const authResolver = toAuthSessionResolver(auth)
+    const authResolver = options.authResolver ?? toAuthSessionResolver(auth)
     const resolvedAccess = validateAndResolveAccess(
       options.schema,
       options.access,
@@ -465,6 +474,19 @@ export async function createBunderstack<
       sweep(olderThanMs = DEFAULT_PENDING_TTL_MS) {
         return sweepOrphans(registry, db, olderThanMs)
       },
+      async getUrl(key, opts = {}) {
+        const bucketName =
+          opts.bucket ??
+          key.split('/')[0] ??
+          registry.defaultBucketName
+        const adapter = registry.get(bucketName)?.adapter
+        if (adapter?.presignGet) {
+          return adapter.presignGet(key, {
+            expiresIn: opts.expiresIn ?? 3600,
+          })
+        }
+        return `/api/files/${key}`
+      },
     }
     const jobRunner = jobsDefs
       ? createJobRunner({
@@ -708,6 +730,7 @@ export {
   verifyScheduleRequest,
 } from './jobs/index'
 export type {
+  BunderstackJobContext,
   BunderstackJobsBuilder,
   BackgroundDefinition,
   BackgroundDefs,
@@ -760,6 +783,7 @@ export type {
 } from './storage/buckets'
 // StorageFacade is declared+exported inline above.
 export type { TransformSpec } from './storage/thumbnails'
+export { mockAuthSession } from './testing'
 
 export type { RealtimeAction } from './realtime/index'
 export { createRealtimeFacade } from './realtime/facade'

package/src/jobs/define.ts

@@ -49,6 +49,11 @@ export type JobContext<
   realtime: RealtimeFacade<TSchema>
 }
 
+export type BunderstackJobContext<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = JobContext<TSchema, TEnvResult>
+
 export type QueueJobDefinition<
   TInput,
   TSchema extends Record<string, unknown> = Record<string, unknown>,
@@ -82,9 +87,10 @@ export type CronInvocation = { scheduledFor: Date }
 export type CronDefinition<
   TSchema extends Record<string, unknown> = Record<string, unknown>,
   TEnvResult = Record<string, unknown>,
+  TSchedule extends string = string,
 > = {
   kind: 'cron'
-  schedule: string
+  schedule: TSchedule
   handler: (
     invocation: CronInvocation,
     ctx: JobContext<TSchema, TEnvResult>,
@@ -97,18 +103,22 @@ export type BackgroundDefinition =
 export type BackgroundDefs = Record<string, BackgroundDefinition>
 
 /** @deprecated Use QueueJobDefinition. */
-export type JobDefinition<TInput, TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>> = QueueJobDefinition<
+export type JobDefinition<
   TInput,
-  TSchema,
-  TEnvResult
->
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = QueueJobDefinition<TInput, TSchema, TEnvResult>
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type AnyJobDefinition = QueueJobDefinition<any, any, any>
 export type JobsDefs = BackgroundDefs
 
 export type QueueJobKeys<TDefs extends BackgroundDefs> = {
-  [K in keyof TDefs & string]: TDefs[K] extends QueueJobDefinition<any, any, any>
+  [K in keyof TDefs & string]: TDefs[K] extends QueueJobDefinition<
+    any,
+    any,
+    any
+  >
     ? K
     : never
 }[keyof TDefs & string]
@@ -123,11 +133,21 @@ export function validateBackgroundDefs(defs: BackgroundDefs): void {
       parseCron(def.schedule)
       continue
     }
-    if (def.retries !== undefined && (def.retries < 0 || !Number.isInteger(def.retries))) {
-      throw new Error(`[bunderstack] job "${name}": retries must be a non-negative integer`)
+    if (
+      def.retries !== undefined &&
+      (def.retries < 0 || !Number.isInteger(def.retries))
+    ) {
+      throw new Error(
+        `[bunderstack] job "${name}": retries must be a non-negative integer`,
+      )
     }
-    if (def.concurrency !== undefined && (def.concurrency < 1 || !Number.isInteger(def.concurrency))) {
-      throw new Error(`[bunderstack] job "${name}": concurrency must be a positive integer`)
+    if (
+      def.concurrency !== undefined &&
+      (def.concurrency < 1 || !Number.isInteger(def.concurrency))
+    ) {
+      throw new Error(
+        `[bunderstack] job "${name}": concurrency must be a positive integer`,
+      )
     }
     if (def.timeout !== undefined && def.timeout <= 0) {
       throw new Error(`[bunderstack] job "${name}": timeout must be positive`)
@@ -162,9 +182,9 @@ export function createJobsBuilder<
     ): QueueJobDefinition<TInput, TSchema, TEnvResult> {
       return { kind: 'job', ...def }
     },
-    cron(
-      def: Omit<CronDefinition<TSchema, TEnvResult>, 'kind'>,
-    ): CronDefinition<TSchema, TEnvResult> {
+    cron<const TSchedule extends string>(
+      def: Omit<CronDefinition<TSchema, TEnvResult, TSchedule>, 'kind'>,
+    ): CronDefinition<TSchema, TEnvResult, TSchedule> {
       parseCron(def.schedule)
       return { kind: 'cron', ...def }
     },
@@ -187,9 +207,8 @@ export type BunderstackJobsBuilder<
 // `TDef extends { input: ZodType<infer I> }` fails structurally because
 // `input?: ZodType<TInput>` desugars to `ZodType<TInput> | undefined`, which
 // can never satisfy a required-property pattern.
-type JobInputOf<TDef> = TDef extends QueueJobDefinition<infer TInput, any, any>
-  ? TInput
-  : undefined
+type JobInputOf<TDef> =
+  TDef extends QueueJobDefinition<infer TInput, any, any> ? TInput : undefined
 
 /**
  * `app.jobs`: `enqueue` narrowed to declared names + payloads. `Omit`s the

package/src/jobs/index.ts

@@ -10,6 +10,7 @@ export type {
   AnyJobDefinition,
   BackgroundDefinition,
   BackgroundDefs,
+  BunderstackJobContext,
   BunderstackJobsBuilder,
   EnqueueOptions,
   JobContext,

package/src/jobs/local-cron.ts

@@ -1,6 +1,6 @@
 import { cronMatches, parseCron } from './cron'
 
-type Timer = ReturnType<typeof setTimeout>
+type Timer = ReturnType<typeof setTimeout> | number
 
 export type LocalCronDefinition = {
   name: string
@@ -45,7 +45,9 @@ export function startLocalCronScheduler(
     timer = setTimer(() => {
       timer = undefined
       void tick().catch((error: unknown) => {
-        options.onError?.(error instanceof Error ? error : new Error(String(error)))
+        options.onError?.(
+          error instanceof Error ? error : new Error(String(error)),
+        )
       })
     }, delay)
   }

package/src/testing.ts

@@ -0,0 +1,31 @@
+// src/testing.ts — test utilities for Bunderstack applications.
+
+export type AuthSessionResolverLike = {
+  api: {
+    getSession: (opts: { headers: Headers }) => Promise<unknown>
+  }
+}
+
+export type BunderstackAppLike = {
+  auth: unknown
+}
+
+/**
+ * Mock the auth session resolver on a Bunderstack app instance for unit testing.
+ */
+export function mockAuthSession<
+  TUser extends { id: string; email: string; name?: string; role?: string },
+>(
+  app: BunderstackAppLike,
+  resolver: (opts: { headers: Headers }) => Promise<{
+    user: TUser
+    session?: { activeOrganizationId?: string | null } | null
+  } | null>,
+): void {
+  const auth = app.auth as unknown as AuthSessionResolverLike
+  if (auth?.api) {
+    auth.api.getSession = resolver as unknown as (opts: {
+      headers: Headers
+    }) => Promise<unknown>
+  }
+}