@teja-app/api-client 0.0.1-dev.20260124115708.06e82a3 → 0.0.1-dev.20260125152414.0c955c4

package/dist/index.d.ts

@@ -4,6 +4,8 @@
  * Type-safe API client generated from OpenAPI specification.
  * Provides full TypeScript support for all API endpoints.
  *
+ * ## Basic Usage
+ *
  * @example
  * ```typescript
  * import { OpenAPI, ClientsService, isApiError, getErrorMessage } from '@teja-app/api-client';
@@ -14,15 +16,55 @@
  *
  * // Make typed API calls with error handling
  * try {
- *   const clients = await ClientsService.listClients({ limit: 10 });
+ *   const clients = await ClientsService.getClients({ status: 'active' });
  * } catch (error) {
  *   if (isApiError(error)) {
  *     console.error('API Error:', getErrorMessage(error));
  *   }
  * }
  * ```
+ *
+ * ## Telemetry Integration
+ *
+ * The API client supports OpenTelemetry integration for distributed tracing.
+ * Configure it once at app initialization to automatically add trace context
+ * headers to all API requests.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   OpenAPI,
+ *   configureTelemetry,
+ *   setupInterceptors
+ * } from '@teja-app/api-client';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * // 1. Configure API client
+ * OpenAPI.BASE = import.meta.env.VITE_API_URL;
+ * OpenAPI.TOKEN = () => getAccessToken();
+ *
+ * // 2. Configure telemetry with your trace context provider
+ * configureTelemetry({
+ *   enabled: true,
+ *   getTraceContext: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *     const ctx = span.spanContext();
+ *     return {
+ *       traceId: ctx.traceId,
+ *       spanId: ctx.spanId,
+ *       traceFlags: ctx.traceFlags,
+ *     };
+ *   },
+ * });
+ *
+ * // 3. Enable interceptors (adds traceparent header to requests)
+ * setupInterceptors();
+ * ```
  */
 export * from "./generated";
 export * from "./errors";
 export * from "./interceptors";
+export * from "./telemetry";
+export * from "./request-with-interceptors";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,cAAc,aAAa,CAAC;AAG5B,cAAc,UAAU,CAAC;AAGzB,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAGH,cAAc,aAAa,CAAC;AAG5B,cAAc,UAAU,CAAC;AAGzB,cAAc,gBAAgB,CAAC;AAG/B,cAAc,aAAa,CAAC;AAG5B,cAAc,6BAA6B,CAAC"}

package/dist/index.js

@@ -4,6 +4,8 @@
  * Type-safe API client generated from OpenAPI specification.
  * Provides full TypeScript support for all API endpoints.
  *
+ * ## Basic Usage
+ *
  * @example
  * ```typescript
  * import { OpenAPI, ClientsService, isApiError, getErrorMessage } from '@teja-app/api-client';
@@ -14,13 +16,51 @@
  *
  * // Make typed API calls with error handling
  * try {
- *   const clients = await ClientsService.listClients({ limit: 10 });
+ *   const clients = await ClientsService.getClients({ status: 'active' });
  * } catch (error) {
  *   if (isApiError(error)) {
  *     console.error('API Error:', getErrorMessage(error));
  *   }
  * }
  * ```
+ *
+ * ## Telemetry Integration
+ *
+ * The API client supports OpenTelemetry integration for distributed tracing.
+ * Configure it once at app initialization to automatically add trace context
+ * headers to all API requests.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   OpenAPI,
+ *   configureTelemetry,
+ *   setupInterceptors
+ * } from '@teja-app/api-client';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * // 1. Configure API client
+ * OpenAPI.BASE = import.meta.env.VITE_API_URL;
+ * OpenAPI.TOKEN = () => getAccessToken();
+ *
+ * // 2. Configure telemetry with your trace context provider
+ * configureTelemetry({
+ *   enabled: true,
+ *   getTraceContext: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *     const ctx = span.spanContext();
+ *     return {
+ *       traceId: ctx.traceId,
+ *       spanId: ctx.spanId,
+ *       traceFlags: ctx.traceFlags,
+ *     };
+ *   },
+ * });
+ *
+ * // 3. Enable interceptors (adds traceparent header to requests)
+ * setupInterceptors();
+ * ```
  */
 // Re-export everything from generated code
 export * from "./generated";
