@hue-run/sdk 0.1.2 → 0.1.3

package/README.md

@@ -177,6 +177,39 @@ drain, including records emitted before its call. Stop request production
 before shutdown so late spans cannot race it. A client does not own instrumented
 operations still running in the application.
 
+## Verify a stored application trace
+
+After exercising a real application request and finishing its stream, flush the
+providers that own its spans, then verify their OpenTelemetry IDs:
+
+```ts
+// traceId and requestSpanId come from the application request you just exercised.
+await hue.flush(); // borrowed providers must also finish their own work
+const result = await hue.verifyTrace(traceId, {
+  expectedSpanIds: [requestSpanId], // include known model/tool span IDs when available
+  requiredFields: ["input", "output", "model"], // choose fields this request should emit
+});
+if (!result.verified) throw new Error("Trace verification timed out; inspect missing spans and fields.");
+console.log(result.receipt?.traceUrl);
+```
+
+Available in TypeScript `0.1.3`. `verifyTrace` makes a read-only, project-key-authenticated
+receipt request. It does not flush, run your application, create a test span, or
+read captured values. `fields` reports the presence of stored normalized input,
+output, model, usage, and session data across the trace; it does not establish
+content correctness or that every possible span has arrived. Leave unknown usage
+and intentionally disabled content out of `requiredFields`.
+
+The default budget is 10 seconds; set `timeoutMillis` up to 60,000. Only a recognized
+missing trace, HTTP 429, or HTTP 503 is retried, respecting `Retry-After` and the
+overall deadline. Incomplete evidence is also checked again within that deadline.
+A timeout returns `{ verified: false, receipt }`, retaining the latest observed
+receipt or `null`. Authentication, unsupported endpoint, transport, and invalid
+response failures throw `HueTraceVerificationError` with a safe `code` and optional
+HTTP `status`. Missing expected spans and required fields remain explicit; a 200
+response alone is not success. A successful result verifies those requested
+conditions only. Use Hue's UI to inspect captured values and redaction.
+
 ## Package verification
 
 From the repository root with Node 24 and Bun 1.3.9 on PATH:

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 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 } from "./types.js";
+import type { ExportReport, FlushableLoggerProvider, FlushableTracerProvider, HueOptions, HueSpan, JsonValue, ProjectConnection, SpanOptions, VerifyTraceOptions, TraceVerification } from "./types.js";
 export interface ExistingHueProviders {
     transport: HueTransport;
     tracerProvider: FlushableTracerProvider;
@@ -23,6 +23,7 @@ export declare class HueClient {
     private shutdownPromise?;
     private flushPromise?;
     constructor(options: HueOptions | ExistingHueProviders);
+    verifyTrace(traceId: string, options?: VerifyTraceOptions): Promise<TraceVerification>;
     getContext(): Context;
     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>;

package/dist/client.js

@@ -6,6 +6,7 @@ import { TracerProvider } from "@opentelemetry/sdk-trace";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { MAX_CONTENT_BYTES } from "./config.js";
 import { createHueTransport, HueExportError } from "./transport.js";
+import { verifyTrace } from "./receipt.js";
 export class HueConnectionError extends Error {
     status;
     constructor(message, status) {
@@ -97,8 +98,11 @@ export class HueClient {
             this.loggerProvider = logger;
         }
         this.captureContent = this.transport.options.captureContent;
-        this.tracer = new ContextualTracer(this.tracerProvider.getTracer("@hue-run/sdk", "0.1.2"), this.storage);
-        this.logger = this.loggerProvider.getLogger("@hue-run/sdk", "0.1.2");
+        this.tracer = new ContextualTracer(this.tracerProvider.getTracer("@hue-run/sdk", "0.1.3"), this.storage);
+        this.logger = this.loggerProvider.getLogger("@hue-run/sdk", "0.1.3");
+    }
+    verifyTrace(traceId, options = {}) {
+        return verifyTrace(this.transport.options, traceId, options);
     }
     getContext() {
         return this.storage.getStore()?.context ?? context.active();

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { createHue, HueClient, HueConnectionError, type ExistingHueProviders } from "./client.js";
 export { createHueTransport, HueTransport, HueExportError } from "./transport.js";
+export { HueTraceVerificationError } from "./receipt.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { createHue, HueClient, HueConnectionError } from "./client.js";
 export { createHueTransport, HueTransport, HueExportError } from "./transport.js";
+export { HueTraceVerificationError } from "./receipt.js";

package/dist/receipt.d.ts

@@ -0,0 +1,10 @@
+import type { HueOptions, TraceVerification, VerifyTraceOptions } from "./types.js";
+export declare class HueTraceVerificationError extends Error {
+    readonly code: "authentication" | "http" | "invalid_response" | "transport";
+    readonly status?: number | undefined;
+    constructor(code: "authentication" | "http" | "invalid_response" | "transport", message: string, status?: number | undefined);
+}
+/** Observe persisted evidence after the application and its exporter have finished. */
+export declare function verifyTrace(connection: Pick<HueOptions, "apiKey"> & {
+    baseUrl: string;
+}, traceId: string, options?: VerifyTraceOptions): Promise<TraceVerification>;

package/dist/receipt.js

@@ -0,0 +1,207 @@
+const fields = ["input", "output", "model", "usage", "session"];
+const MAX_RESPONSE_BYTES = 64 * 1024;
+export class HueTraceVerificationError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "HueTraceVerificationError";
+    }
+}
+function invalidResponse() {
+    throw new HueTraceVerificationError("invalid_response", "Hue returned an invalid trace receipt. Check the server and SDK versions.");
+}
+function validId(value, length) {
+    return (typeof value === "string" &&
+        value.length === length &&
+        new RegExp(`^[0-9a-f]{${length}}$`).test(value) &&
+        !/^0+$/.test(value));
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseReceipt(value, traceId, expected, origin) {
+    if (!record(value) ||
+        value.traceId !== traceId ||
+        !Number.isSafeInteger(value.spanCount) ||
+        value.spanCount < 0 ||
+        !Number.isSafeInteger(value.revision) ||
+        value.revision < 0 ||
+        !record(value.fields) ||
+        fields.some((field) => typeof value.fields[field] !== "boolean") ||
+        typeof value.traceUrl !== "string" ||
+        value.traceUrl.length > 2048)
+        invalidResponse();
+    let traceUrl;
+    try {
+        traceUrl = new URL(value.traceUrl);
+    }
+    catch {
+        invalidResponse();
+    }
+    if (traceUrl.origin !== origin || traceUrl.username || traceUrl.password)
+        invalidResponse();
+    const matched = value.matchedSpanIds, missing = value.missingSpanIds;
+    if (!Array.isArray(matched) ||
+        !Array.isArray(missing) ||
+        matched.length + missing.length !== expected.length ||
+        [...matched, ...missing].some((id) => !validId(id, 16) || !expected.includes(id)) ||
+        new Set([...matched, ...missing]).size !== expected.length ||
+        matched.length > value.spanCount)
+        invalidResponse();
+    // Return only the documented fields, never arbitrary response content.
+    return {
+        traceId,
+        spanCount: value.spanCount,
+        revision: value.revision,
+        fields: Object.fromEntries(fields.map((field) => [field, value.fields[field]])),
+        matchedSpanIds: expected.filter((id) => matched.includes(id)),
+        missingSpanIds: expected.filter((id) => missing.includes(id)),
+        traceUrl: traceUrl.href,
+    };
+}
+async function readJson(response) {
+    const length = response.headers.get("content-length");
+    if (length && /^\d+$/.test(length) && Number(length) > MAX_RESPONSE_BYTES) {
+        await response.body?.cancel();
+        invalidResponse();
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        invalidResponse();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (size > MAX_RESPONSE_BYTES) {
+                await reader.cancel();
+                invalidResponse();
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        invalidResponse();
+    }
+}
+function retryDelay(value) {
+    if (!value)
+        return 0;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0;
+}
+async function pause(milliseconds, signal) {
+    if (signal.aborted)
+        return;
+    await new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, milliseconds);
+        signal.addEventListener("abort", finish, { once: true });
+    });
+}
+/** Observe persisted evidence after the application and its exporter have finished. */
+export async function verifyTrace(connection, traceId, options = {}) {
+    if (!validId(traceId, 32))
+        throw new TypeError("traceId must be a nonzero lowercase 32-character OpenTelemetry trace ID");
+    if (options === null || typeof options !== "object" || Array.isArray(options))
+        throw new TypeError("Trace verification options must be an object");
+    const expected = options.expectedSpanIds === undefined ? [] : options.expectedSpanIds;
+    if (!Array.isArray(expected) ||
+        expected.length > 100 ||
+        expected.some((id) => !validId(id, 16)) ||
+        new Set(expected).size !== expected.length)
+        throw new TypeError("expectedSpanIds must contain at most 100 unique nonzero lowercase 16-character span IDs");
+    const required = options.requiredFields === undefined ? [] : options.requiredFields;
+    if (!Array.isArray(required) ||
+        required.some((field) => !fields.includes(field)) ||
+        new Set(required).size !== required.length)
+        throw new TypeError("requiredFields must contain unique receipt field names: input, output, model, usage, session");
+    const timeout = options.timeoutMillis === undefined ? 10_000 : options.timeoutMillis;
+    if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 60_000)
+        throw new TypeError("timeoutMillis must be greater than zero and at most 60000");
+    // Snapshot caller arrays so concurrent mutation cannot alter the verification criteria.
+    const expectedIds = [...expected], requiredFields = [...required];
+    const url = new URL(`/api/v1/traces/${traceId}/receipt`, connection.baseUrl);
+    for (const id of expectedIds)
+        url.searchParams.append("expectedSpanId", id);
+    const controller = new AbortController();
+    const deadline = performance.now() + timeout;
+    const timer = setTimeout(() => controller.abort(), timeout);
+    let receipt = null;
+    let delay = 250;
+    try {
+        while (!controller.signal.aborted && performance.now() < deadline) {
+            const response = await fetch(url, {
+                headers: { Authorization: `Bearer ${connection.apiKey}`, Accept: "application/json" },
+                redirect: "manual",
+                credentials: "omit",
+                cache: "no-store",
+                signal: controller.signal,
+            });
+            let retryAfter = 0;
+            if (response.status === 200) {
+                receipt = parseReceipt(await readJson(response), traceId, expectedIds, url.origin);
+                if (!controller.signal.aborted &&
+                    performance.now() < deadline &&
+                    receipt.missingSpanIds.length === 0 &&
+                    requiredFields.every((field) => receipt.fields[field]))
+                    return { verified: true, receipt };
+            }
+            else if (response.status === 404) {
+                const body = await readJson(response);
+                if (!record(body) || body.code !== "TRACE_NOT_FOUND")
+                    throw new HueTraceVerificationError("http", "This Hue server does not support trace receipts. Check the server version and baseUrl.", 404);
+            }
+            else {
+                await response.body?.cancel();
+                if (response.status === 429 || response.status === 503) {
+                    retryAfter = retryDelay(response.headers.get("retry-after"));
+                }
+                else if (response.status === 401 || response.status === 403) {
+                    throw new HueTraceVerificationError("authentication", "Hue denied trace verification. Check the project key, its access, and expiration.", response.status);
+                }
+                else {
+                    throw new HueTraceVerificationError("http", "Hue refused trace verification. Check the server version and configured origin; redirects are not followed.", response.status);
+                }
+            }
+            const remaining = deadline - performance.now();
+            if (remaining <= 0)
+                break;
+            const wait = Math.max(delay, retryAfter);
+            await pause(Math.min(wait, remaining), controller.signal);
+            // A truncated backoff exhausts this call even if a timer wakes just early.
+            if (wait >= remaining)
+                break;
+            delay = Math.min(delay * 2, 1000);
+        }
+    }
+    catch (error) {
+        if (!controller.signal.aborted && performance.now() < deadline) {
+            if (error instanceof HueTraceVerificationError)
+                throw error;
+            throw new HueTraceVerificationError("transport", "Hue trace verification could not reach the server. Check the network and configured origin.");
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return { verified: false, receipt };
+}

package/dist/types.d.ts

@@ -61,3 +61,24 @@ export interface ProjectConnection {
     organizationId: string;
     slug: string;
 }
+export type TraceReceiptField = "input" | "output" | "model" | "usage" | "session";
+export interface TraceReceipt {
+    traceId: string;
+    spanCount: number;
+    revision: number;
+    /** Presence of stored normalized fields; not a judgment of content correctness. */
+    fields: Record<TraceReceiptField, boolean>;
+    matchedSpanIds: string[];
+    missingSpanIds: string[];
+    traceUrl: string;
+}
+export interface VerifyTraceOptions {
+    expectedSpanIds?: string[];
+    requiredFields?: TraceReceiptField[];
+    /** Total request/retry budget, including response bodies. Default 10000; maximum 60000. */
+    timeoutMillis?: number;
+}
+export interface TraceVerification {
+    verified: boolean;
+    receipt: TraceReceipt | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "license": "MIT",
   "publishConfig": {