@spfn/core 0.2.0-beta.8 → 0.3.0-beta.1

package/dist/token-manager-BT5EnUAR.d.ts

@@ -0,0 +1,278 @@
+import { TSchema } from '@sinclair/typebox';
+
+/**
+ * Event System Types
+ */
+
+/**
+ * Pub/Sub capable cache interface for multi-instance events
+ */
+interface PubSubCache {
+    /**
+     * Publish a message to a channel
+     */
+    publish(channel: string, message: unknown): Promise<void>;
+    /**
+     * Subscribe to a channel
+     */
+    subscribe(channel: string, handler: (message: unknown) => void | Promise<void>): Promise<void>;
+}
+/**
+ * Event handler function type
+ */
+type EventHandler<TPayload> = (payload: TPayload) => void | Promise<void>;
+/**
+ * Job queue sender function type (used by job module)
+ */
+type JobQueueSender = (queueName: string, payload: unknown) => Promise<void>;
+/**
+ * Event definition interface
+ */
+interface EventDef<TPayload = void> {
+    /**
+     * Unique event name
+     */
+    readonly name: string;
+    /**
+     * TypeBox payload schema (optional)
+     */
+    readonly schema?: TSchema;
+    /**
+     * Subscribe to this event (in-memory handler)
+     */
+    subscribe: (handler: EventHandler<TPayload>) => () => void;
+    /**
+     * Unsubscribe all handlers
+     */
+    unsubscribeAll: () => void;
+    /**
+     * Emit the event (triggers all subscribers and queued jobs)
+     */
+    emit: TPayload extends void ? () => Promise<void> : (payload: TPayload) => Promise<void>;
+    /**
+     * Enable cache-based pub/sub for multi-instance support
+     * Must await before emitting events to ensure subscription is ready
+     */
+    useCache: (cache: PubSubCache) => Promise<EventDef<TPayload>>;
+    /**
+     * Internal: Register a job queue to receive this event
+     * Called by job registration system
+     */
+    _registerJobQueue: (queueName: string, sender: JobQueueSender) => void;
+    /**
+     * Internal: Drop the cache binding (cache + subscribed flag).
+     * Called by the event cache transport on shutdown so a later useCache can
+     * rebind a fresh cache in the same process.
+     */
+    _resetCache: () => void;
+    /**
+     * Type inference helper
+     */
+    _payload: TPayload;
+}
+/**
+ * Infer payload type from EventDef
+ */
+type InferEventPayload$1<TEvent> = TEvent extends EventDef<infer TPayload> ? TPayload : never;
+
+/**
+ * Event Router
+ *
+ * Type-safe event router for SSE subscription
+ *
+ * @example
+ * ```typescript
+ * import { defineEvent, defineEventRouter } from '@spfn/core/event';
+ * import { Type } from '@sinclair/typebox';
+ *
+ * const userCreated = defineEvent('user.created', Type.Object({
+ *     userId: Type.String(),
+ * }));
+ *
+ * const orderPlaced = defineEvent('order.placed', Type.Object({
+ *     orderId: Type.String(),
+ *     amount: Type.Number(),
+ * }));
+ *
+ * export const eventRouter = defineEventRouter({
+ *     userCreated,
+ *     orderPlaced,
+ * });
+ *
+ * export type EventRouter = typeof eventRouter;
+ * ```
+ */
+
+/**
+ * Event Router Definition
+ */
+interface EventRouterDef<TEvents extends Record<string, EventDef<any>>> {
+    /**
+     * Event definitions
+     */
+    readonly events: TEvents;
+    /**
+     * Event names as array
+     */
+    readonly eventNames: (keyof TEvents)[];
+    /**
+     * Type inference helper - payload types by event name
+     */
+    readonly _types: {
+        [K in keyof TEvents]: TEvents[K]['_payload'];
+    };
+}
+/**
+ * Infer event names from EventRouter
+ */
+type InferEventNames<T> = T extends EventRouterDef<infer E> ? keyof E & string : never;
+/**
+ * Infer payload type for specific event
+ */
+type InferEventPayload<T extends EventRouterDef<any>, K extends InferEventNames<T>> = T['_types'][K];
+/**
+ * Infer all event payloads map
+ */
+type InferEventPayloads<T extends EventRouterDef<any>> = T['_types'];
+/**
+ * Define an event router for SSE subscription
+ *
+ * @example
+ * ```typescript
+ * export const eventRouter = defineEventRouter({
+ *     userCreated,
+ *     orderPlaced,
+ * });
+ *
+ * // Type inference
+ * type Names = InferEventNames<typeof eventRouter>;
+ * // 'userCreated' | 'orderPlaced'
+ *
+ * type Payload = InferEventPayload<typeof eventRouter, 'userCreated'>;
+ * // { userId: string }
+ * ```
+ */
+declare function defineEventRouter<TEvents extends Record<string, EventDef<any>>>(events: TEvents): EventRouterDef<TEvents>;
+
+/**
+ * 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 {
+    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);
+    /**
+     * How long an issued token stays valid, in milliseconds.
+     *
+     * Exposed so a caller that has to report an expiry to its client computes the same
+     * number this manager stamps on the token, instead of assuming the default.
+     */
+    get ttlMs(): number;
+    /**
+     * 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 EventDef as E, type InferEventNames as I, type JobQueueSender as J, type PubSubCache as P, SSETokenManager as S, type EventHandler as a, type EventRouterDef as b, type InferEventPayload$1 as c, type InferEventPayloads as d, type InferEventPayload as e, defineEventRouter as f, type SSEToken as g, type SSETokenManagerConfig as h, type SSETokenStore as i };

package/dist/types-2AbaW4Ie.d.ts

@@ -0,0 +1,205 @@
+import { Context } from 'hono';
+import { E as EventDef, b as EventRouterDef, I as InferEventNames, e as InferEventPayload, i as SSETokenStore, S as SSETokenManager } from './token-manager-BT5EnUAR.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;
+    /**
+     * Cross-pod event broadcast via the cache (Redis/Valkey) pub/sub.
+     *
+     * When `true` (default) and a cache is configured (`CACHE_URL`), each event
+     * is auto-wired so an `emit` on one pod reaches subscribers on every pod.
+     * Without a cache this is a no-op (events stay in-process). Set `false` to
+     * force in-process even when a cache is present.
+     *
+     * @default true
+     */
+    multiInstance?: boolean;
+    /**
+     * Pub/sub channel prefix for cross-pod broadcast.
+     *
+     * Defaults to env `SPFN_SSE_CHANNEL_PREFIX`, else `spfn:sse:`. Use distinct
+     * prefixes to isolate apps/tenants that share one Redis instance.
+     */
+    channelPrefix?: string;
+    /**
+     * Maximum inbound message size in bytes. Frames larger than this are
+     * rejected by the ws library before they are buffered or parsed.
+     * @default 1048576 (1 MiB)
+     */
+    maxPayload?: number;
+    /**
+     * Backpressure cap: if a connection's outbound buffer (`bufferedAmount`)
+     * exceeds this many bytes, the connection is closed (1013) instead of
+     * buffering more — a slow consumer cannot drive the process to OOM.
+     * @default 1048576 (1 MiB)
+     */
+    maxBufferedBytes?: number;
+    /**
+     * Maximum number of concurrent connections accepted by this server. New
+     * connections beyond the cap are rejected with close code 1013.
+     * @default 10000
+     */
+    maxConnections?: number;
+    /**
+     * Maximum concurrent connections per authenticated subject (0 = unlimited).
+     * @default 0
+     */
+    maxConnectionsPerSubject?: number;
+    /**
+     * Allow-list of `Origin` header values permitted to open a WebSocket. A
+     * browser sends Origin on the upgrade, so this blocks cross-site scripts from
+     * connecting with the user's ambient cookies (WebSocket has no same-origin
+     * policy / CORS of its own). Connections whose Origin isn't listed are closed
+     * with 1008. Undefined/empty = no Origin check (default; non-browser clients
+     * such as native apps send no Origin and are always allowed).
+     *
+     * @example ['https://app.example.com', 'https://admin.example.com']
+     * @default undefined (disabled)
+     */
+    allowedOrigins?: string[];
+    /**
+     * 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, WSSubscribeOptions as a, WSUnsubscribe as b, WSConnectionState as c, WSClientConfig as d, WSMessageHandlers as e, WSHandlerConfig as f, WSAuthConfig as g, WSEventHandlers as h, WSHandlerAuthConfig as i, WSMessageContext as j, WSMessageHandlerFn as k, WSRawConnection as l };

package/dist/{types-BOPTApC2.d.ts → types-9oszaJqp.d.ts}

@@ -159,7 +159,7 @@ interface ApiConfig {
     /**
      * Request timeout in milliseconds
      *
-     * @default 30000
+     * @default env.SERVER_TIMEOUT (120000)
      */
     timeout?: number;
     /**
@@ -202,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
      */
