@lastshotlabs/bunshot 0.0.13 → 0.0.16

package/docs/sections/extending-context/full.md

@@ -0,0 +1,59 @@
+## Extending the Context (Custom Variables)
+
+When building a tenant app or any app that needs extra typed context variables (beyond the built-in), extend `AppEnv["Variables"]` and create a typed router factory.
+
+```ts
+// src/lib/context.ts
+import { createRouter as coreCreateRouter, type AppEnv } from "@lastshotlabs/bunshot";
+import type { OpenAPIHono } from "@hono/zod-openapi";
+
+export type MyVariables = AppEnv["Variables"] & {
+  tenantId: string;
+};
+
+export type MyEnv = { Variables: MyVariables };
+
+export const createRouter = () => coreCreateRouter() as unknown as OpenAPIHono<MyEnv>;
+```
+
+Use the local `createRouter` instead of the one from the package — your routes will then have full TypeScript access to the extra variables:
+
+```ts
+// src/routes/items.ts
+import { createRouter } from "../lib/context";
+import { userAuth } from "@lastshotlabs/bunshot";
+
+export const router = createRouter();
+
+router.use("/items", userAuth);
+
+router.get("/items", async (c) => {
+  const tenantId = c.get("tenantId"); // fully typed
+  const userId   = c.get("userId");   // still available from AppEnv
+  return c.json({ tenantId, userId });
+});
+```
+
+Populate the extra variables from a global middleware:
+
+```ts
+// src/middleware/tenant.ts
+import type { MiddlewareHandler } from "hono";
+import type { MyEnv } from "../lib/context";
+
+export const tenantMiddleware: MiddlewareHandler<MyEnv> = async (c, next) => {
+  const tenantId = c.req.header("x-tenant-id") ?? "default";
+  c.set("tenantId", tenantId);
+  await next();
+};
+```
+
+Then register it in `createServer`:
+
+```ts
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  app: { name: "My App", version: "1.0.0" },
+  middleware: [tenantMiddleware],
+});
+```

package/docs/sections/header.md

@@ -0,0 +1,3 @@
+# Bunshot by Last Shot Labs
+
+A personal Bun + Hono API framework. Install it in any app and get auth, sessions, rate limiting, WebSocket, queues, and OpenAPI docs out of the box — then add your own routes, workers, models, and services.

package/docs/sections/installation/full.md

@@ -0,0 +1,6 @@
+## Installation
+
+```bash
+# from npm
+bun add @lastshotlabs/bunshot
+```

package/docs/sections/jobs/full.md

