@hue-run/sdk 0.1.2

package/dist/privacy.js

@@ -0,0 +1,138 @@
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { MAX_CONTENT_BYTES } from "./config.js";
+const contentPrefixes = [
+    "gen_ai.input.messages",
+    "gen_ai.output.messages",
+    "gen_ai.system_instructions",
+    "gen_ai.prompt",
+    "gen_ai.completion",
+    "gen_ai.tool.call.arguments",
+    "gen_ai.tool.call.result",
+    "gen_ai.tool.definitions",
+    "gen_ai.event.content",
+    "llm.input_messages",
+    "llm.output_messages",
+    "llm.prompts",
+    "llm.completions",
+    "llm.invocation_parameters",
+    "input.value",
+    "output.value",
+    "ai.prompt",
+    "ai.response.text",
+    "ai.response.object",
+    "ai.response.toolCalls",
+    "ai.response.body",
+    "ai.toolCall.args",
+    "ai.toolCall.result",
+    "ai.value",
+    "ai.values",
+    "ai.embedding",
+    "ai.embeddings",
+    "traceloop.entity.input",
+    "traceloop.entity.output",
+    "tool.parameters",
+    "exception.message",
+    "exception.stacktrace",
+];
+// Kept as a function so metadata-only filtering is applied consistently to every exporter location.
+function isContentKey(key) {
+    return contentPrefixes.some((prefix) => key === prefix || key.startsWith(`${prefix}.`));
+}
+function redactValue(value, path, options, depth = 0) {
+    if (depth > 32)
+        throw new Error("Telemetry value exceeds the supported nesting limit");
+    if (typeof value === "string") {
+        const result = options.redact ? options.redact(value, path) : value;
+        if (typeof result !== "string" || !result.isWellFormed() || result.includes("\u0000"))
+            throw new Error("Redaction produced unsupported text");
+        if (Buffer.byteLength(result) > MAX_CONTENT_BYTES)
+            throw new Error("Telemetry text exceeds 256 KiB");
+        return result;
+    }
+    if (Array.isArray(value))
+        return value.map((item, index) => redactValue(item, `${path}.${index}`, options, depth + 1));
+    if (value instanceof Uint8Array) {
+        if (value.byteLength > MAX_CONTENT_BYTES)
+            throw new Error("Telemetry bytes exceed 256 KiB");
+        return value;
+    }
+    if (value !== null && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            redactValue(item, `${path}.${key}`, options, depth + 1),
+        ]));
+    return value;
+}
+function attributes(source, options, path) {
+    return Object.fromEntries(Object.entries(source).flatMap(([key, value]) => !options.captureContent && isContentKey(key)
+        ? []
+        : [[key, redactValue(value, `${path}.${key}`, options)]]));
+}
+function redactResource(resource, options, cache) {
+    let result = cache.get(resource);
+    if (!result) {
+        result = resourceFromAttributes(attributes(resource.attributes, options, "resource.attributes"), { schemaUrl: resource.schemaUrl });
+        cache.set(resource, result);
+    }
+    return result;
+}
+export function redactSpan(span, options, cache) {
+    return {
+        name: span.name,
+        kind: span.kind,
+        spanContext: () => span.spanContext(),
+        parentSpanContext: span.parentSpanContext,
+        startTime: span.startTime,
+        endTime: span.endTime,
+        duration: span.duration,
+        ended: span.ended,
+        status: {
+            code: span.status.code,
+            ...(options.captureContent && span.status.message !== undefined
+                ? { message: String(redactValue(span.status.message, "status.message", options)) }
+                : {}),
+        },
+        attributes: attributes(span.attributes, options, "attributes"),
+        events: span.events
+            .filter((event) => options.captureContent ||
+            !/^gen_ai\.(?:system|user|assistant|tool|choice)/.test(event.name))
+            .map((event) => ({
+            ...event,
+            attributes: attributes(event.attributes ?? {}, options, `events.${event.name}`),
+        })),
+        links: span.links.map((link) => ({
+            ...link,
+            attributes: attributes(link.attributes ?? {}, options, "links.attributes"),
+        })),
+        resource: redactResource(span.resource, options, cache),
+        instrumentationScope: span.instrumentationScope,
+        droppedAttributesCount: span.droppedAttributesCount,
+        droppedEventsCount: span.droppedEventsCount,
+        droppedLinksCount: span.droppedLinksCount,
+    };
+}
+export function redactLog(log, options, cache) {
+    const body = options.captureContent ? redactValue(log.body, "body", options) : undefined;
+    if (body !== undefined && Buffer.byteLength(JSON.stringify(body)) > MAX_CONTENT_BYTES)
+        throw new Error("Telemetry log body exceeds 256 KiB");
+    return {
+        hrTime: log.hrTime,
+        hrTimeObserved: log.hrTimeObserved,
+        spanContext: log.spanContext,
+        severityText: log.severityText,
+        severityNumber: log.severityNumber,
+        eventName: log.eventName,
+        body: body,
+        attributes: attributes(log.attributes, options, "attributes"),
+        resource: redactResource(log.resource, options, cache),
+        instrumentationScope: {
+            ...log.instrumentationScope,
+            ...(log.instrumentationScope.attributes
+                ? {
+                    attributes: attributes(log.instrumentationScope.attributes, options, "scope.attributes"),
+                }
+                : {}),
+        },
+        droppedAttributesCount: log.droppedAttributesCount,
+    };
+}

