@lastshotlabs/bunshot 0.0.21 → 0.0.25

package/docs/sections/uploads/full.md

@@ -0,0 +1,199 @@
+## File Uploads
+
+Bunshot provides opt-in file upload handling with pluggable storage adapters (memory, local filesystem, S3/R2), server-side multipart parsing, and optional presigned URL generation for direct client-to-storage uploads.
+
+### Configuration
+
+Enable uploads by passing `upload` to `createApp` or `createServer`:
+
+```typescript
+import { createServer, memoryStorage } from "@lastshotlabs/bunshot";
+
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  upload: {
+    storage: memoryStorage(),       // swap for localStorage() or s3Storage()
+    maxFileSize: 5 * 1024 * 1024,  // 5 MB per file
+    maxFiles: 3,
+    allowedMimeTypes: ["image/*", "application/pdf"],
+    keyPrefix: "uploads/",
+    tenantScopedKeys: false,
+    presignedUrls: true,            // mounts POST /uploads/presign and DELETE /uploads/:key
+  },
+});
+```
+
+**`UploadConfig` fields:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `storage` | `StorageAdapter` | required | Storage backend instance |
+| `maxFileSize` | `number` | `10485760` (10 MB) | Max bytes per file |
+| `maxFiles` | `number` | `10` | Max files per request |
+| `allowedMimeTypes` | `string[]` | all allowed | Permitted MIME types (supports wildcards like `image/*`) |
+| `keyPrefix` | `string` | `"uploads/"` | Path prefix prepended to generated keys |
+| `generateKey` | `(file, ctx) => string` | UUID-based | Custom key generation function |
+| `tenantScopedKeys` | `boolean` | `false` | Prepend `tenantId/` to generated keys |
+| `presignedUrls` | `boolean \| PresignedUrlConfig` | `false` | Mount presigned URL routes |
+
+### Storage Adapters
+
+#### Memory (testing)
+
+```typescript
+import { memoryStorage, clearMemoryUploadStore } from "@lastshotlabs/bunshot";
+
+const storage = memoryStorage();
+// clearMemoryUploadStore() is called automatically by clearMemoryStore() in tests
+```
+
+Does not implement `presignPut` / `presignGet`. The presigned URL route returns `501` when this adapter is used.
+
+#### Local Filesystem
+
+```typescript
+import { localStorage } from "@lastshotlabs/bunshot";
+
+const storage = localStorage({
+  directory: import.meta.dir + "/uploads",
+  baseUrl: "https://example.com/files",   // optional — appended to key for public URL
+});
+```
+
+#### S3 / R2 / MinIO
+
+Requires `@aws-sdk/client-s3`. Presigned URLs additionally require `@aws-sdk/s3-request-presigner`.
+
+```typescript
+import { s3Storage } from "@lastshotlabs/bunshot";
+
+const storage = s3Storage({
+  bucket: "my-bucket",
+  region: "us-east-1",
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+  publicUrl: "https://cdn.example.com",  // optional — used to build the returned URL
+  // For Cloudflare R2 or MinIO:
+  // endpoint: "https://<account>.r2.cloudflarestorage.com",
+  // forcePathStyle: true,
+});
+```
+
+### Server-Side Upload (Middleware)
+
+Use `handleUpload` middleware in your route handler. It parses the multipart body, validates files, stores them, and sets `uploadResults` on the context.
+
+```typescript
+import { createRoute, handleUpload } from "@lastshotlabs/bunshot";
+import { createRouter } from "@lastshotlabs/bunshot";
+
+export const router = createRouter();
+
+const uploadRoute = createRoute({
+  method: "post",
+  path: "/photos",
+  summary: "Upload photos",
+  responses: {
+    200: { description: "Uploaded", content: { "application/json": { schema: z.object({ keys: z.array(z.string()) }) } } },
+  },
+});
+
+router.openapi(uploadRoute, handleUpload({ field: "photo", allowedMimeTypes: ["image/*"] }), async (c) => {
+  const results = c.get("uploadResults") ?? [];
+  return c.json({ keys: results.map((r) => r.key) });
+});
+```
+
+**`UploadResult` fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | `string` | Storage key |
+| `originalName` | `string` | Original filename from the browser |
+| `mimeType` | `string` | Detected MIME type |
+| `size` | `number` | File size in bytes |
+| `url` | `string \| undefined` | Public URL (when adapter returns one) |
+
+### Presigned URL Flow (Client-Side Upload)
+
+When `presignedUrls` is set, two routes are mounted (default base path `/uploads`, requires authentication):
+
+- `POST /uploads/presign` — returns a time-limited PUT URL
+- `DELETE /uploads/:key` — deletes a stored file
+
+```typescript
+// 1. Client requests a presigned URL from your API
+const { url, key } = await fetch("/uploads/presign", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ key: "photos/my-image.jpg", mimeType: "image/jpeg", expirySeconds: 300 }),
+}).then(r => r.json());
+
+// 2. Client uploads directly to storage (no server bandwidth used)
+await fetch(url, { method: "PUT", body: file, headers: { "Content-Type": "image/jpeg" } });
+
+// 3. Store the key in your database
+await savePhotoRecord({ key, userId: currentUser.id });
+```
+
+Configure the base path and default expiry:
+
+```typescript
+presignedUrls: {
+  path: "/media",         // mounts POST /media/presign and DELETE /media/:key
+  expirySeconds: 600,     // default 10-minute expiry
+}
+```
+
+If the configured storage adapter does not support `presignPut` (e.g., memory or local filesystem), the endpoint returns `501 { error: "Presigned URLs not supported by the configured storage adapter" }`.
+
+### Dynamic Bucket Selection
+
+Set `c.set("uploadBucket", "tenant-bucket-name")` before calling `handleUpload` (or `parseUpload`) to override the default bucket on a per-request basis. Supported by `s3Storage` — `meta.bucket` takes priority over `config.bucket`.
+
+```typescript
+router.use("/uploads/*", async (c, next) => {
+  const tenant = c.get("tenantId");
+  if (tenant) c.set("uploadBucket", `tenant-${tenant}`);
+  await next();
+});
+```
+
+### MIME Type Wildcards
+
+`allowedMimeTypes` supports exact matches and `type/*` wildcards:
+
+```typescript
+allowedMimeTypes: ["image/*", "video/mp4", "application/pdf"]
+```
+
+### Tenant-Scoped Keys
+
+When `tenantScopedKeys: true`, generated keys are prefixed with the request's `tenantId`:
+
+```
+uploads/tenant-abc/550e8400-e29b-41d4-a716-446655440000.jpg
+```
+
+### Context Variables
+
+| Variable | Type | Set by |
+|----------|------|--------|
+| `uploadResults` | `UploadResult[] \| null` | `handleUpload` middleware |
+| `uploadBucket` | `string \| undefined` | Application code (per-request bucket override) |
+
+### `parseUpload` (lower-level)
+
+`parseUpload(c, opts?)` is the underlying function used by `handleUpload`. It returns `UploadResult[]` directly without touching `c.set("uploadResults", ...)`. Use it when you need more control over the response or want to handle results inline:
+
+```typescript
+import { parseUpload } from "@lastshotlabs/bunshot";
+
+router.post("/avatar", async (c) => {
+  const [result] = await parseUpload(c, { field: "avatar", maxFiles: 1, allowedMimeTypes: ["image/*"] });
+  await db.users.update({ id: c.get("authUserId")! }, { avatar: result.key });
+  return c.json({ key: result.key });
+});
+```