@@ -28,4 +68,8 @@ export * from "./generated";
 export * from "./errors";
 // Export interceptors
 export * from "./interceptors";
+// Export telemetry utilities
+export * from "./telemetry";
+// Export interceptor setup utilities
+export * from "./request-with-interceptors";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,2CAA2C;AAC3C,cAAc,aAAa,CAAC;AAE5B,yBAAyB;AACzB,cAAc,UAAU,CAAC;AAEzB,sBAAsB;AACtB,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,2CAA2C;AAC3C,cAAc,aAAa,CAAC;AAE5B,yBAAyB;AACzB,cAAc,UAAU,CAAC;AAEzB,sBAAsB;AACtB,cAAc,gBAAgB,CAAC;AAE/B,6BAA6B;AAC7B,cAAc,aAAa,CAAC;AAE5B,qCAAqC;AACrC,cAAc,6BAA6B,CAAC"}

package/dist/request-with-interceptors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Enhanced request function with interceptor support
+ *
+ * This module provides a way to integrate interceptors with the generated
+ * request function. Since the generated code can't be modified, apps need
+ * to configure the OpenAPI object to use the enhanced request behavior.
+ *
+ * @example
+ * ```typescript
+ * import { setupInterceptors } from '@teja-app/api-client';
+ *
+ * // Call this once at app initialization
+ * setupInterceptors();
+ *
+ * // Now all API calls will run through interceptors
+ * ```
+ */
+/**
+ * Setup interceptors to work with the generated API client
+ *
+ * This patches the OpenAPI.HEADERS configuration to run request interceptors.
+ * Call this once at application startup after configuring telemetry.
+ *
+ * @example
+ * ```typescript
+ * import { configureTelemetry, setupInterceptors, OpenAPI } from '@teja-app/api-client';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * // 1. Configure the API client
+ * OpenAPI.BASE = 'https://api.example.com';
+ * OpenAPI.TOKEN = () => getAccessToken();
+ *
+ * // 2. Configure telemetry
+ * configureTelemetry({
+ *   enabled: true,
+ *   getTraceContext: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *     const ctx = span.spanContext();
+ *     return { traceId: ctx.traceId, spanId: ctx.spanId, traceFlags: ctx.traceFlags };
+ *   },
+ * });
+ *
+ * // 3. Setup interceptors (enables telemetry header injection)
+ * setupInterceptors();
+ * ```
+ */
+export declare function setupInterceptors(): void;
+/**
+ * Remove interceptor integration and restore original configuration
+ */
+export declare function teardownInterceptors(): void;
+/**
+ * Check if interceptors are currently set up
+ */
+export declare function areInterceptorsSetup(): boolean;
+//# sourceMappingURL=request-with-interceptors.d.ts.map

package/dist/request-with-interceptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-with-interceptors.d.ts","sourceRoot":"","sources":["../src/request-with-interceptors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CA8BxC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C"}

package/dist/request-with-interceptors.js