@@ -0,0 +1,140 @@
+## Jobs (BullMQ)
+
+> **Redis requirement**: BullMQ requires `maxmemory-policy noeviction`. Set it in `redis.conf` or via Docker:
+> ```yaml
+> command: redis-server --maxmemory-policy noeviction
+> ```
+
+Queues and workers share the existing Redis connection automatically.
+
+### Define a queue
+
+```ts
+// src/queues/email.ts
+import { createQueue } from "@lastshotlabs/bunshot";
+
+export type EmailJob = { to: string; subject: string; body: string };
+
+export const emailQueue = createQueue<EmailJob>("email");
+```
+
+### Add jobs
+
+```ts
+import { emailQueue } from "../queues/email";
+
+await emailQueue.add("send-welcome", { to: "user@example.com", subject: "Welcome", body: "..." });
+
+// with options
+await emailQueue.add("send-reset", payload, { delay: 5000, attempts: 3 });
+```
+
+### Define a worker
+
+```ts
+// src/workers/email.ts
+import { createWorker } from "@lastshotlabs/bunshot";
+import type { EmailJob } from "../queues/email";
+
+export const emailWorker = createWorker<EmailJob>("email", async (job) => {
+  const { to, subject, body } = job.data;
+  // send email...
+});
+```
+
+Workers in `workersDir` are auto-discovered and registered after the server starts — no manual imports needed. Subdirectories are supported.
+
+### Broadcasting WebSocket messages from a worker
+
+Use `publish` to broadcast to all connected clients from inside a worker (or anywhere):
+
+```ts
+// src/workers/notify.ts
+import { createWorker, publish } from "@lastshotlabs/bunshot";
+import type { NotifyJob } from "../queues/notify";
+
+export const notifyWorker = createWorker<NotifyJob>("notify", async (job) => {
+  const { text, from } = job.data;
+  publish("broadcast", { text, from, timestamp: new Date().toISOString() });
+});
+```
+
+`publish` is available after `createServer` resolves. Workers are loaded after that point, so it's always safe to use inside a worker.
+
+### Cron / scheduled workers
+
+Use `createCronWorker` for recurring jobs. It creates both a queue and worker, and uses BullMQ's `upsertJobScheduler` for idempotent scheduling across restarts.
+
+```ts
+// src/workers/cleanup.ts
+import { createCronWorker } from "@lastshotlabs/bunshot/queue";
+
+export const { worker, queue } = createCronWorker(
+  "cleanup",
+  async (job) => {
+    // runs every hour
+    await deleteExpiredRecords();
+  },
+  { cron: "0 * * * *" }         // or { every: 3_600_000 } for interval-based
+);
+```
+
+**Ghost job cleanup**: When a cron worker is renamed or removed, the old scheduler persists in Redis. Bunshot handles this automatically — after all workers in `workersDir` are loaded, stale schedulers are pruned. For workers managed outside `workersDir`, call `cleanupStaleSchedulers(activeNames)` manually.
+
+### Job status endpoint
+
+Expose job state via REST for client-side polling (e.g., long-running uploads or exports):
+
+```ts
+import { userAuth, requireRole } from "@lastshotlabs/bunshot";
+
+await createServer({
+  jobs: {
+    statusEndpoint: true,                           // default: false
+    auth: "userAuth",                                // "userAuth" | "none" | MiddlewareHandler[]
+    roles: ["admin"],                                // require these roles (works with userAuth)
+    allowedQueues: ["export", "upload"],              // whitelist — empty = nothing exposed (secure by default)
+    scopeToUser: false,                              // when true with userAuth, users only see their own jobs
+  },
+});
+```
+
+**Auth options:**
+- `"userAuth"` — requires an authenticated user session. Combine with `roles` for RBAC.
+- `"none"` — no auth protection (not recommended for production).
+- `MiddlewareHandler[]` — pass a custom middleware stack for full control, e.g. `[userAuth, requireRole("admin")]`.
+
+#### Endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /jobs` | List available queues |
+| `GET /jobs/:queue` | List jobs in a queue (paginated, filterable by state) |
+| `GET /jobs/:queue/:id` | Job state, progress, result, or failure reason |
+| `GET /jobs/:queue/:id/logs` | Job logs |
+| `GET /jobs/:queue/dead-letters` | Paginated list of DLQ jobs |
+
+The list endpoint (`GET /jobs/:queue`) accepts `?state=waiting|active|completed|failed|delayed|paused` and `?start=0&end=19` for pagination.
+
+### Dead Letter Queue (DLQ)
+
+Automatically move permanently failed jobs to a DLQ for inspection and retry:
+
+```ts
+import { createWorker, createDLQHandler } from "@lastshotlabs/bunshot/queue";
+
+const emailWorker = createWorker("email", async (job) => { ... });
+
+const { dlqQueue, retryJob } = createDLQHandler(emailWorker, "email", {
+  maxSize: 1000,                                    // default: 1000 — oldest trimmed when exceeded
+  onDeadLetter: async (job, error) => {              // optional alerting callback
+    await alertSlack(`Job ${job.id} failed: ${error.message}`);
+  },
+  preserveJobOptions: true,                          // default: true — retry with original delay/priority/attempts
+});
+
+// Retry a specific failed job
+await retryJob("job-id-123");
+```
+
+The DLQ queue is named `${sourceQueueName}-dlq` (e.g., `email-dlq`). It's automatically available via the job status endpoint if listed in `allowedQueues`.

package/docs/sections/jobs/overview.md

@@ -0,0 +1,15 @@
+## Jobs (BullMQ)
+
+Queue-based background jobs powered by BullMQ (requires Redis with `noeviction` policy).
+
+```ts
+// Define a queue
+import { createQueue } from "@lastshotlabs/bunshot";
+export const emailQueue = createQueue<{ to: string; subject: string }>("email");
+
+// Define a worker (auto-discovered from workersDir)
+import { createWorker } from "@lastshotlabs/bunshot";
+export const emailWorker = createWorker("email", async (job) => { /* send email */ });
+```
+
+Features include cron/scheduled workers via `createCronWorker`, dead letter queues via `createDLQHandler`, job status REST endpoints, and WebSocket broadcasting from workers via `publish`.

package/docs/sections/mongodb-connections/full.md

