@lastshotlabs/bunshot 0.0.27 → 0.1.0

package/docs/sections/configuration/full.md

@@ -1,172 +0,0 @@
-## Configuration
-
-```ts
-await createServer({
-  // Required
-  routesDir: import.meta.dir + "/routes",
-
-  // Shared schemas (imported before routes; see "Shared schemas across routes" above)
-  modelSchemas: import.meta.dir + "/schemas",   // string shorthand — registration: "auto"
-  // modelSchemas: [dir + "/schemas", dir + "/models"],              // multiple dirs
-  // modelSchemas: { paths: dir + "/schemas", registration: "explicit" }, // full object
-
-  // App metadata (shown in root endpoint + OpenAPI docs)
-  app: {
-    name: "My App",      // default: "Bun Core API"
-    version: "1.0.0",   // default: "1.0.0"
-  },
-
-  // Auth, roles, and OAuth
-  auth: {
-    enabled: true,                          // default: true — set false to disable /auth/* routes
-    adapter: pgAuthAdapter,                 // custom adapter — overrides db.auth (use for Postgres etc.)
-    roles: ["admin", "editor", "user"],     // valid roles — required to use requireRole
-    defaultRole: "user",                    // assigned to every new user on /auth/register
-    primaryField: "email",                  // default: "email" — use "username" or "phone" to change the login identifier
-    emailVerification: {                    // optional — only active when primaryField is "email"
-      required: true,                       // default: false (soft gate) — set true to block login until verified
-      tokenExpiry: 60 * 60,                 // default: 86400 (24 hours) — token TTL in seconds
-      onSend: async (email, token) => {     // called after registration and resend — use any email provider
-        await resend.emails.send({ to: email, subject: "Verify your email", text: `Token: ${token}` });
-      },
-    },
-    passwordReset: {                        // optional — only active when primaryField is "email"
-      tokenExpiry: 60 * 60,                 // default: 3600 (1 hour) — token TTL in seconds
-      onSend: async (email, token) => {     // called by POST /auth/forgot-password — use any email provider
-        await resend.emails.send({ to: email, subject: "Reset your password", text: `Token: ${token}` });
-      },
-    },
-    rateLimit: {                            // optional — built-in auth endpoint rate limiting
-      login:              { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 failures / 15 min
-      register:           { windowMs: 60 * 60 * 1000, max: 5  }, // default: 5 attempts / hour (per IP)
-      verifyEmail:        { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 attempts / 15 min (per IP)
-      resendVerification: { windowMs: 60 * 60 * 1000, max: 3  }, // default: 3 attempts / hour (per user)
-      forgotPassword:     { windowMs: 15 * 60 * 1000, max: 5  }, // default: 5 attempts / 15 min (per IP)
-      resetPassword:      { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 attempts / 15 min (per IP)
-      mfaVerify:          { windowMs: 15 * 60 * 1000, max: 10 }, // default: 10 attempts / 15 min (per IP)
-      mfaResend:          { windowMs: 60 * 1000,      max: 5  }, // default: 5 attempts / minute (per IP)
-      store: "redis",                       // default: "redis" when Redis is enabled, else "memory"
-    },
-    sessionPolicy: {                        // optional — session concurrency and metadata
-      maxSessions: 6,                       // default: 6 — max simultaneous sessions per user; oldest evicted when exceeded
-      persistSessionMetadata: true,         // default: true — keep IP/UA/timestamp row after session expires (for device detection)
-      includeInactiveSessions: false,       // default: false — include expired/deleted sessions in GET /auth/sessions
-      trackLastActive: false,               // default: false — update lastActiveAt on every auth'd request (adds one DB write)
-    },
-    passwordPolicy: {                        // optional — password complexity rules (applies to register + reset, not login)
-      minLength: 8,                         // default: 8
-      requireLetter: true,                  // default: true — at least one a–z or A–Z
-      requireDigit: true,                   // default: true — at least one 0–9
-      requireSpecial: false,                // default: false — at least one non-alphanumeric character
-    },
-    oauth: {
-      providers: { google: { ... }, apple: { ... } }, // omit a provider to disable it
-      postRedirect: "/dashboard",           // default: "/"
-      allowedRedirectUrls: ["https://myapp.com"], // optional — validate postRedirect against allowlist at startup
-    },
-    refreshTokens: {                        // optional — short-lived access + long-lived refresh tokens
-      accessTokenExpiry: 900,               // default: 900 (15 min)
-      refreshTokenExpiry: 2_592_000,        // default: 2_592_000 (30 days)
-      rotationGraceSeconds: 30,             // default: 30 — old token still works briefly after rotation
-    },
-    mfa: {                                  // optional — TOTP/MFA support (requires otpauth peer dep)
-      issuer: "My App",                     // shown in authenticator apps (default: app name)
-      recoveryCodes: 10,                    // default: 10
-      challengeTtlSeconds: 300,             // default: 300 (5 min)
-      emailOtp: {                           // optional — email OTP as alternative MFA method
-        onSend: async (email, code) => {},  // called to deliver the OTP code — use any email provider
-        codeLength: 6,                      // default: 6
-      },
-    },
-    accountDeletion: {                      // optional — enables DELETE /auth/me
-      onBeforeDelete: async (userId) => {}, // throw to abort
-      onAfterDelete: async (userId) => {},  // cleanup callback
-    },
-  },
-
-  // Multi-tenancy
-  tenancy: {
-    resolution: "header",                   // "header" | "subdomain" | "path"
-    headerName: "x-tenant-id",             // header name (when resolution is "header")
-    onResolve: async (tenantId) => ({}),    // validate/load tenant — return null to reject
-    cacheTtlMs: 60_000,                    // LRU cache TTL (default: 60s, 0 to disable)
-    cacheMaxSize: 500,                     // max cached entries (default: 500)
-    exemptPaths: [],                       // extra paths that skip tenant resolution
-    rejectionStatus: 403,                  // 403 (default) or 404
-  },
-
-  // Job status endpoint
-  jobs: {
-    statusEndpoint: true,                  // default: false
-    auth: "userAuth",                      // "userAuth" | "none" | MiddlewareHandler[]
-    roles: ["admin"],                      // require roles (works with userAuth)
-    allowedQueues: ["export"],             // whitelist — empty = nothing exposed
-    scopeToUser: false,                    // when true with userAuth, users see only their own jobs
-  },
-
-  // Security
-  security: {
-    cors: ["https://myapp.com"],            // default: "*"
-    rateLimit: { windowMs: 60_000, max: 100 }, // default: 100 req/min
-    bearerAuth: true,                       // default: true — set false to disable, or { bypass: ["/my-public-route"] }
-    botProtection: {
-      fingerprintRateLimit: true,           // rate-limit by HTTP fingerprint (IP-rotation resistant). default: false
-      blockList: ["198.51.100.0/24"],       // IPv4 CIDRs or exact IPs to block with 403. default: []
-    },
-    headers: {                              // optional — additional security headers via Hono secureHeaders
-      contentSecurityPolicy: "default-src 'self'",  // CSP header value
-      permissionsPolicy: "camera=(), microphone=()", // Permissions-Policy header value
-    },
-    trustProxy: 1,                          // default: false — see "Trusted Proxy" section below
-    csrf: {                                 // opt-in CSRF protection for cookie-based auth
-      enabled: true,                        // default: false
-      exemptPaths: ["/webhooks/*"],         // additional exempt paths (OAuth callbacks auto-exempt)
-      checkOrigin: true,                    // validate Origin header against CORS origins (default: true)
-    },
-  },
-
-  // Validation error formatting
-  validation: {
-    // Custom formatter for Zod validation errors. Receives issues + requestId, returns JSON body.
-    // Default produces: { error: "msg1, msg2", details: [{ path, message }], requestId }
-    formatError: (issues, requestId) => ({
-      errors: issues.map((i) => ({ field: i.path.join("."), message: i.message })),
-      requestId,
-    }),
-  },
-
-  // API versioning — isolates routes into per-version OpenAPI specs
-  versioning: {
-    versions: ["v1", "v2"],    // subdirectories under routesDir (routes/v1/, routes/v2/)
-    defaultVersion: "v2",      // /docs and /openapi.json redirect here (default: last in array)
-    sharedDir: "shared",       // routes/shared/ — mounted on all versions, unprefixed schemas (default: "shared", false to disable)
-  },
-
-  // Extra middleware injected after identify, before route matching
-  middleware: [],
-
-  // Connections & store routing (all optional — shown with defaults)
-  db: {
-    mongo: "single",        // "single" | "separate" | false
-    redis: true,            // false to skip auto-connect
-    sqlite: undefined,      // absolute path to .db file — required when any store is "sqlite"
-    auth: "mongo",          // "mongo" | "sqlite" | "memory" — which built-in auth adapter to use
-    sessions: "redis",      // "redis" | "mongo" | "sqlite" | "memory"
-    oauthState: "redis",    // default: follows sessions
-    cache: "redis",         // global default for cacheResponse (overridable per-route)
-  },
-
-  // Server
-  port: 3000,                                    // default: process.env.PORT ?? 3000
-  workersDir: import.meta.dir + "/workers",      // auto-imports all .ts files after server starts
-  enableWorkers: true,                           // default: true — set false to disable auto-loading
-
-  // WebSocket (see WebSocket section for full examples)
-  ws: {
-    handler: { ... },                                  // override open/message/close/drain handlers
-    upgradeHandler: async (req, server) => { ... },    // replace default cookie-JWT upgrade logic
-    onRoomSubscribe(ws, room) { return true; },        // gate room subscriptions; can be async
-    maxMessageSize: 65_536,                            // default: 65536 (64 KB) — close connection on oversized messages
-  },
-});
-```

