okengine 0.18.4 → 0.19.0

package/src/client/types.ts

@@ -185,6 +185,59 @@ export type ClientFetch = (input: string | URL | Request, init?: RequestInit) =>
 /** Header bag accepted by the client. */
 export type ClientHeaders = Record<string, string> | [string, string][];
 
+/**
+ * Fetch credentials mode (avoids DOM `RequestCredentials` coupling).
+ * Use `"include"` for cookie sessions.
+ */
+export type ClientCredentials = "include" | "omit" | "same-origin";
+
+/**
+ * Raw request body accepted by the transport (avoids DOM `BodyInit` coupling).
+ * Mirrors what {@link createTransport} treats as non-JSON via `instanceof` checks.
+ */
+export type ClientBodyInit =
+  | Blob
+  | FormData
+  | ArrayBuffer
+  | ArrayBufferView
+  | ReadableStream
+  | string
+  | URLSearchParams;
+
+/**
+ * Bare transport Bearer hooks (no {@link AuthClient}).
+ * Prefer session options (`mode` / `persist` / `csrfConfigured`) so
+ * `createClient` attaches `api.auth`.
+ */
+export interface ClientTransportAuth {
+  /** Current access token (Bearer), or null. */
+  readonly getToken: () => string | null | undefined | Promise<string | null | undefined>;
+  /** Obtain a new access token after 401. */
+  readonly refresh: () => Promise<string | null | undefined>;
+}
+
+/**
+ * Session orchestration options for `createClient({ auth })` → `api.auth`.
+ * Mirrors {@link CreateAuthClientOptions} plus optional SSR token overrides.
+ */
+export interface ClientSessionAuthOptions {
+  readonly mode?: "bearer" | "cookie";
+  readonly persist?: "memory" | "sessionStorage" | "localStorage";
+  readonly storageKey?: string;
+  readonly tenantHeader?: string;
+  readonly csrfConfigured?: boolean;
+  readonly session?: import("./auth/session.ts").MemorySession;
+  readonly env?: {
+    readonly localStorage?: Storage;
+    readonly sessionStorage?: Storage;
+    readonly warn?: (message: string) => void;
+  };
+  /** SSR / custom: override Bearer getToken (cookie mode still uses credentials). */
+  readonly getToken?: ClientTransportAuth["getToken"];
+  /** SSR / custom: override refresh after 401. */
+  readonly refresh?: ClientTransportAuth["refresh"];
+}
+
 /**
  * Options for {@link createClient}.
  */
@@ -205,15 +258,20 @@ export interface ClientOptions {
     readonly backoff?: number;
   };
   /**
-   * Auth token + refresh. On HTTP 401, `refresh` runs once and the
-   * request is retried with the new token.
+   * Session orchestration (`mode` / `csrfConfigured` / …) → attaches `api.auth`,
+   * or bare `{ getToken, refresh }` transport hooks only.
    */
-  readonly auth?: {
-    /** Current access token (Bearer), or null. */
-    readonly getToken: () => string | null | undefined | Promise<string | null | undefined>;
-    /** Obtain a new access token after 401. */
-    readonly refresh: () => Promise<string | null | undefined>;
-  };
+  readonly auth?: ClientTransportAuth | ClientSessionAuthOptions;
+  /**
+   * Fetch credentials mode. Use `"include"` for cookie sessions
+   * (`gate.auth.cookies` + `createClient({ auth: { mode: "cookie" } })`).
+   */
+  readonly credentials?: ClientCredentials;
+  /**
+   * Optional AbortSignal for all calls from this client (per-call override
+   * not yet exposed on the proxy).
+   */
+  readonly signal?: AbortSignal;
   /**
    * Runtime REST table (optional). Keys are `unit.flow`.
    * When absent, the client uses `POST /_oke/{unit}/{flow}` unless
@@ -234,6 +292,14 @@ export interface ClientOptions {
  */
 export type ClientThenableIterable<T> = PromiseLike<T> & AsyncIterable<T>;
 
