@highflame/sdk 0.3.3 → 0.3.5

package/dist/index.cjs

@@ -148,8 +148,53 @@ async function* streamSseResponse(response) {
   }
 }
 
+// src/telemetry.ts
+var _otelApi;
+function getOtelApi() {
+  if (_otelApi !== void 0) return _otelApi;
+  try {
+    _otelApi = require("@opentelemetry/api");
+  } catch {
+    _otelApi = null;
+  }
+  return _otelApi;
+}
+function injectTraceContext(headers) {
+  const api = getOtelApi();
+  if (!api) return;
+  const propagator = api.propagation;
+  const context = api.context.active();
+  propagator.inject(context, headers, {
+    set(carrier, key, value) {
+      carrier[key] = value;
+    }
+  });
+}
+async function withSpan(name, attributes, fn) {
+  const api = getOtelApi();
+  if (!api) return fn();
+  const tracer = api.trace.getTracer("@highflame/sdk", VERSION);
+  const parentContext = api.context.active();
+  const span = tracer.startSpan(name, { attributes }, parentContext);
+  const spanContext = api.trace.setSpan(parentContext, span);
+  try {
+    const result = await api.context.with(spanContext, fn);
+    span.setStatus({ code: api.SpanStatusCode.OK });
+    return result;
+  } catch (err) {
+    span.setStatus({
+      code: api.SpanStatusCode.ERROR,
+      message: err instanceof Error ? err.message : String(err)
+    });
+    span.recordException(err instanceof Error ? err : new Error(String(err)));
+    throw err;
+  } finally {
+    span.end();
+  }
+}
+
 // src/client.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.4";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
 var RETRY_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
