@trustgateai/sdk 1.0.0

package/README.md

@@ -0,0 +1,124 @@
+# trustgate-node
+
+TrustGate Node.js SDK with **Shadow AI** detection: workflow context, middleware for Vercel AI SDK and LangChain, n8n header helper, and SSE streaming.
+
+## Install
+
+```bash
+npm install trustgate-node
+```
+
+Optional peer dependencies for middleware:
+
+```bash
+npm install ai @ai-sdk/openai          # Vercel AI SDK
+npm install @langchain/openai         # LangChain
+```
+
+## Core client
+
+```ts
+import { TrustGate, getWorkflowContextFromEnv } from 'trustgate-node';
+
+const client = new TrustGate({
+  baseUrl: process.env.TRUSTGATE_BASE_URL!,
+  apiKey: process.env.TRUSTGATE_API_KEY,
+  // workflowContext optional; otherwise read from process.env (n8n, Vercel, GitHub)
+});
+
+// Non-streaming
+const res = await client.fetch('/v1/chat/completions', {
+  method: 'POST',
+  body: JSON.stringify({ model: 'gpt-4', messages: [...] }),
+});
+
+// SSE streaming (workflow_id sent in request for background attribution)
+const streamRes = await client.fetchStream('/v1/chat/completions', {
+  method: 'POST',
+  body: JSON.stringify({ model: 'gpt-4', messages: [...], stream: true }),
+});
+// Consume streamRes.body (ReadableStream) as usual for SSE
+```
+
+## Context provider
+
+Workflow metadata is read from `process.env` so TrustGate can attribute traffic (Shadow AI detection):
+
+| Source  | Example env vars |
+|---------|-------------------|
+| **n8n** | `N8N_WORKFLOW_ID`, `N8N_EXECUTION_ID`, `N8N_WORKFLOW_NAME` |
+| **Vercel** | `VERCEL`, `VERCEL_ENV`, `VERCEL_URL`, `VERCEL_GIT_*` |
+| **GitHub** | `GITHUB_ACTION`, `GITHUB_WORKFLOW`, `GITHUB_RUN_ID`, `GITHUB_REPOSITORY` |
+
+```ts
+import { getWorkflowContextFromEnv } from 'trustgate-node';
+
+const ctx = getWorkflowContextFromEnv();
+// { source: 'n8n', workflow_id: '...', execution_id: '...', metadata: {...} }
+```
+
+## Middleware: Vercel AI SDK
+
+Point the OpenAI provider at TrustGate so all calls go through the gateway with workflow context:
+
+```ts
+import { createOpenAI } from '@ai-sdk/openai';
+import { createTrustGateOpenAIOptions } from 'trustgate-node/middleware/vercel-ai';
+
+const openai = createOpenAI(
+  createTrustGateOpenAIOptions({
+    baseUrl: process.env.TRUSTGATE_BASE_URL!,
+    apiKey: process.env.TRUSTGATE_API_KEY,
+  })
+);
+
+// Use with streamText / generateText as usual
+import { streamText } from 'ai';
+const result = streamText({
+  model: openai('gpt-4'),
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+```
+
+## Middleware: LangChain
+
+Use TrustGate as the OpenAI endpoint for LangChain with one config object:
+
+```ts
+import { ChatOpenAI } from '@langchain/openai';
+import { createTrustGateLangChainConfig } from 'trustgate-node/middleware/langchain';
+
+const config = createTrustGateLangChainConfig({
+  baseUrl: process.env.TRUSTGATE_BASE_URL!,
+  apiKey: process.env.TRUSTGATE_API_KEY,
+});
+
+const llm = new ChatOpenAI({
+  ...config,
+  modelName: 'gpt-4',
+  temperature: 0,
+});
+```
+
+## n8n HTTP Request node: header snippet
+
+Get a pre-formatted JSON object of headers for n8n “HTTP Request” nodes so each request includes TrustGate auth and workflow context:
+
+```ts
+import { getN8nHeaderSnippet } from 'trustgate-node';
+
+const { headers, json } = getN8nHeaderSnippet();
+// headers: [ { name: 'X-Trustgate-Source', value: 'n8n' }, ... ]
+// json: '{"X-Trustgate-Source":"n8n","X-Trustgate-Workflow-Id":"...", ...}'
+```
+
+In n8n, set **Send Headers** (or equivalent) to the `headers` array or paste the `json` into your node config. You can pass `apiKey` and `baseUrl` explicitly or rely on `TRUSTGATE_API_KEY` and `TRUSTGATE_BASE_URL` in the environment.
+
+## Streaming (SSE)
+
+- Use `client.fetchStream(path, init, options)` for SSE endpoints. The client sets `Accept: text/event-stream` and sends workflow context (e.g. `workflow_id`) in the **initial request**, so the gateway can attribute the background stream.
+- The returned `Response` body is the raw stream; consume it with `response.body.getReader()` or pass through to your framework’s SSE handling.
+
+## License
+
+MIT