@@ -0,0 +1,45 @@
+## MongoDB Connections
+
+MongoDB and Redis connect automatically inside `createServer` / `createApp`. Control the behavior via the `db` config object:
+
+### Single database (default)
+
+Both auth and app data share one server. Uses `MONGO_*` env vars.
+
+```ts
+await createServer({
+  // ...
+  db: { mongo: "single", redis: true }, // these are the defaults — can omit db entirely
+  // app, auth, security are all optional with sensible defaults
+});
+```
+
+### Separate auth database
+
+Auth users live on a dedicated server (`MONGO_AUTH_*` env vars), app data on its own server (`MONGO_*` env vars). Useful when multiple tenant apps share one auth cluster.
+
+```ts
+await createServer({
+  // ...
+  db: { mongo: "separate" },
+});
+```
+
+### Manual connections
+
+Set `mongo: false` and/or `redis: false` to skip auto-connect and manage connections yourself:
+
+```ts
+import { connectAuthMongo, connectAppMongo, connectRedis, createServer } from "@lastshotlabs/bunshot";
+
+await connectAuthMongo();
+await connectAppMongo();
+await connectRedis();
+
+await createServer({
+  // ...
+  db: { mongo: false, redis: false },
+});
+```
+
+`AuthUser` and all built-in auth routes always use `authConnection`. Your app models use `appConnection` (see Adding Models below).

package/docs/sections/mongodb-connections/overview.md

@@ -0,0 +1,7 @@
+## MongoDB Connections
+
+MongoDB and Redis connect automatically inside `createServer` / `createApp`. Control via the `db` config:
+
+- **`mongo: "single"`** (default) — auth and app data share one server (`MONGO_*` env vars)
+- **`mongo: "separate"`** — auth on its own server (`MONGO_AUTH_*` env vars), app data on another
+- **`mongo: false`** — skip auto-connect, manage connections yourself via `connectAuthMongo()`, `connectAppMongo()`, `connectRedis()`

package/docs/sections/multi-tenancy/full.md

@@ -0,0 +1,62 @@
+## Multi-Tenancy
+
+Add multi-tenancy to your app by configuring tenant resolution. Bunshot resolves the tenant on each request and attaches `tenantId` + `tenantConfig` to the Hono context.
+
+```ts
+await createServer({
+  tenancy: {
+    resolution: "header",               // "header" | "subdomain" | "path"
+    headerName: "x-tenant-id",          // default for "header" strategy
+    onResolve: async (tenantId) => {     // validate + load tenant config — return null to reject
+      const tenant = await getTenant(tenantId);
+      return tenant?.config ?? null;
+    },
+    cacheTtlMs: 60_000,                 // LRU cache TTL for onResolve (default: 60s, 0 to disable)
+    cacheMaxSize: 500,                  // max cached entries (default: 500)
+    exemptPaths: ["/webhooks"],          // additional paths that skip tenant resolution
+    rejectionStatus: 403,               // 403 (default) or 404 when onResolve returns null
+  },
+});
+```
+
+### Resolution strategies
+
+| Strategy | How it extracts tenant ID | Example |
+|---|---|---|
+| `"header"` | From request header (default `x-tenant-id`) | `x-tenant-id: acme` |
+| `"subdomain"` | From first subdomain | `acme.myapp.com` → `"acme"` |
+| `"path"` | From URL path segment (does **not** strip prefix) | `/acme/api/users` → `"acme"` |
+
+### Default exempt paths
+
+These paths skip tenant resolution by default: `/health`, `/docs`, `/openapi.json`, `/auth/` (auth is global — all tenants share a user pool). Add more via `exemptPaths`.
+
+### Accessing tenant in routes
+
+```ts
+router.openapi(myRoute, async (c) => {
+  const tenantId = c.get("tenantId");         // string | null
+  const tenantConfig = c.get("tenantConfig"); // Record<string, unknown> | null
+  // Filter queries by tenantId, apply tenant-specific settings, etc.
+});
+```
+
+### Tenant provisioning helpers
+
+CRUD utilities for managing tenants (stored in the auth database via MongoDB):
+
+```ts
+import { createTenant, getTenant, listTenants, deleteTenant } from "@lastshotlabs/bunshot";
+
+await createTenant("acme", { displayName: "Acme Corp", config: { maxUsers: 100 } });
+const tenant = await getTenant("acme");      // { tenantId, displayName, config, createdAt }
+const all = await listTenants();             // active tenants only
+await deleteTenant("acme");                  // soft-delete + invalidates resolution cache
+```
+
+### Per-tenant namespacing
+
+When tenant context is present, rate limits and cache keys are automatically namespaced per-tenant — no code changes needed. Each tenant gets independent rate limit buckets and cache entries.
+
+- Rate limit keys: `t:${tenantId}:ip:${ip}` (instead of `ip:${ip}`)
+- Cache keys: `cache:${appName}:${tenantId}:${key}` (instead of `cache:${appName}:${key}`)

