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

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-CKH0D3Dy.js';
+export { c as ApiError, d as ApiOutcome, C as CallOptions, e as CookieOptions, f as RouterInput, g as RouterOutput, S as SetCookie, h as StructuredInput } from '../types-CKH0D3Dy.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
@@ -107,14 +143,39 @@ type Client<TRouter extends Router<any>> = {
 declare function createApi<TRouter extends Router<any>>(config?: ApiConfig): Client<TRouter>;
 
 /**
- * Typed client error
+ * 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 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);
-}
+declare function documentCookieEntries(): Array<[string, string]>;
 
-export { ApiConfig, ApiError, type Client, InferRouteInput, InferRouteOutput, RequestInterceptor, ResponseInterceptor, type RouteClient, createApi };
+export { ApiConfig, 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;
@@ -103,7 +103,7 @@ async function autoDetectServerCookies() {
     return {};
   }
   try {
-    const { cookies } = await import('next/headers');
+    const { cookies } = await import('next/headers.js');
     const cookieStore = await cookies();
     const allCookies = cookieStore.getAll();
     const result = Object.fromEntries(
@@ -123,55 +123,90 @@ 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) {
+function errorFromResponse(response, body, fullUrl, errorRegistry, debug, logger3) {
   if (debug) {
     logErrorResponse(logger3, response.status, body);
   }
-  let deserializedError = null;
-  if (errorRegistry && body && typeof body === "object" && "__type" in body) {
+  const deserializedError = deserializeRegisteredError(body, errorRegistry, debug, logger3);
+  if (deserializedError) {
     if (debug) {
-      logErrorDeserializationAttempt(logger3, body.__type, errorRegistry.getRegisteredTypes());
+      logThrowingDeserializedError(logger3, deserializedError);
     }
-    try {
-      deserializedError = errorRegistry.deserialize(body);
-      if (debug) {
-        logErrorDeserializationSuccess(logger3, deserializedError);
-      }
-    } catch (deserializeError) {
-      if (debug) {
-        logErrorDeserializationFailure(logger3, deserializeError);
-      }
+    return deserializedError;
+  }
+  return fallbackApiError(response, body, fullUrl, logger3);
+}
+function deserializeRegisteredError(body, errorRegistry, debug, logger3) {
+  if (!errorRegistry || !body || typeof body !== "object" || !("__type" in body)) {
+    if (debug) {
+      logErrorDeserializationSkipped(logger3, errorRegistry, body);
     }
-  } else if (debug) {
-    logErrorDeserializationSkipped(logger3, errorRegistry, body);
+    return null;
   }
-  if (deserializedError) {
+  if (debug) {
+    logErrorDeserializationAttempt(logger3, body.__type, errorRegistry.getRegisteredTypes());
+  }
+  try {
+    const deserializedError = errorRegistry.deserialize(body);
     if (debug) {
-      logThrowingDeserializedError(logger3, deserializedError);
+      logErrorDeserializationSuccess(logger3, deserializedError);
+    }
+    return deserializedError;
+  } catch (deserializeError) {
+    if (debug) {
+      logErrorDeserializationFailure(logger3, deserializeError);
     }
-    throw deserializedError;
+    return null;
   }
+}
+function fallbackApiError(response, body, fullUrl, logger3) {
   if (response.status === 404 && process.env.NODE_ENV !== "production") {
     logger3.warn(
       "\n\u26A0\uFE0F  404 Not Found\n\nCheck the following:\n  1. Routes are registered in server.config.ts:\n     \u2192 defineServerConfig().routes(appRouter)\n  2. Delete .spfn cache if you recently added new routes:\n     \u2192 rm -rf .spfn\n"
     );
   }
-  throw new ApiError(
+  return new ApiError(
     body?.message || `HTTP ${response.status}: ${response.statusText}`,
     response.status,
     fullUrl,
@@ -180,7 +215,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 +257,7 @@ var RouteCallBuilder = class _RouteCallBuilder {
   _headers;
   _cookies;
   _fetchOptions;
+  _timeout;
   _onRequest;
   _onResponse;
   /**
@@ -202,6 +271,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 +300,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 +349,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 +364,53 @@ var RouteCallBuilder = class _RouteCallBuilder {
 
 // src/nextjs/client/core.ts
 var apiLogger = logger.child("@spfn/core:api-client");
+function transportOutcome(errorType, message, status, url, options) {
+  return { ok: false, errorType, status, error: new ApiError(message, status, url, void 0, errorType, options) };
+}
+function transportError(failure, site, timeout) {
+  if (failure.cause === "timeout") {
+    apiLogger.error("Request timeout", { ...site, timeout });
+    return transportOutcome("timeout", `Request timeout after ${timeout}ms`, 408, site.url);
+  }
+  if (failure.cause === "caller") {
+    apiLogger.debug("Request aborted by caller", site);
+    return transportOutcome("aborted", "Request aborted", 0, site.url, { cause: failure.error });
+  }
+  const { error } = failure;
+  if (error instanceof Error && error.name === "AbortError") {
+    apiLogger.error("Request timeout", { ...site, timeout });
+    return transportOutcome("timeout", `Request timeout after ${timeout}ms`, 408, site.url);
+  }
+  const errorMessage = error instanceof Error ? error.message : "Network error";
+  apiLogger.error("Network error", {
+    ...site,
+    error: errorMessage,
+    errorName: error instanceof Error ? error.name : "unknown"
+  });
+  return transportOutcome("network", errorMessage, 0, site.url);
+}
+function notifyOutcome(onOutcome, outcome) {
+  if (!onOutcome) {
+    return;
+  }
+  try {
+    const returned = onOutcome(outcome);
+    if (isThenable(returned)) {
+      Promise.resolve(returned).catch(logObserverFailure);
+    }
+  } catch (error) {
+    logObserverFailure(error);
+  }
+}
+function isThenable(value) {
+  return typeof value?.then === "function";
+}
+function logObserverFailure(error) {
+  apiLogger.error("onOutcome observer failed; the call result is unchanged", {
+    errorName: error instanceof Error ? error.name : typeof error,
+    errorMessage: error instanceof Error ? error.message : String(error)
+  });
+}
 function createApi(config = {}) {
   const {
     baseUrl = "/api/rpc",
@@ -285,6 +419,7 @@ function createApi(config = {}) {
     fetch: customFetch = fetch,
     onRequest: globalOnRequest,
     onResponse: globalOnResponse,
+    onOutcome,
     errorRegistry: errorRegistryConfig,
     debug = false
   } = config;
@@ -299,7 +434,7 @@ function createApi(config = {}) {
     let appUrl = env.SPFN_APP_URL || "";
     if (!appUrl && typeof window === "undefined") {
       try {
-        const { headers: headers2 } = await import('next/headers');
+        const { headers: headers2 } = await import('next/headers.js');
         const headersList = await headers2();
         const host = headersList.get("host");
         const protocol = headersList.get("x-forwarded-proto") || "http";
@@ -335,6 +470,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,59 +527,33 @@ 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) {
+      const outcome = transportError(fetched, { route: routeName, method, url: fullUrl }, appliedTimeout);
+      notifyOutcome(onOutcome, outcome);
+      throw outcome.error;
+    }
+    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);
+      const error = errorFromResponse(response, body, fullUrl, errorRegistry$1, debug, apiLogger);
+      notifyOutcome(onOutcome, { ok: false, errorType: "http", status: response.status, error });
+      throw error;
     }
+    notifyOutcome(onOutcome, { ok: true, response, body });
     return body;
   }
   function buildProxy(prefix = "") {
@@ -457,6 +573,6 @@ function createApi(config = {}) {
   return buildProxy();
 }
 
-export { ApiError, createApi };
+export { ApiError, CSRF_HEADER, createApi, csrfHeaderValue, documentCookieEntries };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map