package/dist/chunk-R2YXTU4L.mjs

@@ -0,0 +1,30 @@
+import {
+  buildContextHeaders,
+  getWorkflowContextFromEnv
+} from "./chunk-SV5FTXAH.mjs";
+
+// src/middleware/langchain.ts
+function createTrustGateLangChainConfig(config) {
+  const baseUrl = config.baseUrl.replace(/\/$/, "");
+  const ctx = config.workflowContext ?? getWorkflowContextFromEnv();
+  const headers = {
+    ...config.headers,
+    ...buildContextHeaders(ctx)
+  };
+  if (config.apiKey) {
+    headers["authorization"] = `Bearer ${config.apiKey}`;
+    headers["x-api-key"] = config.apiKey;
+  }
+  return {
+    baseURL: baseUrl,
+    defaultHeaders: Object.keys(headers).length ? headers : void 0,
+    configuration: {
+      baseURL: baseUrl,
+      defaultHeaders: Object.keys(headers).length ? headers : void 0
+    }
+  };
+}
+
+export {
+  createTrustGateLangChainConfig
+};

package/dist/chunk-SV5FTXAH.mjs

@@ -0,0 +1,112 @@
+// src/version.ts
+var SDK_VERSION = "1.0.0";
+
+// src/context.ts
+var HEADER_PREFIX = "x-trustgate";
+var SOURCE_TOOL_HEADER = "x-trustgate-source-tool";
+var N8N_KEYS = [
+  "N8N_WORKFLOW_ID",
+  "N8N_EXECUTION_ID",
+  "N8N_WORKFLOW_NAME",
+  "N8N_EXECUTION_MODE"
+];
+var VERCEL_KEYS = [
+  "VERCEL",
+  "VERCEL_ENV",
+  "VERCEL_URL",
+  "VERCEL_GIT_COMMIT_REF",
+  "VERCEL_GIT_REPO_ID",
+  "VERCEL_GIT_COMMIT_SHA"
+];
+var GITHUB_KEYS = [
+  "GITHUB_ACTION",
+  "GITHUB_ACTIONS",
+  "GITHUB_WORKFLOW",
+  "GITHUB_RUN_ID",
+  "GITHUB_RUN_NUMBER",
+  "GITHUB_REPOSITORY",
+  "GITHUB_SHA"
+];
+function pickEnv(keys) {
+  const out = {};
+  for (const key of keys) {
+    const v = process.env[key];
+    if (v !== void 0 && v !== "") out[key] = v;
+  }
+  return out;
+}
+function getBaseMetadata() {
+  return {
+    sdk_version: SDK_VERSION,
+    node_version: process.version,
+    os: process.platform,
+    arch: process.arch
+  };
+}
+function getWorkflowContextFromEnv() {
+  const baseMeta = getBaseMetadata();
+  const n8n = pickEnv(N8N_KEYS);
+  if (Object.keys(n8n).length > 0) {
+    return {
+      source: "n8n",
+      workflow_id: n8n.N8N_WORKFLOW_ID,
+      execution_id: n8n.N8N_EXECUTION_ID,
+      metadata: { ...baseMeta, ...n8n }
+    };
+  }
+  const vercel = pickEnv(VERCEL_KEYS);
+  if (Object.keys(vercel).length > 0) {
+    return {
+      source: "vercel",
+      workflow_id: vercel.VERCEL_GIT_REPO_ID || vercel.VERCEL_URL,
+      execution_id: vercel.VERCEL_GIT_COMMIT_SHA,
+      metadata: { ...baseMeta, ...vercel }
+    };
+  }
+  const github = pickEnv(GITHUB_KEYS);
+  if (Object.keys(github).length > 0) {
+    return {
+      source: "github",
+      workflow_id: github.GITHUB_WORKFLOW || github.GITHUB_REPOSITORY,
+      execution_id: github.GITHUB_RUN_ID || github.GITHUB_RUN_NUMBER,
+      metadata: { ...baseMeta, ...github }
+    };
+  }
+  return {
+    source: "local_script",
+    metadata: baseMeta
+  };
+}
+function buildSourceToolJson(ctx) {
+  const meta = ctx.metadata ?? getBaseMetadata();
+  const payload = {
+    source: ctx.source,
+    metadata: meta
+  };
+  if (ctx.workflow_id !== void 0) payload.workflow_id = ctx.workflow_id;
+  if (ctx.execution_id !== void 0) payload.execution_id = ctx.execution_id;
+  if (ctx.workflow_step !== void 0) payload.workflow_step = ctx.workflow_step;
+  return JSON.stringify(payload);
+}
+function buildContextHeaders(ctx) {
+  const meta = ctx.metadata ?? getBaseMetadata();
+  const h = {
+    [SOURCE_TOOL_HEADER]: buildSourceToolJson({ ...ctx, metadata: meta }),
+    [`${HEADER_PREFIX}-source`]: ctx.source
+  };
+  if (ctx.workflow_id) h[`${HEADER_PREFIX}-workflow-id`] = ctx.workflow_id;
+  if (ctx.execution_id) h[`${HEADER_PREFIX}-execution-id`] = ctx.execution_id;
+  if (ctx.workflow_step) h[`${HEADER_PREFIX}-workflow-step`] = ctx.workflow_step;
+  for (const [k, v] of Object.entries(meta)) {
+    if (v) h[`${HEADER_PREFIX}-meta-${k.toLowerCase()}`] = String(v);
+  }
+  return h;
+}
+
+export {
+  HEADER_PREFIX,
+  SOURCE_TOOL_HEADER,
+  getWorkflowContextFromEnv,
+  buildSourceToolJson,
+  buildContextHeaders
+};

