@hue-run/sdk 0.1.5 → 0.2.0

package/dist/client.d.ts

@@ -1,19 +1,45 @@
 import { type Context, type Span, type Tracer } from "@opentelemetry/api";
 import { HueTransport } from "./transport.js";
-import type { ExportReport, FlushableLoggerProvider, FlushableTracerProvider, HueOptions, HueSpan, JsonValue, ProjectConnection, SpanOptions, VerifyTraceOptions, TraceVerification, SafeLifecycleOptions, SafeLifecycleResult } from "./types.js";
+import type { ExportReport, FlushableLoggerProvider, FlushableTracerProvider, HueOptions, HueSpan, ModelOptions, ProjectConnection, SpanOptions, VerifyTraceOptions, TraceVerification, SafeLifecycleOptions, SafeLifecycleResult } from "./types.js";
+/**
+ * Attach mode: the application owns its OpenTelemetry providers and passes the transport whose
+ * processors it attached to them. The client flushes these providers but never shuts them down.
+ */
 export interface ExistingHueProviders {
+    /** Transport from {@link createHueTransport} whose processors are attached to the providers below. */
     transport: HueTransport;
+    /** Application-owned tracer provider; must support `forceFlush()`. */
     tracerProvider: FlushableTracerProvider;
+    /** Application-owned logger provider; must support `forceFlush()`. */
     loggerProvider: FlushableLoggerProvider;
 }
+/**
+ * Thrown by {@link HueClient.checkConnection} and {@link HueClient.verifyTrace} when Hue cannot be
+ * reached, rejects the project key or answers unexpectedly. The message is fixed and safe to log;
+ * the underlying network, timeout or parsing error, when there is one, is available as `cause`.
+ */
 export declare class HueConnectionError extends Error {
+    /** HTTP status when Hue answered; absent for network, timeout and parsing failures. */
     readonly status?: number | undefined;
-    constructor(message: string, status?: number | undefined);
+    constructor(message: string, 
+    /** HTTP status when Hue answered; absent for network, timeout and parsing failures. */
+    status?: number | undefined, options?: {
+        cause?: unknown;
+    });
 }