package/dist/transport.d.ts

@@ -0,0 +1,44 @@
+import { type ReadableSpan, type SpanProcessor } from "@opentelemetry/sdk-trace";
+import { type LogRecordProcessor, type ReadableLogRecord } from "@opentelemetry/sdk-logs";
+import { validateOptions } from "./config.js";
+import type { ExportIssue, ExportReport, HueOptions, Signal } from "./types.js";
+type RecordValue = ReadableSpan | ReadableLogRecord;
+export declare class HueExportError extends Error {
+    readonly issues: ExportIssue[];
+    readonly report: ExportReport;
+    constructor(issues: ExportIssue[], report: ExportReport);
+}
+/** Owned transport components; attach processors during provider construction. */
+export declare class HueTransport {
+    readonly options: ReturnType<typeof validateOptions>;
+    readonly spanProcessor: SpanProcessor;
+    readonly logRecordProcessor: LogRecordProcessor;
+    private sequence;
+    private observedSequence;
+    private failureSequence;
+    private issues;
+    private accepted;
+    private rejected;
+    private failed;
+    private spans;
+    private logs;
+    private traceExporter;
+    private logExporter;
+    private closed;
+    private shutdownPromise?;
+    private flushPromise?;
+    constructor(options: HueOptions);
+    private enqueue;
+    finish(signal: Signal, records: RecordValue[]): void;
+    acceptedRecords(signal: Signal, count: number): void;
+    issue(signal: Signal, kind: ExportIssue["kind"], count: number, message: string, status?: number): void;
+    getReport(): ExportReport;
+    getIssues(): ExportIssue[];
+    /** Monotonic failure marker, retained even when the bounded issue history rolls over. */
+    getFailureSequence(): number;
+    flush(): Promise<ExportReport>;
+    private flushOnce;
+    shutdown(): Promise<ExportReport>;
+}
+export declare function createHueTransport(options: HueOptions): HueTransport;
+export {};

package/dist/transport.js

