@lastshotlabs/bunshot 0.0.25 → 0.0.28

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

@@ -0,0 +1,2 @@
+import type { UserResolver } from '../../../packages/bunshot-core/src/index.js';
+export declare function resolveUserId(req: Request, resolver: UserResolver | null): Promise<string | null>;

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

@@ -0,0 +1,5 @@
+export async function resolveUserId(req, resolver) {
+    if (!resolver)
+        return null;
+    return resolver.resolveUserId(req);
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Returns true if the Hono route pattern could match the given literal SSE path.
+ * Normalizes trailing slashes. Handles: exact match, :param segments,
+ * terminal wildcard *, catch-all /*, and prefix wildcard /path/*.
+ */
+export declare function routePatternCanMatchLiteral(pattern: string, literal: string): boolean;

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

@@ -0,0 +1,26 @@
+/**
+ * Returns true if the Hono route pattern could match the given literal SSE path.
+ * Normalizes trailing slashes. Handles: exact match, :param segments,
+ * terminal wildcard *, catch-all /*, and prefix wildcard /path/*.
+ */
+export function routePatternCanMatchLiteral(pattern, literal) {
+    const norm = (s) => s.replace(/\/+$/, '') || '/';
+    pattern = norm(pattern);
+    literal = norm(literal);
+    if (pattern === '/*' || pattern === '*')
+        return true;
+    const patSegs = pattern.split('/');
+    const litSegs = literal.split('/');
+    for (let i = 0; i < patSegs.length; i++) {
+        const p = patSegs[i];
+        if (p === '*')
+            return true; // terminal wildcard — rest matches
+        if (i >= litSegs.length)
+            return false;
+        if (p.startsWith(':'))
+            continue; // param segment — matches any
+        if (p !== litSegs[i])
+            return false; // literal mismatch
+    }
+    return patSegs.length === litSegs.length;
+}

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

@@ -0,0 +1 @@
+export type { StorageAdapter, UploadResult } from '../../../packages/bunshot-core/src/index.js';

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

@@ -0,0 +1 @@
+export {};

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

@@ -10,11 +10,11 @@
  */
 export function stripUnreferencedSchemas(spec) {
     const schemas = spec?.components?.schemas;
-    if (!schemas || typeof schemas !== "object")
+    if (!schemas || typeof schemas !== 'object')
         return spec;
     // Collect all $ref strings from an arbitrary JSON node
     function collectRefs(node, refs) {
-        if (!node || typeof node !== "object")
+        if (!node || typeof node !== 'object')
             return;
         if (Array.isArray(node)) {
             for (const item of node)
@@ -22,7 +22,7 @@ export function stripUnreferencedSchemas(spec) {
             return;
         }
         for (const [key, val] of Object.entries(node)) {
-            if (key === "$ref" && typeof val === "string") {
+            if (key === '$ref' && typeof val === 'string') {
                 refs.add(val);
             }
             else {
@@ -32,7 +32,7 @@ export function stripUnreferencedSchemas(spec) {
     }
     // Extract schema name from a $ref like "#/components/schemas/Foo"
     function schemaNameFromRef(ref) {
-        const prefix = "#/components/schemas/";
+        const prefix = '#/components/schemas/';
         return ref.startsWith(prefix) ? ref.slice(prefix.length) : null;
     }
     // Collect initial refs from paths (not from components to avoid circular bootstrapping)

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

@@ -0,0 +1,21 @@
+import type { Connection } from 'mongoose';
+export interface TenantInfo {
+    tenantId: string;
+    displayName?: string;
+    config?: Record<string, unknown>;
+    createdAt: Date;
+    deletedAt?: Date | null;
+}
+export interface CreateTenantOptions {
+    displayName?: string;
+    config?: Record<string, unknown>;
+}
+export interface TenantService {
+    createTenant(tenantId: string, options?: CreateTenantOptions): Promise<void>;
+    deleteTenant(tenantId: string): Promise<void>;
+    getTenant(tenantId: string): Promise<TenantInfo | null>;
+    listTenants(): Promise<TenantInfo[]>;
+}
+export declare function createTenantService(conn: Connection, getTenantCache?: () => {
+    delete(tenantId: string): void;
+} | null): TenantService;

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

@@ -0,0 +1,70 @@
+import { getMongooseModule } from '../../lib/mongo';
+function getTenantModel(conn) {
+    if (conn.models['Tenant']) {
+        return conn.models['Tenant'];
+    }
+    const mg = getMongooseModule();
+    const { Schema } = mg;
+    const schema = new Schema({
+        tenantId: { type: String, required: true, unique: true },
+        displayName: { type: String },
+        config: { type: Schema.Types.Mixed },
+        deletedAt: { type: Date, default: null },
+    }, { timestamps: true });
+    return conn.model('Tenant', schema);
+}
+export function createTenantService(conn, getTenantCache) {
+    return {
+        async createTenant(tenantId, options) {
+            const Tenant = getTenantModel(conn);
+            const existing = await Tenant.findOne({ tenantId }).lean();
+            if (existing && !existing.deletedAt) {
+                throw new Error(`Tenant "${tenantId}" already exists`);
+            }
+            if (existing && existing.deletedAt) {
+                // Reactivate soft-deleted tenant
+                await Tenant.findOneAndUpdate({ tenantId }, { $set: { deletedAt: null, displayName: options?.displayName, config: options?.config } });
+                return;
+            }
+            await Tenant.create({
+                tenantId,
+                displayName: options?.displayName,
+                config: options?.config,
+            });
+        },
+        async deleteTenant(tenantId) {
+            const Tenant = getTenantModel(conn);
+            const existing = await Tenant.findOne({ tenantId }).lean();
+            // Already deleted (or never existed) — nothing to do
+            if (!existing || existing.deletedAt)
+                return;
+            // Soft-delete
+            await Tenant.findOneAndUpdate({ tenantId }, { $set: { deletedAt: new Date() } });
+            const cache = getTenantCache?.();
+            if (cache)
+                cache.delete(tenantId);
+        },
+        async getTenant(tenantId) {
+            const Tenant = getTenantModel(conn);
+            const doc = await Tenant.findOne({ tenantId, deletedAt: null }).lean();
+            if (!doc)
+                return null;
+            return {
+                tenantId: doc.tenantId,
+                displayName: doc.displayName,
+                config: doc.config,
+                createdAt: doc.createdAt,
+            };
+        },
+        async listTenants() {
+            const Tenant = getTenantModel(conn);
+            const docs = await Tenant.find({ deletedAt: null }).lean();
+            return docs.map(doc => ({
+                tenantId: doc.tenantId,
+                displayName: doc.displayName,
+                config: doc.config,
+                createdAt: doc.createdAt,
+            }));
+        },
+    };
+}

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

@@ -1,6 +1,6 @@
-import type { Context } from "hono";
-import type { AppEnv } from "./context";
-import type { StorageAdapter, UploadResult } from "./storageAdapter";
+import type { StorageAdapter, UploadResult } from '../lib/storageAdapter';
+import type { Context } from 'hono';
+import type { AppEnv } from '../../../packages/bunshot-core/src/index.js';
 export interface UploadOpts {
     field?: string | string[];
     maxFileSize?: number;
@@ -13,23 +13,28 @@ export interface UploadOpts {
     }) => string;
     tenantScopedKeys?: boolean;
 }
-export declare const setStorageAdapter: (adapter: StorageAdapter) => void;
-export declare const getStorageAdapter: () => StorageAdapter | null;
-export declare const setUploadConfig: (config: UploadOpts) => void;
-export declare const getUploadConfig: () => UploadOpts;
+type UploadCarrier = object;
+export declare const getStorageAdapter: (input: UploadCarrier) => StorageAdapter | null;
+export declare const getUploadConfig: (input: UploadCarrier) => UploadOpts;
 export declare const generateUploadKey: (file: File, ctx: {
     userId?: string;
     tenantId?: string;
-}, opts?: UploadOpts) => string;
+}, opts?: UploadOpts, input?: UploadCarrier) => string;
+export declare const generateUploadKeyFromFilename: (filename: string | undefined, ctx: {
+    userId?: string;
+    tenantId?: string;
+}, opts?: UploadOpts, input?: UploadCarrier) => string;
 export declare const validateFile: (file: File, opts: {
     maxFileSize?: number;
     allowedMimeTypes?: string[];
-}) => string | null;
+}, input?: UploadCarrier) => string | null;
 export declare const processUpload: (file: File, opts: UploadOpts & {
     ctx?: {
         userId?: string;
         tenantId?: string;
     };
     bucket?: string;
+    carrier?: object;
 }) => Promise<UploadResult>;
 export declare const parseUpload: (c: Context<AppEnv>, opts?: UploadOpts) => Promise<UploadResult[]>;
+export {};

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

@@ -0,0 +1,132 @@
+import { extname } from 'node:path';
+import { HttpError, resolveContext } from '../../../packages/bunshot-core/src/index.js';
+function getUploadState(input) {
+    const ctx = resolveContext(input);
+    const state = ctx.upload;
+    if (!state)
+        return { adapter: null, config: {} };
+    return {
+        adapter: state.adapter ?? null,
+        config: { ...state.config },
+    };
+}
+export const getStorageAdapter = (input) => getUploadState(input).adapter;
+export const getUploadConfig = (input) => getUploadState(input).config;
+function mergeUploadConfig(input, opts) {
+    const base = input ? getUploadConfig(input) : {};
+    return { ...base, ...opts };
+}
+export const generateUploadKey = (file, ctx, opts, input) => {
+    const merged = mergeUploadConfig(input, opts);
+    if (merged.generateKey)
+        return merged.generateKey(file, ctx);
+    const rawExt = extname(file.name);
+    const ext = /^\.[a-zA-Z0-9]{1,10}$/.test(rawExt) ? rawExt : '';
+    const uuid = crypto.randomUUID();
+    const prefix = merged.keyPrefix ?? 'uploads/';
+    const tenantPrefix = merged.tenantScopedKeys && ctx.tenantId ? `${ctx.tenantId}/` : '';
+    return `${prefix}${tenantPrefix}${uuid}${ext}`;
+};
+export const generateUploadKeyFromFilename = (filename, ctx, opts, input) => {
+    const merged = mergeUploadConfig(input, opts);
+    if (merged.generateKey) {
+        const stub = new File([], filename ?? 'upload');
+        return merged.generateKey(stub, ctx);
+    }
+    const rawExt = filename ? extname(filename) : '';
+    const ext = /^\.[a-zA-Z0-9]{1,10}$/.test(rawExt) ? rawExt : '';
+    const uuid = crypto.randomUUID();
+    const prefix = merged.keyPrefix ?? 'uploads/';
+    const tenantPrefix = merged.tenantScopedKeys && ctx.tenantId ? `${ctx.tenantId}/` : '';
+    return `${prefix}${tenantPrefix}${uuid}${ext}`;
+};
+const mimeMatches = (mimeType, pattern) => {
+    if (pattern.endsWith('/*')) {
+        return mimeType.startsWith(pattern.slice(0, -1));
+    }
+    return mimeType === pattern;
+};
+export const validateFile = (file, opts, input) => {
+    const merged = mergeUploadConfig(input, opts);
+    const maxFileSize = merged.maxFileSize ?? 10 * 1024 * 1024;
+    if (file.size > maxFileSize) {
+        return `File "${file.name}" exceeds maximum size of ${maxFileSize} bytes`;
+    }
+    const allowedMimeTypes = merged.allowedMimeTypes;
+    if (allowedMimeTypes && allowedMimeTypes.length > 0) {
+        const allowed = allowedMimeTypes.some(pattern => mimeMatches(file.type, pattern));
+        if (!allowed) {
+            return `File "${file.name}" has disallowed MIME type "${file.type}"`;
+        }
+    }
+    return null;
+};
+export const processUpload = async (file, opts) => {
+    const carrier = opts.carrier;
+    const adapter = carrier ? getStorageAdapter(carrier) : null;
+    if (!adapter)
+        throw new HttpError(500, 'No storage adapter configured');
+    const validationError = validateFile(file, opts, carrier);
+    if (validationError)
+        throw new HttpError(400, validationError);
+    const key = generateUploadKey(file, opts.ctx ?? {}, opts, carrier);
+    const { url } = await adapter.put(key, file, {
+        mimeType: file.type,
+        size: file.size,
+        bucket: opts.bucket,
+    });
+    if (carrier) {
+        const { registerUpload } = await import('../lib/uploadRegistry');
+        await registerUpload({
+            key,
+            ownerUserId: opts.ctx?.userId,
+            tenantId: opts.ctx?.tenantId,
+            mimeType: file.type,
+            bucket: opts.bucket,
+            createdAt: Date.now(),
+        }, carrier);
+    }
+    return {
+        key,
+        originalName: file.name,
+        mimeType: file.type,
+        size: file.size,
+        ...(url !== undefined ? { url } : {}),
+    };
+};
+export const parseUpload = async (c, opts) => {
+    const bunshotCtx = c.get('bunshotCtx');
+    const merged = mergeUploadConfig(bunshotCtx, opts);
+    const fields = merged.field
+        ? Array.isArray(merged.field)
+            ? merged.field
+            : [merged.field]
+        : ['file'];
+    const maxFiles = merged.maxFiles ?? 10;
+    const body = await c.req.parseBody({ all: true });
+    const results = [];
+    const userId = c.get('authUserId') ?? undefined;
+    const tenantId = c.get('tenantId') ?? undefined;
+    const bucket = c.get('uploadBucket');
+    for (const field of fields) {
+        const raw = body[field];
+        if (!raw)
+            continue;
+        const files = Array.isArray(raw) ? raw : [raw];
+        for (const f of files) {
+            if (!(f instanceof File))
+                continue;
+            if (results.length >= maxFiles) {
+                throw new HttpError(400, `Too many files. Maximum is ${maxFiles}`);
+            }
+            const result = await processUpload(f, {
+                ...merged,
+                ctx: { userId, tenantId },
+                bucket: bucket ?? undefined,
+                carrier: bunshotCtx,
+            });
+            results.push(result);
+        }
+    }
+    return results;
+};

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

@@ -0,0 +1,23 @@
+import type { UploadRecord } from '../../../packages/bunshot-core/src/index.js';
+export type { UploadRecord };
+/**
+ * Store a new upload record. Keyed by the storage key.
+ *
+ * @param record - The upload record to store
+ * @param app - The Hono app instance (required — used to resolve the context)
+ */
+export declare const registerUpload: (record: UploadRecord, app: object) => Promise<void>;
+/**
+ * Retrieve an upload record by key. Returns null if not found.
+ *
+ * @param key - The storage key
+ * @param app - The Hono app instance (required — used to resolve the context)
+ */
+export declare const getUploadRecord: (key: string, app: object) => Promise<UploadRecord | null>;
+/**
+ * Delete an upload record by key. Returns true if it existed.
+ *
+ * @param key - The storage key
+ * @param app - The Hono app instance (required — used to resolve the context)
+ */
+export declare const deleteUploadRecord: (key: string, app: object) => Promise<boolean>;

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

@@ -0,0 +1,34 @@
+// ---------------------------------------------------------------------------
+// Upload Registry — thin wrappers that consume repositories from context
+// ---------------------------------------------------------------------------
+import { resolveContext } from '../../../packages/bunshot-core/src/index.js';
+/**
+ * Store a new upload record. Keyed by the storage key.
+ *
+ * @param record - The upload record to store
+ * @param app - The Hono app instance (required — used to resolve the context)
+ */
+export const registerUpload = async (record, app) => {
+    const ctx = resolveContext(app);
+    await ctx.persistence.uploadRegistry.register(record);
+};
+/**
+ * Retrieve an upload record by key. Returns null if not found.
+ *
+ * @param key - The storage key
+ * @param app - The Hono app instance (required — used to resolve the context)
+ */
+export const getUploadRecord = async (key, app) => {
+    const ctx = resolveContext(app);
+    return ctx.persistence.uploadRegistry.get(key);
+};
+/**
+ * Delete an upload record by key. Returns true if it existed.
+ *
+ * @param key - The storage key
+ * @param app - The Hono app instance (required — used to resolve the context)
+ */
+export const deleteUploadRecord = async (key, app) => {
+    const ctx = resolveContext(app);
+    return ctx.persistence.uploadRegistry.delete(key);
+};

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

@@ -1,2 +1,2 @@
-import { z } from "zod";
+import { z } from 'zod';
 export declare const validate: <T extends z.ZodType>(schema: T, req: Request) => Promise<z.output<T>>;

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

@@ -1,5 +1,5 @@
-import { z } from "zod";
-import { ValidationError } from "./HttpError";
+import { z } from 'zod';
+import { ValidationError } from '../../../packages/bunshot-core/src/index.js';
 export const validate = async (schema, req) => {
     try {
         const body = await req.json();

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

@@ -0,0 +1,19 @@
+import type { ServerWebSocket } from 'bun';
+import type { WsState } from '../../../packages/bunshot-core/src/index.js';
+type WithRooms = {
+    rooms: Set<string>;
+};
+type WithSocketId = {
+    id: string;
+    endpoint: string;
+} & WithRooms;
+type RoomGuard<T extends WithRooms> = (ws: ServerWebSocket<T>, room: string) => boolean | Promise<boolean>;
+export declare const publish: (state: WsState, endpoint: string, room: string, data: unknown) => void;
+export declare const getRooms: (state: WsState, endpoint: string) => string[];
+export declare const getRoomSubscribers: (state: WsState, endpoint: string, room: string) => string[];
+export declare const handleRoomActions: <T extends WithSocketId>(state: WsState, ws: ServerWebSocket<T>, message: string | Buffer, onSubscribe?: RoomGuard<T>) => Promise<boolean>;
+export declare const subscribe: <T extends WithSocketId>(state: WsState, ws: ServerWebSocket<T>, room: string) => void;
+export declare const unsubscribe: <T extends WithSocketId>(state: WsState, ws: ServerWebSocket<T>, room: string) => void;
+export declare const getSubscriptions: <T extends WithRooms>(ws: ServerWebSocket<T>) => string[];
+export declare const cleanupSocket: <T extends WithSocketId>(state: WsState, ws: ServerWebSocket<T>) => void;
+export {};

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

@@ -0,0 +1,130 @@
+import { wsEndpointKey } from './wsNamespace';
+import { addPresence, cleanupPresence, removePresence } from './wsPresence';
+const MAX_ROOM_ACTION_SIZE = 4096;
+function isValidRoomName(room) {
+    return typeof room === 'string' && /^[a-zA-Z0-9_:./\-]{1,128}$/.test(room);
+}
+export const publish = (state, endpoint, room, data) => {
+    const key = wsEndpointKey(endpoint, room);
+    const msg = JSON.stringify(data);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    state.server?.publish?.(key, msg);
+    if (state.transport) {
+        state.transport
+            .publish(endpoint, room, msg, state.instanceId)
+            .catch(e => console.error('[ws-transport] publish error:', e));
+    }
+};
+export const getRooms = (state, endpoint) => {
+    const prefix = encodeURIComponent(endpoint) + ':';
+    const rooms = [];
+    for (const key of state.roomRegistry.keys()) {
+        if (key.startsWith(prefix)) {
+            const colonIdx = key.indexOf(':');
+            rooms.push(decodeURIComponent(key.slice(colonIdx + 1)));
+        }
+    }
+    return rooms;
+};
+export const getRoomSubscribers = (state, endpoint, room) => [
+    ...(state.roomRegistry.get(wsEndpointKey(endpoint, room)) ?? []),
+];
+export const handleRoomActions = async (state, ws, message, onSubscribe) => {
+    try {
+        const raw = typeof message === 'string' ? message : Buffer.from(message).toString();
+        if (raw.length > MAX_ROOM_ACTION_SIZE)
+            return false;
+        const data = JSON.parse(raw);
+        if (data.action === 'subscribe' && typeof data.room === 'string') {
+            if (!isValidRoomName(data.room))
+                return true;
+            if (onSubscribe) {
+                let allowed;
+                try {
+                    allowed = await onSubscribe(ws, data.room);
+                }
+                catch (e) {
+                    console.error(`[ws] onRoomSubscribe guard error for room "${data.room}":`, e);
+                    allowed = false;
+                }
+                if (!allowed) {
+                    ws.send(JSON.stringify({ event: 'subscribe_denied', room: data.room }));
+                    return true;
+                }
+            }
+            subscribe(state, ws, data.room);
+            ws.send(JSON.stringify({ event: 'subscribed', room: data.room }));
+            return true;
+        }
+        if (data.action === 'unsubscribe' && typeof data.room === 'string') {
+            if (!isValidRoomName(data.room))
+                return true;
+            unsubscribe(state, ws, data.room);
+            ws.send(JSON.stringify({ event: 'unsubscribed', room: data.room }));
+            return true;
+        }
+    }
+    catch {
+        // not JSON
+    }
+    return false;
+};
+export const subscribe = (state, ws, room) => {
+    const key = wsEndpointKey(ws.data.endpoint, room);
+    ws.subscribe(key);
+    ws.data.rooms.add(room);
+    if (!state.roomRegistry.has(key))
+        state.roomRegistry.set(key, new Set());
+    state.roomRegistry.get(key).add(ws.data.id);
+    if (state.presenceEnabled) {
+        const result = addPresence(state, ws.data.id, ws.data.endpoint, room);
+        if (result?.isNewUser) {
+            publish(state, ws.data.endpoint, room, {
+                event: 'presence_join',
+                room,
+                userId: result.userId,
+            });
+        }
+    }
+};
+export const unsubscribe = (state, ws, room) => {
+    const key = wsEndpointKey(ws.data.endpoint, room);
+    ws.unsubscribe(key);
+    ws.data.rooms.delete(room);
+    const ids = state.roomRegistry.get(key);
+    if (ids) {
+        ids.delete(ws.data.id);
+        if (ids.size === 0)
+            state.roomRegistry.delete(key);
+    }
+    if (state.presenceEnabled) {
+        const result = removePresence(state, ws.data.id, ws.data.endpoint, room);
+        if (result?.isLastSocket) {
+            publish(state, ws.data.endpoint, room, {
+                event: 'presence_leave',
+                room,
+                userId: result.userId,
+            });
+        }
+    }
+};
+export const getSubscriptions = (ws) => [
+    ...ws.data.rooms,
+];
+export const cleanupSocket = (state, ws) => {
+    if (state.presenceEnabled) {
+        const departed = cleanupPresence(state, ws.data.id, ws.data.endpoint, ws.data.rooms);
+        for (const { room, userId } of departed) {
+            publish(state, ws.data.endpoint, room, { event: 'presence_leave', room, userId });
+        }
+    }
+    for (const room of ws.data.rooms) {
+        const key = wsEndpointKey(ws.data.endpoint, room);
+        const ids = state.roomRegistry.get(key);
+        if (ids) {
+            ids.delete(ws.data.id);
+            if (ids.size === 0)
+                state.roomRegistry.delete(key);
+        }
+    }
+};

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

@@ -0,0 +1,12 @@
+import type { ServerWebSocket } from 'bun';
+import type { WsState } from '../../../packages/bunshot-core/src/index.js';
+export interface HeartbeatConfig {
+    intervalMs?: number;
+    timeoutMs?: number;
+}
+export declare const registerSocket: (state: WsState, ws: ServerWebSocket<any>, socketId: string, endpoint: string) => void;
+export declare const deregisterSocket: (state: WsState, id: string) => void;
+export declare const handlePong: (state: WsState, id: string) => void;
+export declare const startHeartbeat: (state: WsState, configs: Record<string, HeartbeatConfig | boolean>) => void;
+export declare const stopHeartbeat: (state: WsState) => void;
+export declare const clearHeartbeatState: (state: WsState) => void;

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

@@ -0,0 +1,53 @@
+const DEFAULT_INTERVAL_MS = 30_000;
+const DEFAULT_TIMEOUT_MS = 10_000;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const registerSocket = (state, ws, socketId, endpoint) => {
+    const timeoutMs = state.heartbeatEndpointConfigs.get(endpoint)?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    state.heartbeatSockets.set(socketId, { ws, endpoint, timeoutAt: Date.now() + timeoutMs });
+};
+export const deregisterSocket = (state, id) => {
+    state.heartbeatSockets.delete(id);
+};
+export const handlePong = (state, id) => {
+    const entry = state.heartbeatSockets.get(id);
+    if (!entry)
+        return;
+    const timeoutMs = state.heartbeatEndpointConfigs.get(entry.endpoint)?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    entry.timeoutAt = Date.now() + timeoutMs;
+};
+export const startHeartbeat = (state, configs) => {
+    if (state.heartbeatTimer)
+        return;
+    for (const [endpoint, cfg] of Object.entries(configs)) {
+        const opts = typeof cfg === 'object' ? cfg : {};
+        state.heartbeatEndpointConfigs.set(endpoint, {
+            intervalMs: opts.intervalMs ?? DEFAULT_INTERVAL_MS,
+            timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        });
+    }
+    const minInterval = Math.min(...[...state.heartbeatEndpointConfigs.values()].map(c => c.intervalMs ?? DEFAULT_INTERVAL_MS));
+    state.heartbeatTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [, entry] of state.heartbeatSockets) {
+            if (now >= entry.timeoutAt) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                entry.ws.close(1001, 'Heartbeat timeout');
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                entry.ws.ping();
+            }
+        }
+    }, minInterval);
+};
+export const stopHeartbeat = (state) => {
+    if (state.heartbeatTimer) {
+        clearInterval(state.heartbeatTimer);
+        state.heartbeatTimer = null;
+    }
+};
+export const clearHeartbeatState = (state) => {
+    stopHeartbeat(state);
+    state.heartbeatSockets.clear();
+    state.heartbeatEndpointConfigs.clear();
+};