@trustgateai/sdk 1.0.0

package/src/context.ts

@@ -0,0 +1,132 @@
+import type { WorkflowContext, RuntimeMetadata } from "./types.js";
+import { SDK_VERSION } from "./version.js";
+
+/** Lowercase header prefix for proxy/gateway parity with Python SDK. */
+export const HEADER_PREFIX = "x-trustgate";
+/** Header carrying the full context JSON (structurally identical to Python SDK). */
+export const SOURCE_TOOL_HEADER = "x-trustgate-source-tool";
+
+/** Env keys we check for workflow/source metadata (Shadow AI context). */
+const N8N_KEYS = [
+  "N8N_WORKFLOW_ID",
+  "N8N_EXECUTION_ID",
+  "N8N_WORKFLOW_NAME",
+  "N8N_EXECUTION_MODE",
+] as const;
+
+const VERCEL_KEYS = [
+  "VERCEL",
+  "VERCEL_ENV",
+  "VERCEL_URL",
+  "VERCEL_GIT_COMMIT_REF",
+  "VERCEL_GIT_REPO_ID",
+  "VERCEL_GIT_COMMIT_SHA",
+] as const;
+
+const GITHUB_KEYS = [
+  "GITHUB_ACTION",
+  "GITHUB_ACTIONS",
+  "GITHUB_WORKFLOW",
+  "GITHUB_RUN_ID",
+  "GITHUB_RUN_NUMBER",
+  "GITHUB_REPOSITORY",
+  "GITHUB_SHA",
+] as const;
+
+function pickEnv(keys: readonly string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const key of keys) {
+    const v = process.env[key];
+    if (v !== undefined && v !== "") out[key] = v;
+  }
+  return out;
+}
+
+/** Base runtime metadata (sdk_version, node_version, os, arch) for Python parity. */
+function getBaseMetadata(): RuntimeMetadata {
+  return {
+    sdk_version: SDK_VERSION,
+    node_version: process.version,
+    os: process.platform,
+    arch: process.arch,
+  };
+}
+
+/**
+ * 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.
+ */
+export function getWorkflowContextFromEnv(): WorkflowContext {
+  const baseMeta = getBaseMetadata();
+
+  const n8n = pickEnv(N8N_KEYS as unknown as string[]);
+  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 as unknown as string[]);
+  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 as unknown as string[]);
+  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,
+  };
+}
+
+/**
+ * JSON payload for x-trustgate-source-tool header (structurally identical to Python SDK).
+ */
+export function buildSourceToolJson(ctx: WorkflowContext): string {
+  const meta = ctx.metadata ?? getBaseMetadata();
+  const payload: Record<string, unknown> = {
+    source: ctx.source,
+    metadata: meta,
+  };
+  if (ctx.workflow_id !== undefined) payload.workflow_id = ctx.workflow_id;
+  if (ctx.execution_id !== undefined) payload.execution_id = ctx.execution_id;
+  if (ctx.workflow_step !== undefined) payload.workflow_step = ctx.workflow_step;
+  return JSON.stringify(payload);
+}
+
+/**
+ * Builds lowercase TrustGate context headers plus x-trustgate-source-tool JSON.
+ * Use for proxy/gateway parity and Python SDK contract.
+ */
+export function buildContextHeaders(ctx: WorkflowContext): Record<string, string> {
+  const meta = ctx.metadata ?? getBaseMetadata();
+  const h: Record<string, string> = {
+    [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;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * TrustGate Node.js SDK
+ *
+ * Provides a TypeScript client, workflow context from n8n/Vercel/GitHub env vars,
+ * middleware for Vercel AI SDK and LangChain, n8n header snippet helper, and
+ * SSE streaming with workflow_id preserved for Shadow AI detection.
+ */
+
+export { TrustGate } from "./client.js";
+export {
+  getWorkflowContextFromEnv,
+  buildContextHeaders,
+  buildSourceToolJson,
+  HEADER_PREFIX,
+  SOURCE_TOOL_HEADER,
+} from "./context.js";
+export { getN8nHeaderSnippet } from "./n8n.js";
+export {
+  getTrustGateHeaders,
+  createTrustGateOpenAIOptions,
+  type TrustGateOpenAIOptions,
+} from "./middleware/vercel-ai.js";
+export { createTrustGateLangChainConfig } from "./middleware/langchain.js";
+
+export type {
+  WorkflowContext,
+  RuntimeMetadata,
+  TrustGateConfig,
+  RequestOptions,
+  N8nHeaderSnippet,
+} from "./types.js";

package/src/middleware/langchain.ts

@@ -0,0 +1,57 @@
+/**
+ * LangChain middleware: use TrustGate as the OpenAI endpoint with one line.
+ *
+ * ChatOpenAI (and other LangChain OpenAI integrations) support baseURL and
+ * defaultHeaders. Point them to your TrustGate gateway and inject workflow
+ * context so Shadow AI detection can attribute requests.
+ *
+ * Example:
+ *
+ *   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,
+ *   });
+ */
+
+import type { TrustGateConfig } from "../types.js";
+import { getWorkflowContextFromEnv, buildContextHeaders } from "../context.js";
+
+/**
+ * Configuration to pass to LangChain's ChatOpenAI (or other OpenAI-based classes).
+ * Sets baseURL and defaultHeaders (lowercase keys) so requests go through TrustGate
+ * with workflow context and x-trustgate-source-tool JSON for Shadow AI detection.
+ */
+export function createTrustGateLangChainConfig(config: TrustGateConfig): {
+  configuration?: { baseURL: string; defaultHeaders?: Record<string, string> };
+  baseURL?: string;
+  defaultHeaders?: Record<string, string>;
+} {
+  const baseUrl = config.baseUrl.replace(/\/$/, "");
+  const ctx = config.workflowContext ?? getWorkflowContextFromEnv();
+  const headers: Record<string, string> = {
+    ...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 : undefined,
+    configuration: {
+      baseURL: baseUrl,
+      defaultHeaders: Object.keys(headers).length ? headers : undefined,
+    },
+  };
+}

package/src/middleware/vercel-ai.ts

@@ -0,0 +1,78 @@
+/**
+ * Vercel AI SDK middleware: swap the provider to TrustGate with one line.
+ *
+ * Use createOpenAI from @openai/api or the AI SDK's OpenAI provider, and point
+ * baseURL to your TrustGate gateway. This ensures all LLM calls go through
+ * TrustGate with workflow context for Shadow AI detection.
+ *
+ * Example:
+ *
+ *   import { createOpenAI } from '@ai-sdk/openai';
+ *   import { createTrustGateOpenAI } from 'trustgate-node/middleware/vercel-ai';
+ *
+ *   const openai = createTrustGateOpenAI({
+ *     baseUrl: process.env.TRUSTGATE_BASE_URL!,
+ *     apiKey: process.env.TRUSTGATE_API_KEY,
+ *   });
+ *
+ *   // Then use `openai` with streamText() as usual — requests go through TrustGate.
+ *   const result = streamText({ model: openai('gpt-4'), messages, ... });
+ */
+
+import type { TrustGateConfig } from "../types.js";
+import { getWorkflowContextFromEnv, buildContextHeaders } from "../context.js";
+
+export interface TrustGateOpenAIOptions extends TrustGateConfig {
+  /**
+   * Optional OpenAI-compatible API key (if your gateway expects it in addition to TrustGate key).
+   */
+  openaiApiKey?: string;
+}
+
+/**
+ * Returns extra headers (lowercase keys) to pass to the Vercel AI SDK OpenAI provider
+ * so that requests sent to TrustGate include workflow context and x-trustgate-source-tool
+ * JSON for Shadow AI detection. Use with createOpenAI({ baseURL, headers: getTrustGateHeaders() }).
+ */
+export function getTrustGateHeaders(workflowContext?: TrustGateConfig["workflowContext"]): Record<string, string> {
+  const ctx = workflowContext ?? getWorkflowContextFromEnv();
+  return buildContextHeaders(ctx);
+}
+
+/**
+ * Creates options suitable for the Vercel AI SDK's OpenAI provider so that
+ * you can swap the provider to TrustGate in one line.
+ *
+ * Usage with AI SDK 3.x:
+ *
+ *   import { createOpenAI } from '@ai-sdk/openai';
+ *   import { createTrustGateOpenAIOptions } from 'trustgate-node/middleware/vercel-ai';
+ *
+ *   const openaiOptions = createTrustGateOpenAIOptions({
+ *     baseUrl: process.env.TRUSTGATE_BASE_URL!,
+ *     apiKey: process.env.TRUSTGATE_API_KEY,
+ *   });
+ *
+ *   const openai = createOpenAI(openaiOptions);
+ *   // use openai('gpt-4') with streamText()
+ */
+export function createTrustGateOpenAIOptions(options: TrustGateOpenAIOptions): {
+  baseURL: string;
+  apiKey?: string;
+  headers?: Record<string, string>;
+} {
+  const baseUrl = options.baseUrl.replace(/\/$/, "");
+  const headers: Record<string, string> = {
+    ...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 : undefined,
+  };
+}

package/src/n8n.ts

@@ -0,0 +1,51 @@
+import type { N8nHeaderSnippet } from "./types.js";
+import { getWorkflowContextFromEnv, buildContextHeaders, HEADER_PREFIX } from "./context.js";
+
+/**
+ * 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.
+ */
+export function getN8nHeaderSnippet(
+  apiKey?: string,
+  baseUrl?: string
+): N8nHeaderSnippet {
+  const key = apiKey ?? process.env.TRUSTGATE_API_KEY ?? "";
+  const url = baseUrl ?? process.env.TRUSTGATE_BASE_URL ?? "";
+  const ctx = getWorkflowContextFromEnv();
+  const contextHeaders = buildContextHeaders(ctx);
+
+  const headers: Array<{ name: string; value: string }> = [];
+
+  if (url) {
+    headers.push({ name: `${HEADER_PREFIX}-gateway-url`, value: url });
+  }
+  if (key) {
+    headers.push({ name: "authorization", value: `Bearer ${key}` });
+    headers.push({ name: "x-api-key", value: key });
+  }
+
+  for (const [name, value] of Object.entries(contextHeaders)) {
+    headers.push({ name, value });
+  }
+
+  const json = JSON.stringify(
+    headers.reduce<Record<string, string>>((acc, { name, value }) => {
+      acc[name] = value;
+      return acc;
+    }, {}),
+    null,
+    2
+  );
+
+  return { headers, json };
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Runtime metadata included in every context for parity with the Python SDK.
+ * Sent in x-trustgate-source-tool and in x-trustgate-meta-* headers.
+ */
+export interface RuntimeMetadata {
+  /** SDK version (e.g. "1.0.0"). */
+  sdk_version: string;
+  /** Node.js version (e.g. "v20.1.0"). */
+  node_version: string;
+  /** Operating system platform (process.platform, e.g. "win32", "darwin", "linux"). */
+  os: string;
+  /** CPU architecture (process.arch, e.g. "x64", "arm64"). */
+  arch: string;
+  [key: string]: string;
+}
+
+/**
+ * Workflow/source metadata for Shadow AI detection and observability.
+ * Populated from n8n, Vercel, GitHub Actions, or default "local_script".
+ * Metadata always includes sdk_version, node_version, os, arch for Python parity.
+ */
+export interface WorkflowContext {
+  /** Source: "n8n" | "vercel" | "github" | "local_script" | "custom". Never null. */
+  source: string;
+  /** Workflow or execution identifier */
+  workflow_id?: string;
+  /** Execution or run ID */
+  execution_id?: string;
+  /** Step identifier; key for generating Gantt chart bars in the Agent Intelligence dashboard. */
+  workflow_step?: string;
+  /** Runtime + environment metadata. When omitted, SDK fills sdk_version, node_version, os, arch. */
+  metadata?: RuntimeMetadata;
+}
+
+/**
+ * TrustGate client configuration.
+ */
+export interface TrustGateConfig {
+  /** TrustGate gateway base URL (e.g. https://gateway.example.com) */
+  baseUrl: string;
+  /** API key for gateway authentication (if required) */
+  apiKey?: string;
+  /** Override workflow context; if not set, context is derived from process.env (never null). */
+  workflowContext?: WorkflowContext;
+  /** Extra headers sent with every request */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Options for a single request (merge with client config).
+ */
+export interface RequestOptions {
+  /** Override workflow context for this request only */
+  workflowContext?: WorkflowContext;
+  /** Additional headers for this request */
+  headers?: Record<string, string>;
+  /** Request timeout in ms */
+  timeout?: number;
+}
+
+/**
+ * Pre-formatted headers for n8n HTTP Request node (name/value pairs).
+ */
+export interface N8nHeaderSnippet {
+  headers: Array<{ name: string; value: string }>;
+  /** JSON string suitable for pasting into n8n */
+  json: string;
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+/** SDK version; kept in sync with package.json for x-trustgate-source-tool metadata. */
+export const SDK_VERSION = "1.0.0";

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}