@@ -242,4 +247,4 @@ interface CallOptions {
     };
 }
 
-export type { ApiConfig as A, CallOptions as C, InferRouteInput as I, RequestInterceptor as R, StructuredInput as S, ResponseInterceptor as a, InferRouteOutput as b, RouterInput as c, RouterOutput as d, CookieOptions as e, SetCookie as f };
+export type { ApiConfig as A, CallOptions as C, InferRouteInput as I, RequestInterceptor as R, SetCookie as S, ResponseInterceptor as a, InferRouteOutput as b, CookieOptions as c, RouterInput as d, RouterOutput as e, StructuredInput as f };

package/dist/types-Bvvig_tT.d.ts

@@ -0,0 +1,115 @@
+import { b as RouteAuthProfile } from './router-ukNdAZcN.js';
+import { HttpMethod } from './route/types.js';
+
+/**
+ * Contract Document Types
+ *
+ * The shape of `contracts/current.json` and of a released snapshot under
+ * `contracts/released/<version>.json`.
+ *
+ * An operation is identified by its **name** — the key it holds in the router —
+ * not by method and path. That is what lets a changed path be reported as a
+ * broken promise instead of read as one operation disappearing and another
+ * appearing.
+ */
+
+/** A JSON Schema object as TypeBox serializes it. */
+type JsonSchema = Record<string, unknown>;
+/** Request schemas, one per part of the request. */
+interface ContractRequest {
+    params?: JsonSchema;
+    query?: JsonSchema;
+    body?: JsonSchema;
+    /**
+     * Never produced: a contracted route carrying multipart is refused at
+     * collection. Kept because a snapshot released before that rule may still
+     * have one, and the compatibility comparison has to read it.
+     */
+    formData?: JsonSchema;
+    headers?: JsonSchema;
+    cookies?: JsonSchema;
+}
+/** One contracted operation. */
+interface ContractOperation {
+    /** Router key. The operation's identity across versions. */
+    name: string;
+    method: HttpMethod;
+    path: string;
+    /** Contract version the operation first appeared in. */
+    since: string;
+    auth: RouteAuthProfile;
+    requiresSession: boolean;
+    /** Present only when the operation is announced for removal. */
+    deprecatedIn?: string;
+    /**
+     * Present only when the operation is gone.
+     *
+     * A client generated before this version may still call it, so the record
+     * outlives the route: without it a caller sees an operation that simply
+     * stopped existing, with nothing saying when or that it was announced.
+     */
+    removedIn?: string;
+    /** What the client sends. */
+    request: ContractRequest;
+    /**
+     * What middleware injects into the request before the handler sees it.
+     *
+     * A web client never sends these — an interceptor fills them in. A client
+     * that talks to the route directly does send them, so they are part of the
+     * published request shape and are compared under the request rules.
+     */
+    interceptor: ContractRequest;
+    /** What the client reads. */
+    response: JsonSchema;
+}
+/**
+ * How a client's version is judged against the server's.
+ *
+ * - `allOrNothing` — one contract version is the whole surface's pass or
+ *   refusal. Right for an auth primitive, where admitting a client that agrees
+ *   about part of the admission sequence and not the rest is not a safe middle.
+ * - `perOperation` — availability is recorded per operation, so the verdict
+ *   narrows to the operations a client actually calls. Deleting a response field
+ *   from one route then stops blocking a client that never calls it.
+ *
+ * Stated rather than inferred: an app contract and @spfn/auth's mobile contract
+ * share this format under different rules, and a consumer must not have to guess
+ * which one it is holding.
+ */
+type CompatibilityPolicy = 'allOrNothing' | 'perOperation';
+/** The generated contract. */
+interface ContractDocument {
+    /** Shape version of this document, not of the API it describes. */
+    documentVersion: 1;
+    /**
+     * The version this document publishes, from `.contractVersion()` on the
+     * router. Absent when the router declares none — the gate still runs, but
+     * nothing can be released or announced.
+     */
+    contractVersion?: string;
+    /** Always `perOperation` for an app contract. See the type. */
+    compatibilityPolicy: CompatibilityPolicy;
+    /** Sorted by name, so the file does not churn on router reordering. */
+    operations: ContractOperation[];
+}
+/** A released snapshot: the document plus the digest that pins it. */
+interface ContractSnapshot {
+    version: string;
+    /** SHA-256 over the canonical encoding of `document`. */
+    sha256: string;
+    document: ContractDocument;
+}
+/** What a gate violation is about. */
+type ContractViolationKind = 'operation.removed' | 'operation.path-changed' | 'operation.method-changed' | 'request.required-field-added' | 'request.field-became-required' | 'request.type-changed' | 'response.field-removed' | 'response.field-became-optional' | 'response.type-changed' | 'usage.undecidable' | 'usage.still-called' | 'snapshot.digest-mismatch';
+/** One reason the build refuses. */
+interface ContractViolation {
+    kind: ContractViolationKind;
+    /** Operation name, when the violation belongs to one. */
+    operation?: string;
+    /** Where inside the operation, e.g. `request.body.email`. */
+    location?: string;
+    /** What went wrong, in one line. */
+    detail: string;
+}
+
+export type { ContractDocument as C, JsonSchema as J, ContractViolation as a, ContractOperation as b, ContractSnapshot as c, CompatibilityPolicy as d, ContractRequest as e, ContractViolationKind as f };