+/**
+ * Hue tracing client. Helpers create spans through a private tracer and local async context, never
+ * through global OpenTelemetry registration, and they fail open: capture problems are counted in
+ * the export report while application code runs and returns unchanged.
+ */
 export declare class HueClient {
+    /** Export pipeline: counters, issue history and the processors that feed Hue. */
     readonly transport: HueTransport;
+    /** Hue's tracer for other instrumentations; spans parent under `withSpan` and inherit identifiers. */
     readonly tracer: Tracer;
+    /** Whether helpers record content, as configured. */
     readonly captureContent: boolean;
+    /** False for `enabled: false` clients and for `createHueSafe` fallbacks; helpers then only run callbacks. */
     readonly enabled: boolean;
     private logger;
     private storage;
@@ -26,26 +52,115 @@ export declare class HueClient {
     private safeFlushPromise?;
     private safeShutdownPromise?;
     constructor(options: HueOptions | ExistingHueProviders);
+    /**
+     * Verifies that Hue stored a trace by ID, optionally waiting for expected span IDs and normalized
+     * fields within the budget. Read-only; it does not flush or inspect content.
+     *
+     * @throws HueConnectionError when the client is disabled.
+     * @throws HueTraceVerificationError for authentication, unsupported endpoint, transport or invalid response failures.
+     * @throws TypeError for an invalid trace ID or options.
+     */
     verifyTrace(traceId: string, options?: VerifyTraceOptions): Promise<TraceVerification>;
+    /** The helper's current context: the innermost active Hue span, else the OpenTelemetry active context. */
     getContext(): Context;
+    /**
+     * Runs `callback` inside a new span that nests under the active Hue span. Application errors are
+     * recorded on the span and rethrown unchanged; the span always ends when the callback settles.
+     */
     withSpan<T>(name: string, callback: (span: HueSpan) => Promise<T> | T, options?: SpanOptions): Promise<T>;
-    tool<T extends JsonValue | undefined>(name: string, input: JsonValue, execute: () => Promise<T> | T): Promise<T>;
+    /**
+     * Runs `execute` inside an `execute_tool` span named after the tool. `input` and a defined result
+     * are recorded as `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result` when `captureContent`
+     * is true; values that are not JSON-encodable are omitted with an instrumentation failure.
+     * `options.callId` is recorded as `gen_ai.tool.call.id`, like the Python `call_id=` keyword.
+     */
+    tool<T>(name: string, input: unknown, execute: () => Promise<T> | T, options?: Pick<SpanOptions, "parentContext"> & {
+        /** Provider-issued identifier of this tool call, recorded as `gen_ai.tool.call.id`. */
+        callId?: string;
+    }): Promise<T>;
+    /**
+     * Runs `callback` inside a GenAI client span for one direct provider call, named
+     * `{operation} {model}` unless `options.name` is given and carrying `gen_ai.operation.name`,
+     * `gen_ai.request.model` and `gen_ai.provider.name`. The argument order matches `withSpan`. The
+     * handle's `setInput`/`setOutput` record `gen_ai.input.messages` / `gen_ai.output.messages`,
+     * which should use the GenAI semantic-convention message shape; `recordMessages` inside the
+     * callback inherits the request metadata.
+     */
+    model<T>(model: string, callback: (span: HueSpan) => Promise<T> | T, options: ModelOptions): Promise<T>;
+    private setUsage;
+    /**
+     * Writes W3C `traceparent` for the active span into a carrier; never the API key or baggage.
+     * Propagation also runs for a disabled or closed client so downstream tracing stays connected.
+     */
+    inject(carrier: Record<string, string>, activeContext?: Context): void;
+    /** Reads W3C trace context from a carrier for use as `parentContext`. */
+    extract(carrier: Record<string, string | string[] | undefined>): Context;
+    /**
+     * Marks a span failed the same way in every helper: `error.type`, an ERROR status without a
+     * description and an `exception` event carrying only the type. Exception messages and stack
+     * traces are never recorded, whatever `captureContent` is, matching the Python SDK.
+     */
     recordError(span: Span, error: unknown): void;
+    /**
+     * Emits a `gen_ai.client.inference.operation.details` log record correlated with the active (or
+     * given) span, carrying the messages in its body. `gen_ai.operation.name`, `gen_ai.provider.name`
+     * and `gen_ai.request.model` are set as record attributes from the caller's values or the
+     * enclosing {@link model} span, and `gen_ai.conversation.id` from the active session. Nothing is
+     * emitted when `captureContent` is false; capture failures are counted, never thrown.
+     */
     recordMessages(messages: {
-        input?: JsonValue;
-        output?: JsonValue;
+        /** Input messages, ideally in the GenAI semantic-convention shape; any JSON-encodable value. */
+        input?: unknown;
+        /** Output messages, ideally in the GenAI semantic-convention shape; any JSON-encodable value. */
+        output?: unknown;
+        /** `gen_ai.operation.name` for the record; defaults to the enclosing `model()` span's value. */
+        operation?: string;
+        /** `gen_ai.provider.name` for the record; defaults to the enclosing `model()` span's value. */
+        provider?: string;
+        /** `gen_ai.request.model` for the record; defaults to the enclosing `model()` span's value. */
+        model?: string;
     }, explicitContext?: Context): void;
     private setContent;
+    /**
+     * Confirms the key and origin by reading the current project; a setup and CI diagnostic, not a
+     * readiness gate. Redirects are refused and the response is bounded.
+     *
+     * @throws HueConnectionError when the client is disabled, Hue is unreachable (the network or
+     * timeout error is the `cause`), the key is rejected (`status` is set) or the response is invalid.
+     */
     checkConnection(): Promise<ProjectConnection>;
     /** Production lifecycle path: never rejects; timeouts do not cancel borrowed provider work. */
     flushSafe(options?: SafeLifecycleOptions): Promise<SafeLifecycleResult>;
     /** Safe for finally blocks; preserves the application's result or original exception. */
     shutdownSafe(options?: SafeLifecycleOptions): Promise<SafeLifecycleResult>;
     private safeLifecycle;
+    /**
+     * Drains the trace and log providers and waits for Hue's acknowledgements. Each caller gets a
+     * fresh serialized drain that includes records emitted before its call.
+     *
+     * @throws HueExportError when this drain observed a new rejection, delivery failure, drop or
+     * invalid record; its `issues` and `report` are sanitized counts, never server text.
+     */
     flush(): Promise<ExportReport>;
     private flushOnce;
+    /**
+     * Flushes, then shuts down the providers this client owns; borrowed providers are left running.
+     * Idempotent: later calls return the same promise, and later helper calls only run their callbacks.
+     *
+     * @throws HueExportError when the final flush observed new failures; owned providers are still released.
+     */
     shutdown(): Promise<ExportReport>;
 }
+/**
+ * Creates a client that owns its providers ({@link HueOptions}) or attaches to the application's
+ * ({@link ExistingHueProviders}). Strict: use it for setup and CI, `createHueSafe` in serving code.
+ *
+ * @throws TypeError for invalid options, including a missing `captureContent` choice, an invalid
+ * key or `serviceName`, a non-origin or insecure `baseUrl`, or out-of-range budgets.
+ */
 export declare function createHue(options: HueOptions | ExistingHueProviders): HueClient;
-/** Fail-open initialization for production; strict createHue remains available for setup/CI. */
+/**
+ * Fail-open initialization for production: invalid options return a disabled client with one
+ * instrumentation failure recorded instead of throwing. Strict {@link createHue} remains for setup/CI.
+ */
 export declare function createHueSafe(options: HueOptions | ExistingHueProviders): HueClient;