@spfn/core 0.3.0-beta.3 → 0.3.0-beta.30

package/dist/types-CKH0D3Dy.d.ts

@@ -0,0 +1,441 @@
+import { TSchema, Static } from '@sinclair/typebox';
+import { ErrorRegistry, ErrorRegistryInput } from '@spfn/core/errors';
+import { RouteDef, RouteInput } from '@spfn/core/route';
+
+/**
+ * Typed client error
+ *
+ * `errorType` tells apart why a call failed:
+ * - `'http'`: the server answered with a non-2xx status
+ * - `'network'`: the fetch or the body read failed (status 0)
+ * - `'timeout'`: the call's timeout elapsed before response headers arrived (status 408)
+ * - `'aborted'`: the caller's own signal aborted the call (status 0); `cause` is the signal's reason
+ */
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly url: string;
+    readonly response?: unknown | undefined;
+    readonly errorType?: "http" | "network" | "timeout" | "aborted" | undefined;
+    constructor(message: string, status: number, url: string, response?: unknown | undefined, errorType?: "http" | "network" | "timeout" | "aborted" | undefined, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * 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
+ *
+ * Converts TypeBox schemas to their static types for each input field.
+ */
+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']> : {};
+};
+/**
+ * Infer route input type from RouteDef
+ *
+ * @example
+ * ```typescript
+ * // Server route definition
+ * const getUser = route.get('/users/:id')
+ *   .input({ params: Type.Object({ id: Type.String() }) })
+ *   .handler(...);
+ *
+ * // Client: extract input type
+ * type Input = InferRouteInput<typeof getUser>;
+ * // { params: { id: string }, query: {}, body: {}, ... }
+ * ```
+ */
+type InferRouteInput<TRoute> = TRoute extends RouteDef<infer TInput, any, any> ? StructuredInput<TInput> : never;
+/**
+ * Infer route output type from RouteDef
+ *
+ * @example
+ * ```typescript
+ * // Server route definition
+ * const getUser = route.get('/users/:id')
+ *   .handler(async (c) => {
+ *     return { id: '1', name: 'John' };
+ *   });
+ *
+ * // Client: extract output type
+ * type Output = InferRouteOutput<typeof getUser>;
+ * // { id: string, name: string }
+ * ```
+ */
+type InferRouteOutput<TRoute> = TRoute extends RouteDef<any, any, infer TResponse> ? TResponse : never;
+/**
+ * True only for `any`.
+ *
+ * `any` satisfies both branches of a conditional type, so a router whose routes are
+ * unresolved (`Router<any>`) would otherwise flatten into "every name exists" and
+ * accept a misspelled route name. A route record that is not known contributes no
+ * names instead.
+ */
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+/**
+ * True when `T` is a union of two or more members.
+ */
+type IsUnion<T, TCopy = T> = T extends unknown ? ([TCopy] extends [T] ? false : true) : false;
+/**
+ * One leaf of a router tree: the name a route is registered under, its definition, and
+ * the path it was reached by.
+ *
+ * A route is identified by its own key whatever depth it sits at — `registerRoutes`
+ * mounts a nested route under that key, and the contract collector reports a collision
+ * on it. Nesting groups the source; it does not qualify the name. The trail is carried
+ * so that one name reached through two branches stays two leaves.
+ */
+interface RouteLeaf<TName extends PropertyKey, TDef, TTrail extends PropertyKey[]> {
+    name: TName;
+    def: TDef;
+    trail: TTrail;
+}
+/** Decrements the nesting budget; `PrevDepth[0]` is `never`, which ends the walk. */
+type PrevDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+/**
+ * How many levels of nesting are followed.
+ *
+ * A budget rather than open recursion: a router type that refers to itself would
+ * otherwise never terminate, and TypeScript would report an instantiation-depth error
+ * in whichever component happened to read a route type. A route below the budget is not
+ * visible to these types; ten levels is far past any hand-written tree.
+ */
+type MaxNesting = 10;
+/**
+ * Collect every route in a route record as a leaf, descending into nested routers
+ * exactly as `registerRoutes` does.
+ */
+type RouteLeaves<TRoutes, TTrail extends PropertyKey[] = [], TDepth extends number = MaxNesting> = [
+    TDepth
+] extends [never] ? never : IsAny<TRoutes> extends true ? never : {
+    [K in keyof TRoutes]-?: RouteLeafOf<K, Exclude<TRoutes[K], undefined>, [...TTrail, K], TDepth>;
+}[keyof TRoutes];
+/**
+ * A nested router contributes its own leaves; anything else is a leaf.
+ *
+ * `{ _routes: ... }` is the runtime's own test for a router (`isRouter`), and a
+ * `RouteDef` carries `handler`, `_input` and `_response` but never `_routes`, so a
+ * route cannot be mistaken for a router.
+ */
+type RouteLeafOf<TName extends PropertyKey, TValue, TTrail extends PropertyKey[], TDepth extends number> = TValue extends {
+    _routes: infer TNested;
+} ? RouteLeaves<TNested, TTrail, PrevDepth[TDepth]> : RouteLeaf<TName, TValue, TTrail>;
+/** Every name the tree declares. */
+type LeafNames<TLeaves> = Extract<TLeaves extends RouteLeaf<infer TName, any, any> ? TName : never, PropertyKey>;
+/**
+ * The leaves declaring exactly this name.
+ *
+ * Exactly, not assignably: a record typed `Record<string, RouteDef>` contributes the
+ * name `string`, which every literal name is assignable to, and a loose sibling must
+ * not make each of its siblings look doubly declared.
+ */
+type LeavesNamed<TLeaves, TName extends PropertyKey> = TLeaves extends RouteLeaf<infer TLeafName, any, any> ? [TLeafName] extends [TName] ? [TName] extends [TLeafName] ? TLeaves : never : never : never;
+/** The definition a leaf carries. */
+type LeafDef<TLeaves> = TLeaves extends RouteLeaf<any, infer TDef, any> ? TDef : never;
+/** Where a leaf was found — one distinct trail per place the name is declared. */
+type LeafTrail<TLeaves> = TLeaves extends RouteLeaf<any, any, infer TTrail> ? TTrail : never;
+/**
+ * Flatten the leaves into one namespace of name → definition.
+ *
+ * A name that two branches both declare is left out rather than resolved to one of
+ * them: the tree gives it no single meaning, and picking a winner silently would hand
+ * a component another route's types. Naming it then fails the `K` constraint on
+ * `RouterOutput`/`RouterInput`, on the line that named it. Two places is counted by
+ * trail, so one slot holding a union of route definitions stays one route and still
+ * infers the union.
+ *
+ * The result is a fresh mapped type, so no key carries an optional or readonly modifier
+ * out of the source record — a route key that turned optional would change what
+ * `InferRouteInput` returns for it.
+ */
+type FlattenLeaves<TLeaves> = {
+    [TName in LeafNames<TLeaves> as UnambiguousName<TLeaves, TName>]: LeafDef<LeavesNamed<TLeaves, TName>>;
+};
+/** The name itself when one place declares it, and nothing when two do. */
+type UnambiguousName<TLeaves, TName extends PropertyKey> = IsUnion<LeafTrail<LeavesNamed<TLeaves, TName>>> extends true ? never : TName;
+/**
+ * Extract routes from Router type
+ *
+ * `Router<TRoutes>` holds its routes in `_routes`, and a value in that record is either
+ * a route or another router. Nested routers are flattened away, so every route appears
+ * here under its own name at one level — the same set of names the server registers.
+ *
+ * Exported so that the typed client (`Client`, in `./builder`) names a route the same
+ * way `RouterOutput` and `RouterInput` do; the two must not diverge, or a route would
+ * type in one place and not the other. It stays internal to the package: the
+ * `@spfn/core/nextjs` entry point exports a fixed list of type names, and this is not
+ * one of them.
+ */
+type ExtractRoutes<TRouter> = TRouter extends {
+    _routes: infer TRoutes;
+} ? FlattenLeaves<RouteLeaves<TRoutes>> : FlattenLeaves<RouteLeaves<TRouter>>;
+/**
+ * Extract output type for a specific route from router
+ *
+ * @example
+ * ```typescript
+ * import type { RouterOutput } from '@spfn/core/nextjs';
+ * import type { AppRouter } from '@/server/router';
+ *
+ * // Get output type for a specific route
+ * type ListData = RouterOutput<AppRouter, 'listExamples'>;
+ *
+ * // Use in props
+ * interface Props {
+ *     data: RouterOutput<AppRouter, 'listExamples'>;
+ * }
+ *
+ * // Extract item type from paginated response
+ * type Example = RouterOutput<AppRouter, 'listExamples'>['items'][number];
+ * ```
+ *
+ * A route declared inside a nested router is named the same way. The server registers
+ * a nested route under its own key, so `K` is the flat set of route names in the tree
+ * and the depth the route was declared at never appears here:
+ *
+ * ```typescript
+ * const appRouter = defineRouter({
+ *     getRoot,
+ *     examples: defineRouter({ listExamples, createExample }),
+ * });
+ *
+ * type ListData = RouterOutput<typeof appRouter, 'listExamples'>;
+ * ```
+ *
+ * Two branches declaring the same name make that name ambiguous, and it is left out of
+ * `K` rather than resolved to one of them — naming it is a compile error here instead
+ * of the wrong route's types reaching a component.
+ */
+type RouterOutput<TRouter, K extends keyof ExtractRoutes<TRouter>> = InferRouteOutput<ExtractRoutes<TRouter>[K]>;
+/**
+ * Extract input type for a specific route from router
+ *
+ * @example
+ * ```typescript
+ * import type { RouterInput } from '@spfn/core/nextjs';
+ * import type { AppRouter } from '@/server/router';
+ *
+ * // Get input type for a specific route
+ * type CreateInput = RouterInput<AppRouter, 'createExample'>;
+ *
+ * // Use in function parameter
+ * function submitForm(data: RouterInput<AppRouter, 'createExample'>['body']) {
+ *     // ...
+ * }
+ * ```
+ *
+ * `K` is the flat set of route names, so a route declared inside a nested router is
+ * named by its own key here too — see {@link RouterOutput}.
+ */
+type RouterInput<TRouter, K extends keyof ExtractRoutes<TRouter>> = InferRouteInput<ExtractRoutes<TRouter>[K]>;
+/**
+ * Cookie options for setCookie
+ */
+interface CookieOptions {
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+}
+/**
+ * Cookie to set in response
+ */
+interface SetCookie {
+    name: string;
+    value: string;
+    options?: CookieOptions;
+}
+/**
+ * Request interceptor - called before fetch
+ */
+type RequestInterceptor = (url: string, init: RequestInit) => Promise<RequestInit> | RequestInit;
+/**
+ * Response interceptor - called after fetch
+ *
+ * It runs outside the client's transport error handling, so throwing from it is a
+ * supported way to end the call: the error reaches the caller unchanged, which is what
+ * lets `redirect()` and `notFound()` navigate from one (issue #104). Returning
+ * `{ response, body }` replaces both for everything after it, error-status handling
+ * included.
+ */
+type ResponseInterceptor = (response: Response, body: any) => Promise<{
+    response: Response;
+    body: any;
+}> | {
+    response: Response;
+    body: any;
+};
+/**
+ * How one call ended, as `ApiConfig.onOutcome` is told it
+ *
+ * - `ok: true`: the server answered 2xx; `response` and `body` are what the response
+ *   interceptors left, and `body` is what the call returns
+ * - `'http'`: the server answered with an error status; `error` is the object the call
+ *   throws — the registered class a `__type` body names (`NotFoundError`,
+ *   `UnauthorizedError`, …) or else an `ApiError`, hence `Error`
+ * - `'network'` / `'timeout'` / `'aborted'`: no answer; `error` is the `ApiError` the call
+ *   throws, `status` its status (0, 408, 0)
+ */
+type ApiOutcome = {
+    ok: true;
+    response: Response;
+    body: unknown;
+} | {
+    ok: false;
+    errorType: 'http';
+    status: number;
+    error: Error;
+} | {
+    ok: false;
+    errorType: 'network' | 'timeout' | 'aborted';
+    status: number;
+    error: ApiError;
+};
+/**
+ * Client configuration
+ */
+interface ApiConfig {
+    /**
+     * Base URL for RPC endpoint
+     *
+     * @default '/api/rpc'
+     * @example '/api/rpc', 'http://localhost:3000/api/rpc'
+     */
+    baseUrl?: string;
+    /**
+     * Default headers for all requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds
+     *
+     * @default env.SERVER_TIMEOUT (120000)
+     */
+    timeout?: number;
+    /**
+     * Custom fetch implementation
+     */
+    fetch?: typeof fetch;
+    /**
+     * Global request interceptor
+     */
+    onRequest?: RequestInterceptor;
+    /**
+     * Global response interceptor
+     */
+    onResponse?: ResponseInterceptor;
+    /**
+     * Told once how each call that reached fetch ended — after the response interceptors
+     * ran, before the call returns or throws
+     *
+     * Observed: a transport failure (`'network'`, `'timeout'`, `'aborted'`) and every
+     * answer, error statuses included; `error` is the very object the call then throws.
+     * Not observed: a throw from an `onRequest` or `onResponse` interceptor, or from
+     * building the request — those are the app's own and reach the caller unchanged.
+     *
+     * Called synchronously and never awaited. A throw from it, or a rejection of the
+     * promise it returns, is logged and never changes what the call returns or throws.
+     * Config only: there is no per-call observer.
+     *
+     * @example
+     * ```typescript
+     * const api = createApi<AppRouter>({
+     *   onOutcome: (outcome) => setServerStatus(outcome.ok ? 'up' : outcome.errorType),
+     * });
+     * ```
+     */
+    onOutcome?: (outcome: ApiOutcome) => void;
+    /**
+     * Custom error registry for deserialization
+     *
+     * Core HTTP errors are automatically registered. Use this to add your custom application errors.
+     *
+     * @example
+     * ```typescript
+     * import { errorRegistry } from '@spfn/core/errors';
+     * import { authErrorRegistry } from '@myapp/auth/errors';
+     * import { PaymentFailedError } from '@/server/errors';
+     *
+     * const api = createApi<AppRouter>({
+     *   errorRegistry: [errorRegistry, authErrorRegistry, PaymentFailedError]
+     * });
+     * ```
+     */
+    errorRegistry?: ErrorRegistry | ErrorRegistryInput[];
+    /**
+     * Enable debug logging
+     *
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Per-call options
+ */
+interface CallOptions {
+    /**
+     * Request timeout in milliseconds, covering the wait for response headers
+     * Overrides the global timeout set in ApiConfig; set it with `.timeout(ms)`
+     */
+    timeout?: number;
+    /**
+     * Additional headers for this request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Override cookies for this request
+     *
+     * Note: Cookies are automatically forwarded by the proxy.
+     * Use this only when you need to override them.
+     */
+    cookies?: Record<string, string>;
+    /**
+     * Request-specific interceptor
+     */
+    onRequest?: RequestInterceptor;
+    /**
+     * Response-specific interceptor
+     */
+    onResponse?: ResponseInterceptor;
+    /**
+     * Next.js-specific fetch options
+     *
+     * @example
+     * // Time-based revalidation
+     * { next: { revalidate: 60 } }
+     *
+     * // Disable cache
+     * { cache: 'no-store' }
+     *
+     * // Tag-based revalidation
+     * { next: { tags: ['users'] } }
+     */
+    fetchOptions?: RequestInit & {
+        next?: {
+            revalidate?: number | false;
+            tags?: string[];
+        };
+    };
+}
+
+export { type ApiConfig as A, type CallOptions as C, type ExtractRoutes as E, type InferRouteInput as I, type RequestInterceptor as R, type SetCookie as S, type ResponseInterceptor as a, type InferRouteOutput as b, ApiError as c, type ApiOutcome as d, type CookieOptions as e, type RouterInput as f, type RouterOutput as g, type StructuredInput as h };

package/dist/{types-ZQODsBft.d.ts → types-CurMab2Q.d.ts}

@@ -1,5 +1,6 @@
 import { Context } from 'hono';
-import { b as EventRouterDef, I as InferEventNames, e as InferEventPayload, i as SSETokenStore, S as SSETokenManager } from './token-manager-BT5EnUAR.js';
+import { E as EventRouterDef, I as InferEventNames, i as InferEventPayload, l as SubscribeRequest } from './router-CX5uVjmU.js';
+import { c as SSETokenStore, S as SSETokenManager } from './token-manager-Ckjt2-qq.js';
 
 /**
  * SSE Types
@@ -78,6 +79,17 @@ interface SSEHandlerAuthConfig {
      * Return false to skip sending the event to this user.
      */
     filter?: Record<string, (subject: string, payload: unknown) => boolean>;
+    /**
+     * Resolve the principal every `.canSubscribe()` of a connection receives
+     * (called once per connection, after the subject is known).
+     *
+     * The stream request carries no `AuthContext`: the subject comes from the
+     * one-time token, and the stream is mounted without the app's middleware.
+     * So an app that decides on roles or memberships loads them here, once,
+     * instead of in every predicate. Absent → predicates see
+     * `principal: undefined`. A throw refuses the connection with 403.
+     */
+    resolvePrincipal?: (subject: string, request: SubscribeRequest) => unknown | Promise<unknown>;
 }
 /**
  * SSE auth configuration (user-facing, generic)
@@ -113,6 +125,7 @@ interface SSEAuthConfig<TRouter extends EventRouterDef<any>> {
     filter?: {
         [K in InferEventNames<TRouter>]?: (subject: string, payload: InferEventPayload<TRouter, K>) => boolean;
     };
+    resolvePrincipal?: (subject: string, request: SubscribeRequest) => unknown | Promise<unknown>;
 }
 /**
  * SSE Handler configuration
@@ -248,6 +261,13 @@ interface SSESubscribeOptions<TRouter extends EventRouterDef<any>> {
      * Event handlers
      */
     handlers: SSEEventHandlers<TRouter>;
