@lastshotlabs/bunshot 0.0.27 → 0.0.28

package/dist/{lib → src/framework/lib}/captcha.js

@@ -1,7 +1,7 @@
 const VERIFY_URLS = {
-    recaptcha: "https://www.google.com/recaptcha/api/siteverify",
-    hcaptcha: "https://hcaptcha.com/siteverify",
-    turnstile: "https://challenges.cloudflare.com/turnstile/v0/siteverify",
+    recaptcha: 'https://www.google.com/recaptcha/api/siteverify',
+    hcaptcha: 'https://hcaptcha.com/siteverify',
+    turnstile: 'https://challenges.cloudflare.com/turnstile/v0/siteverify',
 };
 /**
  * Verify a CAPTCHA token with the provider's API.
@@ -11,25 +11,28 @@ export async function verifyCaptcha(token, config, ip) {
     const url = VERIFY_URLS[config.provider];
     const body = new URLSearchParams({ secret: config.secretKey, response: token });
     if (ip)
-        body.set("remoteip", ip);
+        body.set('remoteip', ip);
     let data;
     try {
-        const res = await fetch(url, { method: "POST", body });
+        const res = await fetch(url, { method: 'POST', body });
         if (!res.ok)
             return { success: false, error: `Provider returned ${res.status}` };
-        data = await res.json();
+        data = (await res.json());
     }
     catch (err) {
-        return { success: false, error: "CAPTCHA provider unreachable" };
+        return { success: false, error: 'CAPTCHA provider unreachable' };
     }
     if (!data.success) {
-        return { success: false, error: String(data["error-codes"]?.[0] ?? "invalid-token") };
+        return {
+            success: false,
+            error: String(data['error-codes']?.[0] ?? 'invalid-token'),
+        };
     }
     // reCAPTCHA v3: check score
-    if (config.provider === "recaptcha" && typeof data.score === "number") {
+    if (config.provider === 'recaptcha' && typeof data.score === 'number') {
         const minScore = config.minScore ?? 0.5;
         if (data.score < minScore) {
-            return { success: false, score: data.score, error: "score-too-low" };
+            return { success: false, score: data.score, error: 'score-too-low' };
         }
         return { success: true, score: data.score };
     }

package/dist/{lib → src/framework/lib}/createDtoMapper.js

@@ -1,11 +1,11 @@
 /** Check if a Zod type is nullable or optional */
 function isNullable(zodType) {
     const defType = zodType?._zod?.def?.type;
-    if (defType === "nullable")
+    if (defType === 'nullable')
         return true;
-    if (defType === "optional")
+    if (defType === 'optional')
         return true;
-    if (defType === "default")
+    if (defType === 'default')
         return isNullable(zodType._zod.def.innerType);
     return false;
 }
