okengine 0.18.4 → 0.19.0

package/src/client/auth.ts

@@ -1,120 +1,45 @@
 /**
  * Optional auth helpers for {@link createClient} — not a second client factory.
  *
+ * Prefer `createClient(url, { auth: { mode, … } })` so `api.auth` is attached.
+ * {@link createAuthClient} remains the compose / bind escape hatch.
+ *
  * @module
  */
 
-/** Common auth Flow error codes (server `fail` codes). */
-export const AUTH_ERROR_CODES = {
-  AuthFailed: "AuthFailed",
-  AuthRateLimited: "AuthRateLimited",
-  Unauthorized: "Unauthorized",
-  Forbidden: "Forbidden",
-} as const;
-
-/** In-memory session token bag for SPA / Node clients. */
-export interface MemorySession {
-  accessToken: string | null;
-  refreshToken: string | null;
-  accessExpiresAt: number | null;
-  userId: string | null;
-  set(tokens: {
-    readonly accessToken: string;
-    readonly refreshToken: string;
-    readonly accessExpiresAt?: number;
-    readonly userId?: string;
-  }): void;
-  clear(): void;
-  /** Wire into `createClient` `auth.getToken`. */
-  getToken(): string | null;
-  /**
-   * Wire into `createClient` `auth.refresh` — calls the refresh Flow via the client.
-   *
-   * @param api - Client with `auth.refresh` route (or custom path)
-   */
-  refresh(api: {
-    auth: {
-      refresh: (input: { refreshToken: string }) => Promise<{
-        data: {
-          accessToken: string;
-          refreshToken: string;
-          accessExpiresAt?: number;
-          userId?: string;
-        } | null;
-        error: unknown;
-      }>;
-    };
-  }): Promise<string | null>;
-}
-
-/**
- * Create an in-memory session helper for Bearer `createClient` wiring.
- */
-export function memorySession(): MemorySession {
-  const state: {
-    accessToken: string | null;
-    refreshToken: string | null;
-    accessExpiresAt: number | null;
-    userId: string | null;
-  } = {
-    accessToken: null,
-    refreshToken: null,
-    accessExpiresAt: null,
-    userId: null,
-  };
-
-  return {
-    get accessToken() {
-      return state.accessToken;
-    },
-    set accessToken(v) {
-      state.accessToken = v;
-    },
-    get refreshToken() {
-      return state.refreshToken;
-    },
-    set refreshToken(v) {
-      state.refreshToken = v;
-    },
-    get accessExpiresAt() {
-      return state.accessExpiresAt;
-    },
-    set accessExpiresAt(v) {
-      state.accessExpiresAt = v;
-    },
-    get userId() {
-      return state.userId;
-    },
-    set userId(v) {
-      state.userId = v;
-    },
-    set(tokens) {
-      state.accessToken = tokens.accessToken;
-      state.refreshToken = tokens.refreshToken;
-      state.accessExpiresAt = tokens.accessExpiresAt ?? null;
-      state.userId = tokens.userId ?? null;
-    },
-    clear() {
-      state.accessToken = null;
-      state.refreshToken = null;
-      state.accessExpiresAt = null;
-      state.userId = null;
-    },
-    getToken() {
-      return state.accessToken;
-    },
-    async refresh(api) {
-      if (!state.refreshToken) return null;
-      const { data, error } = await api.auth.refresh({ refreshToken: state.refreshToken });
-      if (error || !data) {
-        state.accessToken = null;
-        return null;
-      }
-      state.accessToken = data.accessToken;
-      state.refreshToken = data.refreshToken;
-      state.accessExpiresAt = data.accessExpiresAt ?? null;
-      if (data.userId) state.userId = data.userId;
-      return data.accessToken;
-    },
-  };
-}
+export {
+  AUTH_ERROR_CODES,
+  forbiddenScopes,
+  isAuthRateLimited,
+  isCsrf,
+  isForbidden,
+  isSessionTokens,
+  isTwoFactorRequired,
+  isUnauthorized,
+} from "./auth/denials.ts";
+export {
+  createAuthClient,
+  type AuthApi,
+  type AuthClient,
+  type AuthMode,
+  type AuthPersist,
+  type AuthorizeQuery,
+  type AuthorizeResult,
+  type CreateAuthClientOptions,
+  type SignInResult,
+} from "./auth/create-auth-client.ts";
+export {
+  tokenFromRequestCookies,
+  type CookieSource,
+  type TokenFromCookiesOptions,
+} from "./auth/cookies.ts";
+export { createServerClient } from "./create-with-session.ts";
+export {
+  memorySession,
+  persistSession,
+  type MemorySession,
+  type MemorySessionOptions,
+  type SessionListener,
+  type SessionTokens,
+  type SessionUser,
+} from "./auth/session.ts";