+    /**
+     * Extra connect-query fields, e.g. the key a state event is filtered on
+     * (`{ workspaceId: 'w1' }`). Appended to the stream URL after `events=`,
+     * both sides URI-encoded, and reused on every reconnect. `events` and
+     * `token` are reserved: subscribe throws naming them.
+     */
+    query?: Record<string, string>;
     /**
      * Called when connection opens
      */
@@ -269,6 +289,36 @@ interface SSESubscribeOptions<TRouter extends EventRouterDef<any>> {
      * Called when reconnecting
      */
     onReconnect?: (attempt: number) => void;
+    /**
+     * Called when the server grants or revokes one event on the open connection
+     * (`subscription.granted` / `subscription.revoked` frames). Only events in
+     * `events` can change: an event never requested cannot be granted.
+     */
+    onSubscriptionChange?: (change: SSESubscriptionChange<TRouter>) => void;
+    /**
+     * Called with the server's `connected` frame on every connection — the
+     * first open and each reconnect — after `onOpen`.
+     */
+    onConnected?: (payload: ConnectedPayload) => void;
+}
+/**
+ * The `connected` frame, the first a connection receives: which requested
+ * events it is subscribed to, which are denied, and which were served their
+ * initial frames (written right after this one). `initial` is absent from a
+ * server that predates it.
+ */
+interface ConnectedPayload {
+    subscribedEvents: string[];
+    deniedEvents: string[];
+    initial?: string[];
+    timestamp: number;
+}
+/**
+ * A `grant` / `revoke` the server applied to the open connection.
+ */
+interface SSESubscriptionChange<TRouter extends EventRouterDef<any>> {
+    event: InferEventNames<TRouter>;
+    status: 'granted' | 'revoked';
 }
 /**
  * SSE connection state
@@ -279,4 +329,4 @@ type SSEConnectionState = 'connecting' | 'open' | 'closed' | 'error';
  */
 type SSEUnsubscribe = () => void;
 