@@ -46,7 +46,7 @@ export function createDtoMapper(zodSchema, config = {}) {
     return (doc) => {
         const dto = {};
         for (const field of apiFields) {
-            if (field === "id") {
+            if (field === 'id') {
                 dto.id = doc._id.toString();
                 continue;
             }

package/dist/src/framework/lib/createRoute.d.ts

@@ -0,0 +1 @@
+export { createRoute, withSecurity, registerSchema, registerSchemas, maybeAutoRegister, } from '../../../packages/bunshot-core/src/index.js';

package/dist/src/framework/lib/createRoute.js

@@ -0,0 +1,2 @@
+// Re-export from core — all route utilities now live in @lastshotlabs/bunshot-core
+export { createRoute, withSecurity, registerSchema, registerSchemas, maybeAutoRegister, } from '../../../packages/bunshot-core/src/index.js';

package/dist/{lib → src/framework/lib}/idempotency.d.ts

@@ -1,12 +1,9 @@
-import type { MiddlewareHandler } from "hono";
-import type { AppEnv } from "./context";
+import type { MiddlewareHandler } from 'hono';
+import type { AppEnv } from '../../../packages/bunshot-core/src/index.js';
 export interface IdempotencyOptions {
     /** TTL in seconds for cached responses. Default: 86400 (24 hours). */
     ttl?: number;
 }
-type IdempotencyStore = "redis" | "mongo" | "sqlite" | "memory";
-export declare const setIdempotencyStore: (store: IdempotencyStore) => void;
-export declare const clearIdempotencyMemoryStore: () => void;
 /**
  * Idempotency middleware. Reads the `Idempotency-Key` header and returns a
  * cached response if one exists for this user + key combination. Otherwise
@@ -19,4 +16,3 @@ export declare const clearIdempotencyMemoryStore: () => void;
  * prevent enumeration. When off, raw keys are stored (slight enumeration risk).
  */
 export declare const idempotent: (opts?: IdempotencyOptions) => MiddlewareHandler<AppEnv>;
-export {};

package/dist/src/framework/lib/idempotency.js

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// Idempotency middleware — consumes repository from BunshotContext
+// ---------------------------------------------------------------------------
+import { hmacSign } from '../../lib/signing';
+import { HEADER_IDEMPOTENCY_KEY } from '../../../packages/bunshot-core/src/index.js';
+// ---------------------------------------------------------------------------
+// Key derivation
+// ---------------------------------------------------------------------------
+function deriveKey(rawKey, userId, signing) {
+    const prefix = userId ?? 'anon';
+    if (signing?.config?.idempotencyKeys && signing.secret) {
+        return `${prefix}:${hmacSign(rawKey, signing.secret)}`;
+    }
+    return `${prefix}:${rawKey}`;
+}
+// ---------------------------------------------------------------------------
+// Middleware factory
+// ---------------------------------------------------------------------------
+/**
+ * Idempotency middleware. Reads the `Idempotency-Key` header and returns a
+ * cached response if one exists for this user + key combination. Otherwise
+ * calls the next handler, stores the response, and returns it.
+ *
+ * On write collision (two concurrent identical requests), the second request
+ * re-reads and returns the first-stored result.
+ *
+ * When `signing.idempotencyKeys: true`, keys are HMAC'd before storage to
+ * prevent enumeration. When off, raw keys are stored (slight enumeration risk).
+ */
+export const idempotent = (opts) => async (c, next) => {
+    const rawKey = c.req.header(HEADER_IDEMPOTENCY_KEY);
+    if (!rawKey) {
+        await next();
+        return;
+    }
+    const ctx = c.get('bunshotCtx');
+    const adapter = ctx?.persistence.idempotency;
+    if (!adapter) {
+        // No persistence configured — pass through
+        await next();
+        return;
+    }
+    const userId = c.get('authUserId') ?? null;
+    const signingConfig = ctx?.signing ?? null;
+    const signingSecret = signingConfig?.secret ?? null;
+    const key = deriveKey(rawKey, userId, { config: signingConfig, secret: signingSecret });
+    const ttl = opts?.ttl ?? 86400;
+    // Cache hit — return stored response
+    const cached = await adapter.get(key);
+    if (cached) {
+        return c.json(JSON.parse(cached.response), cached.status);
+    }
+    // Cache miss — call handler
+    await next();
+    // Capture the response body by reading it
+    const status = c.res.status;
+    let body = '';
+    try {
+        body = await c.res.clone().text();
+    }
+    catch {
+        // Non-text/non-json response — skip caching
+        return;
+    }
+    await adapter.set(key, body, status, ttl);
+    // Re-read to handle write collision (NX semantics — set() may have been a no-op)
+    const stored = await adapter.get(key);
+    if (stored && stored.response !== body) {
+        c.res = new Response(stored.response, {
+            status: stored.status,
+            headers: { 'content-type': 'application/json' },
+        });
+    }
+};

package/dist/src/framework/lib/logger.d.ts

@@ -0,0 +1,3 @@
+export declare const log: (...args: unknown[]) => void;
+/** Like log(), but also requires LOGGING_AUTH_TRACE=true. Use for lines that include user/session IDs. */
+export declare const authTrace: (...args: unknown[]) => void;

package/dist/src/framework/lib/logger.js

@@ -0,0 +1,14 @@
+function isVerbose() {
+    const v = process.env.LOGGING_VERBOSE;
+    return v !== undefined ? v === 'true' : process.env.NODE_ENV !== 'production';
+}
+export const log = (...args) => {
+    if (isVerbose())
+        console.log(...args);
+};
+const authTraceEnabled = process.env.LOGGING_AUTH_TRACE === 'true';
+/** Like log(), but also requires LOGGING_AUTH_TRACE=true. Use for lines that include user/session IDs. */
+export const authTrace = (...args) => {
+    if (authTraceEnabled)
+        log(...args);
+};

package/dist/src/framework/lib/metrics.d.ts

@@ -0,0 +1,34 @@
+type Labels = Record<string, string>;
+interface CounterEntry {
+    labels: Labels;
+    value: number;
+}
+interface HistogramEntry {
+    labels: Labels;
+    buckets: number[];
+    sum: number;
+    count: number;
+}
+type GaugeCallback = () => Promise<{
+    labels: Labels;
+    value: number;
+}[]>;
+export interface MetricsState {
+    readonly counters: Map<string, Map<string, CounterEntry>>;
+    readonly histograms: Map<string, {
+        boundaries: number[];
+        entries: Map<string, HistogramEntry>;
+    }>;
+    readonly gaugeCallbacks: Map<string, GaugeCallback>;
+    queues: Map<string, any> | null;
+}
+export declare function createMetricsState(): MetricsState;
+export declare function defaultNormalizePath(path: string): string;
+export declare function incrementCounter(state: MetricsState, name: string, labels: Labels, amount?: number): void;
+export declare function observeHistogram(state: MetricsState, name: string, labels: Labels, value: number, buckets?: number[]): void;
+export declare function registerGaugeCallback(state: MetricsState, name: string, cb: GaugeCallback): void;
+export declare function serializeMetrics(state: MetricsState): Promise<string>;
+export declare function resetMetrics(state: MetricsState): void;
+export declare function setMetricsQueues(state: MetricsState, map: Map<string, any>): void;
+export declare function closeMetricsQueues(state: MetricsState): Promise<void>;
+export {};

package/dist/{lib → src/framework/lib}/metrics.js

@@ -1,44 +1,49 @@
 // In-memory Prometheus-compatible metrics registry.
-// Bun is single-threaded so no atomics are needed.
-// ── Helpers ──────────────────────────────────────────────────────────────────
+// Owned per app instance via MetricsState, not process-global.
+export function createMetricsState() {
+    return {
+        counters: new Map(),
+        histograms: new Map(),
+        gaugeCallbacks: new Map(),
+        queues: null,
+    };
+}
 function labelKey(labels) {
     return Object.entries(labels)
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([k, v]) => `${k}="${v}"`)
-        .join(",");
+        .join(',');
 }
 function formatLabels(labels) {
     const pairs = Object.entries(labels)
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([k, v]) => `${k}="${v}"`);
-    return pairs.length ? `{${pairs.join(",")}}` : "";
+    return pairs.length ? `{${pairs.join(',')}}` : '';
 }
-// ── Path normalization ───────────────────────────────────────────────────────
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const OBJECTID_RE = /^[0-9a-f]{24}$/i;
 const NUMERIC_RE = /^\d+$/;
 export function defaultNormalizePath(path) {
     return path
-        .split("/")
-        .map((seg) => {
+        .split('/')
+        .map(seg => {
         if (!seg)
             return seg;
         if (UUID_RE.test(seg))
-            return ":id";
+            return ':id';
         if (OBJECTID_RE.test(seg))
-            return ":id";
+            return ':id';
         if (NUMERIC_RE.test(seg))
-            return ":id";
+            return ':id';
         return seg;
     })
-        .join("/");
+        .join('/');
 }
-const counters = new Map();
-export function incrementCounter(name, labels, amount = 1) {
-    let metric = counters.get(name);
+export function incrementCounter(state, name, labels, amount = 1) {
+    let metric = state.counters.get(name);
     if (!metric) {
         metric = new Map();
-        counters.set(name, metric);
+        state.counters.set(name, metric);
     }
     const key = labelKey(labels);
     const existing = metric.get(key);
@@ -49,14 +54,12 @@ export function incrementCounter(name, labels, amount = 1) {
         metric.set(key, { labels: { ...labels }, value: amount });
     }
 }
-// ── Histogram ────────────────────────────────────────────────────────────────
 const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
-const histograms = new Map();
-export function observeHistogram(name, labels, value, buckets = DEFAULT_BUCKETS) {
-    let metric = histograms.get(name);
+export function observeHistogram(state, name, labels, value, buckets = DEFAULT_BUCKETS) {
+    let metric = state.histograms.get(name);
     if (!metric) {
         metric = { boundaries: buckets, entries: new Map() };
-        histograms.set(name, metric);
+        state.histograms.set(name, metric);
     }
     const key = labelKey(labels);
     let entry = metric.entries.get(key);
@@ -64,8 +67,6 @@ export function observeHistogram(name, labels, value, buckets = DEFAULT_BUCKETS)
         entry = { labels: { ...labels }, buckets: new Array(buckets.length).fill(0), sum: 0, count: 0 };
         metric.entries.set(key, entry);
     }
-    // Find the first (tightest) bucket the value fits in.
-    // Serialization will compute cumulative sums across buckets.
     for (let i = 0; i < metric.boundaries.length; i++) {
         if (value <= metric.boundaries[i]) {
             entry.buckets[i]++;
@@ -75,43 +76,37 @@ export function observeHistogram(name, labels, value, buckets = DEFAULT_BUCKETS)
     entry.sum += value;
     entry.count++;
 }
-const gaugeCallbacks = new Map();
-export function registerGaugeCallback(name, cb) {
-    gaugeCallbacks.set(name, cb);
+export function registerGaugeCallback(state, name, cb) {
+    state.gaugeCallbacks.set(name, cb);
 }
-// ── Serialize ────────────────────────────────────────────────────────────────
-export async function serializeMetrics() {
+export async function serializeMetrics(state) {
     const lines = [];
-    // Collect gauge callbacks first so any error-counter increments are
-    // included when we serialize counters below.
     const gaugeLines = [];
-    for (const [name, cb] of gaugeCallbacks) {
+    for (const [name, cb] of state.gaugeCallbacks) {
         try {
             const results = await cb();
-            gaugeLines.push(`# HELP ${name} ${name.replace(/_/g, " ")}`);
+            gaugeLines.push(`# HELP ${name} ${name.replace(/_/g, ' ')}`);
             gaugeLines.push(`# TYPE ${name} gauge`);
             for (const { labels, value } of results) {
                 gaugeLines.push(`${name}${formatLabels(labels)} ${value}`);
             }
-            gaugeLines.push("");
+            gaugeLines.push('');
         }
         catch (err) {
             console.warn(`[metrics] Gauge callback "${name}" failed:`, err);
-            incrementCounter("bunshot_gauge_errors_total", { gauge: name });
+            incrementCounter(state, 'bunshot_gauge_errors_total', { gauge: name });
         }
     }
-    // Counters
-    for (const [name, entries] of counters) {
-        lines.push(`# HELP ${name} Total ${name.replace(/_/g, " ")}`);
+    for (const [name, entries] of state.counters) {
+        lines.push(`# HELP ${name} Total ${name.replace(/_/g, ' ')}`);
         lines.push(`# TYPE ${name} counter`);
         for (const entry of entries.values()) {
             lines.push(`${name}${formatLabels(entry.labels)} ${entry.value}`);
         }
-        lines.push("");
+        lines.push('');
     }
-    // Histograms
-    for (const [name, metric] of histograms) {
-        lines.push(`# HELP ${name} ${name.replace(/_/g, " ")}`);
+    for (const [name, metric] of state.histograms) {
+        lines.push(`# HELP ${name} ${name.replace(/_/g, ' ')}`);
         lines.push(`# TYPE ${name} histogram`);
         for (const entry of metric.entries.values()) {
             const lbls = formatLabels(entry.labels);
@@ -121,32 +116,28 @@ export async function serializeMetrics() {
                 const bucketLabels = { ...entry.labels, le: String(metric.boundaries[i]) };
                 lines.push(`${name}_bucket${formatLabels(bucketLabels)} ${cumulative}`);
             }
-            const infLabels = { ...entry.labels, le: "+Inf" };
+            const infLabels = { ...entry.labels, le: '+Inf' };
             lines.push(`${name}_bucket${formatLabels(infLabels)} ${entry.count}`);
             lines.push(`${name}_sum${lbls} ${entry.sum}`);
             lines.push(`${name}_count${lbls} ${entry.count}`);
         }
-        lines.push("");
+        lines.push('');
     }
-    // Gauges (already collected above)
     lines.push(...gaugeLines);
-    return lines.join("\n");
+    return lines.join('\n');
 }
-// ── Reset (for tests) ───────────────────────────────────────────────────────
-export function resetMetrics() {
-    counters.clear();
-    histograms.clear();
-    gaugeCallbacks.clear();
+export function resetMetrics(state) {
+    state.counters.clear();
+    state.histograms.clear();
+    state.gaugeCallbacks.clear();
 }
-// ── Queue cleanup ────────────────────────────────────────────────────────────
-let metricsQueues = null;
-export function setMetricsQueues(map) {
-    metricsQueues = map;
+export function setMetricsQueues(state, map) {
+    state.queues = map;
 }
-export async function closeMetricsQueues() {
-    if (!metricsQueues)
+export async function closeMetricsQueues(state) {
+    if (!state.queues)
         return;
-    for (const q of metricsQueues.values()) {
+    for (const q of state.queues.values()) {
         try {
             await q.close();
         }
@@ -154,5 +145,6 @@ export async function closeMetricsQueues() {
             // best-effort cleanup
         }
     }
-    metricsQueues.clear();
+    state.queues.clear();
+    state.queues = null;
 }

package/dist/src/framework/lib/pagination.d.ts

@@ -0,0 +1,42 @@
+import type { SigningConfig } from '../../lib/signingConfig';
+import { z } from 'zod';
+import type { ZodType } from 'zod';
+export type { PaginationOpts, PaginatedResult } from '../../../packages/bunshot-core/src/index.js';
+export { offsetParams, parseOffsetParams, paginatedResponse } from '../../../packages/bunshot-core/src/index.js';
+export { cursorPaginatedResponse } from '../../../packages/bunshot-core/src/index.js';
+export type { OffsetParamDefaults, ParsedOffsetParams } from '../../../packages/bunshot-core/src/index.js';
+export interface CursorParamDefaults {
+    limit?: number;
+    maxLimit?: number;
+}
+export interface ParsedCursorParams {
+    limit: number;
+    cursor: string | undefined;
+}
+export interface CursorResult<T> {
+    items: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+export declare function cursorParams(defaults?: CursorParamDefaults): z.ZodObject<{
+    limit: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function parseCursorParams(raw: {
+    limit?: string;
+    cursor?: string;
+}, defaults?: CursorParamDefaults, signing?: {
+    config: SigningConfig | null;
+    secret: string | string[] | null;
+}): ParsedCursorParams & {
+    invalidCursor?: true;
+};
+export declare function maybeSignCursor(cursor: string | null, signing?: {
+    config: SigningConfig | null;
+    secret: string | string[] | null;
+}): string | null;
+export declare function cursorResponse<T extends ZodType>(itemSchema: T, name: string): z.ZodObject<{
+    items: z.ZodArray<T>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;

package/dist/src/framework/lib/pagination.js

@@ -0,0 +1,51 @@
+import { signCursor, verifyCursor } from '../../lib/signing';
+import { z } from 'zod';
+import { registerSchema } from '../../../packages/bunshot-core/src/index.js';
+export { offsetParams, parseOffsetParams, paginatedResponse } from '../../../packages/bunshot-core/src/index.js';
+export { cursorPaginatedResponse } from '../../../packages/bunshot-core/src/index.js';
+export function cursorParams(defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    return z.object({
+        limit: z
+            .string()
+            .optional()
+            .describe(`Number of items to return (1-${maxLimit}, default ${defaultLimit})`),
+        cursor: z
+            .string()
+            .optional()
+            .describe("Opaque cursor from a previous response's nextCursor field"),
+    });
+}
+export function parseCursorParams(raw, defaults, signing) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    const rawLimit = parseInt(raw.limit ?? '', 10);
+    const limit = isNaN(rawLimit) ? defaultLimit : Math.min(Math.max(rawLimit, 1), maxLimit);
+    if (!raw.cursor)
+        return { limit, cursor: undefined };
+    if (signing?.config?.cursors && signing.secret) {
+        const verified = verifyCursor(raw.cursor, signing.secret);
+        if (verified === null)
+            return { limit, cursor: undefined, invalidCursor: true };
+        return { limit, cursor: verified };
+    }
+    return { limit, cursor: raw.cursor };
+}
+export function maybeSignCursor(cursor, signing) {
+    if (!cursor)
+        return cursor;
+    if (signing?.config?.cursors && signing.secret) {
+        return signCursor(cursor, signing.secret);
+    }
+    return cursor;
+}
+export function cursorResponse(itemSchema, name) {
+    const wrapper = z.object({
+        items: z.array(itemSchema),
+        nextCursor: z.string().nullable(),
+        hasMore: z.boolean(),
+    });
+    registerSchema(name, wrapper);
+    return wrapper;
+}

package/dist/src/framework/lib/redisTransport.d.ts

@@ -0,0 +1,38 @@
+import type { RedisOptions } from 'ioredis';
+import type { WsTransportAdapter } from './wsTransport';
+export type { WsTransportAdapter };
+export interface RedisTransportOptions {
+    /** ioredis connection options or a Redis URL string */
+    connection: RedisOptions | string;
+    /** Channel prefix for pub/sub. Default: "ws:room:" */
+    channelPrefix?: string;
+}
+/**
+ * Redis pub/sub transport for horizontal WebSocket scaling.
+ *
+ * Uses two ioredis clients — one for publishing and one for subscribing —
+ * as required by the Redis pub/sub protocol (a client in subscribe mode
+ * cannot issue regular commands).
+ *
+ * Uses `psubscribe` on `<prefix>*` so that joining new rooms never
+ * requires an additional SUBSCRIBE call.
+ *
+ * Self-echo prevention: every published message is wrapped with the
+ * `origin` passed in from `ws.ts` (the server instance UUID). Messages
+ * whose origin matches the local instance are dropped by the caller —
+ * the origin is forwarded intact to the `onMessage` callback.
+ *
+ * @example
+ * ```ts
+ * import { createRedisTransport } from '@lastshotlabs/bunshot'
+ *
+ * // Pass transport via ws.transport in createServer config:
+ * createServer({
+ *   ws: {
+ *     transport: createRedisTransport({ connection: { host: 'localhost', port: 6379 } }),
+ *     endpoints: { '/ws': {} },
+ *   },
+ * })
+ * ```
+ */
+export declare function createRedisTransport(opts: RedisTransportOptions): WsTransportAdapter;