@lucern/sdk 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to `@lucern/sdk` will be documented in this file.
 ## [Unreleased]
 - No unreleased changes yet.
 
+## [1.0.3] - 2026-05-27
+- Release notes pending.
+
+## [1.0.2] - 2026-05-27
+- Campaign 1 wrap-up release with expanded CLI targeting and observability pilot surfaces.
+
+
 ## [1.0.1] - 2026-05-26
 - Publish the Campaign 1 runtime lifecycle, graph-native CLI, Effect runtime,
   XState lifecycle, and transport-core package line as a coherent patch release.

package/dist/accessControl.d.ts

@@ -3,6 +3,7 @@ import { GatewayClientConfig } from './coreClient.js';
 import { PolicyEvaluationInput, PolicyDecisionRecord } from './identityClient.js';
 import { SessionPrincipalType } from './contracts/auth-session.contract.js';
 import { JsonObject } from './types.js';
+import '@lucern/transport-core';
 import './control-plane.js';
 import './contracts/workflow-runtime.contract.js';
 import './contracts/lens-workflow.contract.js';

package/dist/accessControl.js

@@ -1,5 +1,7 @@
+import { createTelemetryExporterFromEnv, emitTelemetrySignal } from '@lucern/transport-core';
 import { redactDiagnosticValue } from '@lucern/transport-core/redaction';
 import { classifyRetry } from '@lucern/transport-core/transport';
+import { Effect, Exit, Cause } from 'effect';
 
 // src/authContext.ts
 var LucernSdkAuthContextError = class extends Error {
@@ -167,6 +169,33 @@ function createCanonicalAuthHeaders(authContext) {
   }
   return headers;
 }