@@ -201,7 +246,14 @@ var GuardResource = class {
   }
   /** Evaluate content against guard policies (POST /v1/guard). */
   async evaluate(request, options) {
-    return this._client._postJSON("/v1/guard", request, options?.timeout);
+    return withSpan(
+      "highflame.guard",
+      {
+        "highflame.action": request.action ?? "process_prompt",
+        "highflame.content_type": request.content_type ?? "prompt"
+      },
+      () => this._client._postJSON("/v1/guard", request, options?.timeout)
+    );
   }
   /** Shorthand: evaluate a user prompt. */
   async evaluatePrompt(content, options) {
@@ -236,7 +288,11 @@ var DetectResource = class {
   }
   /** Run detectors without policy evaluation (POST /v1/detect). */
   async run(request, options) {
-    return this._client._postJSON("/v1/detect", request, options?.timeout);
+    return withSpan(
+      "highflame.detect",
+      { "highflame.content_type": request.content_type ?? "prompt" },
+      () => this._client._postJSON("/v1/detect", request, options?.timeout)
+    );
   }
 };
 var DetectorsResource = class {
@@ -281,7 +337,7 @@ var Highflame = class {
     const baseUrl = options.baseUrl ?? SAAS_BASE_URL;
     const tokenUrl = options.tokenUrl ?? SAAS_TOKEN_URL;
     this.#baseUrl = baseUrl.replace(/\/$/, "");
-    this.#tokenUrl = options.apiKey.startsWith("hf_sk") ? tokenUrl : void 0;
+    this.#tokenUrl = options.apiKey.startsWith("hf_sk") || options.apiKey.startsWith("hfa_") ? tokenUrl : void 0;
     this.#apiKey = options.apiKey;
     this.#timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
     this.#maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
@@ -407,6 +463,7 @@ var Highflame = class {
         this.#log.debug("Request body: %s", truncate(init.body));
       }
       const authHeaders = await this.getAuthHeaders();
+      injectTraceContext(authHeaders);
       if (idempotencyKey) {
         authHeaders["X-Idempotency-Key"] = idempotencyKey;
       }
@@ -468,6 +525,7 @@ var Highflame = class {
     const effectiveTimeout = overrideTimeout ?? this.#timeout;
     this.#log.debug("POST %s (stream)", path);
     const authHeaders = await this.getAuthHeaders();
+    injectTraceContext(authHeaders);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), effectiveTimeout);
     let response;

package/dist/index.d.cts

@@ -506,8 +506,8 @@ interface ProblemDetails {
 interface StreamEvent {
     /** Event payload (DetectorResult for detector_result, GuardResponse for decision). */
     data: Record<string, unknown>;
-    /** Event type: detector_result (per-detector), decision (final), or error. */
-    type: "detector_result" | "decision" | "error";
+    /** Event type: detector_result (per-detector), decision (final), error, or message (keepalive/info). */
+    type: "detector_result" | "decision" | "error" | "message";
 }
 /** Response from the token exchange endpoint (used by SDK auth). */
 interface TokenResponse {
@@ -553,7 +553,7 @@ interface TokenResponse {
  */
 
 /** SDK version — kept in sync with package.json via `make version-sync`. */
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.4";
 /**
  * Pluggable logger interface.
  *
@@ -568,11 +568,11 @@ interface Logger {
     warn(message: string, ...args: unknown[]): void;
 }
 interface HighflameOptions {
-    /** Service API key (`hf_sk_...`) or a raw JWT. */
+    /** Service API key (`hf_sk_...`), agent API key (`hfa_...`), or a raw JWT. */
     apiKey: string;
     /** Base URL of the guard service. Defaults to Highflame SaaS. */
     baseUrl?: string;
-    /** Token exchange URL. Defaults to Highflame SaaS. Only used for `hf_sk_*` keys. */
+    /** Token exchange URL. Defaults to Highflame SaaS. Used for `hf_sk_*` and `hfa_*` keys. */
     tokenUrl?: string;
     /** Request timeout in milliseconds. Default: 30000. */
     timeout?: number;

package/dist/index.d.ts

@@ -506,8 +506,8 @@ interface ProblemDetails {
 interface StreamEvent {
     /** Event payload (DetectorResult for detector_result, GuardResponse for decision). */
     data: Record<string, unknown>;
-    /** Event type: detector_result (per-detector), decision (final), or error. */
-    type: "detector_result" | "decision" | "error";
+    /** Event type: detector_result (per-detector), decision (final), error, or message (keepalive/info). */
+    type: "detector_result" | "decision" | "error" | "message";
 }
 /** Response from the token exchange endpoint (used by SDK auth). */
 interface TokenResponse {
@@ -553,7 +553,7 @@ interface TokenResponse {
  */
 
 /** SDK version — kept in sync with package.json via `make version-sync`. */
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.4";
 /**
  * Pluggable logger interface.
  *
@@ -568,11 +568,11 @@ interface Logger {
     warn(message: string, ...args: unknown[]): void;
 }
 interface HighflameOptions {
-    /** Service API key (`hf_sk_...`) or a raw JWT. */
+    /** Service API key (`hf_sk_...`), agent API key (`hfa_...`), or a raw JWT. */
     apiKey: string;
     /** Base URL of the guard service. Defaults to Highflame SaaS. */
     baseUrl?: string;
-    /** Token exchange URL. Defaults to Highflame SaaS. Only used for `hf_sk_*` keys. */
+    /** Token exchange URL. Defaults to Highflame SaaS. Used for `hf_sk_*` and `hfa_*` keys. */
     tokenUrl?: string;
     /** Request timeout in milliseconds. Default: 30000. */
     timeout?: number;

package/dist/index.js

@@ -1,3 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/errors.ts
 var HighflameError = class extends Error {
   constructor(message) {
@@ -110,8 +117,53 @@ async function* streamSseResponse(response) {
   }
 }
 
+// src/telemetry.ts
+var _otelApi;
+function getOtelApi() {
+  if (_otelApi !== void 0) return _otelApi;
+  try {
+    _otelApi = __require("@opentelemetry/api");
+  } catch {
+    _otelApi = null;
+  }
+  return _otelApi;
+}
+function injectTraceContext(headers) {
+  const api = getOtelApi();
+  if (!api) return;
+  const propagator = api.propagation;
+  const context = api.context.active();
+  propagator.inject(context, headers, {
+    set(carrier, key, value) {
+      carrier[key] = value;
+    }
+  });
+}
+async function withSpan(name, attributes, fn) {
+  const api = getOtelApi();
+  if (!api) return fn();
+  const tracer = api.trace.getTracer("@highflame/sdk", VERSION);
+  const parentContext = api.context.active();
+  const span = tracer.startSpan(name, { attributes }, parentContext);
+  const spanContext = api.trace.setSpan(parentContext, span);
+  try {
+    const result = await api.context.with(spanContext, fn);
+    span.setStatus({ code: api.SpanStatusCode.OK });
+    return result;
+  } catch (err) {
+    span.setStatus({
+      code: api.SpanStatusCode.ERROR,
+      message: err instanceof Error ? err.message : String(err)
+    });
+    span.recordException(err instanceof Error ? err : new Error(String(err)));
+    throw err;
+  } finally {
+    span.end();
+  }
+}
+
 // src/client.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.4";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
 var RETRY_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
@@ -163,7 +215,14 @@ var GuardResource = class {
   }
   /** Evaluate content against guard policies (POST /v1/guard). */
   async evaluate(request, options) {
-    return this._client._postJSON("/v1/guard", request, options?.timeout);
+    return withSpan(
+      "highflame.guard",
+      {
+        "highflame.action": request.action ?? "process_prompt",
+        "highflame.content_type": request.content_type ?? "prompt"
+      },
+      () => this._client._postJSON("/v1/guard", request, options?.timeout)
+    );
   }
   /** Shorthand: evaluate a user prompt. */
   async evaluatePrompt(content, options) {
@@ -198,7 +257,11 @@ var DetectResource = class {
   }
   /** Run detectors without policy evaluation (POST /v1/detect). */
   async run(request, options) {
-    return this._client._postJSON("/v1/detect", request, options?.timeout);
+    return withSpan(
+      "highflame.detect",
+      { "highflame.content_type": request.content_type ?? "prompt" },
+      () => this._client._postJSON("/v1/detect", request, options?.timeout)
+    );
   }
 };
 var DetectorsResource = class {
@@ -243,7 +306,7 @@ var Highflame = class {
     const baseUrl = options.baseUrl ?? SAAS_BASE_URL;
     const tokenUrl = options.tokenUrl ?? SAAS_TOKEN_URL;
     this.#baseUrl = baseUrl.replace(/\/$/, "");
-    this.#tokenUrl = options.apiKey.startsWith("hf_sk") ? tokenUrl : void 0;
+    this.#tokenUrl = options.apiKey.startsWith("hf_sk") || options.apiKey.startsWith("hfa_") ? tokenUrl : void 0;
     this.#apiKey = options.apiKey;
     this.#timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
     this.#maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
@@ -369,6 +432,7 @@ var Highflame = class {
         this.#log.debug("Request body: %s", truncate(init.body));
       }
       const authHeaders = await this.getAuthHeaders();
+      injectTraceContext(authHeaders);
       if (idempotencyKey) {
         authHeaders["X-Idempotency-Key"] = idempotencyKey;
       }
@@ -430,6 +494,7 @@ var Highflame = class {
     const effectiveTimeout = overrideTimeout ?? this.#timeout;
     this.#log.debug("POST %s (stream)", path);
     const authHeaders = await this.getAuthHeaders();
+    injectTraceContext(authHeaders);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), effectiveTimeout);
     let response;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highflame/sdk",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "JavaScript/TypeScript SDK for Highflame AI guardrails",
   "type": "module",
   "sideEffects": false,
@@ -30,6 +30,7 @@
     "coverage": "vitest run --coverage"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "@types/node": "^20",
     "@vitest/coverage-v8": "^2",
     "eslint": "^9",
@@ -40,6 +41,14 @@
     "typescript-eslint": "^8",
     "vitest": "^2"
   },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=18"
   }