+/**
+ * Per-call options on a Flow invoke (binary decode / abort).
+ */
+export interface ClientCallOpts {
+  readonly response?: "json" | "blob" | "arrayBuffer";
+  readonly signal?: AbortSignal;
+}
+
 /**
  * Call signature for one flow — thenable (one page) and async-iterable (walk).
  *
@@ -241,11 +307,25 @@ export type ClientThenableIterable<T> = PromiseLike<T> & AsyncIterable<T>;
  * @typeParam O - Output
  * @typeParam E - Errors
  */
-type ClientCallFn<I, O, E extends Record<string, unknown>> = [I] extends [void]
-  ? () => ClientThenableIterable<ClientResult<O, E>>
-  : Partial<I> extends I
-    ? (input?: I) => ClientThenableIterable<ClientResult<O, E>>
-    : (input: I) => ClientThenableIterable<ClientResult<O, E>>;
+type IsAnyInput<T> = 0 extends 1 & T ? true : false;
+
+type ClientCallFn<I, O, E extends Record<string, unknown>> =
+  IsAnyInput<I> extends true
+    ? {
+        (input?: I, opts?: ClientCallOpts): ClientThenableIterable<ClientResult<O, E>>;
+      }
+    : [I] extends [void]
+      ? {
+          (): ClientThenableIterable<ClientResult<O, E>>;
+          (opts: ClientCallOpts): ClientThenableIterable<ClientResult<O, E>>;
+        }
+      : Partial<I> extends I
+        ? {
+            (input?: I, opts?: ClientCallOpts): ClientThenableIterable<ClientResult<O, E>>;
+          }
+        : {
+            (input: I, opts?: ClientCallOpts): ClientThenableIterable<ClientResult<O, E>>;
+          };
 
 /**
  * Call signature for one flow. No `.pages()` — iterate the call or the page.
@@ -311,6 +391,12 @@ type ClientLiveOverloads = {
 
 type IsLiveContract<C> = C extends { readonly live: string } ? true : false;
 
+type IsStreamOnlyContract<C> = C extends { readonly stream: true }
+  ? IsLiveContract<C> extends true
+    ? false
+    : true
+  : false;
+
 type ClientLiveFlowCall<I, O> = [I] extends [void]
   ? (handlers: LiveHandlers<O>) => LiveUnsubscribe
   : Partial<I> extends I
@@ -320,10 +406,18 @@ type ClientLiveFlowCall<I, O> = [I] extends [void]
       }
     : (input: I, handlers: LiveHandlers<O>) => LiveUnsubscribe;
 
+type ClientStreamCall<I, O> = [I] extends [void]
+  ? (opts?: { readonly signal?: AbortSignal }) => AsyncIterable<O>
+  : Partial<I> extends I
+    ? (input?: I, opts?: { readonly signal?: AbortSignal }) => AsyncIterable<O>
+    : (input: I, opts?: { readonly signal?: AbortSignal }) => AsyncIterable<O>;
+
 type ClientCallFor<C> =
   IsLiveContract<C> extends true
     ? ClientLiveFlowCall<ContractIn<C>, ContractOut<C>>
-    : ClientCall<ContractIn<C>, ContractOut<C>, ContractErrors<C>>;
+    : IsStreamOnlyContract<C> extends true
+      ? ClientStreamCall<ContractIn<C>, ContractOut<C>>
+      : ClientCall<ContractIn<C>, ContractOut<C>, ContractErrors<C>>;
 
 /**
  * Pull input from a contract shape (supports required or phantom-optional `in`).
@@ -366,6 +460,12 @@ export type ClientFromRoutes<R extends ClientRouteMap> = {
  */
 export type Client<App = never> = ClientFromRoutes<RoutesOf<ResolveApp<App>>> & {
   readonly live: ClientLive<ResolveApp<App>>;
+  /**
+   * Present when `createClient` was constructed with session `auth` options
+   * (`mode` / `persist` / `csrfConfigured` / …). Merged over the `auth` unit
+   * Flows at runtime (`api.auth.me` still works).
+   */
+  readonly auth?: import("./auth/create-auth-client.ts").AuthClient;
 };
 
 /**
@@ -388,6 +488,10 @@ export interface ClientDescriptor {
         readonly errors?: Readonly<Record<string, string>>;
         readonly method?: string;
         readonly path?: string;
+        readonly live?: string;
+        readonly stream?: true;
+        readonly matchKey?: readonly string[];
+        readonly gates?: readonly string[];
       };
     };
   };

package/src/client-react/index.ts

@@ -18,11 +18,23 @@ export {
   type UseLiveQueryState,
 } from "./use-live-query.ts";
 
-import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
-import type { MemorySession } from "../client/auth.ts";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import type {
+  AuthClient,
+  AuthorizeQuery,
+  AuthorizeResult,
+} from "../client/auth/create-auth-client.ts";
+import type { MemorySession, SessionUser } from "../client/auth/session.ts";
 import type { ClientLive, LiveInput, LiveSignalHandle } from "../client/types.ts";
 
-/** Minimal client surface for session reading. */
+/** Minimal client surface for session reading (legacy). */
 export interface SessionClient {
   auth: {
     me: (input?: unknown) => Promise<{
@@ -31,6 +43,10 @@ export interface SessionClient {
         email: string;
         name: string;
         emailVerified?: boolean;
+        scopes?: readonly string[];
+        tenantId?: string | null;
+        apiKeyId?: string | null;
+        sessionFresh?: boolean;
       } | null;
       error: unknown;
     }>;
@@ -40,38 +56,57 @@ export interface SessionClient {
 /** Session snapshot returned by {@link useSession}. */
 export interface SessionState {
   readonly status: "loading" | "authenticated" | "unauthenticated";
-  readonly user: {
-    readonly userId: string;
-    readonly email: string;
-    readonly name: string;
-    readonly emailVerified?: boolean;
-  } | null;
+  readonly user: SessionUser | null;
+  /** UI-only scopes from last `auth.me` — Gate on Flows is real authz. */
+  readonly scopes: readonly string[];
   readonly accessToken: string | null;
   refresh(): Promise<void>;
-  signOut(): void;
+  signOut(): void | Promise<void>;
+  /** UI-only — never a security boundary. */
+  hasScope(scope: string): boolean;
+  can(...scopes: string[]): boolean;
 }
 
 /**
- * React hook: read session via `auth.me` + optional {@link memorySession} helper.
+ * React hook over {@link AuthClient} (preferred) or legacy `api` + `memorySession`.
  *
- * @param api - Typed client from `createClient`
- * @param session - Optional memory session (Bearer storage)
+ * @param apiOrAuth - AuthClient or typed client with `auth.me`
+ * @param session - Optional memory session when using raw client
  */
-export function useSession(api: SessionClient, session?: MemorySession): SessionState {
+export function useSession(
+  apiOrAuth: AuthClient | SessionClient,
+  session?: MemorySession,
+): SessionState {
+  const authClient = isAuthClient(apiOrAuth) ? apiOrAuth : null;
+  const api = authClient ? null : (apiOrAuth as SessionClient);
+  const bag = authClient?.session ?? session;
+
   const token = useSyncExternalStore(
     (onStoreChange) => {
-      if (!session) return () => {};
-      const id = setInterval(onStoreChange, 250);
-      return () => clearInterval(id);
+      if (authClient) return authClient.subscribe(onStoreChange);
+      if (!bag?.subscribe) {
+        const id = setInterval(onStoreChange, 250);
+        return () => clearInterval(id);
+      }
+      return bag.subscribe(onStoreChange);
     },
-    () => session?.accessToken ?? null,
-    () => session?.accessToken ?? null,
+    () => bag?.accessToken ?? null,
+    () => bag?.accessToken ?? null,
   );
 
-  const [user, setUser] = useState<SessionState["user"]>(null);
+  const [user, setUser] = useState<SessionUser | null>(authClient?.session.user ?? null);
   const [status, setStatus] = useState<SessionState["status"]>("loading");
 
   const refresh = useCallback(async () => {
+    if (authClient) {
+      setStatus("loading");
+      const next = await authClient.getSession();
+      setUser(next);
+      setStatus(next ? "authenticated" : "unauthenticated");
+      return;
+    }
+    if (!api) return;
+    // Legacy SessionClient path — cookie sessions always use AuthClient above.
     if (!token) {
       setUser(null);
       setStatus("unauthenticated");
@@ -84,29 +119,155 @@ export function useSession(api: SessionClient, session?: MemorySession): Session
       setStatus("unauthenticated");
       return;
     }
-    setUser(data);
+    const next: SessionUser = {
+      userId: data.userId,
+      email: data.email,
+      name: data.name,
+      emailVerified: data.emailVerified,
+      scopes: data.scopes ?? [],
+      tenantId: data.tenantId ?? null,
+      apiKeyId: data.apiKeyId ?? null,
+      ...(data.sessionFresh !== undefined ? { sessionFresh: data.sessionFresh } : {}),
+    };
+    bag?.setUser(next);
+    setUser(next);
     setStatus("authenticated");
-  }, [api, token]);
+  }, [api, authClient, bag, token]);
 
   useEffect(() => {
     void refresh();
   }, [refresh]);
 
   const signOut = useCallback(() => {
-    session?.clear();
+    if (authClient) return authClient.signOut();
+    bag?.clear();
     setUser(null);
     setStatus("unauthenticated");
-  }, [session]);
+  }, [authClient, bag]);
+
+  const scopes = user?.scopes ?? bag?.scopes ?? [];
 
   return {
     status,
     user,
+    scopes,
     accessToken: token,
     refresh,
     signOut,
+    hasScope: (scope: string) => scopes.includes(scope),
+    can: (...needed: string[]) => {
+      const have = new Set(scopes);
+      return needed.every((s) => have.has(s));
+    },
   };
 }
 
