bunderstack 0.1.0

package/src/email.ts

@@ -0,0 +1,200 @@
+// src/email.ts — email sending: resend / smtp / console / custom adapter.
+
+export type EmailMessage = {
+  to: string | string[]
+  subject: string
+  html?: string
+  text?: string
+  from?: string
+  replyTo?: string
+  cc?: string | string[]
+  bcc?: string | string[]
+}
+
+export type SentEmail = { id?: string }
+
+/** Adapters receive the message with `from` already resolved. */
+export type EmailAdapter = {
+  send(msg: EmailMessage & { from: string }): Promise<SentEmail>
+}
+
+export type EmailConfigInput = {
+  from: string
+  provider?: 'resend' | 'smtp' | 'console' | EmailAdapter | EmailAdapter['send']
+}
+
+export type EmailFacade = {
+  send(msg: EmailMessage): Promise<SentEmail>
+}
+
+export type CreateEmailOptions = {
+  env: { RESEND_API_KEY?: string; SMTP_URL?: string; NODE_ENV?: string }
+  /** Test seam for the resend adapter. */
+  fetchFn?: typeof fetch
+  /** Test seam for the nodemailer presence check. */
+  canResolveModule?: (specifier: string) => boolean
+}
+
+/** String provider tag ('resend' | 'smtp' | 'console') or undefined. */
+export function emailProviderTag(
+  config: EmailConfigInput | undefined,
+): string | undefined {
+  return typeof config?.provider === 'string' ? config.provider : undefined
+}
+
+const toArray = (v: string | string[] | undefined) =>
+  v === undefined ? undefined : Array.isArray(v) ? v : [v]
+
+function createConsoleAdapter(): EmailAdapter {
+  return {
+    async send(msg) {
+      const line = '─'.repeat(60)
+      console.log(
+        [
+          line,
+          '📧 email (console provider — not sent)',
+          `from:    ${msg.from}`,
+          `to:      ${toArray(msg.to)!.join(', ')}`,
+          `subject: ${msg.subject}`,
+          line,
+          msg.text ?? msg.html ?? '',
+          line,
+        ].join('\n'),
+      )
+      return {}
+    },
+  }
+}
+
+function createResendAdapter(
+  apiKey: string,
+  fetchFn: typeof fetch,
+): EmailAdapter {
+  return {
+    async send(msg) {
+      const res = await fetchFn('https://api.resend.com/emails', {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          from: msg.from,
+          to: toArray(msg.to),
+          subject: msg.subject,
+          html: msg.html,
+          text: msg.text,
+          reply_to: msg.replyTo,
+          cc: toArray(msg.cc),
+          bcc: toArray(msg.bcc),
+        }),
+      })
+      if (!res.ok) {
+        throw new Error(`resend API error (${res.status}): ${await res.text()}`)
+      }
+      const data = (await res.json()) as { id?: string }
+      return { id: data.id }
+    },
+  }
+}
+
+function createSmtpAdapter(
+  smtpUrl: string,
+  canResolve: (specifier: string) => boolean,
+): EmailAdapter {
+  if (!canResolve('nodemailer')) {
+    throw new Error(
+      "email provider 'smtp' requires nodemailer — install it with: bun add nodemailer",
+    )
+  }
+  // Lazy import so boot stays sync; cached across sends. Variable specifier
+  // keeps TS from resolving the optional peer's types at compile time.
+  const specifier = 'nodemailer'
+  let transportPromise: Promise<{
+    sendMail(opts: Record<string, unknown>): Promise<{ messageId?: string }>
+  }> | null = null
+  const getTransport = () => {
+    transportPromise ??= import(specifier).then((mod) =>
+      (mod.default ?? mod).createTransport(smtpUrl),
+    )
+    return transportPromise
+  }
+  return {
+    async send(msg) {
+      const transport = await getTransport()
+      const info = await transport.sendMail({
+        from: msg.from,
+        to: toArray(msg.to)!.join(', '),
+        subject: msg.subject,
+        html: msg.html,
+        text: msg.text,
+        replyTo: msg.replyTo,
+        cc: toArray(msg.cc)?.join(', '),
+        bcc: toArray(msg.bcc)?.join(', '),
+      })
+      return { id: info.messageId }
+    },
+  }
+}
+
+function defaultCanResolve(specifier: string): boolean {
+  try {
+    Bun.resolveSync(specifier, import.meta.dir)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function resolveAdapter(
+  config: EmailConfigInput,
+  opts: CreateEmailOptions,
+): EmailAdapter {
+  const provider = config.provider
+  if (typeof provider === 'function') return { send: provider }
+  if (typeof provider === 'object') return provider
+  const fetchFn = opts.fetchFn ?? globalThis.fetch.bind(globalThis)
+  switch (provider) {
+    case 'resend':
+      return createResendAdapter(opts.env.RESEND_API_KEY ?? '', fetchFn)
+    case 'smtp':
+      return createSmtpAdapter(
+        opts.env.SMTP_URL ?? '',
+        opts.canResolveModule ?? defaultCanResolve,
+      )
+    case 'console':
+      return createConsoleAdapter()
+    case undefined:
+      if (opts.env.NODE_ENV === 'production') {
+        throw new Error(
+          'email is configured without a provider — set email.provider ' +
+            "('resend' | 'smtp' | a custom adapter) for production",
+        )
+      }
+      return createConsoleAdapter()
+  }
+}
+
+export function createEmail(
+  config: EmailConfigInput | undefined,
+  opts: CreateEmailOptions,
+): EmailFacade {
+  if (!config) {
+    return {
+      async send() {
+        throw new Error(
+          'email is not configured — add an email key to your bunderstack config',
+        )
+      },
+    }
+  }
+  const adapter = resolveAdapter(config, opts)
+  return {
+    async send(msg) {
+      if (!msg.html && !msg.text) {
+        throw new Error('email message needs html or text content')
+      }
+      return adapter.send({ ...msg, from: msg.from ?? config.from })
+    },
+  }
+}

package/src/env.ts

@@ -0,0 +1,153 @@
+// src/env.ts — env validation. Browser-safe: imports zod only.
+import { z, type ZodType } from 'zod'
+
+export const CLIENT_PREFIX = 'PUBLIC_' as const
+
+export type EnvConfigInput = {
+  server?: Record<string, ZodType>
+  client?: Record<string, ZodType>
+  /** Explicit value source for client vars (e.g. Vite's import.meta.env). */
+  runtimeEnv?: Record<string, unknown>
+}
+
+/** Vars bunderstack itself consumes, always validated. */
+export type BaseEnv = {
+  NODE_ENV?: string
+  DATABASE_URL: string
+  DATABASE_AUTH_TOKEN?: string
+  AUTH_SECRET: string
+  REDIS_URL?: string
+  RESEND_API_KEY?: string
+  SMTP_URL?: string
+}
+
+type InferVars<T> = T extends Record<string, ZodType>
+  ? { [K in keyof T]: z.output<T[K]> }
+  : unknown
+
+// Non-distributive so `ValidatedEnv<undefined>` is BaseEnv, not `never`.
+export type ValidatedEnv<TEnv extends EnvConfigInput | undefined> = [
+  TEnv,
+] extends [EnvConfigInput]
+  ? BaseEnv &
+      InferVars<NonNullable<TEnv>['server']> &
+      InferVars<NonNullable<TEnv>['client']>
+  : BaseEnv
+
+export class BunderstackEnvError extends Error {
+  readonly issues: string[]
+
+  constructor(issues: string[]) {
+    super(`Invalid environment:\n  - ${issues.join('\n  - ')}`)
+    this.name = 'BunderstackEnvError'
+    this.issues = issues
+  }
+}
+
+export type ValidateEnvOptions = {
+  /** String tag of the configured email provider ('resend' | 'smtp'), if any. */
+  emailProvider?: string
+  /** Value source; defaults to process.env. Tests pass this explicitly. */
+  source?: Record<string, string | undefined>
+}
+
+const DEV_AUTH_SECRET = 'dev-secret-change-in-prod'
+
+function validateSection(
+  section: Record<string, ZodType> | undefined,
+  kind: 'server' | 'client',
+  source: Record<string, unknown>,
+  issues: string[],
+  out: Record<string, unknown>,
+) {
+  for (const [key, schema] of Object.entries(section ?? {})) {
+    const isPublic = key.startsWith(CLIENT_PREFIX)
+    if (kind === 'server' && isPublic) {
+      issues.push(
+        `${key}: server vars must not start with ${CLIENT_PREFIX} (move it to env.client)`,
+      )
+      continue
+    }
+    if (kind === 'client' && !isPublic) {
+      issues.push(
+        `${key}: client vars must start with ${CLIENT_PREFIX} (rename it or move it to env.server)`,
+      )
+      continue
+    }
+    const result = schema.safeParse(source[key])
+    if (result.success) {
+      out[key] = result.data
+    } else {
+      for (const issue of result.error.issues) {
+        issues.push(`${key}: ${issue.message}`)
+      }
+    }
+  }
+}
+
+export function validateEnv<TEnv extends EnvConfigInput | undefined>(
+  envConfig: TEnv,
+  options: ValidateEnvOptions = {},
+): ValidatedEnv<TEnv> {
+  const source =
+    options.source ?? (process.env as Record<string, string | undefined>)
+  const issues: string[] = []
+  const isProduction = source.NODE_ENV === 'production'
+
+  const base: BaseEnv = {
+    NODE_ENV: source.NODE_ENV,
+    DATABASE_URL: source.DATABASE_URL ?? 'file:./data.db',
+    DATABASE_AUTH_TOKEN: source.DATABASE_AUTH_TOKEN,
+    AUTH_SECRET: source.AUTH_SECRET ?? DEV_AUTH_SECRET,
+    REDIS_URL: source.REDIS_URL,
+    RESEND_API_KEY: source.RESEND_API_KEY,
+    SMTP_URL: source.SMTP_URL,
+  }
+  if (isProduction && !source.AUTH_SECRET) {
+    issues.push('AUTH_SECRET: required in production')
+  }
+  if (options.emailProvider === 'resend' && !source.RESEND_API_KEY) {
+    issues.push("RESEND_API_KEY: required when email provider is 'resend'")
+  }
+  if (options.emailProvider === 'smtp' && !source.SMTP_URL) {
+    issues.push("SMTP_URL: required when email provider is 'smtp'")
+  }
+
+  const userVars: Record<string, unknown> = {}
+  validateSection(envConfig?.server, 'server', source, issues, userVars)
+  validateSection(envConfig?.client, 'client', source, issues, userVars)
+
+  if (issues.length > 0) throw new BunderstackEnvError(issues)
+  return { ...base, ...userVars } as ValidatedEnv<TEnv>
+}
+
+/**
+ * Browser-side companion (t3-env style): validates ONLY the client section.
+ * Server keys exist on the returned object as traps that throw on access, so
+ * a leaked import fails loudly instead of silently reading undefined.
+ */
+export function createClientEnv<TEnv extends EnvConfigInput>(
+  envConfig: TEnv,
+): InferVars<TEnv['client']> {
+  const source =
+    envConfig.runtimeEnv ??
+    (typeof process !== 'undefined'
+      ? (process.env as Record<string, unknown>)
+      : {})
+  const issues: string[] = []
+  const values: Record<string, unknown> = {}
+  validateSection(envConfig.client, 'client', source, issues, values)
+  if (issues.length > 0) throw new BunderstackEnvError(issues)
+
+  const serverKeys = new Set(Object.keys(envConfig.server ?? {}))
+  return new Proxy(values, {
+    get(target, prop) {
+      if (typeof prop === 'string' && serverKeys.has(prop)) {
+        throw new Error(
+          `${prop} is server-only and not available in client env`,
+        )
+      }
+      return Reflect.get(target, prop)
+    },
+  }) as InferVars<TEnv['client']>
+}

package/src/errors.ts

@@ -0,0 +1,51 @@
+import type { Context } from 'hono'
+import type { ContentfulStatusCode } from 'hono/utils/http-status'
+
+export const ErrorCode = {
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  FORBIDDEN: 'FORBIDDEN',
+  NOT_FOUND: 'NOT_FOUND',
+  INVALID_CURSOR: 'INVALID_CURSOR',
+  RATE_LIMITED: 'RATE_LIMITED',
+  IDEMPOTENCY_REPLAY: 'IDEMPOTENCY_REPLAY',
+  IDEMPOTENCY_CONFLICT: 'IDEMPOTENCY_CONFLICT',
+} as const
+
+export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode]
+
+export type ApiErrorBody = {
+  error: string
+  code?: ErrorCodeValue
+  details?: unknown
+}
+
+export function apiError(
+  c: Context,
+  code: ErrorCodeValue,
+  message: string,
+  status: ContentfulStatusCode,
+  details?: unknown,
+) {
+  const body: ApiErrorBody = {
+    error: message,
+    code,
+    ...(details ? { details } : {}),
+  }
+  return c.json(body, status)
+}
+
+export class ListQueryError extends Error {
+  readonly code: ErrorCodeValue
+  readonly details?: unknown
+
+  constructor(
+    message: string,
+    code: ErrorCodeValue = ErrorCode.VALIDATION_ERROR,
+    details?: unknown,
+  ) {
+    super(message)
+    this.name = 'ListQueryError'
+    this.code = code
+    this.details = details
+  }
+}

package/src/handler.ts

@@ -0,0 +1,53 @@
+// src/handler.ts
+import { Hono } from 'hono'
+
+import { createRateLimiter, type RateLimitConfig } from './rate-limit'
+
+interface HandlerParts {
+  crudRouter: Hono
+  authHandler?: (req: Request) => Promise<Response>
+  storageRouter?: Hono
+  realtimeRouter?: Hono
+  trpcHandler?: (req: Request) => Promise<Response>
+  rateLimit?: boolean | RateLimitConfig
+}
+
+export function buildHandler(parts: HandlerParts): {
+  handler: (req: Request) => Promise<Response>
+  router: Hono
+} {
+  const app = new Hono()
+  const checkRateLimit = createRateLimiter(parts.rateLimit)
+
+  const health = (c: { json: (data: unknown) => Response }) =>
+    c.json({ status: 'ok' })
+  app.get('/health', health)
+  app.get('/api/health', health)
+  app.route('/api', parts.crudRouter)
+
+  if (parts.authHandler) {
+    app.all('/api/auth/*', (c) => parts.authHandler!(c.req.raw))
+  }
+
+  if (parts.storageRouter) {
+    app.route('/api/files', parts.storageRouter)
+    app.route('/files', parts.storageRouter)
+  }
+
+  if (parts.realtimeRouter) {
+    app.route('/api', parts.realtimeRouter)
+  }
+
+  if (parts.trpcHandler) {
+    app.all('/api/trpc/*', (c) => parts.trpcHandler!(c.req.raw))
+  }
+
+  const inner = (req: Request): Promise<Response> =>
+    Promise.resolve(app.fetch(req))
+  const handler = async (req: Request): Promise<Response> => {
+    const limited = await checkRateLimit(req)
+    if (limited) return limited
+    return inner(req)
+  }
+  return { handler, router: app }
+}

package/src/idempotency.ts

@@ -0,0 +1,102 @@
+import type { LibSQLDatabase } from 'drizzle-orm/libsql'
+
+import { and, eq, lt } from 'drizzle-orm'
+import { createHash } from 'node:crypto'
+
+import { bunderstackIdempotency } from './internal-tables'
+
+export type IdempotencyConfig = {
+  ttlMs?: number
+}
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
+
+function hashBody(body: string): string {
+  return createHash('sha256').update(body).digest('hex')
+}
+
+export type IdempotencyLookup =
+  | { type: 'replay'; status: number; response: string }
+  | { type: 'conflict' }
+  | { type: 'proceed' }
+
+export async function lookupIdempotency(
+  db: LibSQLDatabase<Record<string, unknown>>,
+  tableName: string,
+  key: string,
+  body: string,
+  config: IdempotencyConfig,
+): Promise<IdempotencyLookup> {
+  const now = Date.now()
+
+  // TTL sweep: drop expired rows before reading.
+  await db
+    .delete(bunderstackIdempotency)
+    .where(lt(bunderstackIdempotency.expiresAt, now))
+
+  const bodyHash = hashBody(body)
+  const rows = await db
+    .select({
+      bodyHash: bunderstackIdempotency.bodyHash,
+      status: bunderstackIdempotency.status,
+      response: bunderstackIdempotency.response,
+      expiresAt: bunderstackIdempotency.expiresAt,
+    })
+    .from(bunderstackIdempotency)
+    .where(
+      and(
+        eq(bunderstackIdempotency.key, key),
+        eq(bunderstackIdempotency.tableName, tableName),
+      ),
+    )
+    .limit(1)
+
+  const row = rows[0]
+
+  if (!row) return { type: 'proceed' }
+  if (Number(row.expiresAt) < now) return { type: 'proceed' }
+  if (row.bodyHash !== bodyHash) return { type: 'conflict' }
+  return {
+    type: 'replay',
+    status: Number(row.status),
+    response: String(row.response),
+  }
+}
+
+export async function storeIdempotency(
+  db: LibSQLDatabase<Record<string, unknown>>,
+  tableName: string,
+  key: string,
+  body: string,
+  status: number,
+  response: unknown,
+  config: IdempotencyConfig,
+): Promise<void> {
+  const ttlMs = config.ttlMs ?? DEFAULT_TTL_MS
+  const expiresAt = Date.now() + ttlMs
+  const bodyHash = hashBody(body)
+  const responseText = JSON.stringify(response)
+
+  await db
+    .insert(bunderstackIdempotency)
+    .values({
+      key,
+      tableName,
+      bodyHash,
+      status,
+      response: responseText,
+      expiresAt,
+    })
+    .onConflictDoUpdate({
+      target: [bunderstackIdempotency.key, bunderstackIdempotency.tableName],
+      set: { bodyHash, status, response: responseText, expiresAt },
+    })
+}
+
+export function resolveIdempotencyConfig(
+  config: boolean | IdempotencyConfig | undefined,
+): IdempotencyConfig | null {
+  if (!config) return null
+  if (config === true) return {}
+  return config
+}