@littlebearapps/platform-consumer-sdk 1.0.0

package/src/retry.ts

@@ -0,0 +1,19 @@
+export async function withExponentialBackoff<T>(
+  operation: () => Promise<T>,
+  attempts = 3
+): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      if (attempt === attempts - 1) {
+        break;
+      }
+      const delay = Math.min(1000, 2 ** attempt * 100);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  throw lastError ?? new Error('Operation failed');
+}

package/src/service-client.ts

@@ -0,0 +1,291 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * Platform SDK Service Client
+ *
+ * Provides helpers for making inter-service requests with automatic
+ * propagation of correlation IDs and trace context.
+ *
+ * @example
+ * ```typescript
+ * import { createServiceClient } from './lib/platform-sdk';
+ *
+ * // Create a client for calling another service
+ * const client = createServiceClient(env, 'platform-alert-router');
+ *
+ * // Make a traced request
+ * const response = await client.fetch('https://alert-router/notify', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ message: 'Hello' })
+ * });
+ * ```
+ */
+
+import { getCorrelationId } from './logging';
+import { getTraceContext, propagateTraceContext } from './tracing';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Service client for making inter-service requests.
+ */
+export interface ServiceClient {
+  /** Make a fetch request with propagated context */
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+  /** Get the current correlation ID */
+  readonly correlationId: string;
+  /** Get the current trace ID */
+  readonly traceId: string | undefined;
+}
+
+/**
+ * Options for creating a service client.
+ */
+export interface ServiceClientOptions {
+  /** Target service name (for logging) */
+  targetService: string;
+  /** Additional default headers */
+  defaultHeaders?: Record<string, string>;
+  /** Request timeout in milliseconds */
+  timeoutMs?: number;
+}
+
+// =============================================================================
+// HEADER CONSTANTS
+// =============================================================================
+
+/** Correlation ID header name */
+export const CORRELATION_ID_HEADER = 'x-correlation-id';
+
+/** Source service header name */
+export const SOURCE_SERVICE_HEADER = 'x-source-service';
+
+/** Target service header name */
+export const TARGET_SERVICE_HEADER = 'x-target-service';
+
+/** Feature ID header name */
+export const FEATURE_ID_HEADER = 'x-feature-id';
+
+// =============================================================================
+// SERVICE CLIENT
+// =============================================================================
+
+/**
+ * Create a service client for making inter-service requests.
+ * Automatically propagates correlation ID and trace context.
+ *
+ * @param env - Environment object (tracked or raw)
+ * @param sourceService - Name of the calling service
+ * @param options - Optional configuration
+ * @returns Service client with fetch method
+ */
+export function createServiceClient(
+  env: object,
+  sourceService: string,
+  options: Partial<ServiceClientOptions> = {}
+): ServiceClient {
+  const correlationId = getCorrelationId(env);
+  const traceContext = getTraceContext(env);
+
+  const { defaultHeaders = {}, timeoutMs } = options;
+
+  return {
+    get correlationId() {
+      return correlationId;
+    },
+
+    get traceId() {
+      return traceContext?.traceId;
+    },
+
+    async fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+      // Build headers with propagated context
+      const headers = new Headers(init?.headers);
+
+      // Add correlation ID
+      headers.set(CORRELATION_ID_HEADER, correlationId);
+
+      // Add source service
+      headers.set(SOURCE_SERVICE_HEADER, sourceService);
+
+      // Add target service if known
+      if (options.targetService) {
+        headers.set(TARGET_SERVICE_HEADER, options.targetService);
+      }
+
+      // Add trace context headers
+      if (traceContext) {
+        const traceHeaders = propagateTraceContext(traceContext);
+        traceHeaders.forEach((value, key) => {
+          headers.set(key, value);
+        });
+      }
+
+      // Add default headers
+      for (const [key, value] of Object.entries(defaultHeaders)) {
+        if (!headers.has(key)) {
+          headers.set(key, value);
+        }
+      }
+
+      // Build request options
+      const requestInit: RequestInit = {
+        ...init,
+        headers,
+      };
+
+      // Apply timeout if specified
+      if (timeoutMs) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+        try {
+          return await fetch(input, {
+            ...requestInit,
+            signal: controller.signal,
+          });
+        } finally {
+          clearTimeout(timeoutId);
+        }
+      }
+
+      return fetch(input, requestInit);
+    },
+  };
+}
+
+// =============================================================================
+// SERVICE BINDING HELPERS
+// =============================================================================
+
+/**
+ * Create headers for calling a service binding (Fetcher).
+ * Use this when calling env.SERVICE_BINDING.fetch() directly.
+ *
+ * @param env - Environment object
+ * @param sourceService - Name of the calling service
+ * @returns Headers object with propagated context
+ */
+export function createServiceBindingHeaders(env: object, sourceService: string): Headers {
+  const headers = new Headers();
+
+  // Add correlation ID
+  headers.set(CORRELATION_ID_HEADER, getCorrelationId(env));
+
+  // Add source service
+  headers.set(SOURCE_SERVICE_HEADER, sourceService);
+
+  // Add trace context
+  const traceContext = getTraceContext(env);
+  if (traceContext) {
+    const traceHeaders = propagateTraceContext(traceContext);
+    traceHeaders.forEach((value, key) => {
+      headers.set(key, value);
+    });
+  }
+
+  return headers;
+}
+
+/**
+ * Wrap a service binding (Fetcher) with automatic context propagation.
+ *
+ * @param fetcher - Service binding (Fetcher)
+ * @param env - Environment object
+ * @param sourceService - Name of the calling service
+ * @returns Wrapped fetcher that propagates context
+ *
+ * @example
+ * ```typescript
+ * const tracedAlertRouter = wrapServiceBinding(
+ *   env.ALERT_ROUTER,
+ *   env,
+ *   'platform-usage'
+ * );
+ *
+ * await tracedAlertRouter.fetch('https://alert-router/notify', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ message: 'Alert!' })
+ * });
+ * ```
+ */
+export function wrapServiceBinding(fetcher: Fetcher, env: object, sourceService: string): Fetcher {
+  return {
+    fetch: async (input: RequestInfo | URL, init?: RequestInit) => {
+      const headers = new Headers(init?.headers);
+
+      // Merge in service binding headers
+      const contextHeaders = createServiceBindingHeaders(env, sourceService);
+      contextHeaders.forEach((value, key) => {
+        headers.set(key, value);
+      });
+
+      return fetcher.fetch(input, {
+        ...init,
+        headers,
+      });
+    },
+    connect: fetcher.connect,
+  };
+}
+
+// =============================================================================
+// CORRELATION CHAIN EXTRACTION
+// =============================================================================
+
+/**
+ * Extract correlation chain from request headers.
+ * Returns information about the calling service and trace.
+ */
+export interface CorrelationChain {
+  correlationId: string;
+  sourceService?: string;
+  targetService?: string;
+  featureId?: string;
+  traceId?: string;
+  spanId?: string;
+}
+
+/**
+ * Extract correlation chain from incoming request.
+ *
+ * @param request - Incoming request
+ * @returns Correlation chain information
+ */
+export function extractCorrelationChain(request: Request): CorrelationChain {
+  return {
+    correlationId:
+      request.headers.get(CORRELATION_ID_HEADER) ||
+      request.headers.get('x-request-id') ||
+      crypto.randomUUID(),
+    sourceService: request.headers.get(SOURCE_SERVICE_HEADER) || undefined,
+    targetService: request.headers.get(TARGET_SERVICE_HEADER) || undefined,
+    featureId: request.headers.get(FEATURE_ID_HEADER) || undefined,
+    traceId: extractTraceIdFromRequest(request),
+    spanId: extractSpanIdFromRequest(request),
+  };
+}
+
+/**
+ * Extract trace ID from traceparent header.
+ */
+function extractTraceIdFromRequest(request: Request): string | undefined {
+  const traceparent = request.headers.get('traceparent');
+  if (!traceparent) return undefined;
+
+  const parts = traceparent.split('-');
+  return parts.length >= 2 ? parts[1] : undefined;
+}
+
+/**
+ * Extract span ID from traceparent header.
+ */
+function extractSpanIdFromRequest(request: Request): string | undefined {
+  const traceparent = request.headers.get('traceparent');
+  if (!traceparent) return undefined;
+
+  const parts = traceparent.split('-');
+  return parts.length >= 3 ? parts[2] : undefined;
+}

