@zitadel/api 0.0.0

package/src/runtime/config.ts

@@ -0,0 +1,121 @@
+import { setProxyPath } from "./base-url";
+import { createApi, type ZitadelApi } from "./api-factory";
+
+/**
+ * Input options for {@link configureZitadel}.
+ */
+export interface ZitadelConfig {
+  /** Proxy path for API requests (e.g. `"/__nextgen"`). Optional — defaults to `"/__nextgen"`. */
+  proxyPath?: string;
+
+  /** Project ID passed to flow creation. */
+  projectId: string;
+
+  /**
+   * Full URL of the Zitadel auth backend (e.g. `"http://localhost:8080"`).
+   * Used by server-side middleware for proxying and JWT verification.
+   * Optional — not needed in client-only setups.
+   */
+  url?: string;
+}
+
+/**
+ * The initialized project handle returned by {@link configureZitadel}.
+ * Pure data — use factory functions like {@link getApi} to derive services.
+ */
+export interface ZitadelProject {
+  /** Proxy path for API requests. */
+  readonly proxyPath: string;
+
+  /** Project ID passed to flow creation. */
+  readonly projectId: string;
+
+  /** Full URL of the Zitadel auth backend. */
+  readonly url?: string;
+}
+
+export type { ZitadelApi };
+
+let currentProject: ZitadelProject | null = null;
+
+/**
+ * Per-project API client cache. Ensures `getApi(project)` returns the
+ * same instance for the same project handle — no re-wrapping on every call.
+ */
+const apiCache = new WeakMap<ZitadelProject, ZitadelApi>();
+
+/**
+ * Initializes app-wide SDK configuration and returns the frozen
+ * {@link ZitadelProject} handle.
+ *
+ * Write-once — subsequent calls with the same values return the original
+ * handle; calls with different values log a warning and return the
+ * original. This prevents accidental overwrites while remaining safe
+ * for HMR and framework double-mounts.
+ */
+export function configureZitadel(config: ZitadelConfig): ZitadelProject {
+  const resolvedProxyPath = config.proxyPath ?? "/__nextgen";
+
+  if (currentProject !== null) {
+    // Same values → no-op (safe for HMR / React strict mode double-mount)
+    if (
+      currentProject.proxyPath === resolvedProxyPath &&
+      currentProject.projectId === config.projectId &&
+      currentProject.url === config.url
+    ) {
+      return currentProject;
+    }
+    console.warn(
+      `[zitadel] configureZitadel() already called with different values. ` +
+        `Ignoring: ${JSON.stringify(config)}`,
+    );
+    return currentProject;
+  }
+
+  currentProject = Object.freeze({
+    proxyPath: resolvedProxyPath,
+    projectId: config.projectId,
+    url: config.url,
+  });
+
+  // Keep the global in sync for the generated code's internal use
+  setProxyPath(resolvedProxyPath);
+
+  return currentProject;
+}
+
+/**
+ * Returns a typed API client for the given project, with the base URL
+ * pre-bound. Cached per project handle — safe to call multiple times.
+ *
+ * ```ts
+ * const project = configureZitadel({ ... });
+ * export const api = getApi(project);
+ * ```
+ */
+export function getApi(project: ZitadelProject): ZitadelApi {
+  let api = apiCache.get(project);
+  if (!api) {
+    api = createApi(project.proxyPath);
+    apiCache.set(project, api);
+  }
+  return api;
+}
+
+/**
+ * Returns the current project handle, or `null` if {@link configureZitadel}
+ * has not been called yet.
+ */
+export function getZitadelConfig(): ZitadelProject | null {
+  return currentProject;
+}
+
+/**
+ * Reset internal state. **Test-only** — not exported from the package's
+ * public API. Allows tests to call `configureZitadel()` multiple times
+ * across isolated test cases without the write-once guard rejecting them.
+ */
+export function _resetConfigForTesting(): void {
+  currentProject = null;
+  setProxyPath("");
+}

package/src/runtime/fetch.ts

@@ -0,0 +1,75 @@
+import { getApiAuthToken } from "./auth";
+
+/**
+ * Framework-neutral failure type the orval-generated client throws on
+ * any non-2xx response. Carries the HTTP status, the parsed error body
+ * (the spec's `{code, message, details?}` envelope when the server
+ * returned one), and the request URL — enough for callers to map to
+ * their own error taxonomy without re-implementing the fetch layer.
+ *
+ * Callers that don't care about the distinction can catch `ApiError`
+ * generically; callers that do (the CLI's `toZitadelError`) read
+ * `status` and decide.
+ */
+export class ApiError extends Error {
+  readonly status: number;
+  readonly url: string;
+  readonly body: unknown;
+
+  constructor(status: number, url: string, body: unknown, message: string) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.url = url;
+    this.body = body;
+  }
+}
+
+/**
+ * The orval `mutator` for the fetch client. Every generated operation
+ * routes its request through this function instead of the global
+ * `fetch`. We pin three concerns here so generated call sites stay
+ * focused on the shape of one HTTP call:
+ *
+ * - bearer auth — read from `runtime/auth.ts` and attached automatically;
+ * - non-2xx → throw — orval's stock client parses the body regardless
+ *   of status, so callers would have to inspect every response. Throw
+ *   `ApiError` on `!res.ok` so failures interrupt control flow;
+ * - body parsing — return the parsed JSON typed as `T` (the operation's
+ *   return type, threaded through by orval), or `undefined` for the
+ *   spec's `204`/`205`/`304` no-body responses.
+ */
+export async function customFetch<T>(url: string, options: RequestInit): Promise<T> {
+  const token = getApiAuthToken();
+  const headers = new Headers(options.headers);
+  if (token && !headers.has("authorization")) {
+    headers.set("authorization", `Bearer ${token}`);
+  }
+
+  const res = await fetch(url, { ...options, headers });
+
+  const noBody = [204, 205, 304].includes(res.status);
+  const rawBody = noBody ? "" : await res.text();
+  const parsed = rawBody ? (safeJsonParse(rawBody) as unknown) : undefined;
+
+  if (!res.ok) {
+    const message = `${options.method ?? "GET"} ${url} returned ${res.status}`;
+    throw new ApiError(res.status, url, parsed, message);
+  }
+
+  return parsed as T;
+}
+
+/**
+ * `JSON.parse` wrapped so a non-JSON body (e.g. an HTML 502 from a
+ * proxy) becomes `{ raw: "<text>" }` instead of throwing inside
+ * `customFetch`. The thrown `ApiError` then carries something useful
+ * for the user to see.
+ */
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}