okengine 0.1.4

package/src/client/transport.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Transport — retry, timeout, auth refresh.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createClient } from "./create.ts";
+import type { AppOf } from "./types.ts";
+
+type PingApp = AppOf<{
+  sys: {
+    ping: {
+      out: { ok: true };
+      errors: Record<string, never>;
+    };
+  };
+}>;
+
+describe("transport — retry", () => {
+  test("retries 5xx then succeeds", async () => {
+    let n = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 2, delay: 1, backoff: 1 },
+      fetch: async () => {
+        n += 1;
+        if (n < 3) return new Response("nope", { status: 503 });
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+
+    const { data, error } = await api.sys.ping();
+    expect(error).toBeNull();
+    expect(data).toEqual({ ok: true });
+    expect(n).toBe(3);
+  });
+
+  test("exhausts retries into TransportError", async () => {
+    let n = 0;
+    const api = createClient<PingApp>("http://app.test", {
+      retry: { retries: 1, delay: 1, backoff: 1 },
+      fetch: async () => {
+        n += 1;
+        return new Response("nope", { status: 502 });
+      },
+    });
+
+    const { error } = await api.sys.ping();
+    expect(error?.code).toBe("TransportError");
+    expect(n).toBe(2);
+  });
+});
+
+describe("transport — timeout", () => {
+  test("AbortError becomes TransportError", async () => {
+    const api = createClient<PingApp>("http://app.test", {
+      timeout: 10,
+      fetch: async (_input, init) => {
+        const signal = init?.signal;
+        await new Promise<void>((resolve, reject) => {
+          if (!signal) {
+            resolve();
+            return;
+          }
+          if (signal.aborted) {
+            reject(new DOMException("Aborted", "AbortError"));
+            return;
+          }
+          signal.addEventListener("abort", () => {
+            reject(new DOMException("Aborted", "AbortError"));
+          });
+        });
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+
+    const { error } = await api.sys.ping();
+    expect(error?.code).toBe("TransportError");
+  });
+});
+
+describe("transport — auth refresh", () => {
+  test("401 triggers refresh once and retries", async () => {
+    let token = "old";
+    let refreshes = 0;
+    let auths: Array<string | null> = [];
+
+    const api = createClient<PingApp>("http://app.test", {
+      auth: {
+        getToken: () => token,
+        refresh: async () => {
+          refreshes += 1;
+          token = "new";
+          return token;
+        },
+      },
+      fetch: async (_input, init) => {
+        const headers = new Headers(init?.headers);
+        const auth = headers.get("authorization");
+        auths.push(auth);
+        if (auth === "Bearer old") {
+          return new Response("unauthorized", { status: 401 });
+        }
+        return Response.json({ data: { ok: true }, error: null });
+      },
+    });
+
+    const { data, error } = await api.sys.ping();
+    expect(error).toBeNull();
+    expect(data).toEqual({ ok: true });
+    expect(refreshes).toBe(1);
+    expect(auths).toEqual(["Bearer old", "Bearer new"]);
+  });
+
+  test("401 without refresh returns TransportError envelope", async () => {
+    const api = createClient<PingApp>("http://app.test", {
+      fetch: async () => new Response("no", { status: 401 }),
+    });
+    const { error } = await api.sys.ping();
+    expect(error?.code).toBe("TransportError");
+    if (error?.code === "TransportError") {
+      expect(error.data.status).toBe(401);
+    }
+  });
+});

package/src/client/transport.ts

@@ -0,0 +1,254 @@
+/**
+ * HTTP transport: timeout, retry, and auth refresh.
+ *
+ * Wire default: `POST {base}/_oke/{unit}/{flow}` with JSON body.
+ * Optional `routes` map switches to REST (`method` + path template).
+ */
+
+import type { ClientFetch, ClientOptions, ClientResult } from "./types.ts";
+
+/** Internal transport handle. */
+export interface Transport {
+  /**
+   * Invoke a flow by `unit/flow` key.
+   *
+   * @param key - `unit/flow`
+   * @param input - JSON body / path-param source
+   */
+  call(key: string, input: unknown): Promise<ClientResult>;
+}
+
+/**
+ * Create a transport bound to a base URL.
+ *
+ * @param base - Absolute origin (no trailing slash)
+ * @param opts - Client options
+ */
+export function createTransport(
+  base: string,
+  opts: ClientOptions = {},
+): Transport {
+  const fetchFn: ClientFetch =
+    opts.fetch ?? globalThis.fetch.bind(globalThis);
+  const retries = opts.retry?.retries ?? 0;
+  const delay0 = opts.retry?.delay ?? 50;
+  const backoff = opts.retry?.backoff ?? 2;
+
+  return {
+    async call(key, input) {
+      let refreshed = false;
+      let attempt = 0;
+      let delay = delay0;
+
+      for (;;) {
+        try {
+          const res = await once(base, key, input, opts, fetchFn);
+          if (res.status === 401 && opts.auth?.refresh && !refreshed) {
+            refreshed = true;
+            await opts.auth.refresh();
+            continue;
+          }
+          return decode(res);
+        } catch (err) {
+          const transient = isTransient(err);
+          if (!transient || attempt >= retries) {
+            return {
+              data: null,
+              error: {
+                code: "TransportError",
+                data: {
+                  message: err instanceof Error ? err.message : String(err),
+                },
+              },
+            };
+          }
+          await sleep(delay);
+          delay *= backoff;
+          attempt += 1;
+        }
+      }
+    },
+  };
+}
+
+/**
+ * Single HTTP attempt. Throws on network / abort / 5xx (retryable).
+ *
+ * @param base - Origin
+ * @param key - `unit/flow`
+ * @param input - Payload
+ * @param opts - Options
+ * @param fetchFn - Fetch implementation
+ * @param _reserved - Reserved
+ */
+async function once(
+  base: string,
+  key: string,
+  input: unknown,
+  opts: ClientOptions,
+  fetchFn: ClientFetch,
+): Promise<Response> {
+  const route = opts.routes?.[key.replace("/", ".")];
+  const { url, method, body } = route
+    ? restRequest(base, route.method, route.path, input)
+    : rpcRequest(base, key, input);
+
+  const headers = new Headers();
+  const extra =
+    typeof opts.headers === "function"
+      ? await opts.headers()
+      : opts.headers;
+  if (Array.isArray(extra)) {
+    for (const [k, v] of extra) headers.set(k, v);
+  } else if (extra) {
+    for (const [k, v] of Object.entries(extra)) headers.set(k, v);
+  }
+  if (body !== undefined && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+
+  const token = opts.auth ? await opts.auth.getToken() : undefined;
+  if (token && !headers.has("authorization")) {
+    headers.set("authorization", `Bearer ${token}`);
+  }
+
+  const ctrl = opts.timeout !== undefined ? new AbortController() : undefined;
+  const timer =
+    ctrl && opts.timeout !== undefined
+      ? setTimeout(() => ctrl.abort(), opts.timeout)
+      : undefined;
+
+  try {
+    const res = await fetchFn(url, {
+      method,
+      headers,
+      body,
+      signal: ctrl?.signal,
+    });
+    if (res.status >= 500) {
+      throw new Error(`HTTP ${res.status}`);
+    }
+    return res;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+function rpcRequest(
+  base: string,
+  key: string,
+  input: unknown,
+): { url: string; method: string; body: string | undefined } {
+  const url = `${base}/_oke/${key}`;
+  const body =
+    input === undefined ? undefined : JSON.stringify(input ?? {});
+  return { url, method: "POST", body };
+}
+
+function restRequest(
+  base: string,
+  method: string,
+  path: string,
+  input: unknown,
+): { url: string; method: string; body: string | undefined } {
+  const params =
+    input !== null && typeof input === "object"
+      ? (input as Record<string, unknown>)
+      : {};
+  let pathOut = path;
+  const query: string[] = [];
+  const rest: Record<string, unknown> = {};
+
+  for (const [k, v] of Object.entries(params)) {
+    const token = `:${k}`;
+    if (pathOut.includes(token)) {
+      pathOut = pathOut.replaceAll(token, encodeURIComponent(String(v)));
+    } else {
+      rest[k] = v;
+    }
+  }
+
+  const upper = method.toUpperCase();
+  let body: string | undefined;
+  if (upper === "GET" || upper === "HEAD") {
+    for (const [k, v] of Object.entries(rest)) {
+      if (v !== undefined) {
+        query.push(
+          `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`,
+        );
+      }
+    }
+  } else if (Object.keys(rest).length > 0 || path === pathOut) {
+    body = JSON.stringify(
+      Object.keys(rest).length > 0 ? rest : (input ?? {}),
+    );
+  }
+
+  const qs = query.length ? `?${query.join("&")}` : "";
+  return { url: `${base}${pathOut}${qs}`, method: upper, body };
+}
+
+async function decode(res: Response): Promise<ClientResult> {
+  if (res.status === 204) {
+    return { data: undefined, error: null };
+  }
+
+  const text = await res.text();
+  if (!text) {
+    if (res.ok) return { data: undefined, error: null };
+    return {
+      data: null,
+      error: {
+        code: "TransportError",
+        data: { message: `HTTP ${res.status}`, status: res.status },
+      },
+    };
+  }
+
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    return {
+      data: null,
+      error: {
+        code: "TransportError",
+        data: {
+          message: `Invalid JSON (${res.status})`,
+          status: res.status,
+        },
+      },
+    };
+  }
+
+  if (
+    json !== null &&
+    typeof json === "object" &&
+    "data" in json &&
+    "error" in json
+  ) {
+    return json as ClientResult;
+  }
+
+  if (res.ok) {
+    return { data: json, error: null };
+  }
+
+  return {
+    data: null,
+    error: {
+      code: "TransportError",
+      data: { message: `HTTP ${res.status}`, status: res.status },
+    },
+  };
+}
+
+function isTransient(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  if (err.name === "AbortError") return false;
+  return true;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/client/types.ts

@@ -0,0 +1,282 @@
+/**
+ * Typed client contract surface — type-level only.
+ *
+ * Same-repo: pass `App` with `$routes` (or a bare route map) to {@link createClient}.
+ * Local / separate-repo: augment {@link Register} so `createClient(url)` needs no import.
+ */
+
+/**
+ * One flow's client contract. `in` / `out` / `errors` are phantom (type-only).
+ *
+ * @typeParam I - Request input
+ * @typeParam O - Success data
+ * @typeParam E - Map of error code → data shape
+ */
+export interface FlowContract<
+  I = unknown,
+  O = unknown,
+  E extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /** Phantom input type. */
+  readonly in?: I;
+  /** Phantom success type. */
+  readonly out?: O;
+  /** Phantom error map (`FlightFull` → `{ seatsLeft: number }`). */
+  readonly errors?: E;
+  /** Optional HTTP method when the wire uses REST instead of `/_oke` RPC. */
+  readonly method?: string;
+  /** Optional HTTP path template (`/notes/:id`). */
+  readonly path?: string;
+}
+
+/**
+ * Unit → flow → contract. Drives `api.notes.get(...)`.
+ */
+export type ClientRouteMap = {
+  readonly [unit: string]: {
+    readonly [flow: string]: FlowContract;
+  };
+};
+
+/**
+ * App shape accepted by {@link createClient}. Either a `$routes` carrier
+ * (future `typeof app`) or a bare {@link ClientRouteMap}.
+ */
+export type ClientApp = {
+  readonly $routes: ClientRouteMap;
+};
+
+/**
+ * Module-augmentation slot for modes that skip `import type { App }`.
+ *
+ * @example
+ * ```ts
+ * declare module "okengine/client" {
+ *   interface Register {
+ *     app: { $routes: { notes: { get: { in: { id: string }; out: Note; errors: { NotFound: {} } } } } };
+ *   }
+ * }
+ * ```
+ */
+export interface Register {
+  // intentionally empty — augmented by `oke dev` / `oke client add`
+}
+
+/**
+ * Resolve the App type: explicit type argument wins; else {@link Register}.
+ *
+ * @typeParam App - Explicit app / route map
+ */
+export type ResolveApp<App = never> = [App] extends [never]
+  ? Register extends { readonly app: infer A }
+    ? A
+    : { readonly $routes: {} }
+  : App;
+
+/**
+ * Extract a {@link ClientRouteMap} from an App type.
+ *
+ * Accepts `typeof app` (OkeApp with accumulated `$routes`), {@link ClientApp},
+ * or a bare route map.
+ *
+ * @typeParam App - {@link ClientApp}, `typeof app`, or bare route map
+ */
+export type RoutesOf<App> = App extends { readonly $routes: infer R }
+  ? R extends ClientRouteMap
+    ? R
+    : R extends Record<string, Record<string, FlowContract>>
+      ? R
+      : {
+          [U in keyof R]: {
+            [F in keyof R[U]]: R[U][F] extends FlowContract
+              ? R[U][F]
+              : FlowContract;
+          };
+        }
+  : App extends ClientRouteMap
+    ? App
+    : {};
+
+/**
+ * Discriminated flow-boundary error. Narrow with `error.code === "FlightFull"`.
+ *
+ * @typeParam E - Error code → data map
+ */
+export type ClientError<
+  E extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  [K in keyof E & string]: {
+    readonly code: K;
+    readonly data: E[K];
+    readonly message?: string;
+  };
+}[keyof E & string];
+
+/**
+ * Transport / protocol failure (not a declared flow error).
+ */
+export interface TransportError {
+  readonly code: "TransportError";
+  readonly data: {
+    readonly message: string;
+    readonly status?: number;
+  };
+  readonly message?: string;
+}
+
+/**
+ * Client call result — errors are values, never thrown for flow failures.
+ *
+ * @typeParam O - Success data
+ * @typeParam E - Declared error map
+ */
+export type ClientResult<
+  O = unknown,
+  E extends Record<string, unknown> = Record<string, unknown>,
+> =
+  | { readonly data: O; readonly error: null }
+  | { readonly data: null; readonly error: ClientError<E> | TransportError };
+
+/** Minimal fetch signature (avoids DOM `HeadersInit` / `preconnect` coupling). */
+export type ClientFetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+/** Header bag accepted by the client. */
+export type ClientHeaders = Record<string, string> | [string, string][];
+
+/**
+ * Options for {@link createClient}.
+ */
+export interface ClientOptions {
+  /** Override `globalThis.fetch`. */
+  readonly fetch?: ClientFetch;
+  /** Static headers, or a getter invoked per request. */
+  readonly headers?:
+    | ClientHeaders
+    | (() => ClientHeaders | Promise<ClientHeaders>);
+  /** Abort the request after this many milliseconds. */
+  readonly timeout?: number;
+  /** Retry transient failures (network / 5xx). */
+  readonly retry?: {
+    /** Extra attempts after the first (default 0). */
+    readonly retries?: number;
+    /** Initial delay in ms (default 50). */
+    readonly delay?: number;
+    /** Multiplier applied after each retry (default 2). */
+    readonly backoff?: number;
+  };
+  /**
+   * Auth token + refresh. On HTTP 401, `refresh` runs once and the
+   * request is retried with the new token.
+   */
+  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>;
+  };
+  /**
+   * Runtime REST table (optional). Keys are `unit.flow`.
+   * When absent, the client uses `POST /_oke/{unit}/{flow}` unless
+   * {@link ClientOptions.$routes} supplies HTTP method/path from adopt.
+   */
+  readonly routes?: Readonly<
+    Record<string, { readonly method: string; readonly path: string }>
+  >;
+  /**
+   * Runtime route map from `app.$routes` (typed adopt). HTTP triggers become
+   * REST; flows without method/path fall back to RPC.
+   */
+  readonly $routes?: ClientRouteMap;
+}
+
+/**
+ * Call signature for one flow.
+ *
+ * @typeParam I - Input
+ * @typeParam O - Output
+ * @typeParam E - Errors
+ */
+export type ClientCall<
+  I,
+  O,
+  E extends Record<string, unknown>,
+> = [I] extends [void]
+  ? () => Promise<ClientResult<O, E>>
+  : Partial<I> extends I
+    ? (input?: I) => Promise<ClientResult<O, E>>
+    : (input: I) => Promise<ClientResult<O, E>>;
+
+/**
+ * Pull input from a contract shape (supports required or phantom-optional `in`).
+ */
+type ContractIn<C> = "in" extends keyof C
+  ? [NonNullable<C["in"]>] extends [never]
+    ? void
+    : NonNullable<C["in"]>
+  : void;
+
+/** Pull output from a contract shape. */
+type ContractOut<C> = "out" extends keyof C
+  ? NonNullable<C["out"]>
+  : unknown;
+
+/** Pull error map from a contract shape. */
+type ContractErrors<C> = "errors" extends keyof C
+  ? NonNullable<C["errors"]> extends Record<string, unknown>
+    ? NonNullable<C["errors"]>
+    : Record<string, never>
+  : Record<string, never>;
+
+/**
+ * Typed client proxy derived from a route map.
+ *
+ * @typeParam R - Route map
+ */
+export type ClientFromRoutes<R extends ClientRouteMap> = {
+  readonly [U in keyof R]: {
+    readonly [F in keyof R[U]]: ClientCall<
+      ContractIn<R[U][F]>,
+      ContractOut<R[U][F]>,
+      ContractErrors<R[U][F]>
+    >;
+  };
+};
+
+/**
+ * Fully typed client for an App.
+ *
+ * @typeParam App - App or route map
+ */
+export type Client<App = never> = ClientFromRoutes<RoutesOf<ResolveApp<App>>>;
+
+/**
+ * Convenience: brand a route map as an App (`export type App = AppOf<…>`).
+ *
+ * @typeParam R - Route map
+ */
+export type AppOf<R extends ClientRouteMap> = { readonly $routes: R };
+
+/**
+ * JSON shape served at `GET /_oke/client.json` for {@link clientAdd}.
+ */
+export interface ClientDescriptor {
+  /** Route contracts with TypeScript type strings for emission. */
+  readonly routes: {
+    readonly [unit: string]: {
+      readonly [flow: string]: {
+        readonly in?: string;
+        readonly out?: string;
+        readonly errors?: Readonly<Record<string, string>>;
+        readonly method?: string;
+        readonly path?: string;
+      };
+    };
+  };
+}