@hue-run/sdk 0.1.5 → 0.2.1

package/dist/types.d.ts

@@ -1,107 +1,243 @@
-import type { Attributes, Context, Span, SpanKind, TracerProvider } from "@opentelemetry/api";
+import type { Attributes, Context, Span, SpanKind, Tracer, TracerProvider } from "@opentelemetry/api";
 import type { LoggerProvider } from "@opentelemetry/api-logs";
+/**
+ * JSON-compatible data: the shape content has on the wire after the helpers encode it. Helpers
+ * accept `unknown` and validate at runtime; values that are not plain JSON are omitted with an
+ * instrumentation failure instead of being thrown into application code.
+ */
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
+/** Telemetry signal named by export reports, issues and processors. */
 export type Signal = "traces" | "logs";
-interface SharedHueOptions {
+/** Options accepted by every Hue client and transport, whether enabled or disabled. */
+export interface SharedHueOptions {
+    /**
+     * Whether helpers record prompts, responses, tool arguments and results. Required for an enabled
+     * client, with no default; a disabled client (`enabled: false`) defaults it to `false`.
+     */
     captureContent: boolean;
+    /** Hue origin, `https://app.hue.run` by default. An origin only: no path, query, fragment or credentials. */
     baseUrl?: string;
+    /** Recorded as the `service.version` resource attribute of an owned client. */
     serviceVersion?: string;
+    /**
+     * Additional resource attributes for an owned client, for example `deployment.environment.name`
+     * or `service.namespace`. `service.name` and `service.version` from `serviceName` and
+     * `serviceVersion` take precedence over same-named keys, as in the OpenTelemetry NodeSDK.
+     * Ignored with a warning issue in attach mode, where the application owns the providers and
+     * their resource.
+     */
+    resourceAttributes?: Attributes;
+    /**
+     * Permits `http://` for hosts other than loopback, for example a docker-compose or in-cluster
+     * OpenTelemetry Collector. The project key then travels unencrypted; a one-time warning issue is
+     * recorded. Off by default: HTTPS is required except for loopback development servers.
+     */
+    allowInsecureHttp?: boolean;
     /** Runs on string values before Hue export, including custom attribute values. */
     redact?: (value: string, path: string) => string;
+    /** Receives sanitized export issues, at most one per second; never server response bodies or keys. */
     onExportIssue?: (issue: ExportIssue) => void | Promise<void>;
+    /** Budget for each export request and connection check in milliseconds, 100–60000. Default 10000. */
     timeoutMillis?: number;
     /** Aggregate estimated retained telemetry bytes across both signals, including in-flight work. Default 8 MiB. */
     maxQueueBytes?: number;
 }
-export type HueOptions = SharedHueOptions & ({
+/**
+ * Options for a client that owns its OpenTelemetry providers. An enabled client needs a project
+ * key, a service name and an explicit `captureContent` choice. The kill switch (`enabled: false`)
+ * exports nothing while helpers keep running application code, so it needs no key and
+ * `captureContent` defaults to `false`.
+ */
+export type HueOptions = (SharedHueOptions & {
+    /** Telemetry is on (the default). */
     enabled?: true;
+    /** Project service key sent as a Bearer token; server side only. */
     apiKey: string;
+    /** Recorded as the `service.name` resource attribute, 1–256 characters. */
     serviceName: string;
-} | {
+}) | (Omit<SharedHueOptions, "captureContent"> & {
+    /** Local kill switch: no providers, exports or connection checks. */
     enabled: false;
+    /** Ignored when disabled. */
     apiKey?: string;
+    /** Ignored when disabled. */
     serviceName?: string;
+    /** Optional when disabled; defaults to `false` because nothing is exported. */
+    captureContent?: boolean;
 });
+/** One sanitized delivery or instrumentation problem, kept in a bounded history of 128. */
 export interface ExportIssue {
+    /** Monotonic position in the transport's issue history. */
     sequence: number;
+    /** Signal the issue belongs to. */
     signal: Signal;
+    /** `rejected` by Hue, `failed` to deliver, `dropped` from the queue, `invalid` record or capture, or a non-failing `warning`. */
     kind: "rejected" | "failed" | "dropped" | "invalid" | "warning";
+    /** Records affected; zero for warnings and capture failures. */
     count: number;
+    /** HTTP status when the issue came from a response. */
     status?: number;
+    /** Fixed, sanitized description; never server text or content. */
     message: string;
 }
+/** Cumulative delivery counters and current queue gauges for one transport. */
 export interface ExportReport {
+    /** Spans acknowledged by the collector. */
     acceptedSpans: number;
+    /** Log records acknowledged by the collector. */
     acceptedLogs: number;
+    /** Spans the collector rejected in a partial success. */
     rejectedSpans: number;
+    /** Log records the collector rejected in a partial success. */
     rejectedLogs: number;
+    /** Spans whose delivery failed or is uncertain. */
     failedSpans: number;
+    /** Log records whose delivery failed or is uncertain. */
     failedLogs: number;
+    /** Spans queued or in flight right now. */
     pendingSpans: number;
+    /** Log records queued or in flight right now. */
     pendingLogs: number;
+    /** Spans dropped before export because a queue or byte budget was full. */
     droppedSpans: number;
+    /** Log records dropped before export because a queue or byte budget was full. */
     droppedLogs: number;
+    /** Estimated bytes retained by the queue right now. */
     pendingBytes: number;
+    /** Helper capture or instrumentation failures that omitted telemetry while preserving application results. */
     instrumentationFailures: number;
 }
+/** Caller budget for {@link HueClient.flushSafe} and {@link HueClient.shutdownSafe}. */
 export interface SafeLifecycleOptions {
     /** Caller wait budget, 1–60000 ms. Default 1000. Does not cancel borrowed providers. */
     timeoutMillis?: number;
 }
+/** Non-throwing lifecycle outcome. */
 export interface SafeLifecycleResult {
+    /** Work finished within the budget with no new failures and nothing pending. */
     ok: boolean;
+    /** The budget elapsed before the drain finished; work continues in the background. */
     timedOut: boolean;
+    /** Counters at the time the result was produced. */
     report: ExportReport;
 }
+/** Options for {@link HueClient.withSpan} and the span-level part of {@link HueClient.model}. */
 export interface SpanOptions {
+    /** OpenTelemetry span kind; `INTERNAL` by default. */
     kind?: SpanKind;
+    /** Attributes set when the span starts. */
     attributes?: Attributes;
+    /** Recorded as `gen_ai.conversation.id` on this span and inherited by nested helper spans. */
     sessionId?: string;
+    /** Recorded as `user.id` on this span and inherited by nested helper spans. */
     userId?: string;
-    input?: JsonValue;
+    /** Recorded as `input.value` when `captureContent` is true; any JSON-encodable value. */
+    input?: unknown;
+    /** Explicit parent context, for example from {@link HueClient.extract}. */
     parentContext?: Context;
 }
+/** Provider-reported token counts for {@link HueSpan.setUsage}. */
+export interface TokenUsage {
+    /** Provider-reported prompt tokens (`gen_ai.usage.input_tokens`). */
+    inputTokens?: number;
+    /** Provider-reported completion tokens (`gen_ai.usage.output_tokens`). */
+    outputTokens?: number;
+}
+/**
+ * Options for {@link HueClient.model}: GenAI request metadata plus the {@link SpanOptions} that
+ * apply to a client span. `input` is recorded as `gen_ai.input.messages`.
+ */
+export interface ModelOptions extends Pick<SpanOptions, "sessionId" | "userId" | "input" | "parentContext"> {
+    /** Provider identifier recorded as `gen_ai.provider.name`, for example "openai". */
+    provider: string;
+    /** Recorded as `gen_ai.operation.name`; defaults to "chat". */
+    operation?: string;
+    /** Span name; defaults to "{operation} {model}". */
+    name?: string;
+}
+/** Value for AI SDK 6's `experimental_telemetry` option; AI SDK 7 uses `hueTelemetry` instead. */
+export interface ExperimentalTelemetrySettings {
+    /** Mirrors the client's `enabled` flag. */
+    isEnabled: boolean;
+    /** Mirrors `captureContent`. */
+    recordInputs: boolean;
+    /** Mirrors `captureContent`. */
+    recordOutputs: boolean;
+    /** Hue's tracer, so AI SDK spans parent under `withSpan` and inherit identifiers. */
+    tracer: Tracer;
+}
+/** Handle passed to helper callbacks; content methods respect `captureContent` and never throw. */
 export interface HueSpan {
+    /** The underlying OpenTelemetry span, isolated so provider faults cannot reach the callback. */
     span: Span;
+    /** Context with this span active, for APIs that take an explicit context. */
     context: Context;
+    /** Lowercase hex trace ID, or all zeros when the client is disabled. */
     traceId: string;
+    /** Lowercase hex span ID, or all zeros when the client is disabled. */
     spanId: string;
-    setInput(value: JsonValue): void;
-    setOutput(value: JsonValue): void;
+    /** Records `input.value` (or `gen_ai.input.messages` inside `model()`); any JSON-encodable value. */
+    setInput(value: unknown): void;
+    /** Records `output.value` (or `gen_ai.output.messages` inside `model()`); any JSON-encodable value. */
+    setOutput(value: unknown): void;
+    /** Records nonnegative integer token counts; invalid values are omitted and counted as instrumentation failures. */
+    setUsage(usage: TokenUsage): void;
 }
+/** A tracer provider the client can drain; the OpenTelemetry SDK providers qualify. */
 export type FlushableTracerProvider = TracerProvider & {
+    /** Exports every finished span the provider still holds. */
     forceFlush(): Promise<void>;
 };
+/** A logger provider the client can drain; the OpenTelemetry SDK providers qualify. */
 export type FlushableLoggerProvider = LoggerProvider & {
+    /** Exports every emitted log record the provider still holds. */
     forceFlush(): Promise<void>;
 };
+/** Project identity returned by {@link HueClient.checkConnection}. */
 export interface ProjectConnection {
+    /** Project ID. */
     id: string;
+    /** Display name. */
     name: string;
+    /** Owning organization ID. */
     organizationId: string;
+    /** URL slug. */
     slug: string;
 }
+/** Normalized fields a stored trace receipt can report as present. */
 export type TraceReceiptField = "input" | "output" | "model" | "usage" | "session";
+/** Evidence that Hue stored a trace, returned by {@link HueClient.verifyTrace}. */
 export interface TraceReceipt {
+    /** The verified trace ID. */
     traceId: string;
+    /** Spans stored for the trace so far. */
     spanCount: number;
+    /** Storage revision; increases as more spans arrive. */
     revision: number;
     /** Presence of stored normalized fields; not a judgment of content correctness. */
     fields: Record<TraceReceiptField, boolean>;
+    /** Expected span IDs that are stored. */
     matchedSpanIds: string[];
+    /** Expected span IDs that are not stored yet. */
     missingSpanIds: string[];
+    /** Link to the trace in Hue, on the configured origin. */
     traceUrl: string;
 }
+/** Options for {@link HueClient.verifyTrace}. */
 export interface VerifyTraceOptions {
+    /** Up to 100 span IDs that must be stored before the trace counts as verified. */
     expectedSpanIds?: string[];
+    /** Normalized fields that must be present before the trace counts as verified. */
     requiredFields?: TraceReceiptField[];
     /** Total request/retry budget, including response bodies. Default 10000; maximum 60000. */
     timeoutMillis?: number;
 }
+/** Outcome of {@link HueClient.verifyTrace}. */
 export interface TraceVerification {
+    /** Every expected span and required field was stored within the budget. */
     verified: boolean;
+    /** Latest receipt observed, or `null` when the trace was never found. */
     receipt: TraceReceipt | null;
 }
-export {};

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** Package version shared by the instrumentation scope and the export User-Agent. */
+export declare const sdkVersion = "0.2.1";

package/dist/version.js

@@ -0,0 +1,3 @@
+// Generated by scripts/write-version.mjs from package.json; do not edit by hand.
+/** Package version shared by the instrumentation scope and the export User-Agent. */
+export const sdkVersion = "0.2.1";

package/package.json

@@ -1,48 +1,74 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "private": false,
   "license": "MIT",
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.org/",
-    "provenance": false
+    "registry": "https://registry.npmjs.org/"
   },
   "homepage": "https://docs.hue.run",
+  "bugs": {
+    "url": "https://github.com/hue-run/hue-sdk/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hue-run/hue-sdk.git",
     "directory": "packages/sdk-typescript"
   },
   "description": "Hue OpenTelemetry helpers for Node.js agent applications",
+  "keywords": [
+    "opentelemetry",
+    "otlp",
+    "tracing",
+    "observability",
+    "llm",
+    "ai-agents",
+    "evaluation",
+    "vercel-ai-sdk"
+  ],
   "files": [
     "dist",
     "README.md",
     "EVALUATIONS.md",
+    "ENVIRONMENTS.md",
     "MANAGED_TARGETS.md",
     "LICENSE"
   ],
   "type": "module",
+  "sideEffects": [
+    "./dist/evals/schema-worker.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./ai-sdk": {
       "types": "./dist/ai-sdk.d.ts",
-      "import": "./dist/ai-sdk.js"
+      "import": "./dist/ai-sdk.js",
+      "default": "./dist/ai-sdk.js"
     },
     "./evals": {
       "types": "./dist/evals.d.ts",
-      "import": "./dist/evals.js"
+      "import": "./dist/evals.js",
+      "default": "./dist/evals.js"
+    },
+    "./environment": {
+      "types": "./dist/environment.d.ts",
+      "import": "./dist/environment.js",
+      "default": "./dist/environment.js"
     },
     "./managed": {
       "types": "./dist/managed.d.ts",
-      "import": "./dist/managed.js"
-    }
+      "import": "./dist/managed.js",
+      "default": "./dist/managed.js"
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node scripts/write-version.mjs && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "bun test tests"
   },
@@ -53,22 +79,26 @@
     "@opentelemetry/otlp-transformer": "0.222.0",
     "@opentelemetry/resources": "2.11.0",
     "@opentelemetry/sdk-logs": "0.222.0",
-    "@opentelemetry/sdk-trace": "2.11.0",
-    "ajv": "8.20.0"
+    "@opentelemetry/sdk-trace": "2.11.0"
   },
   "devDependencies": {
     "@ai-sdk/otel": "1.0.99",
     "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/context-async-hooks": "2.11.0",
     "@types/bun": "1.4.2",
-    "@types/node": "24.10.1",
+    "@types/node": "26.5.1",
     "ai": "7.0.99",
+    "ajv": "8.20.0",
     "protobufjs": "8.8.0",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "zod": "4.6.5"
   },
   "peerDependencies": {
     "@ai-sdk/otel": "^1.0.99",
     "@opentelemetry/api": "^1.9.1",
-    "ai": "^6.0.0 || ^7.0.99"
+    "ai": "^6.0.0 || ^7.0.99",
+    "ajv": "^8.17.0",
+    "zod": "^4.6.5"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/otel": {
@@ -76,9 +106,15 @@
     },
     "ai": {
       "optional": true
+    },
+    "ajv": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=22.12"
   }
 }