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

package/src/coreClient.ts

@@ -1,570 +0,0 @@
-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,
-  };
-}