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

package/dist/nextjs/index.d.ts

@@ -1,6 +1,6 @@
 import { Router, RouteDef } from '@spfn/core/route';
-import { R as RequestInterceptor, a as ResponseInterceptor, I as InferRouteInput, b as InferRouteOutput, A as ApiConfig } from '../types-9oszaJqp.js';
-export { C as CallOptions, c as CookieOptions, d as RouterInput, e as RouterOutput, S as SetCookie, f as StructuredInput } from '../types-9oszaJqp.js';
+import { R as RequestInterceptor, a as ResponseInterceptor, I as InferRouteInput, b as InferRouteOutput, E as ExtractRoutes, A as ApiConfig } from '../types-CxhPH4s_.js';
+export { C as CallOptions, c as CookieOptions, d as RouterInput, e as RouterOutput, S as SetCookie, f as StructuredInput } from '../types-CxhPH4s_.js';
 import '@sinclair/typebox';
 import '@spfn/core/errors';
 
@@ -57,6 +57,11 @@ type RouteClient<TRoute extends RouteDef<any, any>> = {
             tags?: string[];
         };
     }): RouteClient<TRoute>;
+    /**
+     * Set this call's timeout in milliseconds, overriding the client-wide one.
+     * Throws a `TypeError` unless `ms` is finite, `> 0` and `<= 2147483647`.
+     */
+    timeout(ms: number): RouteClient<TRoute>;
     /**
      * Set request interceptor
      */
@@ -80,11 +85,42 @@ type RouteClient<TRoute extends RouteDef<any, any>> = {
     call: HasAnyRequiredFields<InferRouteInput<TRoute>> extends true ? (input: CleanStructuredInput<InferRouteInput<TRoute>>) => Promise<InferRouteOutput<TRoute>> : (input?: CleanStructuredInput<InferRouteInput<TRoute>>) => Promise<InferRouteOutput<TRoute>>;
 };
 /**
- * Typed client for entire router
+ * One property per route in a flattened route record.
+ *
+ * A slot the flattening could not resolve to a route definition is `never`, as it was
+ * before nesting was flattened — a record whose values are neither routes nor routers
+ * names nothing callable.
  */