+function isAuthClient(value: unknown): value is AuthClient {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    "signIn" in value &&
+    "getSession" in value &&
+    "clientOptions" in value
+  );
+}
+
+/**
+ * UI-only scope check hook.
+ *
+ * @param auth - AuthClient or session state scopes
+ * @param scope - Required scope
+ */
+export function useScope(auth: AuthClient | SessionState, scope: string): boolean {
+  const scopes = useMemo(() => {
+    if (
+      "hasScope" in auth &&
+      typeof (auth as AuthClient).hasScope === "function" &&
+      "signIn" in auth
+    ) {
+      return (auth as AuthClient).session.user?.scopes ?? (auth as AuthClient).session.scopes;
+    }
+    return (auth as SessionState).scopes;
+  }, [auth]);
+  return scopes.includes(scope);
+}
+
+/**
+ * UI-only multi-scope check.
+ *
+ * @param auth - AuthClient or session state
+ * @param scopes - Required scopes (all)
+ */
+export function useCan(auth: AuthClient | SessionState, ...scopes: string[]): boolean {
+  const have = useMemo(() => {
+    if ("can" in auth && "signIn" in auth) {
+      return new Set(
+        (auth as AuthClient).session.user?.scopes ?? (auth as AuthClient).session.scopes,
+      );
+    }
+    return new Set((auth as SessionState).scopes);
+  }, [auth]);
+  return scopes.every((s) => have.has(s));
+}
+
+/**
+ * UI-only authorize hook — prefers {@link AuthClient.authorize}.
+ * Gate on Flows remains the security boundary.
+ *
+ * @param auth - AuthClient
+ * @param query - all / any scopes
+ */
+export function useAuthorize(auth: AuthClient, query: AuthorizeQuery): AuthorizeResult {
+  useSyncExternalStore(
+    (onStoreChange) => auth.subscribe(onStoreChange),
+    () => auth.session.user,
+    () => auth.session.user,
+  );
+  // Re-read on every render after subscribe notifies.
+  return auth.authorize(query);
+}
+
+/** Props for {@link Can} / {@link Cannot}. */
+export interface CanProps {
+  readonly auth: AuthClient;
+  readonly all?: readonly string[];
+  readonly any?: readonly string[];
+  readonly children?: ReactNode;
+  readonly fallback?: ReactNode;
+  /** Rendered while authorize status is `loading` (default null). */
+  readonly loading?: ReactNode;
+}
+
+function authorizeQueryOf(props: CanProps): AuthorizeQuery {
+  if (props.all) return { all: props.all };
+  if (props.any) return { any: props.any };
+  return { all: [] };
+}
+
+/**
+ * UI-only — render children when authorize status is `allowed`.
+ * Not a security boundary.
+ */
+export function Can(props: CanProps): ReactNode {
+  const query = authorizeQueryOf(props);
+  const result = useAuthorize(props.auth, query);
+  if (result.status === "loading") return props.loading ?? null;
+  if (result.status === "allowed") return props.children ?? null;
+  return props.fallback ?? null;
+}
+
+/**
+ * UI-only — render children when authorize status is not `allowed`
+ * (denied / unauthenticated). Loading uses `loading` prop.
+ */
+export function Cannot(props: CanProps): ReactNode {
+  const query = authorizeQueryOf(props);
+  const result = useAuthorize(props.auth, query);
+  if (result.status === "loading") return props.loading ?? null;
+  if (result.status === "allowed") return props.fallback ?? null;
+  return props.children ?? null;
+}
+
 /** Options for {@link useLive}. */
 export interface UseLiveOptions {
   readonly autoResubscribe?: boolean;

package/src/client-react/use-live-query.ts

@@ -123,17 +123,27 @@ export interface UseLiveQueryState<Row> {
  * @param args.api - Typed client from `createClient`
  * @param args.listFlow - The resource's list call (`api.tasks.list`)
  * @param args.query - Same input as the list Flow (filters)
- * @param args.live - SSE route from `$routes`
+ * @param args.live - SSE route from `$routes` (optional when `listPath` given)
+ * @param args.listPath - List REST path; live defaults to `` `${listPath}/live` ``
  * @param args.options - PK/version extractors, refresh key, `enabled`
  */
 export function useLiveQuery<Row extends Record<string, unknown>, I = void>(args: {
   readonly api: object;
   readonly listFlow: ClientCall<I, Row[], Record<string, never>>;
   readonly query?: I;
-  readonly live: LiveRouteContract;
+  readonly live?: LiveRouteContract;
+  /** List HTTP path — when `live` is omitted, SSE uses `GET ${listPath}/live`. */
+  readonly listPath?: string;
   readonly options?: UseLiveQueryOptions<Row>;
 }): UseLiveQueryState<Row> {
-  const { api, listFlow, query, live, options } = args;
+  const { api, listFlow, query, options } = args;
+  const live: LiveRouteContract = args.live ?? {
+    method: "GET",
+    path: `${(args.listPath ?? "").replace(/\/$/, "")}/live`,
+  };
+  if (!args.live && !args.listPath) {
+    throw new Error("useLiveQuery requires `live` or `listPath` to derive the SSE route");
+  }
   const opts = options ?? {};
   const enabled = opts.enabled ?? true;
   const defaultIdOf = useCallback((row: Row) => String((row as Record<string, unknown>).id), []);

package/src/compiler/aot.test.ts

@@ -129,11 +129,14 @@ describe("typed error narrowing end-to-end", () => {
     const FlightFull = z.object({ seatsLeft: z.number() });
 
     on(
-      http.post("/bookings").public(),
+      http
+        .post("/bookings", {
+          in: Booking,
+          out: z.object({ id: z.string() }),
+          errors: { FlightFull },
+        })
+        .public(),
       flow("bookings.create", {
-        in: Booking,
-        out: z.object({ id: z.string() }),
-        errors: { FlightFull },
         do: (input: { flightId: string; seats: number }, fx) => {
           if (input.seats > 2) {
             return fx.fail("FlightFull", { seatsLeft: 2 });

package/src/compiler/effects-embed.test.ts

@@ -0,0 +1,56 @@
+/**
+ * fx.embed is a distinct effect kind from fx.ask — capability / Manifest honesty.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { parseSync } from "oxc-parser";
+import { inferEffects, type AstNode, type InferBinding } from "./effects-infer.ts";
+
+function doNodeFrom(source: string): AstNode {
+  const wrapped = `const __fn = ${source}`;
+  const result = parseSync("t.ts", wrapped);
+  const program = result.program as unknown as AstNode & { body: AstNode[] };
+  const decl = program.body[0] as AstNode & {
+    declarations: Array<{ init: AstNode }>;
+  };
+  return decl.declarations[0]!.init;
+}
+
+describe("inferEffects — fx.embed ≠ fx.ask", () => {
+  test("fx.embed alone → effects.embeds, never asks", () => {
+    const doNode = doNodeFrom(`async (_input, fx) => {
+      return fx.embed("embedder", "hello");
+    }`);
+    const bindings = new Map<string, InferBinding>([
+      ["embedder", { kind: "unknown", ref: "embedder" }],
+    ]);
+    const inferred = inferEffects({ doNode, bindings, hasExplicitEffects: false });
+    expect(inferred.effects.embeds).toEqual(["embedder"]);
+    expect(inferred.effects.asks).toBeUndefined();
+    expect(inferred.nondeterministic).toBe(true);
+  });
+
+  test("fx.ask alone → effects.asks, never embeds", () => {
+    const doNode = doNodeFrom(`async (_input, fx) => {
+      return fx.ask("triage", { q: "x" });
+    }`);
+    const bindings = new Map<string, InferBinding>([["triage", { kind: "prompt", ref: "triage" }]]);
+    const inferred = inferEffects({ doNode, bindings, hasExplicitEffects: false });
+    expect(inferred.effects.asks).toEqual(["triage"]);
+    expect(inferred.effects.embeds).toBeUndefined();
+  });
+
+  test("both ask and embed keep separate bags", () => {
+    const doNode = doNodeFrom(`async (_input, fx) => {
+      await fx.embed("embedder", "t");
+      return fx.ask("rerank", { query: "q", docs: [] });
+    }`);
+    const inferred = inferEffects({
+      doNode,
+      bindings: new Map(),
+      hasExplicitEffects: false,
+    });
+    expect(inferred.effects.embeds).toEqual(["embedder"]);
+    expect(inferred.effects.asks).toEqual(["rerank"]);
+  });
+});

package/src/compiler/effects-fetch.test.ts

@@ -0,0 +1,43 @@
+/**
+ * fx.fetch is a distinct effect kind — capability / Manifest honesty.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { inferEffects, type AstNode, type InferBinding } from "./effects-infer.ts";
+
+function parseDo(src: string): AstNode {
+  // Minimal CallExpression-shaped tree for fx.fetch("https://…")
+  const match = /fx\.fetch\(\s*"([^"]+)"/.exec(src);
+  if (!match) throw new Error(`no fx.fetch in ${src}`);
+  return {
+    type: "BlockStatement",
+    body: [
+      {
+        type: "ExpressionStatement",
+        expression: {
+          type: "CallExpression",
+          callee: {
+            type: "MemberExpression",
+            object: { type: "Identifier", name: "fx" },
+            property: { type: "Identifier", name: "fetch" },
+            computed: false,
+          },
+          arguments: [{ type: "Literal", value: match[1] }],
+        },
+      },
+    ],
+  } as AstNode;
+}
+
+describe("inferEffects — fx.fetch → effects.fetches", () => {
+  test("fx.fetch URL literal → host in fetches", () => {
+    const inferred = inferEffects({
+      doNode: parseDo(`async (fx) => { await fx.fetch("https://api.stripe.com/v1"); }`),
+      bindings: new Map<string, InferBinding>(),
+      hasExplicitEffects: false,
+    });
+    expect(inferred.effects.fetches).toEqual(["api.stripe.com"]);
+    expect(inferred.effects.calls).toBeUndefined();
+    expect(inferred.effects.sends).toBeUndefined();
+  });
+});