@spfn/core 0.2.0-beta.45 → 0.2.0-beta.47

package/dist/{router-Di7ENoah.d.ts → token-manager-DSwIDD-_.d.ts}

@@ -148,4 +148,119 @@ type InferEventPayloads<T extends EventRouterDef<any>> = T['_types'];
  */
 declare function defineEventRouter<TEvents extends Record<string, EventDef<any>>>(events: TEvents): EventRouterDef<TEvents>;
 
-export { type EventRouterDef as E, type InferEventNames as I, type JobQueueSender as J, type PubSubCache as P, type EventDef as a, type InferEventPayload as b, type InferEventPayloads as c, defineEventRouter as d, type EventHandler as e, type InferEventPayload$1 as f };
+/**
+ * SSE Token Manager
+ *
+ * Auth-agnostic token issuance and verification for SSE connections.
+ * Issues one-time-use tokens with TTL for Token Exchange pattern.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SSETokenManager({ ttl: 30000 });
+ *
+ * // Issue token for authenticated user
+ * const token = await manager.issue('user-123');
+ *
+ * // Verify and consume token (one-time use)
+ * const subject = await manager.verify(token); // 'user-123'
+ * const again = await manager.verify(token);   // null (already consumed)
+ *
+ * // Cleanup on shutdown
+ * manager.destroy();
+ * ```
+ */
+/**
+ * Minimal cache client interface (compatible with ioredis Redis | Cluster)
+ */
+type CacheClient = {
+    set(key: string, value: string, ...args: any[]): Promise<any>;
+    getdel?(key: string): Promise<string | null>;
+    get(key: string): Promise<string | null>;
+    del(key: string | string[]): Promise<number>;
+};
+/**
+ * Stored SSE token data
+ */
+interface SSEToken {
+    token: string;
+    subject: string;
+    expiresAt: number;
+}
+/**
+ * Token storage interface
+ *
+ * Implement this for custom storage backends (e.g., Redis for multi-instance).
+ */
+interface SSETokenStore {
+    /** Store a token */
+    set(token: string, data: SSEToken): Promise<void>;
+    /** Get and delete a token (one-time use) */
+    consume(token: string): Promise<SSEToken | null>;
+    /** Remove expired tokens */
+    cleanup(): Promise<void>;
+}
+/**
+ * SSETokenManager configuration
+ */
+interface SSETokenManagerConfig {
+    /**
+     * Token time-to-live in milliseconds
+     * @default 30000
+     */
+    ttl?: number;
+    /**
+     * Custom token store (default: in-memory Map)
+     */
+    store?: SSETokenStore;
+    /**
+     * Cleanup interval in milliseconds
+     * @default 60000
+     */
+    cleanupInterval?: number;
+}
+/**
+ * Redis/Valkey-backed token store for multi-instance deployments.
+ *
+ * Uses SET EX for automatic TTL expiry and GETDEL for atomic one-time consumption.
+ * No cleanup needed — Redis handles expiration automatically.
+ *
+ * @example
+ * ```typescript
+ * import { getCache } from '@spfn/core/cache';
+ *
+ * const cache = getCache();
+ * if (cache) {
+ *     const store = new CacheTokenStore(cache);
+ *     const manager = new SSETokenManager({ store });
+ * }
+ * ```
+ */
+declare class CacheTokenStore implements SSETokenStore {
+    private cache;
+    private prefix;
+    constructor(cache: CacheClient);
+    set(token: string, data: SSEToken): Promise<void>;
+    consume(token: string): Promise<SSEToken | null>;
+    cleanup(): Promise<void>;
+}
+declare class SSETokenManager {
+    private store;
+    private ttl;
+    private cleanupTimer;
+    constructor(config?: SSETokenManagerConfig);
+    /**
+     * Issue a new one-time-use token for the given subject
+     */
+    issue(subject: string): Promise<string>;
+    /**
+     * Verify and consume a token
+     * @returns subject string if valid, null if invalid/expired/already consumed
+     */
+    verify(token: string): Promise<string | null>;
+    /**
+     * Cleanup timer and resources
+     */
+    destroy(): void;
+}
+
+export { CacheTokenStore as C, type EventRouterDef as E, type InferEventNames as I, type JobQueueSender as J, type PubSubCache as P, SSETokenManager as S, type EventDef as a, type InferEventPayload as b, type InferEventPayloads as c, defineEventRouter as d, type EventHandler as e, type InferEventPayload$1 as f, type SSEToken as g, type SSETokenStore as h, type SSETokenManagerConfig as i };

