@spfn/core 0.3.0-beta.2 → 0.3.0-beta.21

package/dist/{router-Qbssr11H.d.ts → route-builder-DRW-MSCJ.d.ts}

@@ -1,8 +1,8 @@
-import { a as NamedMiddleware } from './define-middleware-DfDP39Nq.js';
 import { Context, MiddlewareHandler } from 'hono';
+import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
 import { TSchema, Static } from '@sinclair/typebox';
 import { ContentfulStatusCode, RedirectStatusCode } from 'hono/utils/http-status';
-import { HttpMethod } from './route/types.js';
+import { HttpMethod, RouteEffect } from './route/types.js';
 
 /**
  * Route Input Types
@@ -296,6 +296,13 @@ type RouteDef<TInput extends RouteInput = RouteInput, TInterceptor extends Route
      * the compatibility gate read it.
      */
     contract?: RouteContract;
+    /**
+     * What invoking this route does. Read by a command surface, which
+     * announces it in its manifest; codegen and the contract ignore it.
+     */
+    effect?: RouteEffect;
+    /** One line a command surface announces beside the route; codegen and the contract ignore it. */
+    summary?: string;
     handler: RouteHandlerFn<TInput, TInterceptor, TResponse>;
     _input: TInput;
     _interceptor: TInterceptor;
@@ -312,6 +319,8 @@ declare class RouteBuilder<TInput extends RouteInput = {}, TInterceptor extends
     _middlewares?: (MiddlewareHandler | NamedMiddleware<string>)[];
     _skipMiddlewares?: string[] | '*';
     _contract?: RouteContract;
+    _effect?: RouteEffect;
+    _summary?: string;
     /**
      * Create a new RouteBuilder with copied properties and optional overrides
      */
@@ -425,7 +434,7 @@ declare class RouteBuilder<TInput extends RouteInput = {}, TInterceptor extends
      * @example
      * ```ts
      * // Skip specific middlewares
-     * route.get('/health')
+     * route.get('/status')
      *   .skip(['auth', 'rateLimit'])
      *   .handler(async (c) => c.json({ status: 'ok' }));
      *
@@ -472,6 +481,45 @@ declare class RouteBuilder<TInput extends RouteInput = {}, TInterceptor extends
      * ```
      */
     contract(contract: RouteContract): RouteBuilder<TInput, TInterceptor, TResponse>;
