@hue-run/sdk 0.1.5 → 0.2.0

package/dist/client.js

@@ -1,16 +1,26 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { context, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { context, isSpanContextValid, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { defaultTextMapGetter, defaultTextMapSetter } from "@opentelemetry/api";
 import { SeverityNumber } from "@opentelemetry/api-logs";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { LoggerProvider } from "@opentelemetry/sdk-logs";
 import { TracerProvider } from "@opentelemetry/sdk-trace";
-import { resourceFromAttributes } from "@opentelemetry/resources";
+import { defaultResource, resourceFromAttributes } from "@opentelemetry/resources";
 import { encodeContent, noopSpan, safeSpan } from "./safety.js";
 import { createHueTransport, HueExportError } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
+import { sdkVersion } from "./version.js";
+/**
+ * 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 class HueConnectionError extends Error {
     status;
-    constructor(message, status) {
-        super(message);
+    constructor(message, 
+    /** HTTP status when Hue answered; absent for network, timeout and parsing failures. */
+    status, options) {
+        super(message, options);
         this.status = status;
         this.name = "HueConnectionError";
     }
@@ -26,6 +36,42 @@ function identifier(value) {
         throw new TypeError("Session/user identifiers must contain 1–4096 valid characters");
     return value;
 }
+/** A usable metadata label: a non-blank string of at most 256 characters. */
+function isLabel(value) {
+    return typeof value === "string" && value.trim() !== "" && value.length <= 256;
+}
+/**
+ * Runs `work` exactly once with `active` as OpenTelemetry's current context, so instrumentations
+ * that use the global API parent under the Hue span. Without a registered context manager
+ * `context.with` only calls `work`; a failing manager is counted and cannot skip or rerun `work`.
+ */
+function runInContext(active, work, failed) {
+    const slot = {};
+    const invoke = () => {
+        try {
+            return { value: work() };
+        }
+        catch (error) {
+            return { error };
+        }
+    };
+    try {
+        context.with(active, () => {
+            slot.outcome = invoke();
+        });
+    }
+    catch {
+        failed();
+    }
+    const settled = slot.outcome ?? invoke();
+    if ("error" in settled)
+        throw settled.error;
+    return settled.value;
+}
+/** Error class name for `error.type` and `exception.type`; never the message or stack. */
+function errorType(error) {
+    return error instanceof Error && error.name ? String(error.name) : "Error";
+}
 /** Local async context preserves nesting without registering or replacing global OTel providers. */
 class ContextualTracer {
     source;
@@ -77,21 +123,36 @@ class ContextualTracer {
             this.failed();
         }
         const span = this.startSpan(name, options, parent);
-        let active = ROOT_CONTEXT;
-        try {
-            active = trace.setSpan(parent, span);
-        }
-        catch {
-            this.failed();
-            active = trace.setSpan(ROOT_CONTEXT, span);
-        }
-        return this.storage.run({ ...this.storage.getStore(), context: active }, () => callback(span));
+        // A disabled client creates no span and leaves the application's active context untouched.
+        const created = isSpanContextValid(span.spanContext());
+        let active = parent;
+        if (created)
+            try {
+                active = trace.setSpan(parent, span);
+            }
+            catch {
+                this.failed();
+                active = trace.setSpan(ROOT_CONTEXT, span);
+            }
+        return this.storage.run({ ...this.storage.getStore(), context: active }, () => created
+            ? runInContext(active, () => callback(span), this.failed)
+            : callback(span));
     }
 }
+const propagator = new W3CTraceContextPropagator();
+/**
+ * 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 class HueClient {
+    /** Export pipeline: counters, issue history and the processors that feed Hue. */
     transport;
+    /** Hue's tracer for other instrumentations; spans parent under `withSpan` and inherit identifiers. */
     tracer;
+    /** Whether helpers record content, as configured. */
     captureContent;
+    /** False for `enabled: false` clients and for `createHueSafe` fallbacks; helpers then only run callbacks. */
     enabled;
     logger;
     storage = new AsyncLocalStorage();
