@spfn/core 0.3.0-beta.17 → 0.3.0-beta.19

package/dist/{token-manager-BT5EnUAR.d.ts → router-CysBmgv3.d.ts}

@@ -25,6 +25,21 @@ 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>;
+/**
+ * What a contracted event promises to clients compiled separately from the
+ * server, written into `contracts/current.json` by `@spfn/core:contract`.
+ *
+ * The same version markers a route's `.contract()` carries; the payload shape
+ * is the event's own schema, so it is not repeated here.
+ */
+interface EventContract {
+    /** Contract version the event first appeared in. */
+    since: string;
+    /** Contract version the event was announced for removal in. */
+    deprecatedIn?: string;
+    /** Contract version the event was removed in. */
+    removedIn?: string;
+}
 /**
  * Event definition interface
  */
@@ -37,6 +52,22 @@ interface EventDef<TPayload = void> {
      * TypeBox payload schema (optional)
      */
     readonly schema?: TSchema;
+    /**
+     * The contract declared with `.contract()`, absent when the event is not
+     * part of the published contract.
+     *
+     * Named with an underscore because `.contract()` holds the plain name, as
+     * a router's `_contractVersion` sits beside `.contractVersion()`.
+     */
+    readonly _contract?: EventContract;
+    /**
+     * Publish this event in `contracts/current.json`.
+     *
+     * Sets the contract on this definition and returns it. An event is defined
+     * once and shared, so a second call throws instead of one of the two
+     * declarations silently winning.
+     */
+    contract: (contract: EventContract) => EventDef<TPayload>;
     /**
      * Subscribe to this event (in-memory handler)
      */
@@ -104,9 +135,32 @@ type InferEventPayload$1<TEvent> = TEvent extends EventDef<infer TPayload> ? TPa
  */
 
 /**
- * Event Router Definition
+ * How a client reaches the contracted events of a router.
+ *
+ * Declared on the router because it is the stream's promise, not one event's:
+ * `createServer` checks it against `.events()` at boot, so the document cannot
+ * describe a path or an auth mode the server does not serve.
  */
-interface EventRouterDef<TEvents extends Record<string, EventDef<any>>> {
+interface EventRouterContract {
+    /**
+     * `'tokenExchange'` when `.events()` enables `auth` — the client first posts
+     * to the token path and opens the stream with `?token=`. `'none'` otherwise.
+     */
+    auth: 'none' | 'tokenExchange';
+    /**
+     * The stream path `.events()` registers.
+     * @default '/events/stream'
+     */
+    streamPath?: string;
+}
+/**
+ * What every router of events carries — the SSE event router and the
+ * WebSocket router alike.
+ *
+ * The WebSocket router builds on this rather than on `EventRouterDef`, because
+ * only an SSE event router can be contracted.
+ */
+interface EventRouterBase<TEvents extends Record<string, EventDef<any>>> {
     /**
      * Event definitions
      */
@@ -122,21 +176,42 @@ interface EventRouterDef<TEvents extends Record<string, EventDef<any>>> {
         [K in keyof TEvents]: TEvents[K]['_payload'];
     };
 }
+/**
+ * Event Router Definition
+ */
+interface EventRouterDef<TEvents extends Record<string, EventDef<any>>> extends EventRouterBase<TEvents> {
+    /**
+     * The contract declared with `.contract()`, absent when the router declares
+     * none. Underscored for the same reason as `EventDef._contract`.
+     */
+    readonly _contract?: EventRouterContract;
+    /**
+     * Declare how a client reaches this router's contracted events.
+     *
+     * Sets the contract on this router and returns it. A `streamPath` that does
+     * not start with `/` throws here, where the typo is.
+     */
+    contract: (contract: EventRouterContract) => EventRouterDef<TEvents>;
+}
 /**
  * Infer event names from EventRouter
  */
-type InferEventNames<T> = T extends EventRouterDef<infer E> ? keyof E & string : never;
+type InferEventNames<T> = T extends EventRouterBase<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];
+type InferEventPayload<T extends EventRouterBase<any>, K extends InferEventNames<T>> = T['_types'][K];
 /**
  * Infer all event payloads map
  */
-type InferEventPayloads<T extends EventRouterDef<any>> = T['_types'];
+type InferEventPayloads<T extends EventRouterBase<any>> = T['_types'];
 /**
  * Define an event router for SSE subscription
  *
+ * `.contract({ auth })` on the router, together with `.contract({ since })` on
+ * its events, publishes those events in `contracts/current.json` — see the
+ * contract README.
+ *
  * @example
  * ```typescript
  * export const eventRouter = defineEventRouter({
@@ -154,125 +229,4 @@ type InferEventPayloads<T extends EventRouterDef<any>> = T['_types'];
  */
 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 };