package/docs/sections/configuration/overview.md

@@ -1,18 +0,0 @@
-## Configuration
-
-`createServer` / `createApp` accept a config object with these top-level keys:
-
-| Key | Purpose |
-|-----|---------|
-| `routesDir` | **(required)** Path to auto-discovered route files |
-| `app` | App name and version (shown in docs) |
-| `auth` | Roles, OAuth, email verification, MFA, refresh tokens, rate limiting, account deletion |
-| `db` | Connection and store routing — mongo, redis, sqlite, sessions, cache, auth adapter |
-| `security` | CORS, bearer auth, rate limiting, bot protection, CSRF |
-| `tenancy` | Multi-tenant resolution (header/subdomain/path) |
-| `jobs` | Job status REST endpoint config |
-| `ws` | WebSocket handler and upgrade overrides |
-| `middleware` | Extra global middleware array |
-| `validation` | Zod validation error formatting (`formatError` callback) |
-| `modelSchemas` | Schema auto-discovery paths |
-| `port`, `workersDir`, `enableWorkers` | Server options |

package/docs/sections/configuration-example/full.md

@@ -1,117 +0,0 @@
-## Full Configuration Example
-
-For production apps, break config into its own file. Here's a real-world setup with MongoDB, Redis, OAuth, and email verification:
-
-```ts
-// src/config/index.ts
-import path from "path";
-import {
-  type CreateServerConfig,
-  type AppMeta,
-  type AuthConfig,
-  type DbConfig,
-  type SecurityConfig,
-  type ModelSchemasConfig,
-} from "@lastshotlabs/bunshot";
-
-const app: AppMeta = {
-  name: "My App",
-  version: "1.0.0",
-};
-
-const db: DbConfig = {
-  mongo: "single",       // "single" | "separate" | false
-  redis: true,           // false to skip Redis
-  sessions: "redis",     // "redis" | "mongo" | "sqlite" | "memory"
-  cache: "memory",       // default store for cacheResponse
-  auth: "mongo",         // "mongo" | "sqlite" | "memory"
-  oauthState: "memory",  // where to store OAuth state tokens
-};
-
-const auth: AuthConfig = {
-  roles: ["admin", "user"],
-  defaultRole: "user",
-  primaryField: "email",
-  rateLimit: { store: "redis" },
-  emailVerification: {
-    required: true,
-    tokenExpiry: 60 * 60, // 1 hour
-    onSend: async (email, token) => {
-      // send verification email using any provider (Resend, SES, etc.)
-    },
-  },
-  oauth: {
-    postRedirect: "http://localhost:5175/oauth/callback",
-    providers: {
-      google: {
-        clientId: process.env.GOOGLE_CLIENT_ID!,
-        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/google/callback`,
-      },
-      apple: {
-        clientId: process.env.APPLE_CLIENT_ID!,
-        teamId: process.env.APPLE_TEAM_ID!,
-        keyId: process.env.APPLE_KEY_ID!,
-        privateKey: process.env.APPLE_PRIVATE_KEY!,
-        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/apple/callback`,
-      },
-      microsoft: {
-        tenantId: process.env.MICROSOFT_TENANT_ID!,
-        clientId: process.env.MICROSOFT_CLIENT_ID!,
-        clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
-        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/microsoft/callback`,
-      },
-      github: {
-        clientId: process.env.GITHUB_CLIENT_ID!,
-        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-        redirectUri: `http://localhost:${process.env.PORT ?? 3000}/auth/github/callback`,
-      },
-    },
-  },
-};
-
-const security: SecurityConfig = {
-  bearerAuth: true,
-  cors: ["*", "http://localhost:5173"],
-  botProtection: { fingerprintRateLimit: true },
-};
-
-const modelSchemas: ModelSchemasConfig = {
-  registration: "auto",
-  paths: [path.join(import.meta.dir, "../schemas/*.ts")],
-};
-
-export const appConfig: CreateServerConfig = {
-  app,
-  routesDir: path.join(import.meta.dir, "../routes"),
-  workersDir: path.join(import.meta.dir, "../workers"),
-  port: process.env.PORT ? parseInt(process.env.PORT) : 3000,
-  db,
-  auth,
-  security,
-  modelSchemas,
-  middleware: [/* your global middleware here */],
-};
-```
-
-Every field above is optional except `routesDir`. See the [Configuration](#configuration) section for the full reference.
-
-### Built-in endpoints
-
-| Endpoint | Description |
-|---|---|
-| `POST /auth/register` | Create account, returns JWT |
-| `POST /auth/login` | Login, returns JWT (includes `emailVerified` when verification is configured) |
-| `POST /auth/logout` | Invalidates the current session only |
-| `GET /auth/me` | Returns current user's `userId`, `email`, `emailVerified`, and `googleLinked` (requires login) |
-| `POST /auth/set-password` | Set or update password (requires login) |
-| `GET /auth/sessions` | List active sessions with metadata — IP, user-agent, timestamps (requires login) |
-| `DELETE /auth/sessions/:sessionId` | Revoke a specific session by ID (requires login) |
-| `POST /auth/verify-email` | Verify email with token (when `emailVerification` is configured) |
-| `POST /auth/resend-verification` | Resend verification email (requires credentials, when `emailVerification` is configured) |
-| `POST /auth/forgot-password` | Request a password reset email (when `passwordReset` is configured) |
-| `POST /auth/reset-password` | Reset password using a token from the reset email (when `passwordReset` is configured) |
-| `GET /health` | Health check |
-| `GET /docs` | Scalar API docs UI |
-| `GET /openapi.json` | OpenAPI spec |
-| `WS /ws` | WebSocket endpoint (cookie-JWT auth) |

package/docs/sections/configuration-example/overview.md

@@ -1,30 +0,0 @@
-## Full Configuration Example
-
-For production apps, break config into its own file with MongoDB, Redis, OAuth, and email verification. See the [Configuration](#configuration) section for the full reference.
-
-```ts
-// src/config/index.ts
-import { type CreateServerConfig } from "@lastshotlabs/bunshot";
-
-export const appConfig: CreateServerConfig = {
-  app: { name: "My App", version: "1.0.0" },
-  routesDir: import.meta.dir + "/routes",
-  workersDir: import.meta.dir + "/workers",
-  db: { mongo: "single", redis: true, sessions: "redis", cache: "memory", auth: "mongo" },
-  auth: { roles: ["admin", "user"], defaultRole: "user", primaryField: "email" },
-  security: { bearerAuth: true, cors: ["*"] },
-};
-```
-
-### Built-in endpoints
-
-| Endpoint | Description |
-|---|---|
-| `POST /auth/register` | Create account, returns JWT |
-| `POST /auth/login` | Login, returns JWT |
-| `POST /auth/logout` | Invalidates the current session |
-| `GET /auth/me` | Current user profile |
-| `GET /health` | Health check |
-| `GET /docs` | Scalar API docs UI |
-| `GET /openapi.json` | OpenAPI spec |
-| `WS /ws` | WebSocket endpoint |

package/docs/sections/documentation/full.md

@@ -1,171 +0,0 @@
-## Documentation Generation
-
-Bunshot ships its documentation as modular markdown sections that you can pull into your own project's README.
-
-### Setup
-
-Create a `docs/` directory in your project with a config and build script:
-
-```
-my-app/
-  docs/
-    readme.config.json
-    build-readme.ts
-    sections/
-      intro/
-        full.md
-      my-api/
-        full.md
-        overview.md
-```
-
-### Config — `docs/readme.config.json`
-
-```json
-{
-  "output": "../README.md",
-  "separator": "---",
-  "sections": [
-    { "topic": "intro", "default": "full", "separator": false },
-    { "topic": "my-api", "default": "full" },
-    { "topic": "bunshot-auth", "file": "@lastshotlabs/bunshot/docs/auth-flow/overview.md" },
-    { "topic": "bunshot-config", "file": "@lastshotlabs/bunshot/docs/configuration/full.md" }
-  ],
-  "profiles": {
-    "short": {
-      "my-api": "overview"
-    }
-  }
-}
-```
-
-**Section entries:**
-
-| Field | Description |
-|-------|-------------|
-| `topic` | Section identifier. Maps to `sections/{topic}/` directory when no `file` is specified. |
-| `default` | Variant to use: `"full"` or `"overview"`. Falls back to `"full"` if the requested variant doesn't exist. |
-| `file` | Explicit file path. Supports relative paths (`sections/header.md`) and package paths (`@lastshotlabs/bunshot/docs/auth-flow/overview.md`). |
-| `separator` | `true`/`false` — whether to insert `---` before this section. Defaults to `true` (except the first section). |
-
-**Profiles** override specific sections' variants. Only list sections you want to change:
-
-```json
-"profiles": {
-  "short": { "my-api": "overview", "bunshot-auth": "overview" }
-}
-```
-
-### Build script — `docs/build-readme.ts`
-
-Copy this into your project:
-
-```ts
-const configPath = import.meta.dir + "/readme.config.json";
-const config = await Bun.file(configPath).json();
-const profile = Bun.argv[2];
-const overrides: Record<string, string> = profile
-  ? config.profiles?.[profile] ?? {}
-  : {};
-const separator: string = config.separator ?? "---";
-
-if (profile && !config.profiles?.[profile]) {
-  console.error(`Unknown profile: "${profile}". Available: ${Object.keys(config.profiles ?? {}).join(", ")}`);
-  process.exit(1);
-}
-
-function resolveFilePath(file: string): string {
-  if (file.startsWith("./") || file.startsWith("/") || file.startsWith("../")) {
-    return import.meta.dir + "/" + file;
-  }
-  if (file.includes("/") && !file.startsWith("sections")) {
-    const resolved = import.meta.resolve(file);
-    return resolved.replace(/^file:\/\/\//, "");
-  }
-  return import.meta.dir + "/" + file;
-}
-
-const parts: string[] = [
-  "<!-- AUTO-GENERATED — edit docs/sections/, not this file. Run: bun run readme -->",
-];
-
-for (let i = 0; i < config.sections.length; i++) {
-  const section = config.sections[i];
-
-  let filePath: string;
-  if (section.file) {
-    filePath = resolveFilePath(section.file);
-  } else {
-    const variant = overrides[section.topic] ?? section.default ?? "full";
-    const candidate = `${import.meta.dir}/sections/${section.topic}/${variant}.md`;
-    filePath = (await Bun.file(candidate).exists())
-      ? candidate
-      : `${import.meta.dir}/sections/${section.topic}/full.md`;
-  }
-
-  const content = (await Bun.file(filePath).text()).replace(/\r\n/g, "\n");
-
-  const useSeparator = section.separator !== undefined ? section.separator : i > 0;
-  if (useSeparator) parts.push(separator);
-
-  parts.push(content.trimEnd());
-}
-
-const outputPath = import.meta.dir + "/" + (config.output ?? "../README.md");
-await Bun.write(outputPath, parts.join("\n\n") + "\n");
-console.log(
-  `README.md compiled (${config.sections.length} sections${profile ? `, profile: ${profile}` : ""})`
-);
-```
-
-### Add to package.json
-
-```json
-"scripts": {
-  "readme": "bun docs/build-readme.ts",
-  "readme:short": "bun docs/build-readme.ts short"
-}
-```
-
-### Available bunshot sections
-
-Pull any of these into your project's README via `"file": "@lastshotlabs/bunshot/docs/{section}/{variant}.md"`:
-
-| Section | Variants |
-|---------|----------|
-| `quick-start` | `full` |
-| `stack` | `full` |
-| `cli` | `full` |
-| `installation` | `full` |
-| `configuration-example` | `full`, `overview` |
-| `adding-routes` | `full`, `overview` |
-| `mongodb-connections` | `full`, `overview` |
-| `adding-models` | `full`, `overview` |
-| `jobs` | `full`, `overview` |
-| `websocket` | `full`, `overview` |
-| `websocket-rooms` | `full`, `overview` |
-| `adding-middleware` | `full` |
-| `response-caching` | `full`, `overview` |
-| `extending-context` | `full` |
-| `configuration` | `full`, `overview` |
-| `running-without-redis` | `full` |
-| `running-without-redis-or-mongodb` | `full` |
-| `auth-flow` | `full`, `overview` |
-| `roles` | `full`, `overview` |
-| `multi-tenancy` | `full`, `overview` |
-| `oauth` | `full`, `overview` |
-| `peer-dependencies` | `full` |
-| `environment-variables` | `full` |
-| `exports` | `full` |
-
-### Writing your own sections
-
-Each section file is self-contained markdown starting with a `## Heading`. Create `docs/sections/{topic}/full.md` and optionally `overview.md`:
-
-```markdown
-## My Feature
-
-Description and code examples here...
-```
-
-The `---` separators between sections are inserted by the build script — don't include them in section files.

package/docs/sections/environment-variables/full.md

@@ -1,55 +0,0 @@
-## Environment Variables
-
-```env
-NODE_ENV=development
-PORT=...
-
-# MongoDB (single connection — used by connectMongo())
-MONGO_USER_DEV=...
-MONGO_PW_DEV=...
-MONGO_HOST_DEV=...
-MONGO_DB_DEV=...
-MONGO_USER_PROD=...
-MONGO_PW_PROD=...
-MONGO_HOST_PROD=...
-MONGO_DB_PROD=...
-
-# MongoDB auth connection (separate server — used by connectAuthMongo())
-# Only needed when running auth on a different cluster from app data
-MONGO_AUTH_USER_DEV=...
-MONGO_AUTH_PW_DEV=...
-MONGO_AUTH_HOST_DEV=...
-MONGO_AUTH_DB_DEV=...
-MONGO_AUTH_USER_PROD=...
-MONGO_AUTH_PW_PROD=...
-MONGO_AUTH_HOST_PROD=...
-MONGO_AUTH_DB_PROD=...
-
-# Redis
-REDIS_HOST_DEV=host:port
-REDIS_USER_DEV=...
-REDIS_PW_DEV=...
-REDIS_HOST_PROD=host:port
-REDIS_USER_PROD=...
-REDIS_PW_PROD=...
-
-# JWT
-JWT_SECRET_DEV=...
-JWT_SECRET_PROD=...
-
-# Bearer API key (required on every non-bypassed request)
-BEARER_TOKEN_DEV=...
-BEARER_TOKEN_PROD=...
-
-# Logging (optional — defaults to on in dev)
-LOGGING_VERBOSE=true
-
-# OAuth (only needed if using oauthProviders)
-GOOGLE_CLIENT_ID=...
-GOOGLE_CLIENT_SECRET=...
-
-APPLE_CLIENT_ID=...
-APPLE_TEAM_ID=...
-APPLE_KEY_ID=...
-APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."
-```