bunderstack 0.15.2 → 0.17.0-beta.0

package/src/api/registry.ts

@@ -0,0 +1,338 @@
+import { getOpenAPIMeta } from '@orpc/openapi'
+
+const RESERVED_EXACT = new Set([
+  '/api/health',
+  '/api/openapi.json',
+  '/api/realtime',
+  '/api/rpc',
+  '/api/auth',
+  '/api/files',
+])
+const RESERVED_PREFIXES = ['/api/rpc/', '/api/auth/', '/api/files/']
+
+function collisionForBunderstackPath(path: string): string | undefined {
+  if (RESERVED_EXACT.has(path)) return 'it is reserved by bunderstack'
+  const prefix = RESERVED_PREFIXES.find((value) => path.startsWith(value))
+  return prefix ? `"${prefix}*" is reserved by bunderstack` : undefined
+}
+
+export interface ApiRegistryEntry {
+  handle: string
+  operationId: string
+  method: string
+  path: string
+  source: string
+}
+
+export interface ApiRegistry {
+  entries: ApiRegistryEntry[]
+}
+
+export interface ForeignSpecEntry {
+  spec: Record<string, unknown>
+  prefix?: string
+  source?: string
+}
+
+export interface BuildApiRegistryOptions {
+  nativeRouter?: Record<string, unknown>
+  foreignSpecs?: Array<Record<string, unknown> | ForeignSpecEntry>
+  /** Native procedures generated by Bunderstack itself may own reserved paths. */
+  reservedCoreHandles?: ReadonlySet<string>
+}
+
+const HTTP_METHODS = new Set([
+  'GET',
+  'POST',
+  'PUT',
+  'PATCH',
+  'DELETE',
+  'HEAD',
+  'OPTIONS',
+])
+
+export function normalizeApiPath(path: string, prefix?: string): string {
+  let cleanPath = path.startsWith('/') ? path : '/' + path
+  if (prefix) {
+    let cleanPrefix = prefix.startsWith('/') ? prefix : '/' + prefix
+    if (cleanPrefix.endsWith('/')) {
+      cleanPrefix = cleanPrefix.slice(0, -1)
+    }
+    if (cleanPath === cleanPrefix || cleanPath.startsWith(cleanPrefix + '/')) {
+      // Path already starts with prefix
+    } else {
+      cleanPath = cleanPrefix + cleanPath
+    }
+  }
+  return cleanPath.replace(/\/+/g, '/')
+}
+
+export interface ForeignSpecOptions {
+  prefix?: string
+  source?: string
+}
+
+export function normalizeForeignOpenAPISpec(
+  spec: Record<string, unknown>,
+  options: ForeignSpecOptions = {},
+): Record<string, unknown> {
+  const prefix = options.prefix
+  const source = options.source
+  const cloned: Record<string, unknown> = JSON.parse(JSON.stringify(spec))
+
+  if (cloned.paths && typeof cloned.paths === 'object') {
+    const normalizedPaths: Record<string, unknown> = {}
+    for (const [routePath, pathItem] of Object.entries(
+      cloned.paths as Record<string, unknown>,
+    )) {
+      const canonicalPath = normalizeApiPath(routePath, prefix)
+      normalizedPaths[canonicalPath] = pathItem
+    }
+    cloned.paths = normalizedPaths
+  }
+
+  if (source) {
+    cloned['x-bunderstack-source'] = source
+  }
+
+  return cloned
+}
+
+export function mergeApiRoutersStrict(
+  target: Record<string, unknown>,
+  source?: Record<string, unknown>,
+  prefix: string[] = [],
+): Record<string, unknown> {
+  if (!source) return { ...target }
+  const result: Record<string, unknown> = { ...target }
+
+  for (const [key, val] of Object.entries(source)) {
+    const currentPath = [...prefix, key]
+    const handle = currentPath.join('.')
+    const targetVal = result[key]
+
+    if (targetVal !== undefined) {
+      const isTargetNamespace =
+        typeof targetVal === 'object' &&
+        targetVal !== null &&
+        !('~orpc' in targetVal)
+
+      const isSourceNamespace =
+        typeof val === 'object' &&
+        val !== null &&
+        !('~orpc' in val)
+
+      if (isTargetNamespace && isSourceNamespace) {
+        result[key] = mergeApiRoutersStrict(
+          targetVal as Record<string, unknown>,
+          val as Record<string, unknown>,
+          currentPath,
+        )
+      } else {
+        throw new Error(
+          `[bunderstack] Router merge collision at handle "${handle}": duplicate procedure or namespace collision`,
+        )
+      }
+    } else {
+      result[key] = val
+    }
+  }
+
+  return result
+}
+
+function normalizePathSegments(path: string): string[] {
+  return path.split('/').filter(Boolean)
+}
+
+function isParamSegment(segment: string): boolean {
+  return (
+    (segment.startsWith('{') && segment.endsWith('}')) ||
+    segment.startsWith(':')
+  )
+}
+
+function normalizePathForCollision(path: string): string {
+  const segments = normalizePathSegments(path)
+  const normalized = segments.map((seg) =>
+    isParamSegment(seg) ? '{param}' : seg,
+  )
+  return '/' + normalized.join('/')
+}
+
+function walkNativeRouter(
+  obj: Record<string, unknown>,
+  pathSegments: string[] = [],
+): ApiRegistryEntry[] {
+  const entries: ApiRegistryEntry[] = []
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (!value || typeof value !== 'object') continue
+    const currentSegments = [...pathSegments, key]
+
+    if ('~orpc' in value) {
+      const meta = (getOpenAPIMeta(value as any) || {}) as Record<string, unknown>
+      const handle = currentSegments.join('.')
+      const method = ((meta.method as string) || 'GET').toUpperCase()
+      const routePath = (meta.path as string) || '/' + currentSegments.join('/')
+      const operationId =
+        typeof meta.operationId === 'string' ? meta.operationId : handle
+
+      entries.push({
+        handle,
+        operationId,
+        method,
+        path: routePath,
+        source: 'native',
+      })
+    } else {
+      entries.push(
+        ...walkNativeRouter(
+          value as Record<string, unknown>,
+          currentSegments,
+        ),
+      )
+    }
+  }
+
+  return entries
+}
+
+function extractForeignEntries(
+  specs: Array<Record<string, unknown> | ForeignSpecEntry>,
+): ApiRegistryEntry[] {
+  const entries: ApiRegistryEntry[] = []
+
+  for (const item of specs) {
+    if (!item) continue
+    let specObj: Record<string, unknown>
+    let source = 'foreign'
+
+    if ('spec' in item && typeof item.spec === 'object' && item.spec !== null) {
+      const entry = item as ForeignSpecEntry
+      source = entry.source || 'foreign'
+      specObj = normalizeForeignOpenAPISpec(entry.spec, {
+        prefix: entry.prefix,
+        source,
+      })
+    } else {
+      const rawSpec = item as Record<string, unknown>
+      source = (rawSpec['x-bunderstack-source'] as string) || 'foreign'
+      specObj = normalizeForeignOpenAPISpec(rawSpec, { source })
+    }
+
+    if (!specObj || typeof specObj.paths !== 'object' || !specObj.paths) continue
+    const paths = specObj.paths as Record<string, Record<string, unknown>>
+
+    for (const [routePath, pathItem] of Object.entries(paths)) {
+      if (!pathItem || typeof pathItem !== 'object') continue
+
+      for (const [methodKey, operation] of Object.entries(pathItem)) {
+        const uppercaseMethod = methodKey.toUpperCase()
+        if (!HTTP_METHODS.has(uppercaseMethod)) continue
+        if (!operation || typeof operation !== 'object') continue
+
+        const op = operation as Record<string, unknown>
+        const handle = `foreign:${source}:${uppercaseMethod}:${routePath}`
+        const operationId =
+          typeof op.operationId === 'string'
+            ? op.operationId
+            : handle
+
+        entries.push({
+          handle,
+          operationId,
+          method: uppercaseMethod,
+          path: routePath,
+          source,
+        })
+      }
+    }
+  }
+
+  return entries
+}
+
+export async function buildApiRegistry(
+  options: BuildApiRegistryOptions = {},
+): Promise<ApiRegistry> {
+  const entries: ApiRegistryEntry[] = []
+
+  if (options.nativeRouter) {
+    entries.push(...walkNativeRouter(options.nativeRouter))
+  }
+
+  if (options.foreignSpecs) {
+    entries.push(...extractForeignEntries(options.foreignSpecs))
+  }
+
+  const errors: string[] = []
+
+  for (const entry of entries) {
+    if (entry.source !== 'native') continue
+    if (options.reservedCoreHandles?.has(entry.handle)) continue
+    const reason = collisionForBunderstackPath(entry.path)
+    if (reason) {
+      errors.push(
+        `Reserved route collision on ${entry.method} ${entry.path}: native handle "${entry.handle}" conflicts because ${reason}`,
+      )
+    }
+  }
+
+  // Check duplicate handles
+  const handleMap = new Map<string, ApiRegistryEntry>()
+  for (const entry of entries) {
+    const existing = handleMap.get(entry.handle)
+    if (existing) {
+      errors.push(
+        `Duplicate handle "${entry.handle}": collision between ${existing.source} (${existing.method} ${existing.path}) and ${entry.source} (${entry.method} ${entry.path})`,
+      )
+    } else {
+      handleMap.set(entry.handle, entry)
+    }
+  }
+
+  // Check duplicate operation IDs
+  const opIdMap = new Map<string, ApiRegistryEntry>()
+  for (const entry of entries) {
+    const existing = opIdMap.get(entry.operationId)
+    if (existing) {
+      errors.push(
+        `Duplicate operation ID "${entry.operationId}": collision between ${existing.source} (${existing.handle}) and ${entry.source} (${entry.handle})`,
+      )
+    } else {
+      opIdMap.set(entry.operationId, entry)
+    }
+  }
+
+  // Check method/path collisions (exact and parameter ambiguity)
+  const routePatternMap = new Map<string, ApiRegistryEntry>()
+  for (const entry of entries) {
+    const normalizedPath = normalizePathForCollision(entry.path)
+    const routeKey = `${entry.method} ${normalizedPath}`
+
+    const existing = routePatternMap.get(routeKey)
+    if (existing) {
+      if (existing.path === entry.path) {
+        errors.push(
+          `Exact method/path collision on ${entry.method} ${entry.path}: collision between ${existing.source} (${existing.handle}) and ${entry.source} (${entry.handle})`,
+        )
+      } else {
+        errors.push(
+          `Ambiguous parameter path collision on ${entry.method} (${existing.path} vs ${entry.path}): collision between ${existing.source} (${existing.handle}) and ${entry.source} (${entry.handle})`,
+        )
+      }
+    } else {
+      routePatternMap.set(routeKey, entry)
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(
+      `[bunderstack] Route registry validation failed (${errors.length} error(s)):\n` +
+        errors.join('\n'),
+    )
+  }
+
+  return { entries }
+}

package/src/api/router.ts

@@ -0,0 +1,34 @@
+import '@orpc/openapi/extensions/route'
+import * as v from 'valibot'
+
+import { createApiBuilder } from './builder'
+import { mergeApiRoutersStrict } from './registry'
+
+export interface BuildApiRouterOptions {
+  crud: Record<string, unknown>
+  storage: Record<string, unknown>
+  realtime?: Record<string, unknown>
+  custom?: Record<string, unknown>
+}
+
+export function buildApiRouter(options: BuildApiRouterOptions) {
+  const builder = createApiBuilder<
+    Record<string, unknown>,
+    Record<string, unknown>
+  >()
+  const health = builder.public
+    .route({ method: 'GET', path: '/api/health', tags: ['system'] })
+    .output(v.strictObject({ status: v.literal('ok') }))
+    .handler(() => ({ status: 'ok' as const }))
+
+  return [
+    { health },
+    options.crud,
+    options.storage,
+    options.realtime,
+    options.custom,
+  ].reduce<Record<string, unknown>>(
+    (router, addition) => mergeApiRoutersStrict(router, addition),
+    {},
+  )
+}

package/src/api/storage-router.ts

@@ -0,0 +1,224 @@
+import '@orpc/openapi/extensions/route'
+import * as v from 'valibot'
+
+import type {
+  StorageExecutionContext,
+  StorageOperations,
+} from '../storage/operations'
+import type { BucketStorageRegistry } from '../storage/registry'
+import type { ApiContext } from './context'
+
+import { createApiBuilder } from './builder'
+
+const uploadResultSchema = v.strictObject({
+  fileId: v.string(),
+  url: v.string(),
+})
+
+const prepareUploadSchema = v.variant('mode', [
+  v.strictObject({
+    mode: v.literal('proxy'),
+    uploadUrl: v.string(),
+  }),
+  v.strictObject({
+    mode: v.literal('presign'),
+    fileId: v.string(),
+    uploadUrl: v.string(),
+    method: v.literal('PUT'),
+    confirmUrl: v.string(),
+  }),
+])
+
+const responseHeadersSchema = v.record(
+  v.string(),
+  v.union([v.string(), v.array(v.string()), v.undefined()]),
+)
+
+async function executionContext(
+  context: ApiContext<Record<string, unknown>, Record<string, unknown>>,
+): Promise<StorageExecutionContext> {
+  const session = await context.getSession()
+  return {
+    request: context.request,
+    user: session.user,
+    session: { activeOrganizationId: session.activeOrganizationId },
+  }
+}
+
+function headersRecord(headers: Headers): Record<string, string> {
+  const result: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    result[key] = value
+  })
+  return result
+}
+
+function buildBucketProcedures(
+  name: string,
+  operations: StorageOperations,
+  builder: ReturnType<
+    typeof createApiBuilder<Record<string, unknown>, Record<string, unknown>>
+  >,
+) {
+  const prepareUpload = builder.public
+    .route({
+      method: 'POST',
+      path: `/api/files/${name}/presign`,
+      summary: `Prepare upload to ${name}`,
+      tags: ['files'],
+    })
+    .input(
+      v.strictObject({
+        filename: v.optional(v.string()),
+        contentType: v.optional(v.string()),
+      }),
+    )
+    .output(prepareUploadSchema)
+    .handler(({ input, context }) =>
+      executionContext(context).then((exec) =>
+        operations.prepareUpload(name, input, exec),
+      ),
+    )
+
+  const upload = builder.public
+    .route({
+      method: 'POST',
+      path: `/api/files/${name}`,
+      summary: `Upload to ${name}`,
+      tags: ['files'],
+      inputStructure: 'detailed',
+      outputStructure: 'detailed',
+      requestBodyHint: 'form-data',
+    })
+    .input(
+      v.strictObject({
+        params: v.optional(v.strictObject({}), {}),
+        query: v.optional(v.record(v.string(), v.unknown()), {}),
+        headers: v.optional(v.record(v.string(), v.unknown()), {}),
+        body: v.strictObject({ file: v.file() }),
+      }),
+    )
+    .output(
+      v.strictObject({
+        status: v.literal(201),
+        body: uploadResultSchema,
+      }),
+    )
+    .handler(async ({ input, context }) => {
+      const result = await operations.upload(
+        name,
+        input.body.file,
+        await executionContext(context),
+      )
+      return {
+        status: result.status,
+        body: { fileId: result.fileId, url: result.url },
+      }
+    })
+
+  const confirmUpload = builder.public
+    .route({
+      method: 'POST',
+      path: `/api/files/${name}/{id}/confirm`,
+      summary: `Confirm upload to ${name}`,
+      tags: ['files'],
+    })
+    .input(v.strictObject({ id: v.string() }))
+    .output(uploadResultSchema)
+    .handler(({ input, context }) =>
+      executionContext(context).then((exec) =>
+        operations.confirmUpload(name, input.id, exec),
+      ),
+    )
+
+  const download = builder.public
+    .route({
+      method: 'GET',
+      path: `/api/files/${name}/{+path}`,
+      summary: `Download from ${name}`,
+      tags: ['files'],
+      inputStructure: 'detailed',
+      outputStructure: 'detailed',
+    })
+    .input(
+      v.strictObject({
+        params: v.strictObject({ path: v.string() }),
+        query: v.optional(v.record(v.string(), v.string()), {}),
+        headers: v.optional(v.record(v.string(), v.unknown()), {}),
+        body: v.optional(v.undefined()),
+      }),
+    )
+    .output(
+      v.union([
+        v.strictObject({
+          status: v.literal(200),
+          headers: responseHeadersSchema,
+          body: v.unknown(),
+        }),
+        v.strictObject({
+          status: v.literal(302),
+          headers: responseHeadersSchema,
+          body: v.optional(v.undefined()),
+        }),
+      ]),
+    )
+    .handler(async ({ input, context }) => {
+      const result = await operations.download(
+        name,
+        input.params.path,
+        input.query,
+        await executionContext(context),
+      )
+      if (result.kind === 'redirect') {
+        return {
+          status: 302 as const,
+          headers: { Location: result.url },
+          body: undefined,
+        }
+      }
+      return {
+        status: 200 as const,
+        headers: headersRecord(result.headers),
+        body: result.body,
+      }
+    })
+
+  const deleteFile = builder.public
+    .route({
+      method: 'DELETE',
+      path: `/api/files/${name}/{+path}`,
+      summary: `Delete from ${name}`,
+      tags: ['files'],
+      successStatus: 204,
+    })
+    .input(v.strictObject({ path: v.string() }))
+    .output(v.undefined())
+    .handler(async ({ input, context }) => {
+      await operations.delete(
+        name,
+        input.path,
+        await executionContext(context),
+      )
+      return undefined
+    })
+
+  return { prepareUpload, upload, confirmUpload, download, delete: deleteFile }
+}
+
+export function buildStorageApiRouter(
+  registry: BucketStorageRegistry,
+  operations: StorageOperations,
+) {
+  const builder = createApiBuilder<
+    Record<string, unknown>,
+    Record<string, unknown>
+  >()
+  return {
+    files: Object.fromEntries(
+      [...registry.keys()].map((name) => [
+        name,
+        buildBucketProcedures(name, operations, builder),
+      ]),
+    ),
+  }
+}