+    /**
+     * Declare what invoking this route does
+     *
+     * Read by a command surface (`@spfn/core/surface`, `@spfn/core/ops`),
+     * which announces it in its manifest so a machine caller can tell a read
+     * from a write before it calls — `spfn ops call` asks for `--yes` before a
+     * `destructive` command. A surface built with `defineSurface` refuses an
+     * app command that does not declare one; on `/_ops` it is optional.
+     *
+     * Nothing else reads it: codegen, the route map, and the contract are
+     * unaffected, and a route outside any surface simply carries it.
+     *
+     * @example
+     * ```ts
+     * export const pageAdd = app.route.post('/pages')
+     *   .input({ body: PageAddBody })
+     *   .effect('write')
+     *   .summary('Add a page to the blueprint')
+     *   .handler(async (c) => { ... });
+     * ```
+     */
+    effect(effect: RouteEffect): RouteBuilder<TInput, TInterceptor, TResponse>;
+    /**
+     * Describe this route in one line for a command surface's manifest
+     *
+     * A surface announces it beside the command in `spfn ops list` and
+     * `--describe`, and refuses one that is empty or longer than 500
+     * characters. Codegen, the route map, and the contract ignore it. On a
+     * module command the module's own summary wins.
+     *
+     * @example
+     * ```ts
+     * export const pageAdd = app.route.post('/pages')
+     *   .effect('write')
+     *   .summary('Add a page to the blueprint')
+     *   .handler(async (c) => { ... });
+     * ```
+     */
+    summary(summary: string): RouteBuilder<TInput, TInterceptor, TResponse>;
     /**
      * Define handler function
      *
@@ -550,127 +598,4 @@ declare const route: {
     delete: (path: string) => RouteBuilder;
 };
 
-/**
- * Router Definition
- *
- * Provides router composition and middleware management
- */
-
-/**
- * Router definition - holds all routes
- */
-interface Router<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>> {
-    routes: TRoutes;
-    _routes: TRoutes;
-    _packageRouters: Router<any>[];
-    _globalMiddlewares: NamedMiddleware<string>[];
-    /** The contract version these routes publish, or null when uncontracted. */
-    _contractVersion: string | null;
-    /**
-     * Register package routers (type-hidden)
-     *
-     * Package routes are:
-     * - Recognized by RPC proxy and backend
-     * - NOT exposed in client types (use package's own API like authApi, cmsApi)
-     *
-     * @example
-     * ```ts
-     * import { authRouter } from '@spfn/auth/server';
-     * import { cmsAppRouter } from '@spfn/cms/server';
-     *
-     * export const appRouter = defineRouter({
-     *     getRoot,
-     *     getHealth,
-     * })
-     * .packages([authRouter, cmsAppRouter]);
-     *
-     * // Client usage:
-     * // api.getRoot.call({})     - app routes
-     * // authApi.login.call({})   - package API
-     * ```
-     */
-    packages(routers: Router<any>[]): Router<TRoutes>;
-    /**
-     * Register global middlewares
-     *
-     * Applied to all routes unless explicitly skipped via .skip()
-     *
-     * @example
-     * ```ts
-     * import { authMiddleware, loggingMiddleware } from './middlewares';
-     *
-     * export const appRouter = defineRouter({
-     *     getRoot,
-     *     getHealth,
-     * })
-     * .packages([authRouter])
-     * .use([authMiddleware, loggingMiddleware]);
-     * ```
-     */
-    use(middlewares: NamedMiddleware<string>[]): Router<TRoutes>;
-    /**
-     * Declare the contract version these routes publish.
-     *
-     * A client compiled against this server — a mobile app in a store — is
-     * generated from one version of the contract and cannot be updated when the
-     * server changes. The server announces this version on every response so
-     * that client can tell whether the two ends still agree.
-     *
-     * This is the version's source. A released snapshot is written to
-     * `contracts/released/<version>.json` from what is declared here, so the
-     * filename follows the code rather than the code having to be told what the
-     * filename said.
-     *
-     * Only a server with contracted routes needs it. Without it the contract
-     * generator still writes `current.json` and still runs the compatibility
-     * gate; what it cannot do is cut a release or announce a version.
-     *
-     * @example
-     * ```ts
-     * export const appRouter = defineRouter({ getRoot, listItems })
-     *     .contractVersion('1.2.0')
-     *     .packages([authRouter]);
-     * ```
-     */
-    contractVersion(version: string): Router<TRoutes>;
-}
-/**
- * Define a router with multiple routes (tRPC-style)
- *
- * Supports chainable API for packages and middlewares:
- *
- * @example
- * ```ts
- * // Basic usage
- * export const appRouter = defineRouter({
- *     getRoot,
- *     getHealth,
- *     listExamples,
- * });
- *
- * // With package routers (type-hidden)
- * export const appRouter = defineRouter({
- *     getRoot,
- *     getHealth,
- * })
- * .packages([authRouter, cmsAppRouter]);
- *
- * // With global middlewares
- * export const appRouter = defineRouter({
- *     getRoot,
- *     getHealth,
- * })
- * .packages([authRouter])
- * .use([authMiddleware, loggingMiddleware]);
- *
- * export type AppRouter = typeof appRouter;
- * ```
- *
- * Package routes:
- * - Recognized by RPC proxy and backend for routing
- * - NOT included in AppRouter type (use authApi, cmsApi instead)
- * - Prevents confusion between app API and package APIs
- */
-declare function defineRouter<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes): Router<TRoutes>;
-
-export { type MergedInput as M, type PaginatedResult as P, type Router as R, type RouteDef as a, RouteBuilder as b, type RouteAuthProfile as c, type RouteBuilderContext as d, type RouteContract as e, type RouteHandlerFn as f, type RouteInput as g, defineRouter as h, route as r };
+export { type MergedInput as M, type PaginatedResult as P, type RouteDef as R, type RouteAuthProfile as a, type RouteBuilderContext as b, type RouteContract as c, type RouteHandlerFn as d, type RouteInput as e, RouteBuilder as f, route as r };

package/dist/router-4YoIy5fN.d.ts

