netra-sdk 1.1.0-beta → 1.1.0

package/dist/index.d.cts

@@ -1206,13 +1206,12 @@ declare class NetraMistralAIInstrumentor {
     instrumentationDependencies(): string[];
     /**
      * Instrument MistralAI client methods (async version)
-     * Uses dynamic import() to ensure we get the same ES module instance
-     * that the application uses.
+     * Tries both ESM and CJS resolution to cover dual-package setups.
      */
     instrumentAsync(options?: InstrumentorOptions$1): Promise<NetraMistralAIInstrumentor>;
     /**
      * Instrument MistralAI client methods (sync version - for backwards compatibility)
-     * Note: This uses a cached Mistral class. Call instrumentAsync() for proper initialization.
+     * Note: This uses cached Mistral classes. Call instrumentAsync() for proper initialization.
      */
     instrument(options?: InstrumentorOptions$1): NetraMistralAIInstrumentor;
     /**
@@ -1390,6 +1389,82 @@ declare class TrialAwareOTLPExporter implements SpanExporter {
     shutdown(): Promise<void>;
 }
 
+/**
+ * Public helpers for distributed tracing context propagation.
+ *
+ * These utilities let users extract incoming W3C Trace Context from HTTP
+ * headers and run code within that context so that all child spans (LLM
+ * calls, database queries, outgoing HTTP, etc.) are linked to the upstream
+ * trace.
+ *
+ * When `@opentelemetry/instrumentation-http` + `@opentelemetry/instrumentation-express`
+ * are installed and working, incoming context extraction happens automatically.
+ * These helpers cover cases where auto-instrumentation is unavailable (e.g.
+ * ESM module loading order issues, missing peer dependencies, or non-Express
+ * frameworks).
+ */
+
+/**
+ * Run a function within a context extracted from HTTP headers.
+ *
+ * All spans created inside `fn` will be children of the trace described by the
+ * incoming `traceparent` / `tracestate` headers, enabling end-to-end
+ * distributed tracing across service boundaries.
+ *
+ * @param headers - Incoming HTTP request headers (e.g. `req.headers`).
+ * @param fn      - The function to execute within the extracted context.
+ *                  May be sync or async -- the return value is forwarded as-is.
+ * @returns The return value of `fn`.
+ *
+ * @example
+ * ```ts
+ * import { runWithExtractedContext } from "netra";
+ *
+ * app.post("/api/chat", async (req, res) => {
+ *   await runWithExtractedContext(req.headers, async () => {
+ *     const result = await myAgent(req.body.message);
+ *     res.json(result);
+ *   });
+ * });
+ * ```
+ */
+declare function runWithExtractedContext<T>(headers: Record<string, string | string[] | undefined>, fn: () => T): T;
+/**
+ * Express/Connect-compatible middleware that extracts W3C Trace Context from
+ * incoming request headers and runs all downstream handlers within the
+ * extracted context.
+ *
+ * This is the recommended way to enable distributed tracing for Express
+ * servers when `@opentelemetry/instrumentation-http` is not available or not
+ * working (e.g. due to ESM module loading order with `tsx`). It is the
+ * TypeScript equivalent of the Python SDK's `NetraFastAPIMiddleware`.
+ *
+ * **Note:** In Express 4.x, async errors thrown inside downstream handlers are
+ * not automatically caught by the Express error handler. Wrap async route
+ * handlers with your own try/catch or use Express 5 which supports async
+ * error propagation natively.
+ *
+ * @returns An Express middleware function.
+ *
+ * @example
+ * ```ts
+ * import express from "express";
+ * import { netraExpressMiddleware } from "netra-sdk";
+ *
+ * const app = express();
+ * app.use(netraExpressMiddleware());
+ *
+ * app.post("/api/chat", async (req, res) => {
+ *   // Spans created here are children of the upstream trace
+ *   const result = await myAgent(req.body.message);
+ *   res.json(result);
+ * });
+ * ```
+ */
+declare function netraExpressMiddleware(): (req: {
+    headers: Record<string, string | string[] | undefined>;
+}, res: unknown, next: () => void) => void;
+
 /**
  * Netra SDK - Main entry point
  * A comprehensive TypeScript/JavaScript SDK for AI application observability
@@ -1453,4 +1528,4 @@ declare class Netra {
     static withBlockedSpansLocal: typeof withBlockedSpansLocal;
 }
 
-export { type ActionModel, Aggregation, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, openaiAgentsInstrumentor, span, task, workflow };
+export { type ActionModel, Aggregation, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, netraExpressMiddleware, openaiAgentsInstrumentor, runWithExtractedContext, span, task, workflow };

package/dist/index.d.ts

@@ -1206,13 +1206,12 @@ declare class NetraMistralAIInstrumentor {
     instrumentationDependencies(): string[];
     /**
      * Instrument MistralAI client methods (async version)
-     * Uses dynamic import() to ensure we get the same ES module instance
-     * that the application uses.
+     * Tries both ESM and CJS resolution to cover dual-package setups.
      */
     instrumentAsync(options?: InstrumentorOptions$1): Promise<NetraMistralAIInstrumentor>;
     /**
      * Instrument MistralAI client methods (sync version - for backwards compatibility)
-     * Note: This uses a cached Mistral class. Call instrumentAsync() for proper initialization.
+     * Note: This uses cached Mistral classes. Call instrumentAsync() for proper initialization.
      */
     instrument(options?: InstrumentorOptions$1): NetraMistralAIInstrumentor;
     /**
@@ -1390,6 +1389,82 @@ declare class TrialAwareOTLPExporter implements SpanExporter {
     shutdown(): Promise<void>;
 }
 
+/**
+ * Public helpers for distributed tracing context propagation.
+ *
+ * These utilities let users extract incoming W3C Trace Context from HTTP
+ * headers and run code within that context so that all child spans (LLM
+ * calls, database queries, outgoing HTTP, etc.) are linked to the upstream
+ * trace.
+ *
+ * When `@opentelemetry/instrumentation-http` + `@opentelemetry/instrumentation-express`
+ * are installed and working, incoming context extraction happens automatically.
+ * These helpers cover cases where auto-instrumentation is unavailable (e.g.
+ * ESM module loading order issues, missing peer dependencies, or non-Express
+ * frameworks).
+ */
+
+/**
+ * Run a function within a context extracted from HTTP headers.
+ *
+ * All spans created inside `fn` will be children of the trace described by the
+ * incoming `traceparent` / `tracestate` headers, enabling end-to-end
+ * distributed tracing across service boundaries.
+ *
+ * @param headers - Incoming HTTP request headers (e.g. `req.headers`).
+ * @param fn      - The function to execute within the extracted context.
+ *                  May be sync or async -- the return value is forwarded as-is.
+ * @returns The return value of `fn`.
+ *
+ * @example
+ * ```ts
+ * import { runWithExtractedContext } from "netra";
+ *
+ * app.post("/api/chat", async (req, res) => {
+ *   await runWithExtractedContext(req.headers, async () => {
+ *     const result = await myAgent(req.body.message);
+ *     res.json(result);
+ *   });
+ * });
+ * ```
+ */
+declare function runWithExtractedContext<T>(headers: Record<string, string | string[] | undefined>, fn: () => T): T;
+/**
+ * Express/Connect-compatible middleware that extracts W3C Trace Context from
+ * incoming request headers and runs all downstream handlers within the
+ * extracted context.
+ *
+ * This is the recommended way to enable distributed tracing for Express
+ * servers when `@opentelemetry/instrumentation-http` is not available or not
+ * working (e.g. due to ESM module loading order with `tsx`). It is the
+ * TypeScript equivalent of the Python SDK's `NetraFastAPIMiddleware`.
+ *
+ * **Note:** In Express 4.x, async errors thrown inside downstream handlers are
+ * not automatically caught by the Express error handler. Wrap async route
+ * handlers with your own try/catch or use Express 5 which supports async
+ * error propagation natively.
+ *
+ * @returns An Express middleware function.
+ *
+ * @example
+ * ```ts
+ * import express from "express";
+ * import { netraExpressMiddleware } from "netra-sdk";
+ *
+ * const app = express();
+ * app.use(netraExpressMiddleware());
+ *
+ * app.post("/api/chat", async (req, res) => {
+ *   // Spans created here are children of the upstream trace
+ *   const result = await myAgent(req.body.message);
+ *   res.json(result);
+ * });
+ * ```
+ */
+declare function netraExpressMiddleware(): (req: {
+    headers: Record<string, string | string[] | undefined>;
+}, res: unknown, next: () => void) => void;
+
 /**
  * Netra SDK - Main entry point
  * A comprehensive TypeScript/JavaScript SDK for AI application observability
@@ -1453,4 +1528,4 @@ declare class Netra {
     static withBlockedSpansLocal: typeof withBlockedSpansLocal;
 }
 
-export { type ActionModel, Aggregation, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, openaiAgentsInstrumentor, span, task, workflow };
+export { type ActionModel, Aggregation, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, netraExpressMiddleware, openaiAgentsInstrumentor, runWithExtractedContext, span, task, workflow };