@@ -0,0 +1,91 @@
+/**
+ * Enhanced request function with interceptor support
+ *
+ * This module provides a way to integrate interceptors with the generated
+ * request function. Since the generated code can't be modified, apps need
+ * to configure the OpenAPI object to use the enhanced request behavior.
+ *
+ * @example
+ * ```typescript
+ * import { setupInterceptors } from '@teja-app/api-client';
+ *
+ * // Call this once at app initialization
+ * setupInterceptors();
+ *
+ * // Now all API calls will run through interceptors
+ * ```
+ */
+import { OpenAPI } from "./generated/core/OpenAPI";
+import { interceptors } from "./interceptors";
+// Store the original HEADERS resolver
+let originalHeaders = undefined;
+/**
+ * Setup interceptors to work with the generated API client
+ *
+ * This patches the OpenAPI.HEADERS configuration to run request interceptors.
+ * Call this once at application startup after configuring telemetry.
+ *
+ * @example
+ * ```typescript
+ * import { configureTelemetry, setupInterceptors, OpenAPI } from '@teja-app/api-client';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * // 1. Configure the API client
+ * OpenAPI.BASE = 'https://api.example.com';
+ * OpenAPI.TOKEN = () => getAccessToken();
+ *
+ * // 2. Configure telemetry
+ * configureTelemetry({
+ *   enabled: true,
+ *   getTraceContext: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *     const ctx = span.spanContext();
+ *     return { traceId: ctx.traceId, spanId: ctx.spanId, traceFlags: ctx.traceFlags };
+ *   },
+ * });
+ *
+ * // 3. Setup interceptors (enables telemetry header injection)
+ * setupInterceptors();
+ * ```
+ */
+export function setupInterceptors() {
+    // Store original HEADERS configuration
+    originalHeaders = OpenAPI.HEADERS;
+    // Patch HEADERS to run interceptors
+    OpenAPI.HEADERS = async (options) => {
+        // Get base headers from original configuration
+        let baseHeaders = {};
+        if (typeof originalHeaders === "function") {
+            baseHeaders = (await originalHeaders(options)) || {};
+        }
+        else if (originalHeaders) {
+            baseHeaders = originalHeaders;
+        }
+        // Create a temporary options object with current headers
+        const optionsWithHeaders = {
+            ...options,
+            headers: baseHeaders,
+        };
+        // Run through request interceptors
+        const interceptedOptions = await interceptors.runRequestInterceptors(optionsWithHeaders);
+        // Return the headers (which may have been modified by interceptors)
+        return interceptedOptions.headers || {};
+    };
+}
+/**
+ * Remove interceptor integration and restore original configuration
+ */
+export function teardownInterceptors() {
+    if (originalHeaders !== undefined) {
+        OpenAPI.HEADERS = originalHeaders;
+        originalHeaders = undefined;
+    }
+}
+/**
+ * Check if interceptors are currently set up
+ */
+export function areInterceptorsSetup() {
+    return originalHeaders !== undefined;
+}
+//# sourceMappingURL=request-with-interceptors.js.map

package/dist/request-with-interceptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-with-interceptors.js","sourceRoot":"","sources":["../src/request-with-interceptors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,sCAAsC;AACtC,IAAI,eAAe,GAA2B,SAAS,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,iBAAiB;IAChC,uCAAuC;IACvC,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAElC,oCAAoC;IACpC,OAAO,CAAC,OAAO,GAAG,KAAK,EACtB,OAA0B,EACQ,EAAE;QACpC,+CAA+C;QAC/C,IAAI,WAAW,GAA2B,EAAE,CAAC;QAE7C,IAAI,OAAO,eAAe,KAAK,UAAU,EAAE,CAAC;YAC3C,WAAW,GAAG,CAAC,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QACtD,CAAC;aAAM,IAAI,eAAe,EAAE,CAAC;YAC5B,WAAW,GAAG,eAAyC,CAAC;QACzD,CAAC;QAED,yDAAyD;QACzD,MAAM,kBAAkB,GAAsB;YAC7C,GAAG,OAAO;YACV,OAAO,EAAE,WAAW;SACpB,CAAC;QAEF,mCAAmC;QACnC,MAAM,kBAAkB,GACvB,MAAM,YAAY,CAAC,sBAAsB,CAAC,kBAAkB,CAAC,CAAC;QAE/D,oEAAoE;QACpE,OAAQ,kBAAkB,CAAC,OAAkC,IAAI,EAAE,CAAC;IACrE,CAAC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB;IACnC,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,CAAC,OAAO,GAAG,eAAe,CAAC;QAClC,eAAe,GAAG,SAAS,CAAC;IAC7B,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB;IACnC,OAAO,eAAe,KAAK,SAAS,CAAC;AACtC,CAAC"}