package/dist/{types-DKQ90YL7.d.ts → types-BOOUBu9l.d.ts}

@@ -1,120 +1,5 @@
 import { Context } from 'hono';
-import { E as EventRouterDef, I as InferEventNames, b as InferEventPayload } from './router-Di7ENoah.js';
-
-/**
- * SSE Token Manager
- *
- * Auth-agnostic token issuance and verification for SSE connections.
- * Issues one-time-use tokens with TTL for Token Exchange pattern.
- *
- * @example
- * ```typescript
- * const manager = new SSETokenManager({ ttl: 30000 });
- *
- * // Issue token for authenticated user
- * const token = await manager.issue('user-123');
- *
- * // Verify and consume token (one-time use)
- * const subject = await manager.verify(token); // 'user-123'
- * const again = await manager.verify(token);   // null (already consumed)
- *
- * // Cleanup on shutdown
- * manager.destroy();
- * ```
- */
-/**
- * Minimal cache client interface (compatible with ioredis Redis | Cluster)
- */
-type CacheClient = {
-    set(key: string, value: string, ...args: any[]): Promise<any>;
-    getdel?(key: string): Promise<string | null>;
-    get(key: string): Promise<string | null>;
-    del(key: string | string[]): Promise<number>;
-};
-/**
- * Stored SSE token data
- */
-interface SSEToken {
-    token: string;
-    subject: string;
-    expiresAt: number;
-}
-/**
- * Token storage interface
- *
- * Implement this for custom storage backends (e.g., Redis for multi-instance).
- */
-interface SSETokenStore {
-    /** Store a token */
-    set(token: string, data: SSEToken): Promise<void>;
-    /** Get and delete a token (one-time use) */
-    consume(token: string): Promise<SSEToken | null>;
-    /** Remove expired tokens */
-    cleanup(): Promise<void>;
-}
-/**
- * SSETokenManager configuration
- */
-interface SSETokenManagerConfig {
-    /**
-     * Token time-to-live in milliseconds
-     * @default 30000
-     */
-    ttl?: number;
-    /**
-     * Custom token store (default: in-memory Map)
-     */
-    store?: SSETokenStore;
-    /**
-     * Cleanup interval in milliseconds
-     * @default 60000
-     */
-    cleanupInterval?: number;
-}
-/**
- * Redis/Valkey-backed token store for multi-instance deployments.
- *
- * Uses SET EX for automatic TTL expiry and GETDEL for atomic one-time consumption.
- * No cleanup needed — Redis handles expiration automatically.
- *
- * @example
- * ```typescript
- * import { getCache } from '@spfn/core/cache';
- *
- * const cache = getCache();
- * if (cache) {
- *     const store = new CacheTokenStore(cache);
- *     const manager = new SSETokenManager({ store });
- * }
- * ```
- */
-declare class CacheTokenStore implements SSETokenStore {
-    private cache;
-    private prefix;
-    constructor(cache: CacheClient);
-    set(token: string, data: SSEToken): Promise<void>;
-    consume(token: string): Promise<SSEToken | null>;
-    cleanup(): Promise<void>;
-}
-declare class SSETokenManager {
-    private store;
-    private ttl;
-    private cleanupTimer;
-    constructor(config?: SSETokenManagerConfig);
-    /**
-     * Issue a new one-time-use token for the given subject
-     */
-    issue(subject: string): Promise<string>;
-    /**
-     * Verify and consume a token
-     * @returns subject string if valid, null if invalid/expired/already consumed
-     */
-    verify(token: string): Promise<string | null>;
-    /**
-     * Cleanup timer and resources
-     */
-    destroy(): void;
-}
+import { h as SSETokenStore, S as SSETokenManager, E as EventRouterDef, I as InferEventNames, b as InferEventPayload } from './token-manager-DSwIDD-_.js';
 
 /**
  * SSE Types
@@ -369,4 +254,4 @@ type SSEConnectionState = 'connecting' | 'open' | 'closed' | 'error';
  */
 type SSEUnsubscribe = () => void;
 
