@spfn/core 0.2.0-beta.5 → 0.2.0-beta.50

package/dist/{router-Di7ENoah.d.ts → token-manager-CyG7la3p.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(...keys: 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-D_N_U-Py.d.ts → types-7Mhoxnnt.d.ts}

@@ -2,6 +2,20 @@ import { TSchema, Static } from '@sinclair/typebox';
 import { ErrorRegistry, ErrorRegistryInput } from '@spfn/core/errors';
 import { RouteDef, RouteInput } from '@spfn/core/route';
 
+/**
+ * Convert File types in schema to actual File for client usage
+ *
+ * TypeBox File schemas become actual File objects on the client side.
+ */
+type ConvertFileTypes<T> = T extends File ? File : T extends File[] ? File[] : T;
+/**
+ * Extract form data input type with File support
+ *
+ * Maps schema types to runtime types, converting FileSchema to File.
+ */
+type FormDataInput<T> = {
+    [K in keyof T]: ConvertFileTypes<T[K]>;
+};
 /**
  * Extract structured input from RouteInput
  *
@@ -11,6 +25,7 @@ type StructuredInput<TInput extends RouteInput> = {
     params: TInput['params'] extends TSchema ? Static<TInput['params']> : {};
     query: TInput['query'] extends TSchema ? Static<TInput['query']> : {};
     body: TInput['body'] extends TSchema ? Static<TInput['body']> : {};
+    formData: TInput['formData'] extends TSchema ? FormDataInput<Static<TInput['formData']>> : {};
     headers: TInput['headers'] extends TSchema ? Static<TInput['headers']> : {};
     cookies: TInput['cookies'] extends TSchema ? Static<TInput['cookies']> : {};
 };
@@ -144,7 +159,7 @@ interface ApiConfig {
     /**
      * Request timeout in milliseconds
      *
-     * @default 30000
+     * @default env.SERVER_TIMEOUT (120000)
      */
     timeout?: number;
     /**
@@ -187,6 +202,11 @@ interface ApiConfig {
  * Per-call options
  */
 interface CallOptions {
+    /**
+     * Request timeout in milliseconds
+     * Overrides the global timeout set in ApiConfig
+     */
+    timeout?: number;
     /**
      * Additional headers for this request
      */

package/dist/types-C1jMLGwK.d.ts

@@ -0,0 +1,257 @@
+import { Context } from 'hono';
+import { h as SSETokenStore, S as SSETokenManager, E as EventRouterDef, I as InferEventNames, b as InferEventPayload } from './token-manager-CyG7la3p.js';
+
+/**
+ * SSE Types
+ *
+ * Type definitions for Server-Sent Events
+ */
+
+/**
+ * SSE message sent from server
+ */
+interface SSEMessage<TEvent extends string = string, TPayload = unknown> {
+    /** Event name */
+    event: TEvent;
+    /** Event payload */
+    data: TPayload;
+    /** Optional message ID for reconnection */
+    id?: string;
+}
+/**
+ * SSE auth configuration (internal, non-generic)
+ *
+ * Stored in SSEHandlerConfig. Generic user-facing version is SSEAuthConfig.
+ */
+interface SSEHandlerAuthConfig {
+    /**
+     * Enable SSE token authentication
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Token TTL in milliseconds
+     * @default 30000
+     */
+    tokenTtl?: number;
+    /**
+     * Custom token store (e.g., Redis for multi-instance)
+     */
+    store?: SSETokenStore;
+    /**
+     * External token manager instance or lazy resolver.
+     *
+     * When provided, the SSE system uses this manager instead of creating its own.
+     * Useful for sharing a single token manager with auth package's one-time token system.
+     *
+     * Use a function when the manager is not available at module load time
+     * (e.g. initialized in a lifecycle hook that runs after config evaluation).
+     *
+     * @example
+     * ```typescript
+     * import { getOneTimeTokenManager } from '@spfn/auth/server';
+     *
+     * // Lazy resolver (recommended — avoids timing issues)
+     * .events(eventRouter, {
+     *     auth: {
+     *         enabled: true,
+     *         tokenManager: () => getOneTimeTokenManager(),
+     *     },
+     * })
+     * ```
+     */
+    tokenManager?: SSETokenManager | (() => SSETokenManager);
+    /**
+     * Extract subject (user ID) from Hono context
+     * @default (c) => c.get('auth')?.userId ?? null
+     */
+    getSubject?: (c: Context) => string | null;
+    /**
+     * Subscription authorization hook (called once on connect)
+     *
+     * Return allowed events subset. Empty array = 403 rejection.
+     */
+    authorize?: (subject: string, events: string[]) => Promise<string[]> | string[];
+    /**
+     * Per-event payload filter map (called on every event emission)
+     *
+     * Return false to skip sending the event to this user.
+     */
+    filter?: Record<string, (subject: string, payload: unknown) => boolean>;
+}
+/**
+ * SSE auth configuration (user-facing, generic)
+ *
+ * Provides type-safe event names and payload inference from EventRouter.
+ *
+ * @example
+ * ```typescript
+ * .events(eventRouter, {
+ *     auth: {
+ *         enabled: true,
+ *         authorize: async (subject, events) => {
+ *             // events: ('userCreated' | 'orderUpdated')[]
+ *             return events.filter(e => hasPermission(subject, e));
+ *         },
+ *         filter: {
+ *             orderUpdated: (subject, payload) => {
+ *                 // payload: { orderId: string; userId: string }
+ *                 return payload.userId === subject;
+ *             },
+ *         },
+ *     },
+ * })
+ * ```
+ */
+interface SSEAuthConfig<TRouter extends EventRouterDef<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;
+    };
+}
+/**
+ * SSE Handler configuration
+ */
+interface SSEHandlerConfig {
+    /**
+     * Keep-alive ping interval in milliseconds
+     * @default 30000
+     */
+    pingInterval?: number;
+    /**
+     * Custom headers for SSE response
+     */
+    headers?: Record<string, string>;
+    /**
+     * Authentication and authorization configuration
+     */
+    auth?: SSEHandlerAuthConfig;
+}
+/**
+ * SSE Client configuration
+ */
+interface SSEClientConfig {
+    /**
+     * Backend API host URL
+     * @default NEXT_PUBLIC_SPFN_API_URL || 'http://localhost:8790'
+     * @example 'http://localhost:8790'
+     * @example 'https://api.example.com'
+     */
+    host?: string;
+    /**
+     * SSE endpoint pathname
+     * @default '/events/stream'
+     */
+    pathname?: string;
+    /**
+     * Full URL (overrides host + pathname)
+     * @deprecated Use host and pathname instead
+     * @example 'http://localhost:8790/events/stream'
+     */
+    url?: string;
+    /**
+     * Auto reconnect on disconnect
+     * @default true
+     */
+    reconnect?: boolean;
+    /**
+     * Reconnect delay in milliseconds
+     * @default 3000
+     */
+    reconnectDelay?: number;
+    /**
+     * Maximum reconnect attempts (0 = infinite)
+     * @default 0
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Include credentials (cookies) in request
+     * @default false
+     */
+    withCredentials?: boolean;
+    /**
+     * Acquire a one-time SSE token before connecting.
+     *
+     * Called on every (re)connect. The returned token is appended
+     * to the SSE URL as `?token=...`.
+     *
+     * For automatic token acquisition via RPC proxy, use `createAuthSSEClient` instead.
+     *
+     * @example
+     * ```typescript
+     * // Recommended: use createAuthSSEClient for automatic token handling
+     * import { createAuthSSEClient } from '@spfn/core/event/sse/client';
+     * const client = createAuthSSEClient<EventRouter>();
+     *
+     * // Manual: provide acquireToken directly
+     * acquireToken: async () => {
+     *     const res = await fetch('/api/rpc/eventsToken', {
+     *         method: 'POST',
+     *         credentials: 'include',
+     *     });
+     *     const data = await res.json();
+     *     return data.token;
+     * }
+     * ```
+     */
+    acquireToken?: () => Promise<string>;
+}
+/**
+ * Event handler function
+ */
+type SSEEventHandler<TPayload> = (payload: TPayload) => void;
+/**
+ * Event handlers map for EventRouter
+ */
+type SSEEventHandlers<TRouter extends EventRouterDef<any>> = {
+    [K in InferEventNames<TRouter>]?: SSEEventHandler<InferEventPayload<TRouter, K>>;
+};
+/**
+ * Subscription options
+ */
+interface SSESubscribeOptions<TRouter extends EventRouterDef<any>> {
+    /**
+     * Events to subscribe
+     */
+    events: InferEventNames<TRouter>[];
+    /**
+     * Event handlers
+     */
+    handlers: SSEEventHandlers<TRouter>;
+    /**
+     * Called when connection opens
+     */
+    onOpen?: () => void;
+    /**
+     * Called on connection error
+     */
+    onError?: (error: Event) => void;
+    /**
+     * Called when connection is permanently closed
+     *
+     * Triggered when:
+     * - unsubscribe() is called
+     * - client.close() is called
+     * - Max reconnect attempts exceeded
+     */
+    onClose?: () => void;
+    /**
+     * Called when reconnecting
+     */
+    onReconnect?: (attempt: number) => void;
+}
+/**
+ * SSE connection state
+ */
+type SSEConnectionState = 'connecting' | 'open' | 'closed' | 'error';
+/**
+ * Unsubscribe function
+ */
+type SSEUnsubscribe = () => void;
+
+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-Cfj--lfr.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-CyG7la3p.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 };