highflame 0.2.0

package/dist/index.js

@@ -0,0 +1,666 @@
+// src/errors.ts
+var HighflameError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HighflameError";
+  }
+};
+var APIError = class extends HighflameError {
+  constructor(status, title, detail) {
+    super(`[${status}] ${title}: ${detail}`);
+    this.status = status;
+    this.title = title;
+    this.detail = detail;
+    this.name = "APIError";
+  }
+};
+var AuthenticationError = class extends APIError {
+  constructor(detail = "Invalid or expired credentials") {
+    super(401, "Unauthorized", detail);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends APIError {
+  constructor(detail = "Rate limit exceeded") {
+    super(429, "Too Many Requests", detail);
+    this.name = "RateLimitError";
+  }
+};
+var APIConnectionError = class extends HighflameError {
+  constructor(message) {
+    super(message);
+    this.name = "APIConnectionError";
+  }
+};
+var BlockedError = class extends HighflameError {
+  constructor(response) {
+    super(`Blocked by guard: ${response.policy_reason || response.decision}`);
+    this.response = response;
+    this.name = "BlockedError";
+  }
+};
+
+// src/stream.ts
+function* parseSseLines(lines) {
+  let event = "detector_result";
+  let data = "";
+  for (const line of lines) {
+    if (line === "") {
+      if (data) {
+        yield { event, data };
+      }
+      event = "detector_result";
+      data = "";
+    } else if (line.startsWith("event:")) {
+      event = line.slice(6).trim();
+    } else if (line.startsWith("data:")) {
+      data = line.slice(5).trim();
+    }
+  }
+  if (data) {
+    yield { event, data };
+  }
+}
+async function* streamSseResponse(response) {
+  if (!response.body) {
+    throw new APIConnectionError("Response body is null");
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const { event, data } of parseSseLines(lines)) {
+        if (!data) continue;
+        let parsed;
+        try {
+          parsed = JSON.parse(data);
+        } catch {
+          continue;
+        }
+        yield {
+          type: event,
+          data: parsed
+        };
+      }
+    }
+    if (buffer) {
+      const lines = buffer.split("\n");
+      for (const { event, data } of parseSseLines([...lines, ""])) {
+        if (!data) continue;
+        let parsed;
+        try {
+          parsed = JSON.parse(data);
+        } catch {
+          continue;
+        }
+        yield {
+          type: event,
+          data: parsed
+        };
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/client.ts
+var VERSION = "0.2.0";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
+var RETRY_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var TOKEN_REFRESH_BUFFER_MS = 6e4;
+var USER_AGENT = `highflame-js/${VERSION}`;
+var SAAS_BASE_URL = "https://shield.api.highflame.ai";
+var SAAS_TOKEN_URL = "https://studio.api.highflame.ai/api/cli-auth/token";
+var LOG_BODY_MAX = 1024;
+var NOOP_LOGGER = {
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  }
+};
+function truncate(text, max = LOG_BODY_MAX) {
+  if (text.length <= max) return text;
+  return text.slice(0, max) + `... (${text.length} chars)`;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function retryDelay(attempt) {
+  const base = 1e3 * Math.pow(2, attempt);
+  const jitter = base * 0.25 * (2 * Math.random() - 1);
+  return Math.max(0, base + jitter);
+}
+async function parseError(response) {
+  let title = response.statusText || "Error";
+  let detail = "";
+  try {
+    const body = await response.json();
+    if (typeof body["title"] === "string") title = body["title"];
+    if (typeof body["detail"] === "string") detail = body["detail"];
+  } catch {
+    try {
+      detail = await response.text();
+    } catch {
+    }
+  }
+  if (response.status === 401) return new AuthenticationError(detail);
+  if (response.status === 429) return new RateLimitError(detail);
+  return new APIError(response.status, title, detail);
+}
+var GuardResource = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  /** Evaluate content against guard policies (POST /v1/guard). */
+  async evaluate(request, options) {
+    return this._client._postJSON("/v1/guard", request, options?.timeout);
+  }
+  /** Shorthand: evaluate a user prompt. */
+  async evaluatePrompt(content, options) {
+    const { timeout, ...rest } = options ?? {};
+    return this.evaluate(
+      { content, content_type: "prompt", action: "process_prompt", ...rest },
+      { timeout }
+    );
+  }
+  /** Shorthand: evaluate a tool call. */
+  async evaluateToolCall(toolName, args, options) {
+    const { timeout, ...rest } = options ?? {};
+    return this.evaluate(
+      {
+        content: `Tool call: ${toolName}`,
+        content_type: "tool_call",
+        action: "call_tool",
+        tool: { name: toolName, is_builtin: false, arguments: args },
+        ...rest
+      },
+      { timeout }
+    );
+  }
+  /** Stream guard evaluation results (POST /v1/guard/stream). */
+  async *stream(request, options) {
+    yield* this._client._stream("/v1/guard/stream", request, options?.timeout);
+  }
+};
+var DetectResource = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  /** Run detectors without policy evaluation (POST /v1/detect). */
+  async run(request, options) {
+    return this._client._postJSON("/v1/detect", request, options?.timeout);
+  }
+};
+var DetectorsResource = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  /** List available detectors (GET /v1/detectors). */
+  async list(options) {
+    return this._client._getJSON("/v1/detectors", options?.timeout);
+  }
+};
+var DebugResource = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  /** Inspect loaded policies (GET /v1/debug/policies). */
+  async policies(product = "guardrails", options) {
+    return this._client._getJSON(
+      `/v1/debug/policies?product=${product}`,
+      options?.timeout
+    );
+  }
+};
+var Highflame = class {
+  #baseUrl;
+  #tokenUrl;
+  #apiKey;
+  #timeout;
+  #maxRetries;
+  #overrideAccountId;
+  #overrideProjectId;
+  #defaultHeaders;
+  #staticHeaders;
+  #log;
+  #cachedToken = null;
+  #tokenPromise = null;
+  guard;
+  detect;
+  detectors;
+  debug;
+  constructor(options) {
+    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.#apiKey = options.apiKey;
+    this.#timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.#maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.#overrideAccountId = options.accountId;
+    this.#overrideProjectId = options.projectId;
+    this.#defaultHeaders = options.defaultHeaders ?? {};
+    this.#staticHeaders = {
+      Authorization: `Bearer ${options.apiKey}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+      ...this.#defaultHeaders
+    };
+    if (options.accountId) this.#staticHeaders["X-Account-ID"] = options.accountId;
+    if (options.projectId) this.#staticHeaders["X-Project-ID"] = options.projectId;
+    this.#log = options.logger ?? NOOP_LOGGER;
+    this.guard = new GuardResource(this);
+    this.detect = new DetectResource(this);
+    this.detectors = new DetectorsResource(this);
+    this.debug = new DebugResource(this);
+  }
+  get accountId() {
+    return this.#overrideAccountId ?? this.#cachedToken?.accountId ?? "";
+  }
+  get projectId() {
+    return this.#overrideProjectId ?? this.#cachedToken?.projectId ?? "";
+  }
+  /** Get auth headers (exposed for external use with custom HTTP clients). */
+  async getAuthHeaders() {
+    if (!this.#tokenUrl) {
+      return this.#staticHeaders;
+    }
+    if (this.#cachedToken && Date.now() < this.#cachedToken.expiresAt) {
+      return this.#buildTokenHeaders(this.#cachedToken);
+    }
+    if (!this.#tokenPromise) {
+      this.#tokenPromise = this.#exchangeToken().finally(() => {
+        this.#tokenPromise = null;
+      });
+    }
+    this.#cachedToken = await this.#tokenPromise;
+    return this.#buildTokenHeaders(this.#cachedToken);
+  }
+  #buildTokenHeaders(token) {
+    const headers = {
+      Authorization: `Bearer ${token.accessToken}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+      ...this.#defaultHeaders
+    };
+    const accountId = this.#overrideAccountId ?? (token.accountId || void 0);
+    const projectId = this.#overrideProjectId ?? (token.projectId || void 0);
+    if (accountId) headers["X-Account-ID"] = accountId;
+    if (projectId) headers["X-Project-ID"] = projectId;
+    return headers;
+  }
+  async #exchangeToken() {
+    this.#log.debug("Token exchange: POST %s", this.#tokenUrl);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.#timeout);
+    let response;
+    try {
+      response = await fetch(this.#tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+        body: JSON.stringify({ grant_type: "api_key", api_key: this.#apiKey }),
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        this.#log.warn("Token exchange timed out after %dms", this.#timeout);
+        throw new APIConnectionError(`Token exchange timed out after ${this.#timeout}ms`);
+      }
+      this.#log.warn("Token exchange failed: %s", err instanceof Error ? err.message : String(err));
+      throw new APIConnectionError(
+        `Token exchange failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) {
+      this.#log.warn("Token exchange error: %d %s", response.status, response.statusText);
+      throw await parseError(response);
+    }
+    const tok = await response.json();
+    this.#log.debug("Token exchange: success (expires_in=%ds)", tok.expires_in);
+    return {
+      accessToken: tok.access_token,
+      expiresAt: Date.now() + tok.expires_in * 1e3 - TOKEN_REFRESH_BUFFER_MS,
+      accountId: tok.account_id ?? "",
+      projectId: tok.project_id ?? "",
+      gatewayId: tok.gateway_id ?? ""
+    };
+  }
+  // -----------------------------------------------------------------------
+  // Internal HTTP helpers (used by resource classes)
+  // -----------------------------------------------------------------------
+  /** @internal */
+  async _fetchWithRetry(path, init, overrideTimeout) {
+    const effectiveTimeout = overrideTimeout ?? this.#timeout;
+    let lastError;
+    let idempotencyKey;
+    const method = (init.method ?? "GET").toUpperCase();
+    for (let attempt = 0; attempt <= this.#maxRetries; attempt++) {
+      if (attempt > 0) {
+        const delay = retryDelay(attempt - 1);
+        this.#log.debug(
+          "Retrying %s %s (attempt %d/%d) after %.0fms",
+          method,
+          path,
+          attempt + 1,
+          this.#maxRetries + 1,
+          delay
+        );
+        await sleep(delay);
+        if (!idempotencyKey) {
+          idempotencyKey = crypto.randomUUID();
+        }
+      }
+      this.#log.debug("%s %s", method, path);
+      if (init.body && typeof init.body === "string") {
+        this.#log.debug("Request body: %s", truncate(init.body));
+      }
+      const authHeaders = await this.getAuthHeaders();
+      if (idempotencyKey) {
+        authHeaders["X-Idempotency-Key"] = idempotencyKey;
+      }
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), effectiveTimeout);
+      let response;
+      try {
+        response = await fetch(this.#baseUrl + path, {
+          ...init,
+          headers: authHeaders,
+          signal: controller.signal
+        });
+      } catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+          this.#log.debug("Request timed out: %s %s", method, path);
+          lastError = new APIConnectionError(`Request timed out after ${effectiveTimeout}ms`);
+          continue;
+        }
+        throw new APIConnectionError(
+          `Connection failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      } finally {
+        clearTimeout(timer);
+      }
+      this.#log.debug("%s %s \u2192 %d", method, path, response.status);
+      if (!RETRY_STATUS_CODES.has(response.status)) {
+        return response;
+      }
+      lastError = await parseError(response);
+    }
+    throw lastError;
+  }
+  /** @internal */
+  async _postJSON(path, body, overrideTimeout) {
+    const response = await this._fetchWithRetry(
+      path,
+      { method: "POST", body: JSON.stringify(body) },
+      overrideTimeout
+    );
+    if (!response.ok) {
+      throw await parseError(response);
+    }
+    return response.json();
+  }
+  /** @internal */
+  async _getJSON(path, overrideTimeout) {
+    const response = await this._fetchWithRetry(
+      path,
+      { method: "GET" },
+      overrideTimeout
+    );
+    if (!response.ok) {
+      throw await parseError(response);
+    }
+    return response.json();
+  }
+  /** @internal */
+  async *_stream(path, body, overrideTimeout) {
+    const effectiveTimeout = overrideTimeout ?? this.#timeout;
+    this.#log.debug("POST %s (stream)", path);
+    const authHeaders = await this.getAuthHeaders();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), effectiveTimeout);
+    let response;
+    try {
+      response = await fetch(this.#baseUrl + path, {
+        method: "POST",
+        headers: { ...authHeaders, Accept: "text/event-stream" },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err instanceof Error && err.name === "AbortError") {
+        this.#log.debug("Stream timed out: POST %s", path);
+        throw new APIConnectionError(`Stream timed out after ${effectiveTimeout}ms`);
+      }
+      throw new APIConnectionError(
+        `Connection failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    this.#log.debug("POST %s (stream) \u2192 %d", path, response.status);
+    if (!response.ok) {
+      clearTimeout(timer);
+      throw await parseError(response);
+    }
+    try {
+      yield* streamSseResponse(response);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  toString() {
+    return `Highflame(baseUrl=${JSON.stringify(this.#baseUrl)})`;
+  }
+};
+
+// src/shield.ts
+function splitOnTopLevelCommas(s) {
+  const parts = [];
+  let depth = 0;
+  let inString = null;
+  let cur = "";
+  let i = 0;
+  while (i < s.length) {
+    const ch = s[i];
+    if (inString !== null) {
+      cur += ch;
+      if (ch === "\\") {
+        i++;
+        if (i < s.length) cur += s[i];
+      } else if (ch === inString) {
+        inString = null;
+      }
+    } else if (ch === '"' || ch === "'" || ch === "`") {
+      inString = ch;
+      cur += ch;
+    } else if (ch === "(" || ch === "[" || ch === "{") {
+      depth++;
+      cur += ch;
+    } else if (ch === ")" || ch === "]" || ch === "}") {
+      depth--;
+      cur += ch;
+    } else if (ch === "," && depth === 0) {
+      parts.push(cur);
+      cur = "";
+    } else {
+      cur += ch;
+    }
+    i++;
+  }
+  if (cur) parts.push(cur);
+  return parts;
+}
+function getParamNames(fn) {
+  try {
+    const src = fn.toString().replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, "");
+    const headerMatch = src.match(/^(?:async\s+)?(?:function\s*\w*\s*|\w+\s*)?\(/);
+    if (!headerMatch) {
+      const singleParam = src.match(/^(?:async\s+)?(\w+)\s*=>/);
+      if (singleParam) return [singleParam[1] ?? "arg0"];
+      return [];
+    }
+    const openIdx = headerMatch[0].length - 1;
+    let depth = 0;
+    let closeIdx = -1;
+    for (let i = openIdx; i < src.length; i++) {
+      if (src[i] === "(") depth++;
+      else if (src[i] === ")") {
+        if (--depth === 0) {
+          closeIdx = i;
+          break;
+        }
+      }
+    }
+    if (closeIdx === -1) return [];
+    const inner = src.slice(openIdx + 1, closeIdx).trim();
+    if (!inner) return [];
+    return splitOnTopLevelCommas(inner).map(
+      (p) => p.trim().replace(/[=:].*/s, "").replace(/^\.\.\./, "").replace(/[{}[\]]/g, "").trim()
+    ).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+function buildArgsDict(fn, args) {
+  const names = getParamNames(fn);
+  const result = {};
+  for (let i = 0; i < args.length; i++) {
+    result[names[i] ?? `arg${i}`] = args[i];
+  }
+  return result;
+}
+function raiseIfBlocked(response) {
+  if (response.decision === "deny") {
+    throw new BlockedError(response);
+  }
+}
+var Shield = class {
+  constructor(client) {
+    this.client = client;
+  }
+  prompt(fn, options) {
+    const argIdx = options?.contentArg ?? 0;
+    const { mode, sessionId } = options ?? {};
+    const wrapper = async (...args) => {
+      const content = args[argIdx];
+      if (typeof content !== "string") {
+        throw new TypeError(
+          `shield.prompt: argument at index ${argIdx} must be string, got ${typeof content}`
+        );
+      }
+      raiseIfBlocked(
+        await this.client.guard.evaluatePrompt(content, { mode, session_id: sessionId })
+      );
+      return fn(...args);
+    };
+    Object.defineProperty(wrapper, "name", { value: fn.name, configurable: true });
+    return wrapper;
+  }
+  tool(fn, options) {
+    const toolName = options?.toolName ?? fn.name;
+    const { mode, sessionId } = options ?? {};
+    const wrapper = async (...args) => {
+      const argsDict = buildArgsDict(fn, args);
+      raiseIfBlocked(
+        await this.client.guard.evaluateToolCall(toolName, argsDict, {
+          mode,
+          session_id: sessionId
+        })
+      );
+      return fn(...args);
+    };
+    Object.defineProperty(wrapper, "name", { value: fn.name, configurable: true });
+    return wrapper;
+  }
+  toolResponse(fn, options) {
+    const toolName = options?.toolName ?? fn.name;
+    const { mode, sessionId } = options ?? {};
+    const wrapper = async (...args) => {
+      const result = await fn(...args);
+      raiseIfBlocked(
+        await this.client.guard.evaluate({
+          content: typeof result === "string" ? result : String(result),
+          content_type: "response",
+          action: "call_tool",
+          mode,
+          session_id: sessionId,
+          tool: { name: toolName, is_builtin: false }
+        })
+      );
+      return result;
+    };
+    Object.defineProperty(wrapper, "name", { value: fn.name, configurable: true });
+    return wrapper;
+  }
+  modelResponse(fn, options) {
+    const { mode, sessionId } = options ?? {};
+    const wrapper = async (...args) => {
+      const result = await fn(...args);
+      raiseIfBlocked(
+        await this.client.guard.evaluate({
+          content: typeof result === "string" ? result : String(result),
+          content_type: "response",
+          action: "process_prompt",
+          mode,
+          session_id: sessionId
+        })
+      );
+      return result;
+    };
+    Object.defineProperty(wrapper, "name", { value: fn.name, configurable: true });
+    return wrapper;
+  }
+  wrap(options) {
+    const { contentType, action, contentArg: argIdx = 0, mode, sessionId } = options;
+    return (fn) => {
+      const wrapper = async (...args) => {
+        const content = args[argIdx];
+        if (typeof content !== "string") {
+          throw new TypeError(
+            `shield.wrap: argument at index ${argIdx} must be string, got ${typeof content}`
+          );
+        }
+        raiseIfBlocked(
+          await this.client.guard.evaluate({
+            content,
+            content_type: contentType,
+            action,
+            mode,
+            session_id: sessionId
+          })
+        );
+        return fn(...args);
+      };
+      Object.defineProperty(wrapper, "name", { value: fn.name, configurable: true });
+      return wrapper;
+    };
+  }
+};
+export {
+  APIConnectionError,
+  APIError,
+  AuthenticationError,
+  BlockedError,
+  DebugResource,
+  DetectResource,
+  DetectorsResource,
+  GuardResource,
+  Highflame,
+  HighflameError,
+  RateLimitError,
+  Shield,
+  VERSION
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "highflame",
+  "version": "0.2.0",
+  "description": "JavaScript/TypeScript SDK for Highflame AI guardrails",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
+    "format": "prettier --write src tests smoke_test.mjs",
+    "format:check": "prettier --check src tests smoke_test.mjs",
+    "check": "tsc --noEmit && eslint src tests",
+    "coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@vitest/coverage-v8": "^2",
+    "eslint": "^9",
+    "msw": "^2",
+    "prettier": "^3",
+    "tsup": "^8",
+    "typescript": "^5.4",
+    "typescript-eslint": "^8",
+    "vitest": "^2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}