@lucern/sdk 0.2.0-alpha.6 → 0.2.0-alpha.7

package/src/coreClient.ts

@@ -0,0 +1,570 @@
+import type { JsonObject, JsonValue } from "./types";
+
+/** Tenant and workspace identifiers used to scope gateway requests. */
+export type GatewayScope = {
+  tenantId?: string;
+  workspaceId?: string;
+};
+
+/** Successful response envelope from the platform gateway with correlation metadata. */
+export type PlatformGatewaySuccess<T> = {
+  success: true;
+  data: T;
+  correlationId: string;
+  policyTraceId: string | null;
+  idempotentReplay: boolean;
+};
+
+/** Failed response envelope with structured error codes and optional invariant references. */
+export type PlatformGatewayFailure = {
+  success: false;
+  /**
+   * Error string is the canonical envelope field.
+   * Object form is legacy-only compatibility for older gateway responses.
+   */
+  error:
+    | string
+    | {
+        code: string;
+        message: string;
+        details?: JsonValue;
+      };
+  code?: string;
+  invariant?: string | null;
+  suggestion?: string | null;
+  details?: JsonValue;
+  legacyError?: {
+    code: string;
+    message: string;
+    details?: JsonValue;
+  };
+  correlationId: string;
+  policyTraceId: string | null;
+};
+
+/** Discriminated union of success and failure gateway responses. */
+export type PlatformGatewayEnvelope<T> =
+  | PlatformGatewaySuccess<T>
+  | PlatformGatewayFailure;
+
+/**
+ * Structured error thrown when a platform API request fails.
+ *
+ * Includes HTTP status, machine-readable error code, optional invariant
+ * reference, and actionable suggestions for common failure modes.
+ */
+export class LucernApiError extends Error {
+  public readonly code: string;
+  public readonly status: number;
+  public readonly invariant?: string | null;
+  public readonly suggestion?: string | null;
+  public readonly details?: JsonValue;
+  public readonly requestId?: string;
+  public readonly correlationId?: string;
+  public readonly policyTraceId?: string | null;
+
+  constructor(args: {
+    code: string;
+    message: string;
+    status: number;
+    invariant?: string | null;
+    suggestion?: string | null;
+    details?: JsonValue;
+    requestId?: string;
+    correlationId?: string;
+    policyTraceId?: string | null;
+  }) {
+    super(args.message);
+    this.name = "LucernApiError";
+    this.code = args.code;
+    this.status = args.status;
+    this.invariant = args.invariant;
+    this.suggestion = args.suggestion;
+    this.details = args.details;
+    this.requestId = args.requestId;
+    this.correlationId = args.correlationId;
+    this.policyTraceId = args.policyTraceId;
+  }
+}
+
+/** Supported HTTP methods for gateway requests. */
+export type GatewayHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+type FetchLike = (
+  input: RequestInfo | URL,
+  init?: RequestInit
+) => Promise<Response>;
+
+/** Context passed to the `onRequest` hook before each gateway request attempt. */
+export type GatewayRequestHookContext = {
+  requestId: string;
+  attempt: number;
+  maxRetries: number;
+  method: GatewayHttpMethod;
+  path: string;
+  url: string;
+  headers: Headers;
+  body?: string;
+  timeoutMs: number;
+};
+
+/** Context passed to the `onResponse` hook after each gateway request attempt (including retries and failures). */
+export type GatewayResponseHookContext = GatewayRequestHookContext & {
+  durationMs: number;
+  status?: number;
+  response?: Response;
+  error?: unknown;
+  correlationId?: string;
+  policyTraceId?: string | null;
+  idempotentReplay?: boolean;
+  retryAfterMs?: number | null;
+  willRetry: boolean;
+};
+
+/**
+ * Low-level transport configuration for the platform gateway client.
+ *
+ * Most developers should use {@link createLucernClient} instead, which wraps
+ * this config with higher-level conveniences like `apiKey` and `environment`.
+ */
+export type GatewayClientConfig = {
+  baseUrl?: string;
+  fetchImpl?: FetchLike;
+  getAuthHeaders?:
+    | (() => Promise<Record<string, string>>)
+    | (() => Record<string, string>);
+  /** Max retries for transient errors (5xx, network). Defaults to 2. */
+  maxRetries?: number;
+  /** Request timeout in ms. Defaults to 15000. */
+  timeoutMs?: number;
+  /** Optional timeout overrides by HTTP method. */
+  timeoutMsByMethod?: Partial<Record<GatewayHttpMethod, number>>;
+  /** Optional request ID factory used for correlation headers. */
+  requestIdFactory?: () => string;
+  /** Invoked before each request attempt, including retries. */
+  onRequest?:
+    | ((context: GatewayRequestHookContext) => void)
+    | ((context: GatewayRequestHookContext) => Promise<void>);
+  /** Invoked after each request attempt, including retries and failures. */
+  onResponse?:
+    | ((context: GatewayResponseHookContext) => void)
+    | ((context: GatewayResponseHookContext) => Promise<void>);
+};
+
+/**
+ * Serialize a gateway query object into a URL query string.
+ */
+export function toQueryString(
+  scope: GatewayScope & Record<string, string | number | boolean | undefined>
+): string {
+  const params = new URLSearchParams();
+  if (scope.tenantId) {
+    params.set("tenantId", scope.tenantId);
+  }
+  if (scope.workspaceId) {
+    params.set("workspaceId", scope.workspaceId);
+  }
+  for (const [key, value] of Object.entries(scope)) {
+    if (key === "tenantId" || key === "workspaceId") {
+      continue;
+    }
+    if (value === undefined) {
+      continue;
+    }
+    params.set(key, String(value));
+  }
+  const serialized = params.toString();
+  return serialized.length > 0 ? `?${serialized}` : "";
+}
+
+function fillRandomBytes(length: number): Uint8Array {
+  const bytes = new Uint8Array(length);
+  if (typeof globalThis.crypto?.getRandomValues === "function") {
+    globalThis.crypto.getRandomValues(bytes);
+    return bytes;
+  }
+
+  for (let index = 0; index < length; index += 1) {
+    bytes[index] = Math.floor(Math.random() * 256);
+  }
+  return bytes;
+}
+
+function generatePortableRequestId(): string {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+
+  const bytes = fillRandomBytes(16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (value) => value.toString(16).padStart(2, "0"));
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(
+    6,
+    8
+  ).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+}
+
+/**
+ * Generate a random idempotency key for retry-safe writes.
+ */
+export function randomIdempotencyKey(): string {
+  return generatePortableRequestId();
+}
+
+function isRetryableStatus(status: number): boolean {
+  return status >= 500 || status === 408 || status === 429;
+}
+
+function fallbackErrorCode(status: number): string {
+  if (status === 401) {
+    return "AUTHENTICATION_REQUIRED";
+  }
+  if (status === 403) {
+    return "FORBIDDEN";
+  }
+  if (status === 404) {
+    return "NOT_FOUND";
+  }
+  if (status === 408) {
+    return "UPSTREAM_ERROR";
+  }
+  if (status === 409) {
+    return "CONFLICT";
+  }
+  if (status === 429) {
+    return "RATE_LIMIT_EXCEEDED";
+  }
+  if (status >= 500) {
+    return "UPSTREAM_ERROR";
+  }
+  return "INTERNAL_ERROR";
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function parseRetryAfterMs(value: string | null): number | null {
+  if (!value) {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const numeric = Number(trimmed);
+  if (Number.isFinite(numeric)) {
+    return Math.max(0, Math.round(numeric * 1000));
+  }
+  const parsedDate = Date.parse(trimmed);
+  if (Number.isFinite(parsedDate)) {
+    return Math.max(0, parsedDate - Date.now());
+  }
+  return null;
+}
+
+function computeRetryDelayMs(args: {
+  attempt: number;
+  status?: number;
+  retryAfterMs?: number | null;
+}): number {
+  const baseDelay =
+    args.status === 429
+      ? Math.max(
+          args.retryAfterMs ?? 0,
+          Math.min(1000 * 2 ** args.attempt, 10_000)
+        )
+      : Math.min(1000 * 2 ** args.attempt, 4000);
+
+  if (args.status !== 429) {
+    return baseDelay;
+  }
+
+  const jitterWindow = Math.max(250, Math.round(baseDelay * 0.25));
+  return baseDelay + Math.round(Math.random() * jitterWindow);
+}
+
+function timeoutError(timeoutMs: number): Error {
+  const error = new Error(`Request timed out after ${timeoutMs}ms`);
+  error.name = "AbortError";
+  return error;
+}
+
+function readPolicySummaryFromDetails(details?: JsonValue): string | null {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    return null;
+  }
+
+  const directSummary = (details as { summary?: JsonValue }).summary;
+  if (typeof directSummary === "string" && directSummary.trim().length > 0) {
+    return directSummary.trim();
+  }
+
+  const policy = (details as { policy?: JsonValue }).policy;
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    return null;
+  }
+
+  const explanation = (policy as { explanation?: JsonValue }).explanation;
+  if (!explanation || typeof explanation !== "object" || Array.isArray(explanation)) {
+    return null;
+  }
+
+  const nestedSummary = (explanation as { summary?: JsonValue }).summary;
+  if (typeof nestedSummary === "string" && nestedSummary.trim().length > 0) {
+    return nestedSummary.trim();
+  }
+
+  return null;
+}
+
+/**
+ * Create the transport client used by all SDK modules.
+ */
+export function createGatewayRequestClient(config: GatewayClientConfig = {}) {
+  const fetchImpl = config.fetchImpl ?? fetch;
+  const baseUrl = config.baseUrl?.replace(/\/+$/, "") ?? "";
+  const maxRetries = config.maxRetries ?? 2;
+  const requestIdFactory = config.requestIdFactory ?? (() => generatePortableRequestId());
+
+  async function resolveAuthHeaders(): Promise<Record<string, string>> {
+    if (!config.getAuthHeaders) {
+      return {};
+    }
+    return await config.getAuthHeaders();
+  }
+
+  async function fetchWithTimeout(
+    url: string,
+    init: RequestInit,
+    timeoutMs: number
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await fetchImpl(url, { ...init, signal: controller.signal });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw timeoutError(timeoutMs);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function parsePayload<T>(
+    response: Response
+  ): Promise<PlatformGatewayEnvelope<T> | null> {
+    const text = await response.text();
+    if (!text) {
+      return null;
+    }
+    try {
+      return JSON.parse(text) as PlatformGatewayEnvelope<T>;
+    } catch {
+      return null;
+    }
+  }
+
+  function resolveTimeoutMs(
+    method: GatewayHttpMethod,
+    requestTimeoutMs?: number
+  ): number {
+    if (typeof requestTimeoutMs === "number") {
+      return requestTimeoutMs;
+    }
+    const methodTimeoutMs = config.timeoutMsByMethod?.[method];
+    if (typeof methodTimeoutMs === "number") {
+      return methodTimeoutMs;
+    }
+    return config.timeoutMs ?? 15_000;
+  }
+
+  function buildApiError(args: {
+    requestId: string;
+    response: Response;
+    failure?: PlatformGatewayFailure | null;
+  }): LucernApiError {
+    const failure = args.failure;
+    const legacyError =
+      failure && typeof failure.error === "object" && failure.error !== null
+        ? failure.error
+        : failure?.legacyError;
+    const correlationId =
+      failure?.correlationId ??
+      args.response.headers.get("x-lucern-correlation-id")?.trim() ??
+      args.requestId;
+    const policyTraceId =
+      failure?.policyTraceId ??
+      args.response.headers.get("x-lucern-policy-trace-id")?.trim() ??
+      null;
+    const details = failure?.details ?? legacyError?.details;
+    const policySummary = readPolicySummaryFromDetails(details);
+
+    return new LucernApiError({
+      code: failure?.code ?? legacyError?.code ?? fallbackErrorCode(args.response.status),
+      message:
+        policySummary ??
+        (typeof failure?.error === "string"
+          ? failure.error
+          : legacyError?.message ??
+            (args.response.ok
+              ? "Platform API returned an invalid success payload."
+              : "Platform API request failed.")),
+      status: args.response.status,
+      invariant: failure?.invariant,
+      suggestion: failure?.suggestion,
+      details,
+      requestId: args.requestId,
+      correlationId,
+      policyTraceId,
+    });
+  }
+
+  async function request<T>(args: {
+    path: string;
+    method?: GatewayHttpMethod;
+    body?: JsonObject;
+    idempotencyKey?: string;
+    requestId?: string;
+    timeoutMs?: number;
+  }): Promise<PlatformGatewaySuccess<T>> {
+    const authHeaders = await resolveAuthHeaders();
+    const method = args.method ?? "GET";
+    const timeoutMs = resolveTimeoutMs(method, args.timeoutMs);
+    const headers = new Headers({
+      "content-type": "application/json",
+      ...authHeaders,
+    });
+    if (args.idempotencyKey) {
+      headers.set("idempotency-key", args.idempotencyKey);
+    }
+    const requestId =
+      headers.get("x-correlation-id")?.trim() ||
+      headers.get("x-request-id")?.trim() ||
+      args.requestId ||
+      requestIdFactory();
+    if (!headers.has("x-correlation-id") && !headers.has("x-request-id")) {
+      headers.set("x-correlation-id", requestId);
+    }
+
+    const url = `${baseUrl}${args.path}`;
+    const serializedBody = args.body ? JSON.stringify(args.body) : undefined;
+    const init: RequestInit = {
+      method,
+      headers,
+      body: serializedBody,
+    };
+
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      const hookRequestContext: GatewayRequestHookContext = {
+        requestId,
+        attempt,
+        maxRetries,
+        method,
+        path: args.path,
+        url,
+        headers: new Headers(headers),
+        body: serializedBody,
+        timeoutMs,
+      };
+      await config.onRequest?.(hookRequestContext);
+      const startedAt = Date.now();
+      try {
+        const response = await fetchWithTimeout(url, init, timeoutMs);
+        const responseClone = response.clone();
+        const payload = await parsePayload<T>(response);
+        const retryAfterMs = parseRetryAfterMs(
+          response.headers.get("Retry-After")
+        );
+
+        if (!response.ok || !payload?.success) {
+          const failure =
+            payload && !payload.success ? (payload as PlatformGatewayFailure) : null;
+          const apiError = buildApiError({
+            requestId,
+            response,
+            failure,
+          });
+          const willRetry = attempt < maxRetries && isRetryableStatus(response.status);
+
+          await config.onResponse?.({
+            ...hookRequestContext,
+            durationMs: Date.now() - startedAt,
+            status: response.status,
+            response: responseClone,
+            error: apiError,
+            correlationId: apiError.correlationId ?? requestId,
+            policyTraceId: apiError.policyTraceId ?? null,
+            retryAfterMs,
+            willRetry,
+          });
+
+          if (willRetry) {
+            lastError = apiError;
+            await delay(
+              computeRetryDelayMs({
+                attempt,
+                status: response.status,
+                retryAfterMs,
+              })
+            );
+            continue;
+          }
+
+          throw apiError;
+        }
+
+        const successPayload = payload as PlatformGatewaySuccess<T>;
+        await config.onResponse?.({
+          ...hookRequestContext,
+          durationMs: Date.now() - startedAt,
+          status: response.status,
+          response: responseClone,
+          correlationId:
+            successPayload.correlationId ??
+            response.headers.get("x-lucern-correlation-id")?.trim() ??
+            requestId,
+          policyTraceId:
+            successPayload.policyTraceId ??
+            response.headers.get("x-lucern-policy-trace-id")?.trim() ??
+            null,
+          idempotentReplay: successPayload.idempotentReplay,
+          retryAfterMs,
+          willRetry: false,
+        });
+
+        return successPayload;
+      } catch (fetchError) {
+        if (fetchError instanceof LucernApiError) {
+          throw fetchError;
+        }
+        const willRetry = attempt < maxRetries;
+        await config.onResponse?.({
+          ...hookRequestContext,
+          durationMs: Date.now() - startedAt,
+          error: fetchError,
+          correlationId: requestId,
+          policyTraceId: null,
+          willRetry,
+        });
+        lastError = fetchError;
+        if (willRetry) {
+          await delay(computeRetryDelayMs({ attempt }));
+        }
+      }
+    }
+
+    throw lastError instanceof Error
+      ? lastError
+      : new Error("Platform API request failed after retries.");
+  }
+
+  return {
+    request,
+  };
+}