+export { type EventRouterDef as E, type InferEventNames as I, type JobQueueSender as J, type PubSubCache as P, type EventDef as a, type EventContract as b, type EventHandler as c, type EventRouterContract as d, type InferEventPayload$1 as e, type InferEventPayloads as f, type InferEventPayload as g, defineEventRouter as h, type EventRouterBase as i };

package/dist/server/index.d.ts

@@ -6,15 +6,16 @@ import { NamedMiddleware, Router } from '@spfn/core/route';
 import { OnErrorContext, ProxyGuardConfig, RateLimitOptions } from '@spfn/core/middleware';
 import { SafeFetchPolicy } from '@spfn/core/security';
 import { c as JobRouter, f as BossOptions } from '../boss-BiDCbbAQ.js';
-import { b as EventRouterDef, E as EventDef } from '../token-manager-BT5EnUAR.js';
-import { d as SSEHandlerConfig, e as SSEAuthConfig } from '../types-ZQODsBft.js';
-import { W as WSRouterDef, f as WSHandlerConfig, e as WSMessageHandlers, g as WSAuthConfig } from '../types-2AbaW4Ie.js';
+import { E as EventRouterDef, a as EventDef } from '../router-CysBmgv3.js';
+import { d as SSEHandlerConfig, e as SSEAuthConfig } from '../types-B8zAxFsE.js';
+import { W as WSRouterDef, f as WSHandlerConfig, e as WSMessageHandlers, g as WSAuthConfig } from '../types-W4u_S0lF.js';
 import { DatabaseProvider, MigrationStatus, MigrationStatusDb } from '@spfn/core/db';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
 import { R as RouteDef } from '../route-builder-2ani2jEI.js';
 import { a as EnvRegistry } from '../registry-C2KQCh0m.js';
 import 'pg-boss';
+import '../token-manager-Ckjt2-qq.js';
 import '../define-middleware-CVKgqo8S.js';
 import 'hono/utils/http-status';
 import '../route/types.js';

package/dist/server/index.js

@@ -644,6 +644,12 @@ async function authorizeEvents(subject, requestedEvents, authConfig) {
   }
   return allowed;
 }
+
+// src/event/sse/paths.ts
+var DEFAULT_SSE_STREAM_PATH = "/events/stream";
+function sseTokenPath(streamPath) {
+  return streamPath.replace(/\/[^/]+$/, "/token");
+}
 function hashToken(token) {
   return createHash("sha256").update(token).digest("hex");
 }
@@ -2126,8 +2132,9 @@ async function registerSSEEndpoint(app, config) {
     return;
   }
   const eventsConfig = config.eventsConfig ?? {};
-  const streamPath = eventsConfig.path ?? "/events/stream";
+  const streamPath = eventsConfig.path ?? DEFAULT_SSE_STREAM_PATH;
   const authConfig = eventsConfig.auth;
+  assertEventContractServed(config.events._contract, streamPath, !!authConfig?.enabled);
   const debug = isDebugMode(config);
   let tokenManager;
   if (authConfig?.enabled) {
@@ -2150,7 +2157,7 @@ async function registerSSEEndpoint(app, config) {
       ttl: authConfig.tokenTtl,
       store
     });
-    const tokenPath = streamPath.replace(/\/[^/]+$/, "/token");
+    const tokenPath = sseTokenPath(streamPath);
     const mwHandlers = resolveEndpointMiddlewares(config).map((mw) => mw.handler);
     const getSubject = authConfig.getSubject ?? ((c) => c.get("auth")?.userId ?? null);
     app.on(["POST"], [tokenPath], ...mwHandlers, async (c) => {
@@ -2179,6 +2186,23 @@ async function registerSSEEndpoint(app, config) {
     });
   }
 }
+function assertEventContractServed(contract, streamPath, authEnabled) {
+  if (!contract) {
+    return;
+  }
+  const contractPath = contract.streamPath ?? DEFAULT_SSE_STREAM_PATH;
+  if (contractPath !== streamPath) {
+    throw new Error(
+      `SSE event router contract declares streamPath ${contractPath} but .events() registers ${streamPath}; the contract would describe a path the server does not serve`
+    );
+  }
+  const servedAuth = authEnabled ? "tokenExchange" : "none";
+  if (contract.auth !== servedAuth) {
+    throw new Error(
+      `SSE event router contract declares auth ${contract.auth} but .events() serves auth ${servedAuth}; the contract would describe an auth mode the server does not serve`
+    );
+  }
+}
 function isDebugMode(config) {
   return config?.debug ?? process.env.NODE_ENV === "development";
 }