@neuraltrust/trustguard-sdk 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# TrustGuard Node.js SDK
+
+Official Node.js / TypeScript client for the TrustGuard runtime guard API (`POST /v1/guard`). Configure a base URL and an API key, send the payload you want evaluated, and act on the verdict: TrustGuard detects, you enforce.
+
+## Install
+
+```bash
+npm install @neuraltrust/trustguard-sdk
+```
+
+Requires Node.js 18+ (uses the built-in `fetch`). Zero runtime dependencies; ships ESM and CJS with full type definitions.
+
+## Usage
+
+```typescript
+import { TrustGuard } from "@neuraltrust/trustguard-sdk";
+
+const client = new TrustGuard({
+  baseUrl: "https://guard.neuraltrust.ai",
+  apiKey: process.env.TRUSTGUARD_API_KEY!,
+});
+
+const response = await client.guard({ input: { prompt: "user text to evaluate" } });
+if (response.isFlagged) {
+  // block the request
+}
+```
+
+### Options
+
+```typescript
+const response = await client.guard({
+  input: { prompt: "user text" },
+  direction: "output",                // "input" (default) or "output"
+  sessionId: "conversation-42",       // groups multi-turn traffic
+  consumerId: "user-7",               // the end user behind the request
+});
+```
+
+### Attachments
+
+Documents are base64-encoded into `metadata.attachments` for file-aware plugins:
+
+```typescript
+const response = await client.guard({
+  input: { prompt: "summarize this file" },
+  attachments: [{ filename: "doc.pdf", contentType: "application/pdf", data: pdfBytes }],
+});
+```
+
+### Response
+
+| Field | Meaning |
+|---|---|
+| `isFlagged` | The enforcement signal: block when `true` |
+| `findings` | What every plugin in the policy chain reported (`detectionType`, `confidence`, `ruleName`, `details`) |
+| `transformedPayload` | The payload as rewritten by in-flight masking, `null` when untouched |
+| `traceId` / `requestId` | Correlation ids for TrustGuard telemetry |
+
+### Errors
+
+Non-2xx responses throw `TrustGuardAPIError` with `status`, `traceId` and `requestId`. Transport failures (timeouts, connection errors) throw the underlying `fetch` errors. The default timeout is 10 seconds (`timeoutMs` to change it); pass `fetch` to supply a custom implementation.
+
+```typescript
+import { TrustGuardAPIError } from "@neuraltrust/trustguard-sdk";
+
+try {
+  await client.guard({ input: { prompt: "..." } });
+} catch (err) {
+  if (err instanceof TrustGuardAPIError && err.status === 401) {
+    // bad API key
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run lint   # tsc --noEmit
+npm test       # vitest
+npm run build  # tsup (ESM + CJS + d.ts)
+```

package/dist/index.cjs