@@ -0,0 +1,320 @@
+import { ExportResultCode } from "@opentelemetry/core";
+import { CompressionAlgorithm, OTLPExporterBase, OTLPExporterError, } from "@opentelemetry/otlp-exporter-base";
+import { convertLegacyHttpOptions, createOtlpHttpExportDelegate, } from "@opentelemetry/otlp-exporter-base/node-http";
+import { LogsExporterMetricsHelper, ProtobufLogsSerializer, ProtobufTraceSerializer, TraceExporterMetricsHelper, } from "@opentelemetry/otlp-transformer";
+import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace";
+import { BatchLogRecordProcessor, } from "@opentelemetry/sdk-logs";
+import { MAX_BODY_BYTES, validateOptions } from "./config.js";
+import { redactLog, redactSpan } from "./privacy.js";
+export class HueExportError extends Error {
+    issues;
+    report;
+    constructor(issues, report) {
+        super("Hue could not accept all telemetry. Inspect issues and report for sanitized counts.");
+        this.issues = issues;
+        this.report = report;
+        this.name = "HueExportError";
+    }
+}
+/** Owned transport components; attach processors during provider construction. */
+export class HueTransport {
+    options;
+    spanProcessor;
+    logRecordProcessor;
+    sequence = 0;
+    observedSequence = 0;
+    failureSequence = 0;
+    issues = [];
+    accepted = { traces: 0, logs: 0 };
+    rejected = { traces: 0, logs: 0 };
+    failed = { traces: 0, logs: 0 };
+    spans = new Set();
+    logs = new Set();
+    traceExporter;
+    logExporter;
+    closed = false;
+    shutdownPromise;
+    flushPromise;
+    constructor(options) {
+        this.options = validateOptions(options);
+        Object.defineProperty(this, "options", { enumerable: false });
+        this.traceExporter = new ReportingExporter(this, "traces", ProtobufTraceSerializer, TraceExporterMetricsHelper, (span, cache) => redactSpan(span, this.options, cache));
+        this.logExporter = new ReportingExporter(this, "logs", ProtobufLogsSerializer, LogsExporterMetricsHelper, (log, cache) => redactLog(log, this.options, cache));
+        const batching = {
+            maxQueueSize: 2048,
+            maxExportBatchSize: 128,
+            scheduledDelayMillis: 1000,
+            exportTimeoutMillis: this.options.timeoutMillis * 16 + 1000,
+        };
+        const spans = new BatchSpanProcessor({ exporter: this.traceExporter, ...batching });
+        const logs = new BatchLogRecordProcessor({ exporter: this.logExporter, ...batching });
+        this.spanProcessor = {
+            onStart: (span, parent) => spans.onStart(span, parent),
+            onEnd: (span) => {
+                if (!(span.spanContext().traceFlags & 1))
+                    return;
+                if (!this.enqueue("traces", span))
+                    return;
+                spans.onEnd(span);
+            },
+            forceFlush: () => spans.forceFlush(),
+            shutdown: () => spans.shutdown(),
+        };
+        this.logRecordProcessor = {
+            onEmit: (log) => {
+                if (!this.enqueue("logs", log))
+                    return;
+                logs.onEmit(log);
+            },
+            forceFlush: () => logs.forceFlush(),
+            shutdown: () => logs.shutdown(),
+        };
+    }
+    enqueue(signal, record) {
+        const pending = signal === "traces" ? this.spans : this.logs;
+        if (this.closed || pending.size >= 2048) {
+            this.issue(signal, "dropped", 1, this.closed
+                ? "Telemetry emitted after transport shutdown"
+                : "Telemetry queue reached 2048 records");
+            return false;
+        }
+        if (signal === "traces")
+            this.spans.add(record);
+        else
+            this.logs.add(record);
+        return true;
+    }
+    finish(signal, records) {
+        for (const record of records) {
+            if (signal === "traces")
+                this.spans.delete(record);
+            else
+                this.logs.delete(record);
+        }
+    }
+    acceptedRecords(signal, count) {
+        this.accepted[signal] += count;
+    }
+    issue(signal, kind, count, message, status) {
+        if (kind === "rejected")
+            this.rejected[signal] += count;
+        else if (kind !== "warning")
+            this.failed[signal] += count;
+        const issue = {
+            sequence: ++this.sequence,
+            signal,
+            kind,
+            count,
+            message,
+            ...(status !== undefined ? { status } : {}),
+        };
+        if (kind !== "warning")
+            this.failureSequence = issue.sequence;
+        this.issues.push(issue);
+        if (this.issues.length > 128)
+            this.issues.shift();
+        try {
+            this.options.onExportIssue?.({ ...issue });
+        }
+        catch {
+            /* Diagnostics callbacks cannot interrupt the customer's application. */
+        }
+    }
+    getReport() {
+        return {
+            acceptedSpans: this.accepted.traces,
+            acceptedLogs: this.accepted.logs,
+            rejectedSpans: this.rejected.traces,
+            rejectedLogs: this.rejected.logs,
+            failedSpans: this.failed.traces,
+            failedLogs: this.failed.logs,
+            pendingSpans: this.spans.size,
+            pendingLogs: this.logs.size,
+        };
+    }
+    getIssues() {
+        return this.issues.map((issue) => ({ ...issue }));
+    }
+    /** Monotonic failure marker, retained even when the bounded issue history rolls over. */
+    getFailureSequence() {
+        return this.failureSequence;
+    }
+    flush() {
+        const from = this.observedSequence;
+        const next = (this.flushPromise ?? Promise.resolve()).then(() => this.flushOnce(from), () => this.flushOnce(from));
+        this.flushPromise = next;
+        const clear = () => {
+            if (this.flushPromise === next)
+                this.flushPromise = undefined;
+        };
+        void next.then(clear, clear);
+        return next;
+    }
+    async flushOnce(from) {
+        const processors = await Promise.allSettled([
+            this.spanProcessor.forceFlush(),
+            this.logRecordProcessor.forceFlush(),
+        ]);
+        await Promise.all([this.traceExporter.forceFlush(), this.logExporter.forceFlush()]);
+        for (const [index, result] of processors.entries())
+            if (result.status === "rejected") {
+                const signal = index === 0 ? "traces" : "logs";
+                if (!this.issues.some((issue) => issue.sequence > from && issue.signal === signal))
+                    this.issue(signal, "failed", 0, "Telemetry processor flush failed");
+            }
+        const issues = this.issues.filter((issue) => issue.sequence > from && issue.kind !== "warning");
+        this.observedSequence = this.sequence;
+        const report = this.getReport();
+        if (this.failureSequence > from)
+            throw new HueExportError(issues, report);
+        return report;
+    }
+    shutdown() {
+        this.shutdownPromise ??= (async () => {
+            this.closed = true;
+            try {
+                return await this.flush();
+            }
+            finally {
+                await Promise.allSettled([
+                    this.spanProcessor.shutdown(),
+                    this.logRecordProcessor.shutdown(),
+                ]);
+            }
+        })();
+        return this.shutdownPromise;
+    }
+}
+class ReportingExporter {
+    transport;
+    signal;
+    serializer;
+    metrics;
+    redact;
+    pending = new Set();
+    constructor(transport, signal, serializer, metrics, redact) {
+        this.transport = transport;
+        this.signal = signal;
+        this.serializer = serializer;
+        this.metrics = metrics;
+        this.redact = redact;
+    }
+    export(records, callback) {
+        const work = this.exportRecords(records)
+            .then(() => callback({ code: ExportResultCode.SUCCESS }), () => callback({
+            code: ExportResultCode.FAILED,
+            error: new Error("Hue telemetry export failed; inspect SDK export issues"),
+        }))
+            .finally(() => {
+            this.transport.finish(this.signal, records);
+            this.pending.delete(work);
+        });
+        this.pending.add(work);
+    }
+    async exportRecords(records) {
+        const accepted = [];
+        const cache = new WeakMap();
+        let failed = false;
+        for (const record of records) {
+            try {
+                await record.resource.waitForAsyncAttributes?.();
+                accepted.push(this.redact(record, cache));
+            }
+            catch {
+                failed = true;
+                this.transport.issue(this.signal, "invalid", 1, "Telemetry record could not be redacted or exceeds supported content limits");
+            }
+        }
+        let batch = [];
+        for (const record of accepted) {
+            const candidate = [...batch, record];
+            // Leave room for gzip headers/blocks when otherwise incompressible data is near the wire cap.
+            if ((this.serializer.serializeRequest(candidate)?.byteLength ?? 0) <= MAX_BODY_BYTES - 1024) {
+                batch = candidate;
+                continue;
+            }
+            if (batch.length && !(await this.send(batch)))
+                failed = true;
+            batch = [];
+            if ((this.serializer.serializeRequest([record])?.byteLength ?? 0) > MAX_BODY_BYTES - 1024) {
+                failed = true;
+                this.transport.issue(this.signal, "invalid", 1, "Telemetry record exceeds the 1 MiB request limit");
+            }
+            else
+                batch = [record];
+        }
+        if (batch.length && !(await this.send(batch)))
+            failed = true;
+        if (failed)
+            throw new Error("Hue telemetry export failed");
+    }
+    async send(records) {
+        const options = this.transport.options;
+        let rejected = 0;
+        let validResponse = true;
+        const serializer = {
+            serializeRequest: (data) => this.serializer.serializeRequest(data),
+            deserializeResponse: (bytes) => {
+                try {
+                    const response = this.serializer.deserializeResponse(bytes);
+                    const partial = response.partialSuccess;
+                    const count = Number(partial?.[this.signal === "traces" ? "rejectedSpans" : "rejectedLogRecords"] ?? 0);
+                    if (!Number.isSafeInteger(count) || count < 0 || count > records.length)
+                        throw new Error("Invalid rejection count");
+                    rejected = count;
+                    if (count || partial?.errorMessage)
+                        this.transport.issue(this.signal, count ? "rejected" : "warning", count, count
+                            ? "Hue rejected telemetry records; inspect the project ingestion settings and supported limits"
+                            : "Hue returned an ingestion warning");
+                    // Do not pass backend error text or raw response bytes into the global OTel diagnostic logger.
+                    return {};
+                }
+                catch {
+                    validResponse = false;
+                    this.transport.issue(this.signal, "failed", records.length, "Hue returned an invalid OTLP acknowledgement; acceptance is uncertain");
+                    return {};
+                }
+            },
+        };
+        const endpoint = `${options.baseUrl}/api/v1/otlp/v1/${this.signal}`;
+        const delegate = createOtlpHttpExportDelegate(convertLegacyHttpOptions({
+            url: endpoint,
+            headers: { Authorization: `Bearer ${options.apiKey}` },
+            timeoutMillis: options.timeoutMillis,
+            concurrencyLimit: 1,
+            compression: CompressionAlgorithm.GZIP,
+        }, this.signal === "traces" ? "TRACES" : "LOGS", `v1/${this.signal}`, { "Content-Type": "application/x-protobuf" }), serializer, this.signal === "traces" ? "otlp_http_span_exporter" : "otlp_http_log_exporter", this.metrics, undefined);
+        const exporter = new OTLPExporterBase(delegate);
+        try {
+            const result = await new Promise((resolve) => exporter.export(records, resolve));
+            if (result.code === ExportResultCode.SUCCESS) {
+                if (validResponse)
+                    this.transport.acceptedRecords(this.signal, records.length - rejected);
+                return validResponse;
+            }
+            else {
+                const status = result.error instanceof OTLPExporterError && Number.isInteger(result.error.code)
+                    ? result.error.code
+                    : undefined;
+                this.transport.issue(this.signal, "failed", records.length, "Hue telemetry request failed", status);
+                return false;
+            }
+        }
+        catch {
+            this.transport.issue(this.signal, "failed", records.length, "Hue telemetry request failed");
+            return false;
+        }
+        finally {
+            await exporter.shutdown();
+        }
+    }
+    async forceFlush() {
+        await Promise.all(this.pending);
+    }
+    async shutdown() {
+        await this.forceFlush();
+    }
+}
+export function createHueTransport(options) {
+    return new HueTransport(options);
+}

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+import type { Attributes, Context, Span, SpanKind, TracerProvider } from "@opentelemetry/api";
+import type { LoggerProvider } from "@opentelemetry/api-logs";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type Signal = "traces" | "logs";
+export interface HueOptions {
+    apiKey: string;
+    serviceName: string;
+    captureContent: boolean;
+    baseUrl?: string;
+    serviceVersion?: string;
+    /** Runs on string values before Hue export, including custom attribute values. */
+    redact?: (value: string, path: string) => string;
+    onExportIssue?: (issue: ExportIssue) => void;
+    timeoutMillis?: number;
+}
+export interface ExportIssue {
+    sequence: number;
+    signal: Signal;
+    kind: "rejected" | "failed" | "dropped" | "invalid" | "warning";
+    count: number;
+    status?: number;
+    message: string;
+}
+export interface ExportReport {
+    acceptedSpans: number;
+    acceptedLogs: number;
+    rejectedSpans: number;
+    rejectedLogs: number;
+    failedSpans: number;
+    failedLogs: number;
+    pendingSpans: number;
+    pendingLogs: number;
+}
+export interface SpanOptions {
+    kind?: SpanKind;
+    attributes?: Attributes;
+    sessionId?: string;
+    userId?: string;
+    input?: JsonValue;
+    parentContext?: Context;
+}
+export interface HueSpan {
+    span: Span;
+    context: Context;
+    traceId: string;
+    spanId: string;
+    setInput(value: JsonValue): void;
+    setOutput(value: JsonValue): void;
+}
+export type FlushableTracerProvider = TracerProvider & {
+    forceFlush(): Promise<void>;
+};
+export type FlushableLoggerProvider = LoggerProvider & {
+    forceFlush(): Promise<void>;
+};
+export interface ProjectConnection {
+    id: string;
+    name: string;
+    organizationId: string;
+    slug: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@hue-run/sdk",
+  "version": "0.1.2",
+  "private": false,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": false
+  },
+  "homepage": "https://docs.hue.run",
+  "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",
+  "files": [
+    "dist",
+    "README.md",
+    "EVALUATIONS.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./ai-sdk": {
+      "types": "./dist/ai-sdk.d.ts",
+      "import": "./dist/ai-sdk.js"
+    },
+    "./evals": {
+      "types": "./dist/evals.d.ts",
+      "import": "./dist/evals.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test tests"
+  },
+  "dependencies": {
+    "@opentelemetry/api-logs": "0.222.0",
+    "@opentelemetry/core": "2.11.0",
+    "@opentelemetry/otlp-exporter-base": "0.222.0",
+    "@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"
+  },
+  "devDependencies": {
+    "@ai-sdk/otel": "1.0.99",
+    "@opentelemetry/api": "1.9.1",
+    "@types/bun": "1.4.2",
+    "@types/node": "24.10.1",
+    "ai": "7.0.99",
+    "protobufjs": "8.8.0",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "@ai-sdk/otel": "^1.0.99",
+    "@opentelemetry/api": "^1.9.1",
+    "ai": "^7.0.99"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/otel": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}