-export { CacheTokenStore as C, type SSEHandlerConfig as S, type SSEAuthConfig as a, SSETokenManager as b, type SSEToken as c, type SSETokenStore as d, type SSETokenManagerConfig as e, type SSEMessage as f, type SSEHandlerAuthConfig as g, type SSEClientConfig as h, type SSEEventHandler as i, type SSEEventHandlers as j, type SSESubscribeOptions as k, type SSEConnectionState as l, type SSEUnsubscribe as m };
+export type { SSEHandlerConfig as S, SSEAuthConfig as a, SSEMessage as b, SSEHandlerAuthConfig as c, SSEClientConfig as d, SSEEventHandler as e, SSEEventHandlers as f, SSESubscribeOptions as g, SSEConnectionState as h, SSEUnsubscribe as i };

package/dist/types-FuJb3yrP.d.ts

@@ -0,0 +1,151 @@
+import { Context } from 'hono';
+import { a as EventDef, E as EventRouterDef, h as SSETokenStore, S as SSETokenManager, I as InferEventNames, b as InferEventPayload } from './token-manager-DSwIDD-_.js';
+
+/**
+ * WebSocket Types
+ */
+
+/**
+ * WebSocket Router Definition
+ *
+ * Extends EventRouterDef with client→server message handlers.
+ */
+interface WSRouterDef<TEvents extends Record<string, EventDef<any>>, TMessages extends WSMessageHandlers = WSMessageHandlers> extends EventRouterDef<TEvents> {
+    messages: TMessages;
+}
+/**
+ * Low-level WS connection handle passed to message handlers
+ */
+interface WSRawConnection {
+    send(type: string, payload: unknown): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Context passed to each client→server message handler
+ */
+interface WSMessageContext<TPayload = unknown> {
+    payload: TPayload;
+    subject?: string;
+    ws: WSRawConnection;
+}
+/**
+ * Single message handler function
+ */
+type WSMessageHandlerFn<TPayload = unknown> = (ctx: WSMessageContext<TPayload>) => void | Promise<void>;
+/**
+ * Map of message type name → handler
+ */
+type WSMessageHandlers = Record<string, WSMessageHandlerFn<any>>;
+/**
+ * WebSocket auth configuration (internal, non-generic)
+ */
+interface WSHandlerAuthConfig {
+    enabled?: boolean;
+    tokenTtl?: number;
+    store?: SSETokenStore;
+    tokenManager?: SSETokenManager | (() => SSETokenManager);
+    /**
+     * Extract subject from Hono context (used on token-issue endpoint)
+     * @default (c) => c.get('auth')?.userId ?? null
+     */
+    getSubject?: (c: Context) => string | null;
+    /**
+     * Authorize event subscriptions on connect
+     * Return allowed events subset. Empty array = 403 rejection.
+     */
+    authorize?: (subject: string, events: string[]) => Promise<string[]> | string[];
+    /**
+     * Per-event payload filter (called on every emission)
+     * Return false to skip sending the event to this client.
+     */
+    filter?: Record<string, (subject: string, payload: unknown) => boolean>;
+}
+/**
+ * WebSocket auth configuration (user-facing, generic)
+ */
+interface WSAuthConfig<TRouter extends WSRouterDef<any, any>> {
+    enabled?: boolean;
+    tokenTtl?: number;
+    store?: SSETokenStore;
+    tokenManager?: SSETokenManager | (() => SSETokenManager);
+    getSubject?: (c: Context) => string | null;
+    authorize?: (subject: string, events: InferEventNames<TRouter>[]) => Promise<InferEventNames<TRouter>[]> | InferEventNames<TRouter>[];
+    filter?: {
+        [K in InferEventNames<TRouter>]?: (subject: string, payload: InferEventPayload<TRouter, K>) => boolean;
+    };
+}
+/**
+ * Configuration for the WebSocket server handler
+ */
+interface WSHandlerConfig {
+    /**
+     * Keep-alive ping interval in ms
+     * @default 30000
+     */
+    pingInterval?: number;
+    /**
+     * Authentication and authorization configuration
+     */
+    auth?: WSHandlerAuthConfig;
+}
+/**
+ * WebSocket client configuration
+ */
+interface WSClientConfig {
+    /**
+     * Backend API host URL (ws:// or wss://)
+     * @default derived from NEXT_PUBLIC_SPFN_API_URL
+     */
+    host?: string;
+    /**
+     * WS endpoint pathname
+     * @default '/ws'
+     */
+    pathname?: string;
+    /**
+     * Auto reconnect on disconnect
+     * @default true
+     */
+    reconnect?: boolean;
+    /**
+     * Reconnect delay in ms
+     * @default 3000
+     */
+    reconnectDelay?: number;
+    /**
+     * Maximum reconnect attempts (0 = infinite)
+     * @default 0
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Acquire a one-time token before connecting
+     */
+    acquireToken?: () => Promise<string>;
+}
+/**
+ * WebSocket connection state
+ */
+type WSConnectionState = 'connecting' | 'open' | 'closed' | 'error';
+/**
+ * Event handlers map for WSRouterDef
+ */
+type WSEventHandlers<TRouter extends WSRouterDef<any, any>> = {
+    [K in InferEventNames<TRouter>]?: (payload: InferEventPayload<TRouter, K>) => void;
+};
+/**
+ * Subscribe options
+ */
+interface WSSubscribeOptions<TRouter extends WSRouterDef<any, any>> {
+    events: InferEventNames<TRouter>[];
+    handlers: WSEventHandlers<TRouter>;
+    onOpen?: () => void;
+    onError?: (error: Event) => void;
+    onClose?: () => void;
+    onReconnect?: (attempt: number) => void;
+}
+/**
+ * Unsubscribe function
+ */
+type WSUnsubscribe = () => void;
+
+export type { WSRouterDef as W, WSHandlerConfig as a, WSMessageHandlers as b, WSAuthConfig as c, WSHandlerAuthConfig as d, WSMessageContext as e, WSMessageHandlerFn as f, WSRawConnection as g, WSClientConfig as h, WSConnectionState as i, WSEventHandlers as j, WSSubscribeOptions as k, WSUnsubscribe as l };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spfn/core",
-  "version": "0.2.0-beta.45",
+  "version": "0.2.0-beta.47",
   "description": "SPFN Framework Core - File-based routing, transactions, repository pattern",
   "type": "module",
   "exports": {
@@ -98,6 +98,16 @@
       "types": "./dist/event/sse/client.d.ts",
       "import": "./dist/event/sse/client.js",
       "require": "./dist/event/sse/client.js"
+    },
+    "./event/ws": {
+      "types": "./dist/event/ws/index.d.ts",
+      "import": "./dist/event/ws/index.js",
+      "require": "./dist/event/ws/index.js"
+    },
+    "./event/ws/client": {
+      "types": "./dist/event/ws/client.d.ts",
+      "import": "./dist/event/ws/client.js",
+      "require": "./dist/event/ws/client.js"
     }
   },
   "keywords": [
@@ -156,11 +166,13 @@
     "zod": "^4.1.11"
   },
   "optionalDependencies": {
-    "ioredis": "^5.4.1"
+    "ioredis": "^5.4.1",
+    "ws": "^8.0.0"
   },
   "devDependencies": {
     "@types/micromatch": "^4.0.9",
     "@types/node": "^20.11.0",
+    "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.0.6",
     "drizzle-kit": "^0.31.6",
     "madge": "^8.0.0",