package/dist/chunk-UUGIIO3Q.mjs

@@ -0,0 +1,31 @@
+import {
+  buildContextHeaders,
+  getWorkflowContextFromEnv
+} from "./chunk-SV5FTXAH.mjs";
+
+// src/middleware/vercel-ai.ts
+function getTrustGateHeaders(workflowContext) {
+  const ctx = workflowContext ?? getWorkflowContextFromEnv();
+  return buildContextHeaders(ctx);
+}
+function createTrustGateOpenAIOptions(options) {
+  const baseUrl = options.baseUrl.replace(/\/$/, "");
+  const headers = {
+    ...options.headers,
+    ...getTrustGateHeaders(options.workflowContext)
+  };
+  if (options.apiKey) {
+    headers["authorization"] = `Bearer ${options.apiKey}`;
+    headers["x-api-key"] = options.apiKey;
+  }
+  return {
+    baseURL: baseUrl,
+    apiKey: options.openaiApiKey ?? options.apiKey,
+    headers: Object.keys(headers).length ? headers : void 0
+  };
+}
+
+export {
+  getTrustGateHeaders,
+  createTrustGateOpenAIOptions
+};

package/dist/index.d.mts

@@ -0,0 +1,75 @@
+import { T as TrustGateConfig, R as RequestOptions, W as WorkflowContext, N as N8nHeaderSnippet } from './types-BxyYog9f.mjs';
+export { a as RuntimeMetadata } from './types-BxyYog9f.mjs';
+export { TrustGateOpenAIOptions, createTrustGateOpenAIOptions, getTrustGateHeaders } from './middleware/vercel-ai.mjs';
+export { createTrustGateLangChainConfig } from './middleware/langchain.mjs';
+
+/**
+ * TrustGate Node.js client. Forwards requests to the TrustGate gateway with
+ * workflow context for Shadow AI detection and observability.
+ *
+ * Context is sent in lowercase headers (e.g. x-trustgate-source) and as JSON
+ * in x-trustgate-source-tool for parity with the Python SDK. The `workflow_step`
+ * field in context is the key used to generate Gantt chart bars in the
+ * Agent Intelligence dashboard.
+ */
+declare class TrustGate {
+    private readonly config;
+    constructor(config: TrustGateConfig);
+    /** Base URL of the TrustGate gateway. */
+    get baseUrl(): string;
+    /**
+     * Get the current effective workflow context (from config override or process.env).
+     * Never null; defaults to source "local_script" when no managed env is detected.
+     */
+    getWorkflowContext(options?: RequestOptions): WorkflowContext;
+    /**
+     * Perform a non-streaming JSON request through TrustGate.
+     */
+    fetch(path: string, init?: RequestInit, options?: RequestOptions): Promise<Response>;
+    /**
+     * Perform a streaming request (SSE). Forwards the response stream and ensures
+     * workflow_id (and other context) is sent in the initial request so the
+     * background task is attributed correctly. Set Accept: text/event-stream
+     * when calling for SSE endpoints.
+     */
+    fetchStream(path: string, init?: RequestInit, options?: RequestOptions): Promise<Response>;
+}
+
+/** Lowercase header prefix for proxy/gateway parity with Python SDK. */
+declare const HEADER_PREFIX = "x-trustgate";
+/** Header carrying the full context JSON (structurally identical to Python SDK). */
+declare const SOURCE_TOOL_HEADER = "x-trustgate-source-tool";
+/**
+ * Searches process.env for workflow metadata from n8n, Vercel, or GitHub.
+ * If no managed environment is detected, returns context with source "local_script"
+ * so local developer usage is correctly tagged as Shadow AI in the dashboard.
+ * Never returns null.
+ */
+declare function getWorkflowContextFromEnv(): WorkflowContext;
+/**
+ * JSON payload for x-trustgate-source-tool header (structurally identical to Python SDK).
+ */
+declare function buildSourceToolJson(ctx: WorkflowContext): string;
+/**
+ * Builds lowercase TrustGate context headers plus x-trustgate-source-tool JSON.
+ * Use for proxy/gateway parity and Python SDK contract.
+ */
+declare function buildContextHeaders(ctx: WorkflowContext): Record<string, string>;
+
+/**
+ * Returns a pre-formatted JSON object of headers for use in n8n "HTTP Request" nodes.
+ * Header keys are lowercase for gateway parity. Includes TrustGate auth and workflow
+ * context (workflow_id, execution_id, source, x-trustgate-source-tool JSON).
+ *
+ * Use in n8n:
+ * 1. Add an "HTTP Request" node.
+ * 2. In "Send Headers" (or equivalent), use the returned `headers` array
+ *    or paste the `json` string into a "JSON" header configuration.
+ *
+ * @param apiKey - Optional TrustGate API key (or use TRUSTGATE_API_KEY env).
+ * @param baseUrl - Optional gateway base URL (or use TRUSTGATE_BASE_URL env).
+ * @returns Headers as name/value list and as a JSON string for n8n.
+ */
+declare function getN8nHeaderSnippet(apiKey?: string, baseUrl?: string): N8nHeaderSnippet;
+
+export { HEADER_PREFIX, N8nHeaderSnippet, RequestOptions, SOURCE_TOOL_HEADER, TrustGate, TrustGateConfig, WorkflowContext, buildContextHeaders, buildSourceToolJson, getN8nHeaderSnippet, getWorkflowContextFromEnv };

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { T as TrustGateConfig, R as RequestOptions, W as WorkflowContext, N as N8nHeaderSnippet } from './types-BxyYog9f.js';
+export { a as RuntimeMetadata } from './types-BxyYog9f.js';
+export { TrustGateOpenAIOptions, createTrustGateOpenAIOptions, getTrustGateHeaders } from './middleware/vercel-ai.js';
+export { createTrustGateLangChainConfig } from './middleware/langchain.js';
+
+/**
+ * TrustGate Node.js client. Forwards requests to the TrustGate gateway with
+ * workflow context for Shadow AI detection and observability.
+ *
+ * Context is sent in lowercase headers (e.g. x-trustgate-source) and as JSON
+ * in x-trustgate-source-tool for parity with the Python SDK. The `workflow_step`
+ * field in context is the key used to generate Gantt chart bars in the
+ * Agent Intelligence dashboard.
+ */
+declare class TrustGate {
+    private readonly config;
+    constructor(config: TrustGateConfig);
+    /** Base URL of the TrustGate gateway. */
+    get baseUrl(): string;
+    /**
+     * Get the current effective workflow context (from config override or process.env).
+     * Never null; defaults to source "local_script" when no managed env is detected.
+     */
+    getWorkflowContext(options?: RequestOptions): WorkflowContext;
+    /**
+     * Perform a non-streaming JSON request through TrustGate.
+     */
+    fetch(path: string, init?: RequestInit, options?: RequestOptions): Promise<Response>;
+    /**
+     * Perform a streaming request (SSE). Forwards the response stream and ensures
+     * workflow_id (and other context) is sent in the initial request so the
+     * background task is attributed correctly. Set Accept: text/event-stream
+     * when calling for SSE endpoints.
+     */
+    fetchStream(path: string, init?: RequestInit, options?: RequestOptions): Promise<Response>;
+}
+
+/** Lowercase header prefix for proxy/gateway parity with Python SDK. */
+declare const HEADER_PREFIX = "x-trustgate";
+/** Header carrying the full context JSON (structurally identical to Python SDK). */
+declare const SOURCE_TOOL_HEADER = "x-trustgate-source-tool";
+/**
+ * Searches process.env for workflow metadata from n8n, Vercel, or GitHub.
+ * If no managed environment is detected, returns context with source "local_script"
+ * so local developer usage is correctly tagged as Shadow AI in the dashboard.
+ * Never returns null.
+ */
+declare function getWorkflowContextFromEnv(): WorkflowContext;
+/**
+ * JSON payload for x-trustgate-source-tool header (structurally identical to Python SDK).
+ */
+declare function buildSourceToolJson(ctx: WorkflowContext): string;
+/**
+ * Builds lowercase TrustGate context headers plus x-trustgate-source-tool JSON.
+ * Use for proxy/gateway parity and Python SDK contract.
+ */
+declare function buildContextHeaders(ctx: WorkflowContext): Record<string, string>;
+
+/**
+ * Returns a pre-formatted JSON object of headers for use in n8n "HTTP Request" nodes.
+ * Header keys are lowercase for gateway parity. Includes TrustGate auth and workflow
+ * context (workflow_id, execution_id, source, x-trustgate-source-tool JSON).
+ *
+ * Use in n8n:
+ * 1. Add an "HTTP Request" node.
+ * 2. In "Send Headers" (or equivalent), use the returned `headers` array
+ *    or paste the `json` string into a "JSON" header configuration.
+ *
+ * @param apiKey - Optional TrustGate API key (or use TRUSTGATE_API_KEY env).
+ * @param baseUrl - Optional gateway base URL (or use TRUSTGATE_BASE_URL env).
+ * @returns Headers as name/value list and as a JSON string for n8n.
+ */
+declare function getN8nHeaderSnippet(apiKey?: string, baseUrl?: string): N8nHeaderSnippet;
+
+export { HEADER_PREFIX, N8nHeaderSnippet, RequestOptions, SOURCE_TOOL_HEADER, TrustGate, TrustGateConfig, WorkflowContext, buildContextHeaders, buildSourceToolJson, getN8nHeaderSnippet, getWorkflowContextFromEnv };