@lastshotlabs/bunshot 0.0.27 → 0.1.0

package/docs/sections/uploads/full.md

@@ -1,208 +0,0 @@
-## 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
-
-**`POST /uploads/presign` request fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `key` | `string` | Storage key for the upload |
-| `mimeType` | `string` (optional) | MIME type of the file. Certain dangerous types are rejected with `400 { error: "File type not allowed." }`: `application/x-executable`, `application/x-sh`, `application/x-msdownload`, `text/html`, `application/x-httpd-php`, `application/javascript`, `text/javascript` |
-| `expirySeconds` | `number` (optional) | URL expiry in seconds |
-| `maxBytes` | `number` (optional) | Maximum allowed file size in bytes (client-enforced via Content-Length). Defaults to 10MB. Maximum: 100MB. Returned in the response so clients can enforce the limit before uploading. |
-
-```typescript
-// 1. Client requests a presigned URL from your API
-const { url, key, maxBytes } = await fetch("/uploads/presign", {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ key: "photos/my-image.jpg", mimeType: "image/jpeg", expirySeconds: 300, maxBytes: 5 * 1024 * 1024 }),
-}).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

@@ -1,85 +0,0 @@
-## 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

@@ -1,100 +0,0 @@
-## 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"` | `"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

@@ -1,196 +0,0 @@
-## WebSocket
-
-The `/ws` endpoint is mounted automatically by `createServer`. No extra setup needed.
-
-### Default behaviour
-
-| What | Default |
-|---|---|
-| Upgrade / auth | Reads `auth-token` cookie → verifies JWT → checks session → sets `ws.data.userId` |
-| `open` | Logs connection, sends `{ event: "connected", id }` |
-| `message` | Checks message size (closes with 1009 if exceeds `maxMessageSize`), handles room actions (see below), drops non-room messages unless custom handler provided |
-| `close` | Clears `ws.data.rooms`, logs disconnection |
-| `maxMessageSize` | 65 536 bytes (64 KB) — configurable via `ws.maxMessageSize` |
-
-### Socket data (`SocketData`)
-
-`SocketData` is generic — pass a type parameter to add your own fields:
-
-```ts
-type SocketData<T extends object = object> = {
-  id: string;            // unique connection ID (UUID)
-  userId: string | null; // null if unauthenticated
-  rooms: Set<string>;    // rooms this socket is subscribed to
-} & T;
-```
-
-**Extending with custom fields:**
-
-```ts
-import { createServer, type SocketData } from "@lastshotlabs/bunshot";
-
-type MyData = { tenantId: string; role: "admin" | "user" };
-
-await createServer<MyData>({
-  ws: {
-    upgradeHandler: async (req, server) => {
-      const tenantId = req.headers.get("x-tenant-id") ?? "default";
-      const upgraded = server.upgrade(req, {
-        data: { id: crypto.randomUUID(), userId: null, rooms: new Set(), tenantId, role: "user" },
-      });
-      return upgraded ? undefined : Response.json({ error: "Upgrade failed" }, { status: 400 });
-    },
-    handler: {
-      open(ws) {
-        // ws.data.tenantId and ws.data.role are fully typed
-        console.log(ws.data.tenantId, ws.data.role);
-      },
-    },
-    onRoomSubscribe(ws, room) {
-      return ws.data.role === "admin" || !room.startsWith("admin:");
-    },
-  },
-});
-```
-
-With no type parameter, `SocketData` defaults to `{ id, userId, rooms }` — the base shape used by the default upgrade handler.
-
-### Overriding the message handler
-
-Pass `ws.handler` to `createServer` to add custom message handling. Room action handling always runs first — your handler only receives non-room messages:
-
-```ts
-await createServer({
-  ws: {
-    handler: {
-      open(ws) {
-        ws.send(JSON.stringify({ event: "connected", id: ws.data.id }));
-      },
-      message(ws, message) {
-        // room subscribe/unsubscribe already handled — put your logic here
-        const parsed = JSON.parse(message as string);
-        if (parsed.action === "ping") ws.send(JSON.stringify({ event: "pong" }));
-      },
-      close(ws, code, reason) {
-        // ws.data.rooms already cleared
-      },
-    },
-  },
-});
-```
-
-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.
-
-### Room Name Validation
-
-Room names sent by clients via `subscribe` and `unsubscribe` actions are validated before any action is taken. Invalid room names are silently dropped — no error is sent to the client.
-
-**Valid room name rules:**
-- Characters: `a–z`, `A–Z`, `0–9`, `_`, `:`, `.`, `/`, `-`
-- Length: 1–128 characters
-
-Examples of valid names: `chat:general`, `user:123`, `tenant/room-1`, `notifications`
-
-Room names containing characters outside this set (e.g. spaces, `@`, `#`, or Unicode) are silently ignored. This prevents injection of arbitrary pub/sub topic names from untrusted client input.
-
-### 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:
-
-```ts
-await createServer({
-  ws: {
-    upgradeHandler: async (req, server) => {
-      const token = req.headers.get("x-my-token");
-      const userId = token ? await verifyMyToken(token) : null;
-      const upgraded = server.upgrade(req, {
-        data: { id: crypto.randomUUID(), userId, rooms: new Set() },
-      });
-      return upgraded ? undefined : Response.json({ error: "Upgrade failed" }, { status: 400 });
-    },
-  },
-});
-```

package/docs/sections/websocket/overview.md

@@ -1,5 +0,0 @@
-## WebSocket
-
-The `/ws` endpoint is mounted automatically by `createServer`. Default behavior: cookie-JWT auth on upgrade, room action handling, message size enforcement (64 KB default). Non-room messages are dropped unless a custom handler is provided.
-
-`SocketData` carries `id`, `userId`, and `rooms` per connection. Pass a type parameter to `createServer<T>` to extend with custom fields. Override `ws.handler` (open/message/close) and `ws.upgradeHandler` for custom behavior.