package/docs/sections/multi-tenancy/overview.md

@@ -0,0 +1,15 @@
+## Multi-Tenancy
+
+Opt-in via `tenancy` config. Resolves tenant ID from header, subdomain, or path segment on each request.
+
+```ts
+await createServer({
+  tenancy: {
+    resolution: "header",
+    headerName: "x-tenant-id",
+    onResolve: async (tenantId) => { /* validate, return config or null */ },
+  },
+});
+```
+
+Auth routes are exempt (global user pool). Rate limits and cache keys are auto-namespaced per-tenant. CRUD helpers: `createTenant`, `getTenant`, `listTenants`, `deleteTenant`.

package/docs/sections/oauth/full.md

@@ -0,0 +1,119 @@
+## Social Login (OAuth)
+
+Pass `auth.oauth.providers` to `createServer` to enable Google and/or Apple sign-in. Routes are mounted automatically for each configured provider.
+
+```ts
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  app: { name: "My App", version: "1.0.0" },
+  auth: {
+    oauth: {
+      postRedirect: "/lobby",  // where to redirect after login (default: "/")
+      providers: {
+        google: {
+          clientId: process.env.GOOGLE_CLIENT_ID!,
+          clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+          redirectUri: "https://myapp.com/auth/google/callback",
+        },
+        apple: {
+          clientId: process.env.APPLE_CLIENT_ID!,       // Services ID, e.g. "com.myapp.auth"
+          teamId: process.env.APPLE_TEAM_ID!,
+          keyId: process.env.APPLE_KEY_ID!,
+          privateKey: process.env.APPLE_PRIVATE_KEY!,   // PEM string
+          redirectUri: "https://myapp.com/auth/apple/callback",
+        },
+      },
+    },
+  },
+});
+```
+
+### Routes mounted automatically
+
+| Provider | Initiate login | Callback | Link to existing account | Unlink |
+|---|---|---|---|---|
+| Google | `GET /auth/google` | `GET /auth/google/callback` | `GET /auth/google/link` | `DELETE /auth/google/link` |
+| Apple | `GET /auth/apple` | `POST /auth/apple/callback` | `GET /auth/apple/link` | — |
+
+> Apple sends its callback as a **POST** with form data. Your server must be publicly reachable and the redirect URI must be registered in the Apple developer console.
+
+### Flow
+
+1. Client navigates to `GET /auth/google` (or `/auth/apple`)
+2. Package redirects to the provider's OAuth page
+3. Provider redirects (or POSTs) back to the callback URL
+4. Package exchanges the code, fetches the user profile, and calls `authAdapter.findOrCreateByProvider`
+5. A session is created, the `auth-token` cookie is set, and the user is redirected to `auth.oauth.postRedirect`
+
+### User storage
+
+The default `mongoAuthAdapter` stores social users in `AuthUser` with a `providerIds` field (e.g. `["google:1234567890"]`). If no existing provider key is found, a new account is created — emails are never auto-linked. To connect a social identity to an existing credential account the user must explicitly use the link flow below.
+
+**Email conflict handling:** If a user attempts to sign in via Google (or Apple) and the email returned by the provider already belongs to a credential-based account, `findOrCreateByProvider` throws `HttpError(409, ...)`. The OAuth callback catches this and redirects to `auth.oauth.postRedirect?error=<message>` so the client can display a helpful prompt (e.g. "An account with this email already exists — sign in with your password, then link Google from your account settings.").
+
+To support social login with a custom adapter, implement `findOrCreateByProvider`:
+
+```ts
+const myAdapter: AuthAdapter = {
+  findByEmail: ...,
+  create: ...,
+  async findOrCreateByProvider(provider, providerId, profile) {
+    // find or upsert user by provider + providerId
+    // return { id: string }
+  },
+};
+```
+
+### Linking a provider to an existing account
+
+A logged-in user can link their account to a Google or Apple identity by navigating to the link route. This is the only way to associate a social login with an existing credential account — email matching is intentionally not done automatically.
+
+```
+GET /auth/google/link   (requires active session via cookie)
+GET /auth/apple/link    (requires active session via cookie)
+```
+
+The link flow:
+1. User is already logged in (session cookie set)
+2. Client navigates to `/auth/google/link`
+3. User completes Google OAuth as normal
+4. On callback, instead of creating a new session, the Google identity is added to their existing account
+5. User is redirected to `auth.oauth.postRedirect?linked=google`
+
+To support linking with a custom adapter, implement `linkProvider`:
+
+```ts
+const myAdapter: AuthAdapter = {
+  // ...
+  async linkProvider(userId, provider, providerId) {
+    const key = `${provider}:${providerId}`;
+    await db.update(users)
+      .set({ providerIds: sql`array_append(provider_ids, ${key})` })
+      .where(eq(users.id, userId));
+  },
+};
+```
+
+### Unlinking a provider
+
+A logged-in user can remove a linked Google identity via:
+
+```
+DELETE /auth/google/link   (requires active session via cookie)
+```
+
+Returns `204 No Content` on success. All `google:*` entries are removed from the user's `providerIds`.
+
+To support unlinking with a custom adapter, implement `unlinkProvider`:
+
+```ts
+const myAdapter: AuthAdapter = {
+  // ...
+  async unlinkProvider(userId, provider) {
+    const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
+    if (!user) throw new HttpError(404, "User not found");
+    const filtered = user.providerIds.filter((id: string) => !id.startsWith(`${provider}:`));
+    await db.update(users).set({ providerIds: filtered }).where(eq(users.id, userId));
+  },
+};
+```