package/docs/sections/versioning/full.md

@@ -0,0 +1,85 @@
+## API Versioning
+
+Mount multiple API versions with isolated OpenAPI specs and Scalar docs pages.
+
+### Directory Structure
+
+```
+routes/
+├── v1/
+│   └── users.ts          # v1-specific routes
+├── v2/
+│   └── users.ts          # v2-specific routes (breaking changes)
+└── shared/
+    └── health.ts         # appears in all versions, unprefixed schemas
+```
+
+### Configuration
+
+```typescript
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  versioning: {
+    versions: ["v1", "v2"],   // subdirectories under routesDir
+    defaultVersion: "v2",     // which version /docs and /openapi.json redirect to (default: last)
+    sharedDir: "shared",      // shared routes dir (default: "shared", set false to disable)
+  },
+});
+```
+
+**What gets mounted:**
+
+| Path | Description |
+|------|-------------|
+| `/v1/users`, `/v2/users` | Version-specific route handlers |
+| `/v1/openapi.json`, `/v2/openapi.json` | Isolated OpenAPI specs |
+| `/v1/docs`, `/v2/docs` | Scalar docs per version |
+| `/docs` | Version selector page (links to each version's docs) |
+| `/openapi.json` | 302 redirect to `/{defaultVersion}/openapi.json` (no merged spec) |
+
+### Route Files
+
+Route files are unchanged — use `createRouter()` and `createRoute()` as normal:
+
+```typescript
+// routes/v2/users.ts
+import { createRouter, createRoute } from "@lastshotlabs/bunshot";
+import { z } from "zod";
+
+export const router = createRouter();
+
+const ListUsersRoute = createRoute({
+  method: "get",
+  path: "/users",
+  responses: {
+    200: {
+      description: "Users",
+      content: { "application/json": { schema: z.object({ users: z.array(UserSchema) }) } },
+    },
+  },
+});
+
+router.openapi(ListUsersRoute, (c) => c.json({ users: [] }));
+```
+
+Schema names are automatically prefixed with the version: `GET /users` in v1 → `V1GetUsersResponse`, in v2 → `V2GetUsersResponse`. This prevents phantom types in generated TypeScript clients when both specs share a registry.
+
+### Shared Routes
+
+Routes in the `shared/` directory are mounted on every versioned app. Their schemas receive **no version prefix** since they are version-agnostic. Shared route files must be stateless — Hono mounts a reference (not a clone), so the same router instance is shared across all versioned apps. Standard `createRouter()` routers are stateless by design.
+
+### Unreferenced Schema Stripping
+
+Each version's spec is post-processed to remove `components/schemas` entries not referenced by that version's routes. This prevents schema bleed from the global OpenAPI registry into specs that don't use them.
+
+`stripUnreferencedSchemas` is also exported from the package for apps that serve OpenAPI specs via custom handlers.
+
+### No Merged Spec
+
+There is no combined spec at `/openapi.json`. Root `/openapi.json` returns a `302` redirect to the default version's spec. This is intentional — merging specs from multiple versions produces ambiguous schema names and defeats the isolation benefit.
+
+### Notes
+
+- **Avoid unbounded top-level `await` in route files.** The framework sets the version prefix module-level before importing each version's route files. A route file whose `createRoute()` calls run synchronously (the normal pattern) works correctly. If `createRoute()` is called after an unbounded top-level `await` (e.g., an unresolved DB call), the prefix may have changed. The framework throws a clear startup error if this is detected.
+- **Non-versioned behavior is unchanged.** If `versioning` is not set, routes are discovered at `routesDir/**/*.ts` and mounted at root exactly as before.
+- **Priority ordering works per-version.** Export `export const priority = <number>` from a versioned route file to control load order within that version.

package/docs/sections/webhook-auth/full.md

@@ -0,0 +1,100 @@
+## Webhook Authentication
+
+`webhookAuth` is a middleware that verifies HMAC signatures on incoming webhook requests. It supports GitHub-style signing, multiple algorithms, replay protection, and per-request dynamic secrets.
+
+```ts
+import { webhookAuth } from "@lastshotlabs/bunshot";
+```
+
+### Basic usage
+
+```ts
+// routes/webhooks.ts
+import { webhookAuth } from "@lastshotlabs/bunshot";
+import { createRouter } from "@lastshotlabs/bunshot";
+
+export const router = createRouter();
+
+router.post(
+  "/webhooks/stripe",
+  webhookAuth({ secret: process.env.STRIPE_WEBHOOK_SECRET! }),
+  async (c) => {
+    const event = await c.req.json();
+    // body is still readable — Hono caches it after webhookAuth reads it
+    return c.json({ received: true });
+  }
+);
+```
+
+### GitHub-style (prefix + sha256)
+
+GitHub sends `X-Hub-Signature-256: sha256=<hex>`. Use `prefix` to strip the `sha256=` before comparing:
+
+```ts
+router.post(
+  "/webhooks/github",
+  webhookAuth({
+    secret: process.env.GITHUB_WEBHOOK_SECRET!,
+    header: "x-hub-signature-256",
+    prefix: "sha256=",
+    algorithm: "sha256",
+  }),
+  async (c) => c.json({ ok: true })
+);
+```
+
+If the header value does **not** start with the configured prefix, the full value is compared as-is — the prefix is stripped when present, not required.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `secret` | `string \| (c) => string \| Promise<string>` | — | Shared HMAC secret. Pass a function for dynamic resolution (e.g. per-tenant lookup). |
+| `header` | `string` | `"x-webhook-signature"` | Header that carries the signature. |
+| `algorithm` | `"sha256" \| "sha512" \| "sha1"` | `"sha256"` | HMAC algorithm. |
+| `prefix` | `string` | — | Strip this prefix before comparing (e.g. `"sha256="` for GitHub). |
+| `timestamp` | `{ header, tolerance }` | — | Opt-in replay protection (see below). |
+
+### Replay protection
+
+Pass `timestamp` to reject requests with a stale timestamp header:
+
+```ts
+webhookAuth({
+  secret: process.env.WEBHOOK_SECRET!,
+  timestamp: {
+    header: "x-webhook-timestamp",  // header name carrying the Unix timestamp
+    tolerance: 300_000,             // 5 minutes in ms
+  },
+})
+```
+
+- Values `< 1e10` in the header are treated as Unix **seconds** and auto-converted to ms
+- Missing or non-numeric timestamps → `401 EXPIRED_TIMESTAMP`
+- Timestamp outside `tolerance` → `401 EXPIRED_TIMESTAMP`
+- Signature check runs after the timestamp check passes
+
+### Dynamic secrets (multi-tenant)
+
+Pass a function to resolve the secret per request — useful when each tenant has its own webhook secret:
+
+```ts
+webhookAuth({
+  secret: async (c) => {
+    const tenantId = c.req.header("x-tenant-id");
+    const tenant = await getTenantWebhookSecret(tenantId);
+    if (!tenant) throw new Error("unknown tenant");
+    return tenant.webhookSecret;
+  },
+})
+```
+
+If the function throws, the request receives `500 { code: "WEBHOOK_SECRET_ERROR" }`.
+
+### Error responses
+
+| Condition | Status | `code` |
+|-----------|--------|--------|
+| Missing or invalid signature | `401` | `INVALID_SIGNATURE` |
+| Missing, non-numeric, or expired timestamp | `401` | `EXPIRED_TIMESTAMP` |
+| Secret function threw | `500` | `WEBHOOK_SECRET_ERROR` |

package/docs/sections/websocket/full.md

@@ -81,6 +81,89 @@ await createServer({
 
 You can supply any subset of `open`, `message`, `close`, `drain` — unset handlers fall back to the defaults.
 
+### Heartbeat / Ping-Pong Keepalive
+
+Opt-in via `ws.heartbeat`. Detects and closes stale connections via ping/pong:
+
+```ts
+await createServer({
+  ws: {
+    heartbeat: true, // 30s interval, 10s timeout
+    // or fine-tune:
+    heartbeat: { intervalMs: 15_000, timeoutMs: 5_000 },
+  },
+});
+```
+
+Every `intervalMs`, the server pings all connected sockets. If a socket hasn't responded within `timeoutMs`, it's closed with code `1001` ("Heartbeat timeout"). `stopHeartbeat()` is called automatically on SIGTERM/SIGINT and is also exported for custom shutdown logic.
+
+### Presence Tracking
+
+Opt-in via `ws.presence`. Tracks which authenticated users are online in each room (multi-tab aware):
+
+```ts
+await createServer({
+  ws: {
+    presence: true,
+  },
+});
+```
+
+When a user's first socket subscribes to a room, all room members receive `{ event: "presence_join", room, userId }`. When the user's last socket leaves (unsubscribe or disconnect), `{ event: "presence_leave", room, userId }` is broadcast.
+
+**Query presence:**
+
+```ts
+import { getRoomPresence, getUserPresence } from "@lastshotlabs/bunshot";
+
+getRoomPresence("chat:general"); // ["user1", "user2"] — deduplicated userIds
+getUserPresence("user1");        // ["chat:general", "chat:vip"] — rooms where user is present
+```
+
+### Message Persistence
+
+Opt-in via `ws.persistence`. Persists messages for late joiners. Rooms must be individually opted in via `configureRoom()`:
+
+```ts
+import { configureRoom, persistMessage, getMessageHistory } from "@lastshotlabs/bunshot";
+
+await createServer({
+  ws: {
+    persistence: {
+      store: "memory", // "redis" | "mongo" | "sqlite" | "memory"
+      defaults: { maxCount: 100, ttlSeconds: 86_400 }, // 24h
+    },
+  },
+});
+
+// Opt rooms in
+configureRoom("chat:general", { persist: true });
+configureRoom("chat:vip", { persist: true, maxCount: 50, ttlSeconds: 3600 });
+
+// Persist from your custom message handler
+await createServer({
+  ws: {
+    handler: {
+      async message(ws, message) {
+        const data = JSON.parse(message as string);
+        if (data.type === "chat") {
+          await persistMessage(data.room, {
+            senderId: ws.data.userId,
+            payload: data,
+          });
+        }
+      },
+    },
+  },
+});
+
+// Retrieve history (cursor-based pagination)
+const history = await getMessageHistory("chat:general", { limit: 50 });
+const older = await getMessageHistory("chat:general", { limit: 50, before: history[0].id });
+```
+
+Messages for non-configured rooms are silently ignored. Store errors are caught and logged (non-blocking) — message delivery is never interrupted by a persistence failure.
+
 ### Overriding the upgrade / auth handler
 
 Replace the default cookie-JWT handshake entirely via `ws.upgradeHandler`. You must call `server.upgrade()` yourself and include `rooms: new Set()` in data:

package/docs/sections/websocket-rooms/full.md

@@ -13,6 +13,11 @@ Rooms are built on Bun's native pub/sub. `createServer` always intercepts room a
 | `getRooms()` | Returns `string[]` of all rooms with at least one active subscriber |
 | `getRoomSubscribers(room)` | Returns `string[]` of socket IDs currently subscribed to `room` |
 | `handleRoomActions(ws, message, onSubscribe?)` | Parses and dispatches subscribe/unsubscribe actions. Returns `true` if the message was a room action (consumed), `false` otherwise. Pass an optional async guard as the third argument. |
+| `getRoomPresence(room)` | Returns deduplicated `string[]` of userIds present in room (requires `ws.presence` enabled) |
+| `getUserPresence(userId)` | Returns `string[]` of rooms where user is present (requires `ws.presence` enabled) |
+| `persistMessage(room, data)` | Store a message for a room (requires `ws.persistence` + `configureRoom`). Returns `StoredMessage \| null` |
+| `getMessageHistory(room, opts?)` | Cursor-based retrieval. `opts`: `{ limit?, before?, after? }` (cursors are message IDs) |
+| `configureRoom(room, opts)` | Opt a room into persistence: `{ persist: true, maxCount?, ttlSeconds? }` |
 
 ### Client → server: join or leave a room
 
@@ -94,4 +99,4 @@ await createServer({
     },
   },
 });
-```
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lastshotlabs/bunshot",
-  "version": "0.0.21",
+  "version": "0.0.25",
   "description": "Batteries-included Bun + Hono API framework — auth, sessions, rate limiting, WebSocket, queues, and OpenAPI docs out of the box",
   "repository": {
     "type": "git",
@@ -52,8 +52,8 @@
     "start": "bun src/index.ts",
     "readme": "bun docs/build-readme.ts",
     "readme:npm": "bun docs/build-readme.ts npm",
-    "test": "bun test tests/unit tests/integration && bun test tests/isolated",
-    "test:isolated": "bun test tests/isolated",
+    "test": "bun test tests/unit tests/integration && bun test tests/isolated/optional-deps.test.ts && bun test tests/isolated/jwt-secret.test.ts && bun test tests/isolated/queue.test.ts tests/isolated/jobs-router.test.ts && bun test tests/isolated/queued-deletion.test.ts",
+    "test:isolated": "bun test tests/isolated/optional-deps.test.ts && bun test tests/isolated/jwt-secret.test.ts && bun test tests/isolated/queue.test.ts tests/isolated/jobs-router.test.ts && bun test tests/isolated/queued-deletion.test.ts",
     "test:coverage": "bun test --coverage tests/unit tests/integration",
     "test:docker:up": "docker compose -f docker-compose.test.yml up -d --wait",
     "test:docker:down": "docker compose -f docker-compose.test.yml down",
@@ -75,7 +75,10 @@
     "ioredis": ">=5.0 <6",
     "bullmq": ">=5.0 <6",
     "otpauth": ">=9.0 <10",
-    "@simplewebauthn/server": ">=10.0.0"
+    "@simplewebauthn/server": ">=10.0.0",
+    "@aws-sdk/client-s3": ">=3.0",
+    "@aws-sdk/s3-request-presigner": ">=3.0",
+    "@aws-sdk/lib-storage": ">=3.0"
   },
   "peerDependenciesMeta": {
     "mongoose": {
@@ -92,6 +95,15 @@
     },
     "@simplewebauthn/server": {
       "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
     }
   },
   "devDependencies": {