-export type { SSEClientConfig as S, SSESubscribeOptions as a, SSEUnsubscribe as b, SSEConnectionState as c, SSEHandlerConfig as d, SSEAuthConfig as e, SSEEventHandler as f, SSEEventHandlers as g, SSEHandlerAuthConfig as h, SSEMessage as i };
+export type { ConnectedPayload as C, SSEClientConfig as S, SSESubscribeOptions as a, SSEUnsubscribe as b, SSEConnectionState as c, SSEHandlerConfig as d, SSEAuthConfig as e, SSEEventHandler as f, SSEEventHandlers as g, SSEHandlerAuthConfig as h, SSEMessage as i, SSESubscriptionChange as j };

package/dist/{types-2AbaW4Ie.d.ts → types-DncqXfWN.d.ts}

@@ -1,5 +1,6 @@
 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';
+import { a as EventDef, o as EventRouterBase, I as InferEventNames, i as InferEventPayload } from './router-CX5uVjmU.js';
+import { c as SSETokenStore, S as SSETokenManager } from './token-manager-Ckjt2-qq.js';
 
 /**
  * WebSocket Types
@@ -8,9 +9,9 @@ import { E as EventDef, b as EventRouterDef, I as InferEventNames, e as InferEve
 /**
  * WebSocket Router Definition
  *
- * Extends EventRouterDef with client→server message handlers.
+ * Extends the event router shape with client→server message handlers.
  */
-interface WSRouterDef<TEvents extends Record<string, EventDef<any>>, TMessages extends WSMessageHandlers = WSMessageHandlers> extends EventRouterDef<TEvents> {
+interface WSRouterDef<TEvents extends Record<string, EventDef<any>>, TMessages extends WSMessageHandlers = WSMessageHandlers> extends EventRouterBase<TEvents> {
     messages: TMessages;
 }
 /**