@@ -0,0 +1,140 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TrustGuard: () => TrustGuard,
+  TrustGuardAPIError: () => TrustGuardAPIError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var TrustGuardAPIError = class extends Error {
+  status;
+  traceId;
+  requestId;
+  constructor(status, message, traceId, requestId) {
+    super(`TrustGuard API error ${status}: ${message} (trace_id=${traceId}, request_id=${requestId})`);
+    this.name = "TrustGuardAPIError";
+    this.status = status;
+    this.traceId = traceId;
+    this.requestId = requestId;
+  }
+};
+
+// src/client.ts
+var GUARD_PATH = "/v1/guard";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var TrustGuard = class {
+  #baseUrl;
+  #apiKey;
+  #timeoutMs;
+  #fetch;
+  constructor(options) {
+    const baseUrl = options.baseUrl?.trim().replace(/\/+$/, "");
+    if (!baseUrl) {
+      throw new Error("TrustGuard: baseUrl is required");
+    }
+    if (!options.apiKey?.trim()) {
+      throw new Error("TrustGuard: apiKey is required");
+    }
+    this.#baseUrl = baseUrl;
+    this.#apiKey = options.apiKey;
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+  }
+  /**
+   * Evaluates the request against the policy attached to the API key and
+   * returns the verdict. Throws TrustGuardAPIError on non-2xx responses.
+   */
+  async guard(request) {
+    if (!request.input) {
+      throw new Error("TrustGuard: request input is required");
+    }
+    const response = await this.#fetch(this.#baseUrl + GUARD_PATH, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.#apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(serializeRequest(request)),
+      signal: AbortSignal.timeout(this.#timeoutMs)
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw apiError(response.status, text);
+    }
+    return deserializeResponse(parseJson(text) ?? {});
+  }
+};
+function serializeRequest(request) {
+  const body = { input: request.input };
+  if (request.direction) body.direction = request.direction;
+  if (request.sessionId) body.session_id = request.sessionId;
+  if (request.consumerId) body.consumer_id = request.consumerId;
+  let metadata = request.metadata;
+  if (request.attachments?.length) {
+    metadata = { ...metadata, attachments: request.attachments.map(serializeAttachment) };
+  }
+  if (metadata && Object.keys(metadata).length > 0) body.metadata = metadata;
+  return body;
+}
+function serializeAttachment(attachment) {
+  const bytes = typeof attachment.data === "string" ? Buffer.from(attachment.data, "utf-8") : Buffer.from(attachment.data);
+  return {
+    filename: attachment.filename,
+    content_type: attachment.contentType,
+    data: bytes.toString("base64")
+  };
+}
+function deserializeResponse(wire) {
+  return {
+    isFlagged: wire.is_flagged ?? false,
+    transformedPayload: wire.transformed_payload ?? null,
+    findings: (wire.findings ?? []).map(
+      (f) => ({
+        detectionType: f.detection_type,
+        confidence: f.confidence,
+        ruleName: f.rule_name,
+        details: f.details
+      })
+    ),
+    traceId: wire.trace_id ?? "",
+    requestId: wire.request_id ?? ""
+  };
+}
+function apiError(status, text) {
+  const payload = parseJson(text);
+  const message = payload?.error || text.trim() || `HTTP ${status}`;
+  return new TrustGuardAPIError(status, message, payload?.trace_id ?? "", payload?.request_id ?? "");
+}
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TrustGuard,
+  TrustGuardAPIError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/client.ts"],"sourcesContent":["export { TrustGuard } from \"./client.js\";\nexport { TrustGuardAPIError } from \"./errors.js\";\nexport type {\n  Attachment,\n  Direction,\n  Finding,\n  GuardRequest,\n  GuardResponse,\n  TrustGuardOptions,\n} from \"./types.js\";\n","/**\n * A non-2xx response from the TrustGuard API, carrying the status code and the\n * correlation ids needed to chase the request in telemetry. Transport-level\n * failures (network errors, timeouts) are thrown as-is instead.\n */\nexport class TrustGuardAPIError extends Error {\n  readonly status: number;\n  readonly traceId: string;\n  readonly requestId: string;\n\n  constructor(status: number, message: string, traceId: string, requestId: string) {\n    super(`TrustGuard API error ${status}: ${message} (trace_id=${traceId}, request_id=${requestId})`);\n    this.name = \"TrustGuardAPIError\";\n    this.status = status;\n    this.traceId = traceId;\n    this.requestId = requestId;\n  }\n}\n","import { TrustGuardAPIError } from \"./errors.js\";\nimport type { Attachment, Finding, GuardRequest, GuardResponse, TrustGuardOptions } from \"./types.js\";\n\nconst GUARD_PATH = \"/v1/guard\";\nconst DEFAULT_TIMEOUT_MS = 10_000;\n\ninterface WireFinding {\n  detection_type?: string;\n  confidence?: number;\n  rule_name?: string;\n  details?: unknown;\n}\n\ninterface WireResponse {\n  is_flagged?: boolean;\n  transformed_payload?: Record<string, unknown> | null;\n  findings?: WireFinding[];\n  trace_id?: string;\n  request_id?: string;\n}\n\n/** Client for the TrustGuard runtime guard API. */\nexport class TrustGuard {\n  readonly #baseUrl: string;\n  readonly #apiKey: string;\n  readonly #timeoutMs: number;\n  readonly #fetch: typeof fetch;\n\n  constructor(options: TrustGuardOptions) {\n    const baseUrl = options.baseUrl?.trim().replace(/\\/+$/, \"\");\n    if (!baseUrl) {\n      throw new Error(\"TrustGuard: baseUrl is required\");\n    }\n    if (!options.apiKey?.trim()) {\n      throw new Error(\"TrustGuard: apiKey is required\");\n    }\n    this.#baseUrl = baseUrl;\n    this.#apiKey = options.apiKey;\n    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    this.#fetch = options.fetch ?? globalThis.fetch;\n  }\n\n  /**\n   * Evaluates the request against the policy attached to the API key and\n   * returns the verdict. Throws TrustGuardAPIError on non-2xx responses.\n   */\n  async guard(request: GuardRequest): Promise<GuardResponse> {\n    if (!request.input) {\n      throw new Error(\"TrustGuard: request input is required\");\n    }\n\n    const response = await this.#fetch(this.#baseUrl + GUARD_PATH, {\n      method: \"POST\",\n      headers: {\n        Authorization: `Bearer ${this.#apiKey}`,\n        \"Content-Type\": \"application/json\",\n      },\n      body: JSON.stringify(serializeRequest(request)),\n      signal: AbortSignal.timeout(this.#timeoutMs),\n    });\n\n    const text = await response.text();\n    if (!response.ok) {\n      throw apiError(response.status, text);\n    }\n\n    return deserializeResponse(parseJson(text) ?? {});\n  }\n}\n\n/** Maps the camelCase request onto the snake_case wire format, omitting empty optionals (the server rejects unknown top-level fields). */\nfunction serializeRequest(request: GuardRequest): Record<string, unknown> {\n  const body: Record<string, unknown> = { input: request.input };\n  if (request.direction) body.direction = request.direction;\n  if (request.sessionId) body.session_id = request.sessionId;\n  if (request.consumerId) body.consumer_id = request.consumerId;\n\n  let metadata = request.metadata;\n  if (request.attachments?.length) {\n    metadata = { ...metadata, attachments: request.attachments.map(serializeAttachment) };\n  }\n  if (metadata && Object.keys(metadata).length > 0) body.metadata = metadata;\n  return body;\n}\n\nfunction serializeAttachment(attachment: Attachment): Record<string, string> {\n  const bytes =\n    typeof attachment.data === \"string\" ? Buffer.from(attachment.data, \"utf-8\") : Buffer.from(attachment.data);\n  return {\n    filename: attachment.filename,\n    content_type: attachment.contentType,\n    data: bytes.toString(\"base64\"),\n  };\n}\n\nfunction deserializeResponse(wire: WireResponse): GuardResponse {\n  return {\n    isFlagged: wire.is_flagged ?? false,\n    transformedPayload: wire.transformed_payload ?? null,\n    findings: (wire.findings ?? []).map(\n      (f): Finding => ({\n        detectionType: f.detection_type,\n        confidence: f.confidence,\n        ruleName: f.rule_name,\n        details: f.details,\n      }),\n    ),\n    traceId: wire.trace_id ?? \"\",\n    requestId: wire.request_id ?? \"\",\n  };\n}\n\nfunction apiError(status: number, text: string): TrustGuardAPIError {\n  const payload = parseJson(text) as { error?: string; trace_id?: string; request_id?: string } | undefined;\n  const message = payload?.error || text.trim() || `HTTP ${status}`;\n  return new TrustGuardAPIError(status, message, payload?.trace_id ?? \"\", payload?.request_id ?? \"\");\n}\n\nfunction parseJson(text: string): WireResponse | undefined {\n  try {\n    return JSON.parse(text) as WireResponse;\n  } catch {\n    return undefined;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,85 @@
+/** Traffic side being evaluated; rules are scoped per side. Defaults to "input" server-side. */
+type Direction = "input" | "output";
+/** A document evaluated alongside the payload by file-aware plugins. */
+interface Attachment {
+    filename: string;
+    contentType: string;
+    /** Raw file content; strings are encoded as UTF-8. Base64 encoding happens on the wire. */
+    data: Uint8Array | string;
+}
+/** Payload for a guard evaluation. */
+interface GuardRequest {
+    /** The payload to evaluate. Required. */
+    input: Record<string, unknown>;
+    /** Traffic side; the server defaults to "input" when omitted. */
+    direction?: Direction;
+    /** Groups multi-turn traffic; the server synthesises one when omitted. */
+    sessionId?: string;
+    /** Identifies the end user on whose behalf the request runs. */
+    consumerId?: string;
+    /**
+     * Optional routing hints. Server-side key: `content_type` (overrides the
+     * payload content type, default application/json).
+     */
+    metadata?: Record<string, unknown>;
+    /** Documents to evaluate; folded into `metadata.attachments` on the wire. */
+    attachments?: Attachment[];
+}
+/** A single plugin's contribution to the guard response. */
+interface Finding {
+    detectionType?: string;
+    confidence?: number;
+    ruleName?: string;
+    details?: unknown;
+}
+/**
+ * Verdict returned by POST /v1/guard. TrustGuard detects; the caller enforces:
+ * block when `isFlagged` is true.
+ */
+interface GuardResponse {
+    /** The enforcement signal: true when the policy flagged the payload. */
+    isFlagged: boolean;
+    /** The payload as rewritten by in-flight masking, null when untouched. */
+    transformedPayload: Record<string, unknown> | null;
+    /** What every plugin in the policy chain reported. */
+    findings: Finding[];
+    /** Correlation ids for TrustGuard telemetry. */
+    traceId: string;
+    requestId: string;
+}
+/** Configuration for the TrustGuard client. */
+interface TrustGuardOptions {
+    /** Base URL of the TrustGuard deployment, e.g. https://guard.neuraltrust.ai */
+    baseUrl: string;
+    /** Collector API key, sent as a Bearer token. */
+    apiKey: string;
+    /** Per-request timeout in milliseconds. Default 10000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (proxies, test doubles). Default globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+
+/** Client for the TrustGuard runtime guard API. */
+declare class TrustGuard {
+    #private;
+    constructor(options: TrustGuardOptions);
+    /**
+     * Evaluates the request against the policy attached to the API key and
+     * returns the verdict. Throws TrustGuardAPIError on non-2xx responses.
+     */
+    guard(request: GuardRequest): Promise<GuardResponse>;
+}
+
+/**
+ * A non-2xx response from the TrustGuard API, carrying the status code and the
+ * correlation ids needed to chase the request in telemetry. Transport-level
+ * failures (network errors, timeouts) are thrown as-is instead.
+ */
+declare class TrustGuardAPIError extends Error {
+    readonly status: number;
+    readonly traceId: string;
+    readonly requestId: string;
+    constructor(status: number, message: string, traceId: string, requestId: string);
+}
+
+export { type Attachment, type Direction, type Finding, type GuardRequest, type GuardResponse, TrustGuard, TrustGuardAPIError, type TrustGuardOptions };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+/** Traffic side being evaluated; rules are scoped per side. Defaults to "input" server-side. */
+type Direction = "input" | "output";
+/** A document evaluated alongside the payload by file-aware plugins. */
+interface Attachment {
+    filename: string;
+    contentType: string;
+    /** Raw file content; strings are encoded as UTF-8. Base64 encoding happens on the wire. */
+    data: Uint8Array | string;
+}
+/** Payload for a guard evaluation. */
+interface GuardRequest {
+    /** The payload to evaluate. Required. */
+    input: Record<string, unknown>;
+    /** Traffic side; the server defaults to "input" when omitted. */
+    direction?: Direction;
+    /** Groups multi-turn traffic; the server synthesises one when omitted. */
+    sessionId?: string;
+    /** Identifies the end user on whose behalf the request runs. */
+    consumerId?: string;
+    /**
+     * Optional routing hints. Server-side key: `content_type` (overrides the
+     * payload content type, default application/json).
+     */
+    metadata?: Record<string, unknown>;
+    /** Documents to evaluate; folded into `metadata.attachments` on the wire. */
+    attachments?: Attachment[];
+}
+/** A single plugin's contribution to the guard response. */
+interface Finding {
+    detectionType?: string;
+    confidence?: number;
+    ruleName?: string;
+    details?: unknown;
+}
+/**
+ * Verdict returned by POST /v1/guard. TrustGuard detects; the caller enforces:
+ * block when `isFlagged` is true.
+ */
+interface GuardResponse {
+    /** The enforcement signal: true when the policy flagged the payload. */
+    isFlagged: boolean;
+    /** The payload as rewritten by in-flight masking, null when untouched. */
+    transformedPayload: Record<string, unknown> | null;
+    /** What every plugin in the policy chain reported. */
+    findings: Finding[];
+    /** Correlation ids for TrustGuard telemetry. */
+    traceId: string;
+    requestId: string;
+}
+/** Configuration for the TrustGuard client. */
+interface TrustGuardOptions {
+    /** Base URL of the TrustGuard deployment, e.g. https://guard.neuraltrust.ai */
+    baseUrl: string;
+    /** Collector API key, sent as a Bearer token. */
+    apiKey: string;
+    /** Per-request timeout in milliseconds. Default 10000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (proxies, test doubles). Default globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+
+/** Client for the TrustGuard runtime guard API. */
+declare class TrustGuard {
+    #private;
+    constructor(options: TrustGuardOptions);
+    /**
+     * Evaluates the request against the policy attached to the API key and
+     * returns the verdict. Throws TrustGuardAPIError on non-2xx responses.
+     */
+    guard(request: GuardRequest): Promise<GuardResponse>;
+}
+
+/**
+ * A non-2xx response from the TrustGuard API, carrying the status code and the
+ * correlation ids needed to chase the request in telemetry. Transport-level
+ * failures (network errors, timeouts) are thrown as-is instead.
+ */
+declare class TrustGuardAPIError extends Error {
+    readonly status: number;
+    readonly traceId: string;
+    readonly requestId: string;
+    constructor(status: number, message: string, traceId: string, requestId: string);
+}
+
+export { type Attachment, type Direction, type Finding, type GuardRequest, type GuardResponse, TrustGuard, TrustGuardAPIError, type TrustGuardOptions };

package/dist/index.js

@@ -0,0 +1,112 @@
+// src/errors.ts
+var TrustGuardAPIError = class extends Error {
+  status;
+  traceId;
+  requestId;
+  constructor(status, message, traceId, requestId) {
+    super(`TrustGuard API error ${status}: ${message} (trace_id=${traceId}, request_id=${requestId})`);
+    this.name = "TrustGuardAPIError";
+    this.status = status;
+    this.traceId = traceId;
+    this.requestId = requestId;
+  }
+};
+
+// src/client.ts
+var GUARD_PATH = "/v1/guard";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var TrustGuard = class {
+  #baseUrl;
+  #apiKey;
+  #timeoutMs;
+  #fetch;
+  constructor(options) {
+    const baseUrl = options.baseUrl?.trim().replace(/\/+$/, "");
+    if (!baseUrl) {
+      throw new Error("TrustGuard: baseUrl is required");
+    }
+    if (!options.apiKey?.trim()) {
+      throw new Error("TrustGuard: apiKey is required");
+    }
+    this.#baseUrl = baseUrl;
+    this.#apiKey = options.apiKey;
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+  }
+  /**
+   * Evaluates the request against the policy attached to the API key and
+   * returns the verdict. Throws TrustGuardAPIError on non-2xx responses.
+   */
+  async guard(request) {
+    if (!request.input) {
+      throw new Error("TrustGuard: request input is required");
+    }
+    const response = await this.#fetch(this.#baseUrl + GUARD_PATH, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.#apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(serializeRequest(request)),
+      signal: AbortSignal.timeout(this.#timeoutMs)
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw apiError(response.status, text);
+    }
+    return deserializeResponse(parseJson(text) ?? {});
+  }
+};
+function serializeRequest(request) {
+  const body = { input: request.input };
+  if (request.direction) body.direction = request.direction;
+  if (request.sessionId) body.session_id = request.sessionId;
+  if (request.consumerId) body.consumer_id = request.consumerId;
+  let metadata = request.metadata;
+  if (request.attachments?.length) {
+    metadata = { ...metadata, attachments: request.attachments.map(serializeAttachment) };
+  }
+  if (metadata && Object.keys(metadata).length > 0) body.metadata = metadata;
+  return body;
+}
+function serializeAttachment(attachment) {
+  const bytes = typeof attachment.data === "string" ? Buffer.from(attachment.data, "utf-8") : Buffer.from(attachment.data);
+  return {
+    filename: attachment.filename,
+    content_type: attachment.contentType,
+    data: bytes.toString("base64")
+  };
+}
+function deserializeResponse(wire) {
+  return {
+    isFlagged: wire.is_flagged ?? false,
+    transformedPayload: wire.transformed_payload ?? null,
+    findings: (wire.findings ?? []).map(
+      (f) => ({
+        detectionType: f.detection_type,
+        confidence: f.confidence,
+        ruleName: f.rule_name,
+        details: f.details
+      })
+    ),
+    traceId: wire.trace_id ?? "",
+    requestId: wire.request_id ?? ""
+  };
+}
+function apiError(status, text) {
+  const payload = parseJson(text);
+  const message = payload?.error || text.trim() || `HTTP ${status}`;
+  return new TrustGuardAPIError(status, message, payload?.trace_id ?? "", payload?.request_id ?? "");
+}
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+export {
+  TrustGuard,
+  TrustGuardAPIError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/client.ts"],"sourcesContent":["/**\n * A non-2xx response from the TrustGuard API, carrying the status code and the\n * correlation ids needed to chase the request in telemetry. Transport-level\n * failures (network errors, timeouts) are thrown as-is instead.\n */\nexport class TrustGuardAPIError extends Error {\n  readonly status: number;\n  readonly traceId: string;\n  readonly requestId: string;\n\n  constructor(status: number, message: string, traceId: string, requestId: string) {\n    super(`TrustGuard API error ${status}: ${message} (trace_id=${traceId}, request_id=${requestId})`);\n    this.name = \"TrustGuardAPIError\";\n    this.status = status;\n    this.traceId = traceId;\n    this.requestId = requestId;\n  }\n}\n","import { TrustGuardAPIError } from \"./errors.js\";\nimport type { Attachment, Finding, GuardRequest, GuardResponse, TrustGuardOptions } from \"./types.js\";\n\nconst GUARD_PATH = \"/v1/guard\";\nconst DEFAULT_TIMEOUT_MS = 10_000;\n\ninterface WireFinding {\n  detection_type?: string;\n  confidence?: number;\n  rule_name?: string;\n  details?: unknown;\n}\n\ninterface WireResponse {\n  is_flagged?: boolean;\n  transformed_payload?: Record<string, unknown> | null;\n  findings?: WireFinding[];\n  trace_id?: string;\n  request_id?: string;\n}\n\n/** Client for the TrustGuard runtime guard API. */\nexport class TrustGuard {\n  readonly #baseUrl: string;\n  readonly #apiKey: string;\n  readonly #timeoutMs: number;\n  readonly #fetch: typeof fetch;\n\n  constructor(options: TrustGuardOptions) {\n    const baseUrl = options.baseUrl?.trim().replace(/\\/+$/, \"\");\n    if (!baseUrl) {\n      throw new Error(\"TrustGuard: baseUrl is required\");\n    }\n    if (!options.apiKey?.trim()) {\n      throw new Error(\"TrustGuard: apiKey is required\");\n    }\n    this.#baseUrl = baseUrl;\n    this.#apiKey = options.apiKey;\n    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    this.#fetch = options.fetch ?? globalThis.fetch;\n  }\n\n  /**\n   * Evaluates the request against the policy attached to the API key and\n   * returns the verdict. Throws TrustGuardAPIError on non-2xx responses.\n   */\n  async guard(request: GuardRequest): Promise<GuardResponse> {\n    if (!request.input) {\n      throw new Error(\"TrustGuard: request input is required\");\n    }\n\n    const response = await this.#fetch(this.#baseUrl + GUARD_PATH, {\n      method: \"POST\",\n      headers: {\n        Authorization: `Bearer ${this.#apiKey}`,\n        \"Content-Type\": \"application/json\",\n      },\n      body: JSON.stringify(serializeRequest(request)),\n      signal: AbortSignal.timeout(this.#timeoutMs),\n    });\n\n    const text = await response.text();\n    if (!response.ok) {\n      throw apiError(response.status, text);\n    }\n\n    return deserializeResponse(parseJson(text) ?? {});\n  }\n}\n\n/** Maps the camelCase request onto the snake_case wire format, omitting empty optionals (the server rejects unknown top-level fields). */\nfunction serializeRequest(request: GuardRequest): Record<string, unknown> {\n  const body: Record<string, unknown> = { input: request.input };\n  if (request.direction) body.direction = request.direction;\n  if (request.sessionId) body.session_id = request.sessionId;\n  if (request.consumerId) body.consumer_id = request.consumerId;\n\n  let metadata = request.metadata;\n  if (request.attachments?.length) {\n    metadata = { ...metadata, attachments: request.attachments.map(serializeAttachment) };\n  }\n  if (metadata && Object.keys(metadata).length > 0) body.metadata = metadata;\n  return body;\n}\n\nfunction serializeAttachment(attachment: Attachment): Record<string, string> {\n  const bytes =\n    typeof attachment.data === \"string\" ? Buffer.from(attachment.data, \"utf-8\") : Buffer.from(attachment.data);\n  return {\n    filename: attachment.filename,\n    content_type: attachment.contentType,\n    data: bytes.toString(\"base64\"),\n  };\n}\n\nfunction deserializeResponse(wire: WireResponse): GuardResponse {\n  return {\n    isFlagged: wire.is_flagged ?? false,\n    transformedPayload: wire.transformed_payload ?? null,\n    findings: (wire.findings ?? []).map(\n      (f): Finding => ({\n        detectionType: f.detection_type,\n        confidence: f.confidence,\n        ruleName: f.rule_name,\n        details: f.details,\n      }),\n    ),\n    traceId: wire.trace_id ?? \"\",\n    requestId: wire.request_id ?? \"\",\n  };\n}\n\nfunction apiError(status: number, text: string): TrustGuardAPIError {\n  const payload = parseJson(text) as { error?: string; trace_id?: string; request_id?: string } | undefined;\n  const message = payload?.error || text.trim() || `HTTP ${status}`;\n  return new TrustGuardAPIError(status, message, payload?.trace_id ?? \"\", payload?.request_id ?? \"\");\n}\n\nfunction parseJson(text: string): WireResponse | undefined {\n  try {\n    return JSON.parse(text) as WireResponse;\n  } catch {\n    return undefined;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@neuraltrust/trustguard-sdk",
+  "version": "0.1.0",
+  "description": "Official Node.js SDK for the TrustGuard runtime guard API (POST /v1/guard)",
+  "license": "MIT",
+  "author": "NeuralTrust",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NeuralTrust/trustguard-sdk.git",
+    "directory": "node"
+  },
+  "keywords": [
+    "neuraltrust",
+    "trustguard",
+    "guardrails",
+    "llm-security",
+    "ai-firewall"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run lint && npm run test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}