package/docs/sections/oauth/overview.md

@@ -0,0 +1,16 @@
+## Social Login (OAuth)
+
+Pass `auth.oauth.providers` to enable Google and/or Apple sign-in. Routes are mounted automatically for each configured provider.
+
+```ts
+auth: {
+  oauth: {
+    postRedirect: "/dashboard",
+    providers: {
+      google: { clientId: "...", clientSecret: "...", redirectUri: "..." },
+    },
+  },
+}
+```
+
+Auto-mounted routes per provider: initiate (`GET /auth/{provider}`), callback, link to existing account (`GET /auth/{provider}/link`), and unlink (`DELETE /auth/{provider}/link`). Supports custom adapters via `findOrCreateByProvider`, `linkProvider`, and `unlinkProvider`.

package/docs/sections/package-development/full.md

@@ -0,0 +1,7 @@
+## Package Development
+
+To test changes locally, install the package from the local path in a sibling project:
+
+```bash
+bun add @lastshotlabs/bunshot@file:../bunshot
+```

package/docs/sections/peer-dependencies/full.md

@@ -0,0 +1,43 @@
+## Peer Dependencies
+
+Bunshot declares the following as peer dependencies so you control their versions and avoid duplicate installs in your app.
+
+### Required
+
+These must be installed in every consuming app:
+
+```bash
+bun add hono zod
+```
+
+| Package | Required version |
+|---|---|
+| `hono` | `>=4.12 <5` |
+| `zod` | `>=4.0 <5` |
+
+### Optional
+
+Install only what your app actually uses:
+
+```bash
+# MongoDB auth / sessions / cache
+bun add mongoose
+
+# Redis sessions, cache, rate limiting, or BullMQ
+bun add ioredis
+
+# Background job queues
+bun add bullmq
+
+# MFA / TOTP
+bun add otpauth
+```
+
+| Package | Required version | When you need it |
+|---|---|---|
+| `mongoose` | `>=9.0 <10` | `db.auth: "mongo"`, `db.sessions: "mongo"`, or `db.cache: "mongo"` |
+| `ioredis` | `>=5.0 <6` | `db.redis: true` (the default), or any store set to `"redis"` |
+| `bullmq` | `>=5.0 <6` | Workers / queues |
+| `otpauth` | `>=9.0 <10` | `auth.mfa` configuration |
+
+If you're running fully on SQLite or memory (no Redis, no MongoDB), none of the optional peers are needed.

package/docs/sections/quick-start/full.md

@@ -0,0 +1,43 @@
+## Quick Start
+
+```bash
+bun add @lastshotlabs/bunshot hono zod
+```
+
+```ts
+// src/index.ts
+import { createServer } from "@lastshotlabs/bunshot";
+
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  db: { auth: "memory", mongo: false, redis: false, sessions: "memory", cache: "memory" },
+});
+```
+
+```ts
+// src/routes/hello.ts
+import { z } from "zod";
+import { createRoute, createRouter } from "@lastshotlabs/bunshot";
+
+export const router = createRouter();
+
+router.openapi(
+  createRoute({
+    method: "get",
+    path: "/hello",
+    responses: {
+      200: {
+        content: { "application/json": { schema: z.object({ message: z.string() }) } },
+        description: "Hello",
+      },
+    },
+  }),
+  (c) => c.json({ message: "Hello world!" }, 200)
+);
+```
+
+```bash
+bun run src/index.ts
+```
+
+Auth, OpenAPI docs (`/docs`), health check, and WebSocket are all live. No databases required — swap `"memory"` for `"redis"` / `"mongo"` / `"sqlite"` when you're ready.