package/dist/telemetry.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Telemetry support for the API client
+ *
+ * This module provides lightweight telemetry integration that works with
+ * OpenTelemetry or any W3C Trace Context compatible tracing system.
+ *
+ * The api-client doesn't include OpenTelemetry as a dependency - apps
+ * provide the trace context through configuration or interceptors.
+ *
+ * @example
+ * ```typescript
+ * import { configureTelemetry, createTelemetryInterceptor } from '@teja-app/api-client';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * // Option 1: Configure with a trace context provider
+ * configureTelemetry({
+ *   enabled: true,
+ *   getTraceContext: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *     const ctx = span.spanContext();
+ *     return {
+ *       traceId: ctx.traceId,
+ *       spanId: ctx.spanId,
+ *       traceFlags: ctx.traceFlags,
+ *     };
+ *   },
+ * });
+ *
+ * // Option 2: Use the request interceptor directly
+ * import { interceptors } from '@teja-app/api-client';
+ * interceptors.addRequestInterceptor(createTelemetryInterceptor());
+ * ```
+ */
+import type { ApiRequestOptions } from "./generated/core/ApiRequestOptions";
+/**
+ * W3C Trace Context format
+ * @see https://www.w3.org/TR/trace-context/
+ */
+export interface TraceContext {
+    /** 32-character hex trace ID */
+    traceId: string;
+    /** 16-character hex span/parent ID */
+    spanId: string;
+    /** Trace flags (1 = sampled) */
+    traceFlags?: number;
+    /** Optional trace state for vendor-specific data */
+    traceState?: string;
+}
+/**
+ * Function that returns the current trace context
+ */
+export type TraceContextProvider = () => TraceContext | null;
+/**
+ * Telemetry configuration options
+ */
+export interface TelemetryConfig {
+    /** Enable/disable telemetry header injection */
+    enabled: boolean;
+    /** Function that returns current trace context */
+    getTraceContext?: TraceContextProvider;
+    /** Custom header name for trace parent (default: 'traceparent') */
+    traceParentHeader?: string;
+    /** Custom header name for trace state (default: 'tracestate') */
+    traceStateHeader?: string;
+    /** Include span attributes in request metadata */
+    includeAttributes?: boolean;
+}
+/**
+ * Request metadata with telemetry info
+ */
+export interface RequestTelemetryMetadata {
+    traceId: string | null;
+    spanId: string | null;
+    startTime: number;
+}
+/**
+ * Configure telemetry for the API client
+ *
+ * @param config - Telemetry configuration options
+ * @returns Cleanup function to remove the telemetry interceptor
+ *
+ * @example
+ * ```typescript
+ * import { configureTelemetry } from '@teja-app/api-client';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * const cleanup = configureTelemetry({
+ *   enabled: true,
+ *   getTraceContext: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *     const ctx = span.spanContext();
+ *     return { traceId: ctx.traceId, spanId: ctx.spanId, traceFlags: ctx.traceFlags };
+ *   },
+ * });
+ *
+ * // Later, to disable:
+ * cleanup();
+ * ```
+ */
+export declare function configureTelemetry(config: TelemetryConfig): () => void;
+/**
+ * Get the current telemetry configuration
+ */
+export declare function getTelemetryConfig(): Readonly<TelemetryConfig>;
+/**
+ * Check if telemetry is enabled
+ */
+export declare function isTelemetryEnabled(): boolean;
+/**
+ * Format trace context as W3C traceparent header value
+ * Format: {version}-{trace-id}-{parent-id}-{trace-flags}
+ *
+ * @see https://www.w3.org/TR/trace-context/#traceparent-header
+ */
+export declare function formatTraceParent(context: TraceContext): string;
+/**
+ * Parse a W3C traceparent header value
+ *
+ * @param header - The traceparent header value
+ * @returns Parsed trace context or null if invalid
+ */
+export declare function parseTraceParent(header: string): TraceContext | null;
+/**
+ * Create a request interceptor that adds W3C trace context headers
+ *
+ * @param config - Optional config override (uses global config if not provided)
+ * @returns Request interceptor function
+ *
+ * @example
+ * ```typescript
+ * import { interceptors, createTelemetryInterceptor } from '@teja-app/api-client';
+ *
+ * interceptors.addRequestInterceptor(
+ *   createTelemetryInterceptor({
+ *     enabled: true,
+ *     getTraceContext: () => ({ traceId: '...', spanId: '...' }),
+ *   })
+ * );
+ * ```
+ */
+export declare function createTelemetryInterceptor(config?: Partial<TelemetryConfig>): (options: ApiRequestOptions) => ApiRequestOptions;
+/**
+ * Get request metadata for a given request (for response correlation)
+ */
+export declare function getRequestMetadata(method: string, url: string): RequestTelemetryMetadata | undefined;
+/**
+ * Generate a random trace ID (32 hex characters)
+ * Use this if you need to create a new trace without OpenTelemetry
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a random span ID (16 hex characters)
+ * Use this if you need to create a new span without OpenTelemetry
+ */
+export declare function generateSpanId(): string;
+/**
+ * Create a simple trace context without OpenTelemetry
+ * Useful for basic tracing when full OpenTelemetry is not needed
+ */
+export declare function createSimpleTraceContext(): TraceContext;
+/**
+ * Span attribute keys for consistent tagging
+ * These match OpenTelemetry semantic conventions
+ */
+export declare const SpanAttributeKeys: {
+    readonly HTTP_METHOD: "http.method";
+    readonly HTTP_URL: "http.url";
+    readonly HTTP_STATUS_CODE: "http.status_code";
+    readonly HTTP_ROUTE: "http.route";
+    readonly API_SERVICE: "api.service";
+    readonly API_OPERATION: "api.operation";
+    readonly CLIENT_ID: "client.id";
+    readonly TENANT_ID: "tenant.id";
+    readonly USER_ID: "user.id";
+    readonly USER_ROLE: "user.role";
+    readonly ERROR_TYPE: "error.type";
+    readonly ERROR_MESSAGE: "error.message";
+    readonly ERROR_CODE: "error.code";
+    readonly MUTATION_TYPE: "mutation.type";
+    readonly MUTATION_ENTITY: "mutation.entity";
+    readonly MUTATION_KEY: "mutation.key";
+};
+export type SpanAttributeKey = (typeof SpanAttributeKeys)[keyof typeof SpanAttributeKeys];
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAG5E;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,YAAY,GAAG,IAAI,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,eAAe,CAAC,EAAE,oBAAoB,CAAC;IACvC,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CAClB;AAUD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,IAAI,CAkBtE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,CAAC,eAAe,CAAC,CAE9D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAI/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAiBpE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAC/B,CAAC,OAAO,EAAE,iBAAiB,KAAK,iBAAiB,CA6CnD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACT,wBAAwB,GAAG,SAAS,CAOtC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAMxC;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAMvC;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,YAAY,CAMvD;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;CA0BpB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAC3B,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/telemetry.js