package/src/client/create-with-session.ts

@@ -0,0 +1,245 @@
+/**
+ * `createClient` with optional session `auth` → `api.auth` ({@link AuthClient}).
+ *
+ * Bare transport stays in {@link ./create.ts} (budget entry). This wrapper is
+ * what `okengine/client` exports.
+ *
+ * @module
+ */
+
+import {
+  createAuthClient,
+  type AuthApi,
+  type AuthClient,
+  type CreateAuthClientOptions,
+} from "./auth/create-auth-client.ts";
+import { tokenFromRequestCookies, type CookieSource } from "./auth/cookies.ts";
+import {
+  createClient as createClientCore,
+  flattenRoutes,
+  transportOf,
+  type AppWithRoutes,
+  type TransportBag,
+} from "./create.ts";
+import type {
+  Client,
+  ClientHeaders,
+  ClientOptions,
+  ClientSessionAuthOptions,
+  ClientTransportAuth,
+  ResolveApp,
+} from "./types.ts";
+
+export { flattenRoutes, transportOf };
+export type { AppWithRoutes, TransportBag };
+
+/** Session-option keys that distinguish orchestration from bare transport hooks. */
+const SESSION_AUTH_KEYS = [
+  "mode",
+  "persist",
+  "csrfConfigured",
+  "storageKey",
+  "session",
+  "tenantHeader",
+  "env",
+] as const;
+
+/**
+ * True when `auth` is bare `{ getToken, refresh }` without session keys.
+ *
+ * @param auth - Client auth option
+ */
+export function isTransportAuthOnly(auth: unknown): auth is ClientTransportAuth {
+  if (auth === null || typeof auth !== "object") return false;
+  const bag = auth as Record<string, unknown>;
+  const hasHooks = typeof bag.getToken === "function" && typeof bag.refresh === "function";
+  if (!hasHooks) return false;
+  for (const key of SESSION_AUTH_KEYS) {
+    if (key in bag && bag[key] !== undefined) return false;
+  }
+  return true;
+}
+
+/**
+ * True when `auth` should construct an {@link AuthClient} on the client.
+ *
+ * @param auth - Client auth option
+ */
+export function isSessionAuthOptions(auth: unknown): auth is ClientSessionAuthOptions {
+  return auth !== null && typeof auth === "object" && !isTransportAuthOnly(auth);
+}
+
+/**
+ * Create a fully typed client from an adopted app value (types + REST).
+ *
+ * @typeParam App - `typeof app` after `.adopt({ notes })`
+ */
+export function createClient<App extends AppWithRoutes>(
+  app: App,
+  url: string,
+  opts?: ClientOptions,
+): Client<App>;
+
+/**
+ * Create a fully typed client from an App type argument / ambient Register.
+ *
+ * @typeParam App - `typeof app`, {@link AppOf} route map, or omit for {@link Register}
+ */
+export function createClient<App = never>(
+  url: string,
+  opts?: ClientOptions,
+): Client<ResolveApp<App>>;
+
+/**
+ * @param appOrUrl - App instance or base URL
+ * @param urlOrOpts - Base URL (when app given) or options
+ * @param maybeOpts - Options when app + url form is used
+ */
+export function createClient(
+  appOrUrl: AppWithRoutes | string,
+  urlOrOpts?: string | ClientOptions,
+  maybeOpts?: ClientOptions,
+): Client {
+  const { url, opts } = normalizeArgs(appOrUrl, urlOrOpts, maybeOpts);
+  if (!opts?.auth || isTransportAuthOnly(opts.auth)) {
+    return createClientCore(appOrUrl as never, urlOrOpts as never, maybeOpts as never);
+  }
+  return buildWithSession(url, opts);
+}
+
+function normalizeArgs(
+  appOrUrl: AppWithRoutes | string,
+  urlOrOpts?: string | ClientOptions,
+  maybeOpts?: ClientOptions,
+): { url: string; opts: ClientOptions } {
+  if (typeof appOrUrl === "string") {
+    return { url: appOrUrl, opts: (urlOrOpts as ClientOptions | undefined) ?? {} };
+  }
+  const url = typeof urlOrOpts === "string" ? urlOrOpts : "";
+  const opts = (typeof urlOrOpts === "string" ? maybeOpts : urlOrOpts) ?? {};
+  return {
+    url,
+    opts: { ...opts, $routes: opts.$routes ?? appOrUrl.$routes },
+  };
+}
+
+function buildWithSession(url: string, opts: ClientOptions): Client {
+  const sessionOpts = opts.auth as CreateAuthClientOptions;
+  const { auth: _drop, ...rest } = opts;
+  const shell = createClientCore(url, rest) as Client & AuthApi;
+  const authClient = createAuthClient(shell, sessionOpts);
+  const merged = mergeClientOptions(rest, authClient, sessionOpts);
+  const api = createClientCore(url, merged) as Client & AuthApi;
+  authClient.bind(api);
+  return attachAuth(api, authClient);
+}
+
+function mergeClientOptions(
+  base: ClientOptions,
+  authClient: AuthClient,
+  sessionOpts: CreateAuthClientOptions,
+): ClientOptions {
+  const fromAuth = authClient.clientOptions;
+  const transportAuth: ClientTransportAuth = {
+    getToken: sessionOpts.getToken ?? fromAuth.auth?.getToken ?? (() => null),
+    refresh: sessionOpts.refresh ?? fromAuth.auth?.refresh ?? (async () => null),
+  };
+  return {
+    ...base,
+    credentials: fromAuth.credentials ?? base.credentials,
+    auth: transportAuth,
+    headers: mergeHeaderGetters(base.headers, fromAuth.headers),
+  };
+}
+
+function mergeHeaderGetters(
+  base: ClientOptions["headers"],
+  over: (() => Record<string, string>) | undefined,
+): ClientOptions["headers"] {
+  if (!over) return base;
+  if (!base) return over;
+  return async () => {
+    const a = typeof base === "function" ? await base() : base;
+    const b = over();
+    return mergeHeaderBags(a, b);
+  };
+}
+
+function mergeHeaderBags(a: ClientHeaders | undefined, b: Record<string, string>): ClientHeaders {
+  if (!a) return b;
+  if (!Array.isArray(a)) return { ...a, ...b };
+  return [...a, ...Object.entries(b)];
+}
+
+/**
+ * Attach {@link AuthClient} at `api.auth`, preserving unit Flow access
+ * (`api.auth.me`, `api.auth.signInEmail`, …) for unbound props.
+ *
+ * @param api - Typed client
+ * @param auth - Session helper
+ */
+function attachAuth(api: Client, auth: AuthClient): Client {
+  return new Proxy(api as object, {
+    get(target, prop, receiver) {
+      if (prop === "auth") {
+        const flows = Reflect.get(target, "auth", receiver);
+        return mergeAuthSurface(auth, flows);
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  }) as Client;
+}
+
+function mergeAuthSurface(auth: AuthClient, flows: unknown): AuthClient {
+  return new Proxy(auth as object, {
+    get(target, prop, receiver) {
+      if (typeof prop === "symbol") return Reflect.get(target, prop, receiver);
+      if (prop in (target as object)) return Reflect.get(target, prop, receiver);
+      if (flows !== null && (typeof flows === "object" || typeof flows === "function")) {
+        return Reflect.get(flows as object, prop, flows);
+      }
+      return undefined;
+    },
+    has(target, prop) {
+      if (prop in (target as object)) return true;
+      if (flows === null || (typeof flows !== "object" && typeof flows !== "function")) {
+        return false;
+      }
+      // Unit namespaces from createClient are Proxies that often implement get
+      // without has — treat a defined get as present so `"me" in api.auth` works.
+      if (prop in (flows as object)) return true;
+      return Reflect.get(flows as object, prop, flows) !== undefined;
+    },
+  }) as AuthClient;
+}
+
+/**
+ * Thin SSR helper — same {@link createClient} with cookie token from the request.
+ *
+ * @param req - Incoming request (cookies)
+ * @param url - API base URL
+ * @param opts - Client options
+ */
+export function createServerClient(
+  req: CookieSource,
+  url: string,
+  opts: ClientOptions = {},
+): Client {
+  const prior = opts.auth;
+  const sessionBase =
+    prior && isSessionAuthOptions(prior)
+      ? prior
+      : prior && isTransportAuthOnly(prior)
+        ? {}
+        : ((prior as ClientSessionAuthOptions | undefined) ?? {});
+  return createClient(url, {
+    ...opts,
+    credentials: opts.credentials ?? "include",
+    auth: {
+      ...sessionBase,
+      mode: "cookie",
+      csrfConfigured: "csrfConfigured" in sessionBase ? sessionBase.csrfConfigured : true,
+      getToken: () => tokenFromRequestCookies(req),
+    },
+  });
+}

package/src/client/create.ts

@@ -22,11 +22,13 @@ import {
   type LiveByFlow,
   type LiveRouteTable,
 } from "./live.ts";
+import { flattenStreamRoutes, openStream, type StreamByFlow } from "./stream.ts";
 import type {
   Client,
   ClientHeaders,
   ClientLive,
   ClientOptions,
+  ClientResult,
   ClientRouteMap,
   LiveHandlers,
   ResolveApp,
@@ -97,6 +99,7 @@ function buildClient(url: string, opts: ClientOptions = {}): Client {
   const base = url.replace(/\/+$/, "");
   const routes = opts.routes ?? flattenRoutes(opts.$routes);
   const live = flattenLiveRoutes(opts.$routes);
+  const streamByFlow = flattenStreamRoutes(opts.$routes);
   const transport = createTransport(base, { ...opts, routes });
   const perCallHeaders = createPerCallHeaders();
   return proxy(transport, [], {
@@ -104,6 +107,7 @@ function buildClient(url: string, opts: ClientOptions = {}): Client {
     opts,
     liveBySignal: live.bySignal,
     liveByFlow: live.byFlow,
+    streamByFlow,
     perCallHeaders,
   }) as Client;
 }
@@ -113,6 +117,7 @@ type ProxyCtx = {
   readonly opts: ClientOptions;
   readonly liveBySignal: LiveRouteTable;
   readonly liveByFlow: LiveByFlow;
+  readonly streamByFlow: StreamByFlow;
   /**
    * Extra headers attached to the next transport call, then cleared — the
    * `X-Oke-Mutation-Id` channel for optimistic dedupe (one-shot by design;
@@ -187,7 +192,7 @@ export function flattenRoutes(
  * @param path - Accumulated property path
  */
 function proxy(transport: Transport, path: readonly string[], ctx: ProxyCtx): unknown {
-  const invoke = async (input?: unknown) => {
+  const invoke = async (input?: unknown, callOpts?: CallOpts): Promise<ClientResult> => {
     if (path.length < 2) {
       return attachPager(
         {
@@ -199,16 +204,20 @@ function proxy(transport: Transport, path: readonly string[], ctx: ProxyCtx): un
             },
           },
         },
-        invoke,
+        (nextInput) => invoke(nextInput, callOpts),
         input,
       );
     }
     const unit = path[0]!;
     const flow = path.slice(1).join(".");
-    const result = await transport.call(`${unit}/${flow}`, input, ctx.perCallHeaders.read());
-    return attachPager(result, invoke, input);
+    const result = await transport.call(`${unit}/${flow}`, input, {
+      headers: ctx.perCallHeaders.read(),
+      ...(callOpts?.response !== undefined ? { response: callOpts.response } : {}),
+      ...(callOpts?.signal !== undefined ? { signal: callOpts.signal } : {}),
+    });
+    return attachPager(result, (nextInput) => invoke(nextInput, callOpts), input);
   };
-  const call = (a?: unknown, b?: unknown) => {
+  const call = (a?: unknown, b?: unknown): unknown => {
     if (path.length >= 2) {
       const key = `${path[0]}.${path.slice(1).join(".")}`;
       const exposure = ctx.liveByFlow[key];
@@ -217,6 +226,20 @@ function proxy(transport: Transport, path: readonly string[], ctx: ProxyCtx): un
         const input = isLiveHandlers(a) ? undefined : a;
         return subscribeLive(ctx.base, exposure, input, handlers, ctx.opts);
       }
+      const streamRoute = ctx.streamByFlow[key];
+      if (streamRoute) {
+        const input = isCallOpts(a) ? undefined : a;
+        const opts = isCallOpts(a) ? a : isCallOpts(b) ? b : undefined;
+        const merged: ClientOptions = opts?.signal
+          ? { ...ctx.opts, signal: opts.signal }
+          : ctx.opts;
+        return openStream(ctx.base, streamRoute, input, merged);
+      }
+      if (isCallOpts(a) || isCallOpts(b)) {
+        const input = isCallOpts(a) ? undefined : a;
+        const opts = (isCallOpts(a) ? a : b) as CallOpts;
+        return asThenableIterable((next) => invoke(next, opts), input);
+      }
     }
     return asThenableIterable(invoke, a);
   };
@@ -313,3 +336,26 @@ function makeLive(ctx: ProxyCtx): ClientLive {
     return subscribeLive(ctx.base, exposure, input, handlers, ctx.opts);
   }) as ClientLive;
 }
+
+function isCallOpts(value: unknown): value is CallOpts {
+  if (value === null || typeof value !== "object" || isLiveHandlers(value)) return false;
+  const v = value as Record<string, unknown>;
+  if ("response" in v) {
+    return (
+      v.response === undefined ||
+      v.response === "json" ||
+      v.response === "blob" ||
+      v.response === "arrayBuffer"
+    );
+  }
+  if ("signal" in v) {
+    return v.signal === undefined || v.signal instanceof AbortSignal;
+  }
+  return false;
+}
+
+/** Per-call options on a Flow invoke (binary decode / abort). */
+export interface CallOpts {
+  readonly response?: "json" | "blob" | "arrayBuffer";
+  readonly signal?: AbortSignal;
+}

package/src/client/index.ts

@@ -13,7 +13,12 @@ export {
   nextResubscribeDelay,
   pickLiveExposure,
 } from "./live.ts";
-export { createClient, flattenRoutes, transportOf } from "./create.ts";
+export {
+  createClient,
+  flattenRoutes,
+  transportOf,
+  createServerClient,
+} from "./create-with-session.ts";
 export type { AppWithRoutes, TransportBag } from "./create.ts";
 export { isErrorCode, isFail, isOk, isTransportError } from "./errors.ts";
 export { isPagerMeta, pagerLink } from "./pager.ts";
@@ -32,12 +37,17 @@ export type {
   Client,
   ClientApp,
   ClientCall,
+  ClientCallOpts,
   ClientDescriptor,
   ClientError,
   ClientFetch,
   ClientFromRoutes,
   ClientHeaders,
+  ClientBodyInit,
+  ClientCredentials,
   ClientOptions,
+  ClientSessionAuthOptions,
+  ClientTransportAuth,
   ClientEnvelope,
   ClientListMeta,
   ClientPagerLink,

package/src/client/live.ts

@@ -4,6 +4,7 @@
 
 import type { ClientFetch, ClientOptions, ClientRouteMap, FlowContract } from "./types.ts";
 import type { LiveHandlers, LiveUnsubscribe } from "./types.ts";
+import { readSse, sseError } from "./sse.ts";
 
 /** One HTTP exposure of a live signal. */
 export interface LiveExposure {
@@ -285,13 +286,21 @@ async function openSse(
   } else if (extra) {
     for (const [k, v] of Object.entries(extra)) headers.set(k, v);
   }
-  const token = opts.auth ? await opts.auth.getToken() : undefined;
+  const token =
+    opts.auth && "getToken" in opts.auth && typeof opts.auth.getToken === "function"
+      ? await opts.auth.getToken()
+      : undefined;
   if (token && !headers.has("authorization")) {
     headers.set("authorization", `Bearer ${token}`);
   }
   if (lastSeenId) headers.set("last-event-id", lastSeenId);
   const fetchFn: ClientFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
-  return fetchFn(url, { method, headers, signal });
+  return fetchFn(url, {
+    method,
+    headers,
+    signal,
+    ...(opts.credentials !== undefined ? { credentials: opts.credentials } : {}),
+  });
 }
 
 function restGet(base: string, path: string, input: unknown): { url: string; method: string } {
@@ -310,80 +319,3 @@ function restGet(base: string, path: string, input: unknown): { url: string; met
   const qs = query.length ? `?${query.join("&")}` : "";
   return { url: `${base}${pathOut}${qs}`, method: "GET" };
 }
-
-async function readSse(
-  res: Response,
-  onEvent: (event: unknown, id: string | undefined) => void,
-  signal: AbortSignal,
-  onOpen?: () => void,
-): Promise<void> {
-  if (signal.aborted) return;
-  const ct = res.headers.get("content-type") ?? "";
-  if (!res.ok || !res.body) {
-    const text = await res.text().catch(() => "");
-    throw sseError(res.status, text);
-  }
-  if (!ct.includes("text/event-stream")) {
-    const text = await res.text().catch(() => "");
-    throw sseError(res.status, text || `Expected text/event-stream, got ${ct || "none"}`);
-  }
-  onOpen?.();
-  const reader = res.body.getReader();
-  const dec = new TextDecoder();
-  let buf = "";
-  try {
-    for (;;) {
-      if (signal.aborted) return;
-      const { done, value } = await reader.read();
-      if (done) break;
-      buf += dec.decode(value, { stream: true });
-      let sep = buf.indexOf("\n\n");
-      while (sep >= 0) {
-        const raw = buf.slice(0, sep);
-        buf = buf.slice(sep + 2);
-        const stop = dispatchFrame(raw, onEvent, signal);
-        if (stop || signal.aborted) return;
-        sep = buf.indexOf("\n\n");
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-
-function dispatchFrame(
-  raw: string,
-  onEvent: (event: unknown, id: string | undefined) => void,
-  signal: AbortSignal,
-): boolean {
-  const dataLines: string[] = [];
-  let id: string | undefined;
-  for (const line of raw.split("\n")) {
-    if (line.startsWith("id:")) id = line.slice(3).replace(/^ /, "");
-    if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
-  }
-  if (dataLines.length === 0) return false;
-  const data = dataLines.join("\n");
-  if (data === "[DONE]") return true;
-  if (signal.aborted) return true;
-  onEvent(JSON.parse(data) as unknown, id);
-  return false;
-}
-
-function sseError(status: number, body: string): Error {
-  let message = `HTTP ${status}`;
-  if (body) {
-    try {
-      const json: unknown = JSON.parse(body);
-      if (json !== null && typeof json === "object" && "error" in json) {
-        const err = (json as { error?: { code?: string; data?: { message?: string } } }).error;
-        message = err?.data?.message ?? err?.code ?? message;
-      }
-    } catch {
-      message = body.slice(0, 200);
-    }
-  }
-  const e = new Error(message);
-  (e as Error & { status?: number }).status = status;
-  return e;
-}