package/src/api/types.ts

@@ -0,0 +1,84 @@
+import type { AnyRouter } from '@orpc/server'
+import type { Table } from 'drizzle-orm'
+
+import type { AccessUser } from '../access'
+import type { TableCrudProcedures } from './crud-router'
+
+export interface ProtectedContextAdditions {
+  user: AccessUser
+  session: {
+    activeOrganizationId: string | null
+  }
+}
+
+type AuthTableName = 'user' | 'session' | 'account' | 'verification'
+type InferSelect<T> = T extends { $inferSelect: infer R } ? R : never
+
+type DisabledKeys<TAccess> = {
+  [K in keyof TAccess & string]: TAccess[K] extends { crud: false } ? K : never
+}[keyof TAccess & string]
+
+type ExplicitKeys<TSchema, TAccess> = {
+  [K in keyof TAccess & keyof TSchema & string]: TAccess[K] extends {
+    crud: false
+  }
+    ? never
+    : K extends AuthTableName
+      ? TAccess[K] extends { exposeAuthTable: true }
+        ? K extends 'user'
+          ? K
+          : never
+        : never
+      : K
+}[keyof TAccess & keyof TSchema & string]
+
+type ConventionKeys<TSchema> = {
+  [K in keyof TSchema & string]: K extends AuthTableName
+    ? never
+    : InferSelect<TSchema[K]> extends { userId: unknown }
+      ? K
+      : never
+}[keyof TSchema & string]
+
+export type ExposedApiTables<TSchema, TAccess> = [TAccess] extends [undefined]
+  ? ConventionKeys<TSchema>
+  :
+      | ExplicitKeys<TSchema, TAccess>
+      | Exclude<
+          ConventionKeys<TSchema>,
+          DisabledKeys<TAccess> | (keyof TAccess & string)
+        >
+
+export type CrudApiRouterFor<
+  TSchema extends Record<string, unknown>,
+  TAccess = undefined,
+> = {
+  [K in ExposedApiTables<TSchema, TAccess> as TSchema[K] extends Table
+    ? K
+    : never]: TableCrudProcedures<Extract<TSchema[K], Table>>
+}
+
+type IsProcedure<T> = T extends { '~orpc': unknown } ? true : false
+
+export type MergeApiRouterTypes<A, B> = {
+  [K in keyof A | keyof B]: K extends keyof A
+    ? K extends keyof B
+      ? IsProcedure<A[K]> extends true
+        ? never
+        : IsProcedure<B[K]> extends true
+          ? never
+          : A[K] extends Record<string, unknown>
+            ? B[K] extends Record<string, unknown>
+              ? MergeApiRouterTypes<A[K], B[K]>
+              : never
+            : never
+      : A[K]
+    : K extends keyof B
+      ? B[K]
+      : never
+}
+
+export type UnifiedApiRouter<
+  TCrud extends AnyRouter,
+  TCustom extends AnyRouter | undefined,
+> = TCustom extends AnyRouter ? MergeApiRouterTypes<TCrud, TCustom> : TCrud

package/src/auth.ts

@@ -1,6 +1,7 @@
 // src/auth.ts
 import { betterAuth } from 'better-auth'
 import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { openAPI } from 'better-auth/plugins'
 
 import type { AuthSessionResolver } from './access'
 import type { BetterAuthConfig } from './config'
@@ -13,8 +14,12 @@ export function createAuth(
   dialect: Dialect,
   userSchema?: Record<string, unknown>,
 ) {
+  const hasOpenApi = cfg.plugins?.some((p: any) => p.id === 'open-api')
+  const plugins = hasOpenApi ? cfg.plugins : [...(cfg.plugins || []), openAPI()]
+
   return betterAuth({
     ...cfg,
+    plugins,
     database: drizzleAdapter(db as Parameters<typeof drizzleAdapter>[0], {
       provider: dialect === 'pg' ? 'pg' : 'sqlite',
       ...(userSchema ? { schema: userSchema } : {}),