+var DEFAULT_GATEWAY_TIMEOUT_MS = 15e3;
+var DEFAULT_GATEWAY_MAX_RETRIES = 2;
+var DEFAULT_ENV_TIMEOUT_MS = "LUCERN_REQUEST_TIMEOUT_MS";
+var DEFAULT_ENV_MAX_RETRIES = "LUCERN_GATEWAY_MAX_RETRIES";
+var ENV_TIMEOUT_BY_METHOD_PREFIX = "LUCERN_REQUEST_TIMEOUT_MS_";
+var GatewayTimeoutError = class extends Error {
+  retryable = true;
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms`);
+    this.name = "AbortError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+var GatewayTransportError = class extends Error {
+  retryable;
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "GatewayTransportError";
+    this.retryable = options?.retryable ?? true;
+    this.cause = options?.cause;
+  }
+};
+function isGatewayRetryableError(error) {
+  return error instanceof GatewayTimeoutError && error.retryable || error instanceof GatewayTransportError && error.retryable || false;
+}
 var LucernApiError = class extends Error {
   code;
   status;
@@ -233,6 +262,99 @@ function generatePortableRequestId() {
     8
   ).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
 }
+function resolveEnvironment() {
+  const processEnv = typeof globalThis === "object" && globalThis !== null && "process" in globalThis ? globalThis.process : void 0;
+  const env = processEnv !== void 0 && typeof processEnv === "object" && processEnv !== null && typeof processEnv.env === "object" ? processEnv.env : void 0;
+  return {
+    get: (name) => {
+      const value = env?.[name];
+      return typeof value === "string" && value.length > 0 ? value : void 0;
+    }
+  };
+}
+function telemetryEnvironmentRecord(environment) {
+  const names = [
+    "LUCERN_TELEMETRY_ENABLED",
+    "AXIOM_TELEMETRY_ENABLED",
+    "LUCERN_AXIOM_TOKEN",
+    "AXIOM_TOKEN",
+    "LUCERN_AXIOM_EVENTS_DATASET",
+    "LUCERN_AXIOM_DATASET",
+    "AXIOM_EVENTS_DATASET",
+    "AXIOM_DATASET",
+    "LUCERN_AXIOM_API_URL",
+    "AXIOM_URL",
+    "LUCERN_ENVIRONMENT",
+    "NODE_ENV",
+    "LUCERN_RELEASE",
+    "SENTRY_RELEASE",
+    "VERCEL_GIT_COMMIT_SHA"
+  ];
+  return Object.fromEntries(
+    names.map((name) => [name, environment.get(name)])
+  );
+}
+function resolveRequestProfile(config, environment) {
+  const requestIdFactory = config.requestIdFactory ?? (() => generatePortableRequestId());
+  const parsedMaxRetries = parseIntegerFromString(
+    config.maxRetries,
+    environment.get(DEFAULT_ENV_MAX_RETRIES)
+  );
+  const parsedTimeoutMs = parseIntegerFromString(
+    config.timeoutMs,
+    environment.get(DEFAULT_ENV_TIMEOUT_MS)
+  );
+  const methodTimeouts = {
+    ...config.timeoutMsByMethod
+  };
+  for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE"]) {
+    const envKey = `${ENV_TIMEOUT_BY_METHOD_PREFIX}${method}`;
+    const raw = environment.get(envKey);
+    if (!raw || methodTimeouts[method] !== void 0) {
+      continue;
+    }
+    const parsed = parseIntegerFromString(void 0, raw);
+    if (typeof parsed === "number") {
+      methodTimeouts[method] = parsed;
+    }
+  }
+  return {
+    maxRetries: parsedMaxRetries ?? DEFAULT_GATEWAY_MAX_RETRIES,
+    timeoutMs: parsedTimeoutMs ?? DEFAULT_GATEWAY_TIMEOUT_MS,
+    timeoutMsByMethod: methodTimeouts,
+    requestIdFactory
+  };
+}
+function createGatewayRuntime(config, environment) {
+  return {
+    fetch: config.fetchImpl ?? fetch,
+    now: () => Date.now(),
+    sleep: (ms) => delay(ms),
+    env: environment,
+    redaction: resolveRequestRedactionValue,
+    profile: resolveRequestProfile(config, environment)
+  };
+}
+function parseIntegerFromString(value, rawValue) {
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0) {
+    return value;
+  }
+  if (typeof rawValue !== "string" || !rawValue.trim()) {
+    return void 0;
+  }
+  const parsed = Number.parseInt(rawValue, 10);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : void 0;
+}
+function resolveRequestRedactionValue(value) {
+  return redactDiagnosticValue(value);
+}
+function resolveGatewayBaseUrl(configBaseUrl, environment) {
+  const envBaseUrl = environment.get("LUCERN_API_URL") ?? environment.get("LUCERN_BASE_URL") ?? environment.get("LUCERN_GATEWAY_BASE_URL");
+  return (configBaseUrl ?? envBaseUrl ?? "").replace(/\/+$/, "");
+}
+function normalizeGatewayEnvironment(value) {
+  return value === "sandbox" || value === "production" ? value : void 0;
+}
 var randomIdempotencyKey = generatePortableRequestId;
 function fallbackErrorCode(status) {
   if (status === 401) {
@@ -272,10 +394,8 @@ function computeRetryDelayMs(args) {
   const jitterWindow = Math.max(250, Math.round(baseDelay * 0.25));
   return baseDelay + Math.round(Math.random() * jitterWindow);
 }
-function timeoutError(timeoutMs) {
-  const error = new Error(`Request timed out after ${timeoutMs}ms`);
-  error.name = "AbortError";
-  return error;
+function classifyGatewayErrorForRetry(error) {
+  return isGatewayRetryableError(error) || classifyRetry({ error }).retryable;
 }
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -330,10 +450,18 @@ function cleanHeaderValue(value) {
   return normalized ? normalized : void 0;
 }
 function createGatewayRequestClient(config = {}) {
-  const fetchImpl = config.fetchImpl ?? fetch;
-  const baseUrl = config.baseUrl?.replace(/\/+$/, "") ?? "";
-  const maxRetries = config.maxRetries ?? 2;
-  const requestIdFactory = config.requestIdFactory ?? (() => generatePortableRequestId());
+  const env = resolveEnvironment();
+  const runtime = createGatewayRuntime(config, env);
+  const baseUrl = resolveGatewayBaseUrl(config.baseUrl, env);
+  const maxRetries = runtime.profile.maxRetries;
+  const requestIdFactory = runtime.profile.requestIdFactory;
+  const requestTimeoutByMethod = runtime.profile.timeoutMsByMethod;
+  const defaultRequestTimeoutMs = runtime.profile.timeoutMs;
+  const normalizedEnvironment = normalizeGatewayEnvironment(config.environment);
+  const telemetryExporter = config.telemetryEnabled === false ? null : config.telemetryExporter ?? createTelemetryExporterFromEnv(telemetryEnvironmentRecord(env), {
+    service: "lucern-sdk",
+    environment: normalizedEnvironment
+  });
   async function resolveAuthHeaders() {
     const provided = config.getAuthHeaders ? await config.getAuthHeaders() : {};
     const headers = new Headers(provided);
@@ -345,7 +473,7 @@ function createGatewayRequestClient(config = {}) {
     };
     setIfAbsent("x-lucern-key", config.apiKey);
     setIfAbsent("x-lucern-session-token", config.userToken);
-    setIfAbsent("x-lucern-environment", config.environment);
+    setIfAbsent("x-lucern-environment", normalizedEnvironment);
     setIfAbsent("x-lucern-clerk-id", config.clerkId);
     setIfAbsent("x-lucern-user-id", config.userId ?? config.clerkId);
     setIfAbsent("x-lucern-deployment-host", config.deploymentHost);
@@ -360,19 +488,73 @@ function createGatewayRequestClient(config = {}) {
     return mergeHeaderRecord(base, createCanonicalAuthHeaders(authContext));
   }
   async function fetchWithTimeout(url, init, timeoutMs) {
+    const normalizeTransportError = (error, isTimeout) => {
+      if (isTimeout) {
+        return new GatewayTimeoutError(timeoutMs);
+      }
+      return error instanceof GatewayTimeoutError || error instanceof GatewayTransportError ? error : new GatewayTransportError(
+        error instanceof Error ? error.message : "Gateway transport error",
+        {
+          cause: error,
+          retryable: classifyGatewayErrorForRetry(error)
+        }
+      );
+    };
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const requestEffect = Effect.tryPromise({
+      try: () => runtime.fetch(url, { ...init, signal: controller.signal }),
+      catch: (error) => normalizeTransportError(error, controller.signal.aborted)
+    });
     try {
-      return await fetchImpl(url, { ...init, signal: controller.signal });
-    } catch (error) {
-      if (controller.signal.aborted) {
-        throw timeoutError(timeoutMs);
+      const exit = await Effect.runPromiseExit(requestEffect);
+      if (Exit.isSuccess(exit)) {
+        return exit.value;
       }
-      throw error;
+      const failure = Array.from(Cause.failures(exit.cause))[0];
+      if (failure !== void 0) {
+        throw failure;
+      }
+      throw Cause.squash(exit.cause);
     } finally {
       clearTimeout(timer);
     }
   }
+  async function emitSdkResponseTelemetry(context) {
+    const retry = classifyRetry({
+      status: context.status,
+      error: context.error,
+      retryAfter: context.retryAfterMs !== null && context.retryAfterMs !== void 0 ? String(context.retryAfterMs / 1e3) : void 0
+    });
+    await emitTelemetrySignal(telemetryExporter, {
+      signalType: "trace",
+      surface: "sdk-retry",
+      eventName: context.willRetry ? "sdk.retry" : context.error ? "sdk.request.error" : "sdk.request.complete",
+      severity: context.error ? context.willRetry ? "warn" : "error" : "info",
+      durationMs: context.durationMs,
+      metricName: "sdk.request.duration_ms",
+      metricValue: context.durationMs,
+      correlationId: context.correlationId ?? context.requestId,
+      policyTraceId: context.policyTraceId ?? null,
+      tenantId: context.headers.get("x-lucern-tenant-id") ?? context.headers.get("x-lucern-tenant") ?? void 0,
+      workspaceId: context.headers.get("x-lucern-workspace-id") ?? context.headers.get("x-lucern-workspace") ?? void 0,
+      attributes: {
+        service: "lucern-sdk",
+        operation: "gateway.request",
+        path: context.path,
+        httpMethod: context.method,
+        httpStatus: context.status,
+        attempt: context.attempt,
+        maxRetries: context.maxRetries,
+        retryReason: retry.reason,
+        retryAfterMs: context.retryAfterMs ?? retry.retryAfterMs,
+        willRetry: context.willRetry,
+        retryable: retry.retryable,
+        errorName: context.error instanceof Error ? context.error.name : void 0,
+        errorMessage: context.error instanceof Error ? context.error.message : void 0
+      }
+    });
+  }
   async function parsePayload(response) {
     const text = await response.text();
     if (!text) {
@@ -388,11 +570,11 @@ function createGatewayRequestClient(config = {}) {
     if (typeof requestTimeoutMs === "number") {
       return requestTimeoutMs;
     }
-    const methodTimeoutMs = config.timeoutMsByMethod?.[method];
+    const methodTimeoutMs = requestTimeoutByMethod?.[method];
     if (typeof methodTimeoutMs === "number") {
       return methodTimeoutMs;
     }
-    return config.timeoutMs ?? 15e3;
+    return defaultRequestTimeoutMs;
   }
   function tryParseGatewayEnvelopeJson(text) {
     const trimmed = text.trim();
@@ -413,8 +595,8 @@ function createGatewayRequestClient(config = {}) {
     const legacyError = failure && isRecord(failure.error) ? 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 = redactJsonDiagnosticValue(
-      failure?.details ?? legacyError?.details
+    const details = runtime.redaction(
+      redactJsonDiagnosticValue(failure?.details ?? legacyError?.details)
     );
     const policySummary = readPolicySummaryFromDetails(details);
     const failureMessage = typeof failure?.error === "string" ? failure.error : legacyError?.message;
@@ -484,7 +666,7 @@ function createGatewayRequestClient(config = {}) {
             failure
           });
           const willRetry = attempt < maxRetries && retry.retryable;
-          await config.onResponse?.({
+          const responseContext2 = {
             ...hookRequestContext,
             durationMs: Date.now() - startedAt,
             status: response.status,
@@ -494,7 +676,9 @@ function createGatewayRequestClient(config = {}) {
             policyTraceId: apiError.policyTraceId ?? null,
             retryAfterMs,
             willRetry
-          });
+          };
+          await config.onResponse?.(responseContext2);
+          await emitSdkResponseTelemetry(responseContext2);
           if (willRetry) {
             lastError = apiError;
             await delay(
@@ -509,7 +693,7 @@ function createGatewayRequestClient(config = {}) {
           throw apiError;
         }
         const successPayload = payload;
-        await config.onResponse?.({
+        const responseContext = {
           ...hookRequestContext,
           durationMs: Date.now() - startedAt,
           status: response.status,
@@ -519,22 +703,25 @@ function createGatewayRequestClient(config = {}) {
           idempotentReplay: successPayload.idempotentReplay,
           retryAfterMs,
           willRetry: false
-        });
+        };
+        await config.onResponse?.(responseContext);
+        await emitSdkResponseTelemetry(responseContext);
         return successPayload;
       } catch (fetchError) {
         if (fetchError instanceof LucernApiError) {
           throw fetchError;
         }
-        const retry = classifyRetry({ error: fetchError });
-        const willRetry = attempt < maxRetries && retry.retryable;
-        await config.onResponse?.({
+        const willRetry = attempt < maxRetries && classifyGatewayErrorForRetry(fetchError);
+        const responseContext = {
           ...hookRequestContext,
           durationMs: Date.now() - startedAt,
           error: fetchError,
           correlationId: requestId,
           policyTraceId: null,
           willRetry
-        });
+        };
+        await config.onResponse?.(responseContext);
+        await emitSdkResponseTelemetry(responseContext);
         lastError = fetchError;
         if (willRetry) {
           await delay(computeRetryDelayMs({ attempt }));