-type Client<TRouter extends Router<any>> = {
-    [K in keyof TRouter['routes']]: TRouter['routes'][K] extends RouteDef<any, any, any> ? RouteClient<TRouter['routes'][K]> : TRouter['routes'][K] extends Router<any> ? Client<TRouter['routes'][K]> : never;
+type RouteClients<TRoutes> = {
+    [K in keyof TRoutes]: TRoutes[K] extends RouteDef<any, any, any> ? RouteClient<TRoutes[K]> : never;
 };
+/**
+ * Typed client for entire router
+ *
+ * One flat namespace, holding the same route names the server registers. A route
+ * declared inside a nested `defineRouter` is reached by its own key — `api.getThing`,
+ * never `api.group.getThing` — because that is the name `registerRoutes` mounts it
+ * under, the name the RPC proxy resolves, and the name `RouterOutput` takes. The group
+ * key is not a route and naming it is a compile error.
+ *
+ * @example
+ * ```typescript
+ * const appRouter = defineRouter({
+ *     getRoot,
+ *     users: defineRouter({ getUser }),
+ * });
+ *
+ * const api = createApi<typeof appRouter>();
+ *
+ * await api.getUser.call({ params: { id: '1' } });   // not api.users.getUser
+ * ```
+ *
+ * A name two branches both declare is left out of the namespace rather than resolved to
+ * one of them — the same collision `RouterOutput` refuses. Routes mounted with
+ * `.packages()` are deliberately absent: a package publishes its own route map and its
+ * own client (`authApi`, `cmsApi`), and that is what calls them.
+ */
+type Client<TRouter extends Router<any>> = RouteClients<ExtractRoutes<TRouter>>;
 
 /**
  * Create type-safe RPC client
@@ -106,15 +142,59 @@ type Client<TRouter extends Router<any>> = {
  */
 declare function createApi<TRouter extends Router<any>>(config?: ApiConfig): Client<TRouter>;
 
+/**
+ * CSRF token transport for the RPC client
+ *
+ * The Next.js proxy sets a readable (non-HttpOnly) cookie carrying an HMAC of
+ * the session's key id; this module mirrors it into a request header. The proxy
+ * never compares cookie against header — it recomputes the value from the
+ * session — so the cookie is transport only and reading it here is not a trust
+ * decision. See the CSRF section of the @spfn/auth README.
+ */
+/**
+ * Header the readable CSRF cookie is mirrored into.
+ *
+ * Must match CSRF_HEADER in @spfn/auth. It is duplicated rather than imported
+ * because @spfn/core cannot depend on @spfn/auth.
+ */
+declare const CSRF_HEADER = "x-spfn-csrf";
+/**
+ * Collect the CSRF token candidates from cookie entries.
+ *
+ * Takes entries rather than a map because a name can legitimately appear twice:
+ * a sibling subdomain that tosses `spfn_csrf` for the parent domain leaves the
+ * browser holding two cookies of that name, and folding them into a map would
+ * throw away whichever the tossed one displaced — locking the user out of every
+ * mutation. Sending both keeps the real one in play, and the tossed one is inert
+ * because the proxy recomputes what it expects.
+ *
+ * @returns Header value (comma-separated), or undefined when no cookie exists
+ */
+declare function csrfHeaderValue(cookies: Iterable<[string, string]>): string | undefined;
+/**
+ * Read the browser cookie jar as entries, duplicates preserved.
+ *
+ * Empty outside a browser (SSR reads the jar it forwards instead).
+ */
+declare function documentCookieEntries(): Array<[string, string]>;
+
 /**
  * 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" | undefined;
-    constructor(message: string, status: number, url: string, response?: unknown | undefined, errorType?: "http" | "network" | "timeout" | 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;
+    });
 }
 
-export { ApiConfig, ApiError, type Client, InferRouteInput, InferRouteOutput, RequestInterceptor, ResponseInterceptor, type RouteClient, createApi };
+export { ApiConfig, ApiError, CSRF_HEADER, type Client, InferRouteInput, InferRouteOutput, RequestInterceptor, ResponseInterceptor, type RouteClient, createApi, csrfHeaderValue, documentCookieEntries };

package/dist/nextjs/index.js

@@ -69,8 +69,8 @@ function logThrowingDeserializedError(logger3, error) {
 
 // src/nextjs/client/errors.ts
 var ApiError = class extends Error {
-  constructor(message, status, url, response, errorType) {
-    super(message);
+  constructor(message, status, url, response, errorType, options) {
+    super(message, options);
     this.status = status;
     this.url = url;
     this.response = response;
@@ -123,19 +123,45 @@ async function autoDetectServerCookies() {
     return {};
   }
 }
-async function executeFetchWithTimeout(url, init, timeout, customFetch = fetch) {
+function openAbortScope(callerSignal, timeout) {
   const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  let cause;
+  const abort = (source, reason) => {
+    cause ??= source;
+    controller.abort(reason);
+  };
+  const onCallerAbort = () => abort("caller", callerSignal?.reason);
+  const timeoutId = setTimeout(() => abort("timeout"), timeout);
+  callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+  return {
+    signal: controller.signal,
+    cause: () => cause,
+    stopTimer: () => clearTimeout(timeoutId),
+    close: () => {
+      clearTimeout(timeoutId);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+  };
+}
+async function fetchInAbortScope(url, init, timeout, customFetch = fetch) {
+  const callerSignal = init.signal ?? void 0;
+  if (callerSignal?.aborted) {
+    return { ok: false, error: callerSignal.reason, cause: "caller" };
+  }
+  const scope = openAbortScope(callerSignal, timeout);
   try {
-    const response = await customFetch(url, {
-      ...init,
-      signal: controller.signal
-    });
-    clearTimeout(timeoutId);
-    return response;
+    const response = await customFetch(url, { ...init, signal: scope.signal });
+    scope.stopTimer();
+    const body = await parseResponseBody(response);
+    if (scope.cause() === "caller") {
+      return { ok: false, error: callerSignal?.reason, cause: "caller" };
+    }
+    return { ok: true, response, body };
   } catch (error) {
-    clearTimeout(timeoutId);
-    throw error;
+    const cause = scope.cause();
+    return { ok: false, cause, error: cause === "caller" ? callerSignal?.reason : error };
+  } finally {
+    scope.close();
   }
 }
 async function handleErrorResponse(response, body, fullUrl, errorRegistry, debug, logger3) {
@@ -180,7 +206,40 @@ async function handleErrorResponse(response, body, fullUrl, errorRegistry, debug
   );
 }
 
+// src/nextjs/client/csrf.ts
+var CSRF_HEADER = "x-spfn-csrf";
+var CSRF_COOKIE_PATTERN = /^spfn_csrf(_\d+)?$/;
+var HEADER_SAFE_VALUE = /^[!-~]+$/;
+var MAX_CANDIDATES = 32;
+function selectCandidates(values) {
+  const unique = Array.from(new Set(values));
+  if (unique.length <= MAX_CANDIDATES) {
+    return unique;
+  }
+  const half = MAX_CANDIDATES / 2;
+  return [...unique.slice(0, half), ...unique.slice(-half)];
+}
+function csrfHeaderValue(cookies) {
+  const values = Array.from(cookies).filter(([name, value]) => CSRF_COOKIE_PATTERN.test(name) && HEADER_SAFE_VALUE.test(value) && !value.includes(",")).map(([, value]) => value);
+  const candidates = selectCandidates(values);
+  return candidates.length > 0 ? candidates.join(",") : void 0;
+}
+function documentCookieEntries() {
+  if (typeof document === "undefined" || !document.cookie) {
+    return [];
+  }
+  const entries = [];
+  for (const pair of document.cookie.split(";")) {
+    const separator = pair.indexOf("=");
+    if (separator > 0) {
+      entries.push([pair.slice(0, separator).trim(), pair.slice(separator + 1).trim()]);
+    }
+  }
+  return entries;
+}
+
 // src/nextjs/client/builder.ts
+var MAX_TIMEOUT_MS = 2147483647;
 var RouteCallBuilder = class _RouteCallBuilder {
   constructor(executor, routeName) {
     this.executor = executor;
@@ -189,6 +248,7 @@ var RouteCallBuilder = class _RouteCallBuilder {
   _headers;
   _cookies;
   _fetchOptions;
+  _timeout;
   _onRequest;
   _onResponse;
   /**
@@ -202,6 +262,7 @@ var RouteCallBuilder = class _RouteCallBuilder {
     builder._headers = this._headers;
     builder._cookies = this._cookies;
     builder._fetchOptions = this._fetchOptions;
+    builder._timeout = this._timeout;
     builder._onRequest = this._onRequest;
     builder._onResponse = this._onResponse;
     return builder;
@@ -230,6 +291,20 @@ var RouteCallBuilder = class _RouteCallBuilder {
     builder._fetchOptions = { ...this._fetchOptions, ...options };
     return builder;
   }
+  /**
+   * Set this call's timeout in milliseconds, overriding the client-wide one
+   *
+   * Throws a `TypeError`, before any request is made, unless `ms` is a finite number
+   * greater than 0 and at most 2147483647 (the largest delay `setTimeout` honours).
+   */
+  timeout(ms) {
+    if (!Number.isFinite(ms) || ms <= 0 || ms > MAX_TIMEOUT_MS) {
+      throw new TypeError(`timeout must be a finite number of milliseconds in (0, ${MAX_TIMEOUT_MS}], got ${String(ms)}`);
+    }
+    const builder = this.clone();
+    builder._timeout = ms;
+    return builder;
+  }
   /**
    * Set request interceptor
    */
@@ -265,6 +340,9 @@ var RouteCallBuilder = class _RouteCallBuilder {
     if (this._fetchOptions) {
       options.fetchOptions = this._fetchOptions;
     }
+    if (this._timeout !== void 0) {
+      options.timeout = this._timeout;
+    }
     if (this._onRequest) {
       options.onRequest = this._onRequest;
     }
@@ -277,6 +355,28 @@ var RouteCallBuilder = class _RouteCallBuilder {
 
 // src/nextjs/client/core.ts
 var apiLogger = logger.child("@spfn/core:api-client");
+function transportError(failure, site, timeout) {
+  if (failure.cause === "timeout") {
+    apiLogger.error("Request timeout", { ...site, timeout });
+    return new ApiError(`Request timeout after ${timeout}ms`, 408, site.url, void 0, "timeout");
+  }
+  if (failure.cause === "caller") {
+    apiLogger.debug("Request aborted by caller", site);
+    return new ApiError("Request aborted", 0, site.url, void 0, "aborted", { cause: failure.error });
+  }
+  const { error } = failure;
+  if (error instanceof Error && error.name === "AbortError") {
+    apiLogger.error("Request timeout", { ...site, timeout });
+    return new ApiError(`Request timeout after ${timeout}ms`, 408, site.url, void 0, "timeout");
+  }
+  const errorMessage = error instanceof Error ? error.message : "Network error";
+  apiLogger.error("Network error", {
+    ...site,
+    error: errorMessage,
+    errorName: error instanceof Error ? error.name : "unknown"
+  });
+  return new ApiError(errorMessage, 0, site.url, void 0, "network");
+}
 function createApi(config = {}) {
   const {
     baseUrl = "/api/rpc",
@@ -335,6 +435,13 @@ function createApi(config = {}) {
     if (Object.keys(cookiesToSend).length > 0) {
       headers["Cookie"] = buildCookieHeader(cookiesToSend);
     }
+    const csrfToken = csrfHeaderValue(
+      typeof window === "undefined" ? Object.entries(cookiesToSend) : documentCookieEntries()
+    );
+    const csrfSetByCaller = Object.keys(headers).some((name) => name.toLowerCase() === CSRF_HEADER);
+    if (csrfToken && !csrfSetByCaller) {
+      headers[CSRF_HEADER] = csrfToken;
+    }
     if (debug && Object.keys(autoDetectedCookies).length > 0) {
       const cookieArray = Object.entries(autoDetectedCookies).map(([name, value]) => ({ name, value }));
       logCookieAutoDetection(apiLogger, cookieArray);
@@ -385,55 +492,24 @@ function createApi(config = {}) {
     if (debug) {
       logRequest(apiLogger, routeName, method, fullUrl, !!init.body);
     }
-    let response;
-    let body;
-    try {
-      response = await executeFetchWithTimeout(fullUrl, init, timeout, customFetch);
-      body = await parseResponseBody(response);
-      if (globalOnResponse) {
-        const result = await globalOnResponse(response, body);
-        response = result.response;
-        body = result.body;
-      }
-      if (options.onResponse) {
-        const result = await options.onResponse(response, body);
-        response = result.response;
-        body = result.body;
-      }
-      if (debug) {
-        logResponse(apiLogger, routeName, response.status, !!body);
-      }
-    } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") {
-        apiLogger.error("Request timeout", {
-          route: routeName,
-          method,
-          url: fullUrl,
-          timeout
-        });
-        throw new ApiError(
-          `Request timeout after ${timeout}ms`,
-          408,
-          fullUrl,
-          void 0,
-          "timeout"
-        );
-      }
-      const errorMessage = error instanceof Error ? error.message : "Network error";
-      apiLogger.error("Network error", {
-        route: routeName,
-        method,
-        url: fullUrl,
-        error: errorMessage,
-        errorName: error instanceof Error ? error.name : "unknown"
-      });
-      throw new ApiError(
-        errorMessage,
-        0,
-        fullUrl,
-        void 0,
-        "network"
-      );
+    const appliedTimeout = options.timeout ?? timeout;
+    const fetched = await fetchInAbortScope(fullUrl, init, appliedTimeout, customFetch);
+    if (!fetched.ok) {
+      throw transportError(fetched, { route: routeName, method, url: fullUrl }, appliedTimeout);
+    }
+    let { response, body } = fetched;
+    if (globalOnResponse) {
+      const result = await globalOnResponse(response, body);
+      response = result.response;
+      body = result.body;
+    }
+    if (options.onResponse) {
+      const result = await options.onResponse(response, body);
+      response = result.response;
+      body = result.body;
+    }
+    if (debug) {
+      logResponse(apiLogger, routeName, response.status, !!body);
     }
     if (!response.ok) {
       await handleErrorResponse(response, body, fullUrl, errorRegistry$1, debug, apiLogger);
@@ -457,6 +533,6 @@ function createApi(config = {}) {
   return buildProxy();
 }
 
-export { ApiError, createApi };
+export { ApiError, CSRF_HEADER, createApi, csrfHeaderValue, documentCookieEntries };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map