@@ -108,13 +169,20 @@ export class HueClient {
             this.transport = options.transport;
             this.tracerProvider = options.tracerProvider;
             this.loggerProvider = options.loggerProvider;
+            if (this.transport.options.resourceAttributes !== undefined)
+                this.transport.issue("traces", "warning", 0, "resourceAttributes are ignored in attach mode; configure the resource on the application's providers");
         }
         else {
             this.transport = createHueTransport(options);
-            const resource = resourceFromAttributes({
-                "service.name": options.serviceName,
+            // The OpenTelemetry default resource supplies the required telemetry.sdk.* attributes and
+            // Hue's service identity is merged on top of any caller-supplied resourceAttributes, so
+            // serviceName and serviceVersion take precedence over same-named keys. Nothing here reads
+            // environment variables.
+            const resource = defaultResource().merge(resourceFromAttributes({
+                ...options.resourceAttributes,
+                "service.name": this.transport.options.serviceName,
                 ...(options.serviceVersion ? { "service.version": options.serviceVersion } : {}),
-            });
+            }));
             const tracer = new TracerProvider({
                 resource,
                 spanProcessors: this.transport.options.enabled === false ? [] : [this.transport.spanProcessor],
@@ -129,14 +197,23 @@ export class HueClient {
         }
         this.captureContent = this.transport.options.captureContent;
         this.enabled = this.transport.options.enabled !== false;
-        this.tracer = new ContextualTracer(this.tracerProvider.getTracer("@hue-run/sdk", "0.1.5"), this.storage, () => this.enabled && !this.closed, () => this.transport.instrumentationFailure());
-        this.logger = this.loggerProvider.getLogger("@hue-run/sdk", "0.1.5");
+        this.tracer = new ContextualTracer(this.tracerProvider.getTracer("@hue-run/sdk", sdkVersion), this.storage, () => this.enabled && !this.closed, () => this.transport.instrumentationFailure());
+        this.logger = this.loggerProvider.getLogger("@hue-run/sdk", sdkVersion);
     }
+    /**
+     * 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, options = {}) {
         if (!this.enabled)
             return Promise.reject(new HueConnectionError("Hue telemetry is disabled"));
         return verifyTrace(this.transport.options, traceId, options);
     }
+    /** The helper's current context: the innermost active Hue span, else the OpenTelemetry active context. */
     getContext() {
         try {
             return this.storage.getStore()?.context ?? context.active();
@@ -146,6 +223,10 @@ export class HueClient {
             return ROOT_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.
+     */
     async withSpan(name, callback, options = {}) {
         let span = noopSpan();
         let active = { context: this.getContext() };
@@ -156,6 +237,7 @@ export class HueClient {
                     context: options.parentContext ?? inherited?.context ?? context.active(),
                     sessionId: identifier(options.sessionId ?? inherited?.sessionId),
                     userId: identifier(options.userId ?? inherited?.userId),
+                    model: inherited?.model,
                 };
                 span = this.storage.run(active, () => this.tracer.startSpan(name, { kind: options.kind ?? SpanKind.INTERNAL, attributes: options.attributes }, active.context));
             }
@@ -163,14 +245,18 @@ export class HueClient {
                 this.transport.instrumentationFailure();
             }
         }
-        let spanContext;
-        try {
-            spanContext = trace.setSpan(active.context, span);
-        }
-        catch {
-            this.transport.instrumentationFailure();
-            spanContext = trace.setSpan(ROOT_CONTEXT, span);
-        }
+        // A disabled or failed client creates no span; the application's own active span then stays
+        // visible through getContext(), inject() and HueSpan.context instead of an invalid one.
+        const created = isSpanContextValid(span.spanContext());
+        let spanContext = active.context;
+        if (created)
+            try {
+                spanContext = trace.setSpan(active.context, span);
+            }
+            catch {
+                this.transport.instrumentationFailure();
+                spanContext = trace.setSpan(ROOT_CONTEXT, span);
+            }
         const handle = {
             span,
             context: spanContext,
@@ -178,8 +264,9 @@ export class HueClient {
             spanId: span.spanContext().spanId,
             setInput: (value) => this.setContent(span, "input.value", value),
             setOutput: (value) => this.setContent(span, "output.value", value),
+            setUsage: (usage) => this.setUsage(span, usage),
         };
-        return this.storage.run({ ...active, context: spanContext }, async () => {
+        const execute = async () => {
             // Setup, capture and cleanup have separate failure boundaries from customer code.
             try {
                 if (this.enabled && !this.closed && options.input !== undefined)
@@ -198,47 +285,168 @@ export class HueClient {
             finally {
                 span.end();
             }
-        });
+        };
+        // The span is also OpenTelemetry's active span while the callback runs, so spans from other
+        // instrumentations (HTTP clients, provider SDKs) join this trace when the application has
+        // registered a context manager. Hue still registers none itself.
+        return this.storage.run({ ...active, context: spanContext }, () => created
+            ? runInContext(spanContext, execute, () => this.transport.instrumentationFailure())
+            : execute());
     }
-    async tool(name, input, execute) {
-        return this.withSpan(name, async ({ span }) => {
+    /**
+     * 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.
+     */
+    async tool(name, input, execute, options = {}) {
+        const attributes = {
+            "gen_ai.operation.name": "execute_tool",
+            "gen_ai.tool.name": name,
+        };
+        const callId = options.callId;
+        if (callId !== undefined) {
+            // A blank or non-string id is omitted and counted; the tool call itself still runs.
+            if (isLabel(callId))
+                attributes["gen_ai.tool.call.id"] = callId;
+            else if (this.enabled && !this.closed)
+                this.transport.instrumentationFailure();
+        }
+        return this.withSpan(`execute_tool ${name}`, async ({ span }) => {
             this.setContent(span, "gen_ai.tool.call.arguments", input);
             const result = await execute();
             if (result !== undefined)
                 this.setContent(span, "gen_ai.tool.call.result", result);
             return result;
-        }, { attributes: { "gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": name } });
+        }, {
+            attributes,
+            ...(options.parentContext ? { parentContext: options.parentContext } : {}),
+        });
+    }
+    /**
+     * 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.
+     */
+    async model(model, callback, options) {
+        // A disabled or closed client creates no span, so invalid metadata is not an instrumentation
+        // failure either; only an active client records it (matching the other helpers).
+        const active = this.enabled && !this.closed;
+        const label = (value, fallback) => {
+            if (isLabel(value))
+                return value;
+            if (active)
+                this.transport.instrumentationFailure();
+            return fallback;
+        };
+        const requestModel = label(model, "unknown");
+        const operation = label(options?.operation ?? "chat", "chat");
+        const provider = label(options?.provider, "unknown");
+        const name = options?.name === undefined
+            ? `${operation} ${requestModel}`
+            : label(options.name, `${operation} ${requestModel}`);
+        const metadata = { operation, provider, requestModel };
+        const { sessionId, userId, parentContext, input } = options ?? {};
+        return this.withSpan(name, (span) => {
+            const handle = {
+                ...span,
+                setInput: (value) => this.setContent(span.span, "gen_ai.input.messages", value),
+                setOutput: (value) => this.setContent(span.span, "gen_ai.output.messages", value),
+            };
+            if (input !== undefined)
+                handle.setInput(input);
+            // recordMessages inside the callback copies this request metadata onto its log record.
+            const store = this.storage.getStore() ?? { context: span.context };
+            return this.storage.run({ ...store, model: metadata }, () => callback(handle));
+        }, {
+            sessionId,
+            userId,
+            parentContext,
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "gen_ai.operation.name": operation,
+                "gen_ai.request.model": requestModel,
+                "gen_ai.provider.name": provider,
+            },
+        });
+    }
+    setUsage(span, usage) {
+        if (!this.enabled || this.closed)
+            return;
+        for (const [key, value] of [
+            ["gen_ai.usage.input_tokens", usage?.inputTokens],
+            ["gen_ai.usage.output_tokens", usage?.outputTokens],
+        ]) {
+            if (value === undefined)
+                continue;
+            if (!Number.isInteger(value) || value < 0) {
+                this.transport.instrumentationFailure();
+                continue;
+            }
+            try {
+                span.setAttribute(key, value);
+            }
+            catch {
+                this.transport.instrumentationFailure();
+            }
+        }
+    }
+    /**
+     * 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, activeContext = this.getContext()) {
+        try {
+            propagator.inject(activeContext, carrier, defaultTextMapSetter);
+        }
+        catch {
+            this.transport.instrumentationFailure();
+        }
+    }
+    /** Reads W3C trace context from a carrier for use as `parentContext`. */
+    extract(carrier) {
+        try {
+            return propagator.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);
+        }
+        catch {
+            this.transport.instrumentationFailure();
+            return ROOT_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, error) {
         if (!this.enabled || this.closed)
             return;
         try {
-            const type = error instanceof Error ? error.name : "Error";
-            span.setStatus({
-                code: SpanStatusCode.ERROR,
-                ...(this.captureContent
-                    ? { message: error instanceof Error ? error.message : "Operation failed" }
-                    : {}),
-            });
-            span.addEvent("exception", {
-                "exception.type": type,
-                ...(this.captureContent && error instanceof Error
-                    ? {
-                        "exception.message": error.message,
-                        ...(error.stack ? { "exception.stacktrace": error.stack } : {}),
-                    }
-                    : {}),
-            });
+            const type = errorType(error);
+            span.setAttribute("error.type", type);
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            span.addEvent("exception", { "exception.type": type });
         }
         catch {
             this.transport.instrumentationFailure();
         }
     }
+    /**
+     * 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, explicitContext) {
         if (!this.enabled || this.closed || !this.captureContent)
             return;
         try {
-            const active = explicitContext ?? this.getContext();
+            const store = this.storage.getStore();
+            const active = explicitContext ?? store?.context ?? context.active();
             if (!trace.getSpanContext(active))
                 throw new Error("Message records require an active span or explicit span context");
             const body = {};
@@ -246,10 +454,29 @@ export class HueClient {
                 body["gen_ai.input.messages"] = messages.input;
             if (messages.output !== undefined)
                 body["gen_ai.output.messages"] = messages.output;
+            // Request metadata is inherited only when the record correlates with the enclosing helper
+            // scope; an unrelated explicit context carries caller-supplied values alone.
+            const enclosing = explicitContext === undefined || explicitContext === store?.context ? store : undefined;
+            const attributes = {};
+            const stamp = (key, explicit, inherited) => {
+                if (explicit === undefined) {
+                    if (inherited !== undefined)
+                        attributes[key] = inherited;
+                }
+                else if (typeof explicit === "string" && explicit.trim() && explicit.length <= 256)
+                    attributes[key] = explicit;
+                else
+                    this.transport.instrumentationFailure("logs");
+            };
+            stamp("gen_ai.operation.name", messages.operation, enclosing?.model?.operation);
+            stamp("gen_ai.provider.name", messages.provider, enclosing?.model?.provider);
+            stamp("gen_ai.request.model", messages.model, enclosing?.model?.requestModel);
+            stamp("gen_ai.conversation.id", undefined, enclosing?.sessionId);
             this.logger.emit({
                 context: active,
                 severityNumber: SeverityNumber.INFO,
                 eventName: "gen_ai.client.inference.operation.details",
+                attributes,
                 body: JSON.parse(encodeContent(body)),
             });
         }
@@ -267,6 +494,13 @@ export class HueClient {
             this.transport.instrumentationFailure();
         }
     }
+    /**
+     * 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.
+     */
     async checkConnection() {
         if (!this.enabled)
             throw new HueConnectionError("Hue telemetry is disabled");
@@ -279,8 +513,8 @@ export class HueClient {
                 signal: AbortSignal.timeout(options.timeoutMillis),
             });
         }
-        catch {
-            throw new HueConnectionError("Unable to connect to Hue; check the endpoint and network");
+        catch (error) {
+            throw new HueConnectionError("Unable to connect to Hue; check the endpoint and network", undefined, { cause: error });
         }
         if (!response.ok) {
             await response.body?.cancel();
@@ -322,8 +556,10 @@ export class HueClient {
                 slug: fields.slug,
             };
         }
-        catch {
-            throw new HueConnectionError("Hue returned an invalid project response");
+        catch (error) {
+            throw new HueConnectionError("Hue returned an invalid project response", undefined, {
+                cause: error,
+            });
         }
     }
     /** Production lifecycle path: never rejects; timeouts do not cancel borrowed provider work. */
@@ -382,6 +618,13 @@ export class HueClient {
             clearTimeout(timer);
         }
     }
+    /**
+     * 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() {
         // Each caller needs a drain after its own preceding span/log emissions.
         // Joining an earlier drain can acknowledge records that were not in its batch.
@@ -413,6 +656,12 @@ export class HueClient {
                 this.transport.issue(index === 0 ? "traces" : "logs", "failed", 0, "OpenTelemetry provider flush failed");
         return this.transport.flush();
     }
+    /**
+     * 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() {
         this.shutdownPromise ??= (async () => {
             this.closed = true;
@@ -432,17 +681,41 @@ export class HueClient {
         return this.shutdownPromise;
     }
 }
+/**
+ * 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 function createHue(options) {
     return new HueClient(options);
 }
-/** 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 function createHueSafe(options) {
     try {
         return new HueClient(options);
     }
-    catch {
-        const disabled = new HueClient({ enabled: false, captureContent: false });
-        disabled.transport.instrumentationFailure();
+    catch (error) {
+        // The caller's diagnostics hook stays attached and hears why telemetry is off.
+        const disabled = new HueClient({ enabled: false, onExportIssue: issueCallback(options) });
+        const reason = error instanceof Error && error.message ? error.message : "unknown error";
+        disabled.transport.instrumentationFailure("traces", `Hue is disabled: ${reason.slice(0, 256)}`);
         return disabled;
     }
 }
+function issueCallback(options) {
+    try {
+        const source = options && typeof options === "object" && "transport" in options
+            ? options.transport?.options
+            : options;
+        const callback = source?.onExportIssue;
+        return typeof callback === "function" ? callback : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/config.d.ts

@@ -1,4 +1,13 @@
-import type { HueOptions } from "./types.js";
+import type { HueOptions, SharedHueOptions } from "./types.js";
 export declare const MAX_BODY_BYTES: number;
 export declare const MAX_CONTENT_BYTES: number;
-export declare function validateOptions(options: HueOptions): Required<Pick<HueOptions, "apiKey" | "serviceName" | "baseUrl" | "captureContent" | "timeoutMillis" | "maxQueueBytes">> & HueOptions;
+/** Loopback hostnames that may use plain HTTP without opting in. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/** True when a validated origin exports over plain HTTP to a host other than loopback. */
+export declare function isInsecureOrigin(baseUrl: string): boolean;
+export declare function validateOptions(options: HueOptions): HueOptions & Required<Pick<SharedHueOptions, "captureContent" | "baseUrl" | "timeoutMillis" | "maxQueueBytes">> & {
+    /** Project key after validation; empty for a disabled client. */
+    apiKey: string;
+    /** Service name after validation; `hue-disabled` for a disabled client. */
+    serviceName: string;
+};

package/dist/config.js

@@ -1,13 +1,29 @@
 export const MAX_BODY_BYTES = 1024 * 1024;
 export const MAX_CONTENT_BYTES = 256 * 1024;
+/** Loopback hostnames that may use plain HTTP without opting in. */
+export function isLoopbackHost(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/** True when a validated origin exports over plain HTTP to a host other than loopback. */
+export function isInsecureOrigin(baseUrl) {
+    const url = new URL(baseUrl);
+    return url.protocol === "http:" && !isLoopbackHost(url.hostname);
+}
+// The return type stays anonymous: HueTransport.options exposes it through ReturnType, and the
+// API reference must not reference a name that is not part of the public entry points.
 export function validateOptions(options) {
-    if (typeof options.captureContent !== "boolean")
-        throw new TypeError("Choose captureContent explicitly: true or false");
     if (options.enabled !== undefined && typeof options.enabled !== "boolean")
         throw new TypeError("enabled must be a boolean");
-    if (options.enabled === false)
+    if (options.enabled === false) {
+        // The kill switch exports nothing, so the content decision defaults to metadata-only. The
+        // diagnostics hook stays attached so a disabled client can still report why it is off.
+        if (options.captureContent !== undefined && typeof options.captureContent !== "boolean")
+            throw new TypeError("captureContent must be a boolean");
         return {
-            captureContent: options.captureContent,
+            ...(typeof options.onExportIssue === "function"
+                ? { onExportIssue: options.onExportIssue }
+                : {}),
+            captureContent: options.captureContent ?? false,
             enabled: false,
             apiKey: "",
             serviceName: "hue-disabled",
@@ -15,6 +31,9 @@ export function validateOptions(options) {
             timeoutMillis: 10000,
             maxQueueBytes: 8 * 1024 * 1024,
         };
+    }
+    if (typeof options.captureContent !== "boolean")
+        throw new TypeError("Choose captureContent explicitly: true or false");
     if (typeof options.apiKey !== "string" ||
         !options.apiKey ||
         options.apiKey.length > 4096 ||
@@ -25,6 +44,13 @@ export function validateOptions(options) {
         !options.serviceName.trim() ||
         options.serviceName.length > 256)
         throw new TypeError("A serviceName of 1–256 characters is required");
+    if (options.allowInsecureHttp !== undefined && typeof options.allowInsecureHttp !== "boolean")
+        throw new TypeError("allowInsecureHttp must be a boolean");
+    if (options.resourceAttributes !== undefined &&
+        (options.resourceAttributes === null ||
+            typeof options.resourceAttributes !== "object" ||
+            Array.isArray(options.resourceAttributes)))
+        throw new TypeError("resourceAttributes must be an object of attribute values");
     let url;
     try {
         url = new URL(options.baseUrl ?? "https://app.hue.run");
@@ -32,9 +58,12 @@ export function validateOptions(options) {
     catch {
         throw new TypeError("Invalid Hue baseUrl");
     }
-    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
-    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback))
-        throw new TypeError("Hue requires HTTPS except for a loopback development server");
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        throw new TypeError("Hue baseUrl must use https, or http for a loopback development server");
+    if (url.protocol === "http:" &&
+        !isLoopbackHost(url.hostname) &&
+        options.allowInsecureHttp !== true)
+        throw new TypeError("Hue requires HTTPS except for a loopback development server; set allowInsecureHttp: true to export over plain HTTP to another host");
     if (url.username || url.password || url.pathname !== "/" || url.search || url.hash)
         throw new TypeError("Hue baseUrl must be an origin without credentials, a path, query parameters or fragments");
     const timeoutMillis = options.timeoutMillis ?? 10000;