package/src/telemetry.ts

@@ -0,0 +1,342 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * Platform SDK Telemetry
+ *
+ * Queue-based telemetry for reporting feature usage metrics.
+ * Uses waitUntil for non-blocking telemetry submission.
+ */
+
+import type { FeatureId, FeatureMetrics, MetricsAccumulator, TelemetryMessage } from './types';
+import { createLogger, type Logger } from './logging';
+
+// =============================================================================
+// MODULE LOGGER (lazy-initialized to avoid global scope crypto calls)
+// =============================================================================
+
+let _log: Logger | null = null;
+function getLog(): Logger {
+  if (!_log) {
+    _log = createLogger({
+      worker: 'platform-sdk',
+      featureId: 'platform:sdk:telemetry',
+    });
+  }
+  return _log;
+}
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Telemetry context for a single request.
+ */
+export interface TelemetryContext {
+  featureId: FeatureId;
+  metrics: MetricsAccumulator;
+  startTime: number;
+  queue?: Queue<TelemetryMessage>;
+  ctx?: ExecutionContext;
+  correlationId?: string;
+  /** W3C Trace ID for distributed tracing */
+  traceId?: string;
+  /** W3C Span ID for distributed tracing */
+  spanId?: string;
+  /** External API cost in USD (e.g., OpenAI, Apify) */
+  externalCostUsd?: number;
+}
+
+// =============================================================================
+// CONTEXT MANAGEMENT
+// =============================================================================
+
+/**
+ * WeakMap to store telemetry context per proxied environment.
+ * Using WeakMap allows garbage collection when env is no longer referenced.
+ */
+const telemetryContexts = new WeakMap<object, TelemetryContext>();
+
+/**
+ * Store telemetry context for a proxied environment.
+ */
+export function setTelemetryContext(env: object, context: TelemetryContext): void {
+  telemetryContexts.set(env, context);
+}
+
+/**
+ * Get telemetry context for a proxied environment.
+ */
+export function getTelemetryContext(env: object): TelemetryContext | undefined {
+  return telemetryContexts.get(env);
+}
+
+/**
+ * Remove telemetry context for a proxied environment.
+ */
+export function clearTelemetryContext(env: object): void {
+  telemetryContexts.delete(env);
+}
+
+// =============================================================================
+// TELEMETRY REPORTING
+// =============================================================================
+
+/**
+ * Parse a feature ID into its component parts.
+ */
+function parseFeatureId(featureId: FeatureId): {
+  project: string;
+  category: string;
+  feature: string;
+} {
+  const parts = featureId.split(':');
+  if (parts.length !== 3) {
+    throw new Error(
+      `Invalid featureId format: "${featureId}". Expected "project:category:feature"`
+    );
+  }
+  return {
+    project: parts[0],
+    category: parts[1],
+    feature: parts[2],
+  };
+}
+
+/**
+ * Convert MetricsAccumulator to FeatureMetrics, excluding zero values.
+ */
+function accumulatorToMetrics(accumulator: MetricsAccumulator): FeatureMetrics {
+  const metrics: FeatureMetrics = {};
+
+  // Only include non-zero values
+  if (accumulator.d1Writes > 0) metrics.d1Writes = accumulator.d1Writes;
+  if (accumulator.d1Reads > 0) metrics.d1Reads = accumulator.d1Reads;
+  if (accumulator.d1RowsRead > 0) metrics.d1RowsRead = accumulator.d1RowsRead;
+  if (accumulator.d1RowsWritten > 0) metrics.d1RowsWritten = accumulator.d1RowsWritten;
+  if (accumulator.kvReads > 0) metrics.kvReads = accumulator.kvReads;
+  if (accumulator.kvWrites > 0) metrics.kvWrites = accumulator.kvWrites;
+  if (accumulator.kvDeletes > 0) metrics.kvDeletes = accumulator.kvDeletes;
+  if (accumulator.kvLists > 0) metrics.kvLists = accumulator.kvLists;
+  if (accumulator.aiRequests > 0) metrics.aiRequests = accumulator.aiRequests;
+  if (accumulator.aiNeurons > 0) metrics.aiNeurons = accumulator.aiNeurons;
+  // Convert Map to object for JSON serialization
+  if (accumulator.aiModelCounts.size > 0) {
+    metrics.aiModelBreakdown = Object.fromEntries(accumulator.aiModelCounts);
+  }
+  if (accumulator.vectorizeQueries > 0) metrics.vectorizeQueries = accumulator.vectorizeQueries;
+  if (accumulator.vectorizeInserts > 0) metrics.vectorizeInserts = accumulator.vectorizeInserts;
+  // vectorizeDeletes removed - Analytics Engine 20 double limit
+
+  // R2
+  if (accumulator.r2ClassA > 0) metrics.r2ClassA = accumulator.r2ClassA;
+  if (accumulator.r2ClassB > 0) metrics.r2ClassB = accumulator.r2ClassB;
+
+  // Queue
+  if (accumulator.queueMessages > 0) metrics.queueMessages = accumulator.queueMessages;
+
+  // Durable Objects
+  if (accumulator.doRequests > 0) metrics.doRequests = accumulator.doRequests;
+
+  // DO latency stats (only if we have samples)
+  if (accumulator.doRequests > 0 && accumulator.doLatencyMs.length > 0) {
+    const sorted = [...accumulator.doLatencyMs].sort((a, b) => a - b);
+    metrics.doAvgLatencyMs = accumulator.doTotalLatencyMs / accumulator.doLatencyMs.length;
+    metrics.doMaxLatencyMs = sorted[sorted.length - 1];
+    const p99Index = Math.ceil(sorted.length * 0.99) - 1;
+    metrics.doP99LatencyMs = sorted[Math.max(0, p99Index)];
+  }
+
+  // Workflow
+  if (accumulator.workflowInvocations > 0)
+    metrics.workflowInvocations = accumulator.workflowInvocations;
+
+  return metrics;
+}
+
+/**
+ * Check if a telemetry message has any data worth reporting.
+ */
+function hasDataToReport(message: TelemetryMessage): boolean {
+  const hasMetrics = Object.values(message.metrics).some((v) => typeof v === 'number' && v > 0);
+  const hasErrors = (message.error_count ?? 0) > 0;
+  return hasMetrics || hasErrors;
+}
+
+/**
+ * Build telemetry message from context.
+ */
+function buildTelemetryMessage(context: TelemetryContext): TelemetryMessage {
+  const { project, category, feature } = parseFeatureId(context.featureId);
+  const metrics = accumulatorToMetrics(context.metrics);
+
+  const message: TelemetryMessage = {
+    feature_key: context.featureId,
+    project,
+    category,
+    feature,
+    metrics,
+    timestamp: Date.now(),
+  };
+
+  // Include error information if present
+  if (context.metrics.errorCount > 0) {
+    message.error_count = context.metrics.errorCount;
+  }
+  if (context.metrics.lastErrorCategory) {
+    message.error_category = context.metrics.lastErrorCategory;
+  }
+  if (context.metrics.errorCodes.length > 0) {
+    message.error_codes = context.metrics.errorCodes;
+  }
+  if (context.correlationId) {
+    message.correlation_id = context.correlationId;
+  }
+
+  // Include request duration (wall-clock time)
+  const durationMs = Date.now() - context.startTime;
+  if (durationMs > 0) {
+    message.request_duration_ms = durationMs;
+  }
+
+  // Include distributed tracing context
+  if (context.traceId) {
+    message.trace_id = context.traceId;
+  }
+  if (context.spanId) {
+    message.span_id = context.spanId;
+  }
+
+  // Include external cost if provided
+  if (context.externalCostUsd && context.externalCostUsd > 0) {
+    message.external_cost_usd = context.externalCostUsd;
+  }
+
+  return message;
+}
+
+/**
+ * Flush metrics to the telemetry queue.
+ *
+ * This is called automatically when the request completes.
+ * Uses waitUntil if ExecutionContext is available, otherwise awaits directly.
+ *
+ * @param env - The proxied environment object
+ * @returns Promise that resolves when flush is scheduled (not completed)
+ */
+export async function flushMetrics(env: object): Promise<void> {
+  const context = getTelemetryContext(env);
+  if (!context) {
+    getLog().warn('flushMetrics called without telemetry context');
+    return;
+  }
+
+  // Build the message
+  const message = buildTelemetryMessage(context);
+
+  // Skip if nothing to report
+  if (!hasDataToReport(message)) {
+    clearTelemetryContext(env);
+    return;
+  }
+
+  // Send to queue - always await to ensure send completes
+  // Also use waitUntil if ctx is available as a safety net
+  const sendPromise = sendToQueue(context.queue, message);
+  if (context.ctx?.waitUntil) {
+    context.ctx.waitUntil(sendPromise);
+  }
+  await sendPromise;
+
+  // Clean up context
+  clearTelemetryContext(env);
+}
+
+/**
+ * Send telemetry message to queue with error handling.
+ * Fails open - errors are logged but don't break the request.
+ */
+async function sendToQueue(
+  queue: Queue<TelemetryMessage> | undefined,
+  message: TelemetryMessage
+): Promise<void> {
+  if (!queue) {
+    // No queue binding - log warning but don't fail
+    getLog().warn('No PLATFORM_TELEMETRY queue binding, metrics not sent', undefined, {
+      featureKey: message.feature_key,
+    });
+    return;
+  }
+
+  try {
+    await queue.send(message);
+    getLog().debug('Telemetry sent', {
+      featureKey: message.feature_key,
+      metrics: message.metrics,
+    });
+  } catch (error) {
+    // Fail open - log error but don't throw
+    getLog().error('Failed to send telemetry', error, { featureKey: message.feature_key });
+  }
+}
+
+/**
+ * Schedule telemetry flush using waitUntil.
+ * This is the preferred method when ExecutionContext is available.
+ *
+ * @param ctx - ExecutionContext from the worker
+ * @param env - The proxied environment object
+ */
+export function scheduleFlush(ctx: ExecutionContext, env: object): void {
+  ctx.waitUntil(flushMetrics(env));
+}
+
+// =============================================================================
+// DIRECT REPORTING (for use outside proxied context)
+// =============================================================================
+
+/**
+ * Check if metrics have any non-zero values.
+ */
+function hasMetrics(metrics: FeatureMetrics): boolean {
+  return Object.values(metrics).some((v) => typeof v === 'number' && v > 0);
+}
+
+/**
+ * Report usage metrics directly without proxy tracking.
+ * Use this for manual metric reporting in edge cases.
+ *
+ * @param featureId - Feature identifier (project:category:feature)
+ * @param metrics - Metrics to report
+ * @param queue - Telemetry queue binding
+ * @param ctx - Optional ExecutionContext for waitUntil
+ */
+export async function reportUsage(
+  featureId: FeatureId,
+  metrics: FeatureMetrics,
+  queue: Queue<TelemetryMessage>,
+  ctx?: ExecutionContext
+): Promise<void> {
+  if (!hasMetrics(metrics)) {
+    return;
+  }
+
+  const { project, category, feature } = parseFeatureId(featureId);
+
+  const message: TelemetryMessage = {
+    feature_key: featureId,
+    project,
+    category,
+    feature,
+    metrics,
+    timestamp: Date.now(),
+  };
+
+  const sendPromise = sendToQueue(queue, message);
+
+  if (ctx?.waitUntil) {
+    ctx.waitUntil(sendPromise);
+  } else {
+    await sendPromise;
+  }
+}