@@ -0,0 +1,257 @@
+/**
+ * Telemetry support for the API client
+ *
+ * This module provides lightweight telemetry integration that works with
+ * OpenTelemetry or any W3C Trace Context compatible tracing system.
+ *
+ * The api-client doesn't include OpenTelemetry as a dependency - apps
+ * provide the trace context through configuration or interceptors.
+ *
+ * @example
+ * ```typescript
+ * import { configureTelemetry, createTelemetryInterceptor } from '@teja-app/api-client';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * // Option 1: Configure with a trace context provider
+ * configureTelemetry({
+ *   enabled: true,
+ *   getTraceContext: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *     const ctx = span.spanContext();
+ *     return {
+ *       traceId: ctx.traceId,
+ *       spanId: ctx.spanId,
+ *       traceFlags: ctx.traceFlags,
+ *     };
+ *   },
+ * });
+ *
+ * // Option 2: Use the request interceptor directly
+ * import { interceptors } from '@teja-app/api-client';
+ * interceptors.addRequestInterceptor(createTelemetryInterceptor());
+ * ```
+ */
+import { interceptors } from "./interceptors";
+// Global telemetry configuration
+let telemetryConfig = {
+    enabled: false,
+};
+// Store for request metadata (keyed by request URL + method)
+const requestMetadata = new Map();
+/**
+ * Configure telemetry for the API client
+ *
+ * @param config - Telemetry configuration options
+ * @returns Cleanup function to remove the telemetry interceptor
+ *
+ * @example
+ * ```typescript
+ * import { configureTelemetry } from '@teja-app/api-client';
+ * import { trace } from '@opentelemetry/api';
+ *
+ * const cleanup = configureTelemetry({
+ *   enabled: true,
+ *   getTraceContext: () => {
+ *     const span = trace.getActiveSpan();
+ *     if (!span) return null;
+ *     const ctx = span.spanContext();
+ *     return { traceId: ctx.traceId, spanId: ctx.spanId, traceFlags: ctx.traceFlags };
+ *   },
+ * });
+ *
+ * // Later, to disable:
+ * cleanup();
+ * ```
+ */
+export function configureTelemetry(config) {
+    telemetryConfig = { ...config };
+    if (config.enabled && config.getTraceContext) {
+        // Add the telemetry interceptor
+        const removeInterceptor = interceptors.addRequestInterceptor(createTelemetryInterceptor(config));
+        return () => {
+            telemetryConfig = { enabled: false };
+            removeInterceptor();
+        };
+    }
+    return () => {
+        telemetryConfig = { enabled: false };
+    };
+}
+/**
+ * Get the current telemetry configuration
+ */
+export function getTelemetryConfig() {
+    return telemetryConfig;
+}
+/**
+ * Check if telemetry is enabled
+ */
+export function isTelemetryEnabled() {
+    return telemetryConfig.enabled;
+}
+/**
+ * Format trace context as W3C traceparent header value
+ * Format: {version}-{trace-id}-{parent-id}-{trace-flags}
+ *
+ * @see https://www.w3.org/TR/trace-context/#traceparent-header
+ */
+export function formatTraceParent(context) {
+    const version = "00";
+    const traceFlags = (context.traceFlags ?? 1).toString(16).padStart(2, "0");
+    return `${version}-${context.traceId}-${context.spanId}-${traceFlags}`;
+}
+/**
+ * Parse a W3C traceparent header value
+ *
+ * @param header - The traceparent header value
+ * @returns Parsed trace context or null if invalid
+ */
+export function parseTraceParent(header) {
+    const parts = header.split("-");
+    if (parts.length !== 4)
+        return null;
+    const [version, traceId, spanId, flags] = parts;
+    // Validate format
+    if (version !== "00")
+        return null;
+    if (traceId.length !== 32)
+        return null;
+    if (spanId.length !== 16)
+        return null;
+    if (flags.length !== 2)
+        return null;
+    return {
+        traceId,
+        spanId,
+        traceFlags: parseInt(flags, 16),
+    };
+}
+/**
+ * Create a request interceptor that adds W3C trace context headers
+ *
+ * @param config - Optional config override (uses global config if not provided)
+ * @returns Request interceptor function
+ *
+ * @example
+ * ```typescript
+ * import { interceptors, createTelemetryInterceptor } from '@teja-app/api-client';
+ *
+ * interceptors.addRequestInterceptor(
+ *   createTelemetryInterceptor({
+ *     enabled: true,
+ *     getTraceContext: () => ({ traceId: '...', spanId: '...' }),
+ *   })
+ * );
+ * ```
+ */
+export function createTelemetryInterceptor(config) {
+    return (options) => {
+        const effectiveConfig = config
+            ? { ...telemetryConfig, ...config }
+            : telemetryConfig;
+        if (!effectiveConfig.enabled || !effectiveConfig.getTraceContext) {
+            return options;
+        }
+        const traceContext = effectiveConfig.getTraceContext();
+        if (!traceContext) {
+            return options;
+        }
+        const traceParentHeader = effectiveConfig.traceParentHeader ?? "traceparent";
+        const traceStateHeader = effectiveConfig.traceStateHeader ?? "tracestate";
+        // Build headers with trace context
+        const headers = {
+            ...options.headers,
+            [traceParentHeader]: formatTraceParent(traceContext),
+        };
+        // Add tracestate if provided
+        if (traceContext.traceState) {
+            headers[traceStateHeader] = traceContext.traceState;
+        }
+        // Store metadata for response correlation
+        if (effectiveConfig.includeAttributes) {
+            const requestKey = `${options.method}:${options.url}`;
+            requestMetadata.set(requestKey, {
+                traceId: traceContext.traceId,
+                spanId: traceContext.spanId,
+                startTime: Date.now(),
+            });
+        }
+        return {
+            ...options,
+            headers,
+        };
+    };
+}
+/**
+ * Get request metadata for a given request (for response correlation)
+ */
+export function getRequestMetadata(method, url) {
+    const key = `${method}:${url}`;
+    const metadata = requestMetadata.get(key);
+    if (metadata) {
+        requestMetadata.delete(key); // Clean up after retrieval
+    }
+    return metadata;
+}
+/**
+ * Generate a random trace ID (32 hex characters)
+ * Use this if you need to create a new trace without OpenTelemetry
+ */
+export function generateTraceId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Generate a random span ID (16 hex characters)
+ * Use this if you need to create a new span without OpenTelemetry
+ */
+export function generateSpanId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Create a simple trace context without OpenTelemetry
+ * Useful for basic tracing when full OpenTelemetry is not needed
+ */
+export function createSimpleTraceContext() {
+    return {
+        traceId: generateTraceId(),
+        spanId: generateSpanId(),
+        traceFlags: 1, // Sampled
+    };
+}
+/**
+ * Span attribute keys for consistent tagging
+ * These match OpenTelemetry semantic conventions
+ */
+export const SpanAttributeKeys = {
+    // HTTP semantic conventions
+    HTTP_METHOD: "http.method",
+    HTTP_URL: "http.url",
+    HTTP_STATUS_CODE: "http.status_code",
+    HTTP_ROUTE: "http.route",
+    // API client specific
+    API_SERVICE: "api.service",
+    API_OPERATION: "api.operation",
+    // Application context
+    CLIENT_ID: "client.id",
+    TENANT_ID: "tenant.id",
+    USER_ID: "user.id",
+    USER_ROLE: "user.role",
+    // Error context
+    ERROR_TYPE: "error.type",
+    ERROR_MESSAGE: "error.message",
+    ERROR_CODE: "error.code",
+    // Mutation context (for React Query integration)
+    MUTATION_TYPE: "mutation.type",
+    MUTATION_ENTITY: "mutation.entity",
+    MUTATION_KEY: "mutation.key",
+};
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teja-app/api-client",
-  "version": "0.0.1-dev.20260124115708.06e82a3",
+  "version": "0.0.1-dev.20260125152414.0c955c4",
   "description": "TypeScript SDK for the Teja API",
   "author": "Teja App",
   "license": "MIT",