@@ -0,0 +1,172 @@
+import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
+import { R as RouteDef } from './route-builder-DRW-MSCJ.js';
+
+/**
+ * Router Definition
+ *
+ * Provides router composition and middleware management
+ */
+
+/**
+ * Router definition - holds all routes
+ */
+interface Router<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>> {
+    routes: TRoutes;
+    _routes: TRoutes;
+    _packageRouters: Router<any>[];
+    _globalMiddlewares: NamedMiddleware<string>[];
+    /** The contract version these routes publish, or null when uncontracted. */
+    _contractVersion: string | null;
+    /**
+     * Whether a client ever addresses these routes by name.
+     *
+     * True for an ordinary router. A mounted package router that is true here
+     * has its routes written into the app's generated route map, which is what
+     * lets the package's own client (`authApi.login`) resolve a name through the
+     * app's RPC proxy. It is also what makes an app route sharing a name with a
+     * package route a defect worth refusing a build over: the map holds one
+     * entry per name, so one of the two paths would become unreachable while the
+     * generated types still describe the app's route.
+     *
+     * False says no client names these routes: they are reached by URL, by
+     * something that was handed the URL, so nothing of them belongs in the map
+     * and a name they share with an app route is only a shared name.
+     * `createOpsRouter` sets it — `spfn ops` invokes an ops command over the URL
+     * the manifest gave it.
+     */
+    _publishesRouteMap: boolean;
+    /**
+     * The namespace of the command surface that built this router, absent on
+     * any other. Set by `defineSurface` (and so by `createOpsRouter`) as a
+     * non-enumerable property, so `.packages()` can refuse two surfaces on one
+     * namespace.
+     */
+    readonly _surfaceNamespace?: string;
+    /**
+     * Register package routers (type-hidden)
+     *
+     * Package routes are:
+     * - Recognized by RPC proxy and backend
+     * - NOT exposed in client types (use package's own API like authApi, cmsApi)
+     *
+     * @example
+     * ```ts
+     * import { authRouter } from '@spfn/auth/server';
+     * import { cmsAppRouter } from '@spfn/cms/server';
+     *
+     * export const appRouter = defineRouter({
+     *     getRoot,
+     *     getStatus,
+     * })
+     * .packages([authRouter, cmsAppRouter]);
+     *
+     * // Client usage:
+     * // api.getRoot.call({})     - app routes
+     * // authApi.login.call({})   - package API
+     * ```
+     */
+    packages(routers: Router<any>[]): Router<TRoutes>;
+    /**
+     * Register global middlewares
+     *
+     * Applied to all routes unless explicitly skipped via .skip()
+     *
+     * @example
+     * ```ts
+     * import { authMiddleware, loggingMiddleware } from './middlewares';
+     *
+     * export const appRouter = defineRouter({
+     *     getRoot,
+     *     getStatus,
+     * })
+     * .packages([authRouter])
+     * .use([authMiddleware, loggingMiddleware]);
+     * ```
+     */
+    use(middlewares: NamedMiddleware<string>[]): Router<TRoutes>;
+    /**
+     * Declare the contract version these routes publish.
+     *
+     * A client compiled against this server — a mobile app in a store — is
+     * generated from one version of the contract and cannot be updated when the
+     * server changes. The server announces this version on every response so
+     * that client can tell whether the two ends still agree.
+     *
+     * This is the version's source. A released snapshot is written to
+     * `contracts/released/<version>.json` from what is declared here, so the
+     * filename follows the code rather than the code having to be told what the
+     * filename said.
+     *
+     * Only a server with contracted routes needs it. Without it the contract
+     * generator still writes `current.json` and still runs the compatibility
+     * gate; what it cannot do is cut a release or announce a version.
+     *
+     * @example
+     * ```ts
+     * export const appRouter = defineRouter({ getRoot, listItems })
+     *     .contractVersion('1.2.0')
+     *     .packages([authRouter]);
+     * ```
+     */
+    contractVersion(version: string): Router<TRoutes>;
+}
+/**
+ * Define a router with multiple routes (tRPC-style)
+ *
+ * Supports chainable API for packages and middlewares:
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getStatus,
+ *     listExamples,
+ * });
+ *
+ * // With package routers (type-hidden)
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getStatus,
+ * })
+ * .packages([authRouter, cmsAppRouter]);
+ *
+ * // With global middlewares
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getStatus,
+ * })
+ * .packages([authRouter])
+ * .use([authMiddleware, loggingMiddleware]);
+ *
+ * export type AppRouter = typeof appRouter;
+ * ```
+ *
+ * Package routes:
+ * - Recognized by RPC proxy and backend for routing
+ * - NOT included in AppRouter type (use authApi, cmsApi instead)
+ * - Prevents confusion between app API and package APIs
+ */
+declare function defineRouter<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes): Router<TRoutes>;
+/**
+ * A router no client addresses by name.
+ *
+ * The app's generated route map carries the routes of every package router the
+ * app mounts with `.packages()`, so that a package client calling its own route
+ * by name resolves through the app's RPC proxy. A router built here is left out
+ * of that map: its routes are reached by URL, by a tool that was told the URL,
+ * so no name of theirs has to resolve anywhere and a name shared with an app
+ * route is only a shared name.
+ *
+ * Declared by the package that ships the router, because only it knows whether
+ * any client names these routes: `createOpsRouter` and the tracking routes of
+ * `@spfn/notification` do it, and any package whose surface is reached by URL
+ * may. The obligation is the whole of it — a package whose client *does* name
+ * its routes must use `defineRouter`, or those names land in nobody's map and
+ * resolve nowhere (and a collision that really would take an app route's entry
+ * generates silently). `defineRouter` is the default for exactly that reason: a
+ * package that says nothing is carried and checked.
+ */
+declare function defineUnmappedRouter<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes): Router<TRoutes>;
+
+export { type Router as R, defineUnmappedRouter as a, defineRouter as d };

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 };