@entrys/client 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# Entrys
+
+Give your AI agents a single entry point to access internal APIs and tools. Redact PII by default, audit every request, and control access, without modifying your existing services.
+
+
+## Installation
+
+```bash
+npm install @entrys/client
+# or
+pnpm add @entrys/client
+```
+
+## Quick Start
+
+```typescript
+import Entry from "@entrys/client";
+
+const entry = new Entry({
+  apiKey: process.env.ENTRYS_API_KEY
+});
+
+const customer = await entry.invoke("get_customer", {
+  params: { id: "123" }
+});
+
+console.log(customer);
+// { name: "Jane Doe", email: "[REDACTED]", ... }
+```
+
+## Configuration
+
+Set your API key pass it directly:
+
+```typescript
+const entry = new Entry({ apiKey: "ent_your_api_key" });
+```
+
+For self-hosted deployments, also set the base URL:
+
+```typescript
+const entry = new Entry({
+  apiKey: process.env.ENTRYS_API_KEY,
+  baseUrl: "http://localhost:3001"
+});
+```
+
+## API
+
+### `new Entry(options?)`
+
+Create a new entrys client.
+
+**Options (all optional):**
+- `apiKey` - Your agent API key. Defaults to `ENTRYS_API_KEY` env var
+- `baseUrl` - Gateway URL. Defaults to `ENTRYS_BASE_URL` env var or `https://api.entrys.co`
+- `fetch` - Custom fetch implementation
+
+### `agent.invoke(toolName, options?)`
+
+Invoke a registered tool through the gateway. Returns the output directly.
+
+**Parameters:**
+- `toolName` (string) - Name of the tool to invoke
+- `options.params` (object) - URL path parameters
+- `options.input` (object) - Request body data
+- `options.context` (object) - Additional context
+
+**Returns:** `Promise<T>` - The tool output (with PII automatically redacted)
+
+**Throws:** `EntryError` on failure
+
+```typescript
+const customer = await entry.invoke("get_customer", {
+  params: { id: "123" }
+});
+
+const invoice = await entry.invoke("get_invoice", {
+  params: { customerId: "123" }
+});
+```
+
+### `agent.invokeWithMeta(toolName, options?)`
+
+Same as `invoke` but also returns metadata including redaction info.
+
+```typescript
+const { output, meta } = await entry.invokeWithMeta("get_customer", {
+  params: { id: "123" }
+});
+
+console.log(meta.requestId);   // Unique request ID
+console.log(meta.latencyMs);   // Request latency
+console.log(meta.redactions);  // [{ type: "email", count: 1 }]
+```
+
+### `agent.invokeRaw(toolName, options?)`
+
+Returns the raw response without throwing on errors. Useful if you want to handle errors yourself.
+
+## Error Handling
+
+```typescript
+import { Entry, EntryError } from "@entrys/client";
+
+try {
+  await entry.invoke("get_customer", { params: { id: "123" } });
+} catch (err) {
+  if (err instanceof EntryError) {
+    console.log(err.code);      // 'TOOL_NOT_FOUND', 'UNAUTHORIZED', etc.
+    console.log(err.message);   // Human-readable message
+    console.log(err.requestId); // For debugging
+  }
+}
+```
+
+## Error Codes
+
+- `TOOL_NOT_FOUND` - Tool doesn't exist in this environment
+- `UNAUTHORIZED` - Agent not authorized for this tool
+- `RATE_LIMITED` - Rate limit exceeded (60 req/min)
+- `VALIDATION_ERROR` - Invalid parameters
+- `UPSTREAM_ERROR` - The upstream API returned an error

package/dist/index.d.mts

@@ -0,0 +1,143 @@
+/**
+ * Summary of redactions applied to output
+ */
+interface RedactionSummary {
+    type: string;
+    count: number;
+}
+/**
+ * Successful tool invocation response
+ */
+interface InvokeSuccessResponse {
+    ok: true;
+    tool: string;
+    output: unknown;
+    meta: {
+        requestId: string;
+        latencyMs: number;
+        redactions: RedactionSummary[];
+        version?: string;
+        backendType?: string;
+    };
+}
+/**
+ * Error response from tool invocation
+ */
+interface InvokeErrorResponse {
+    ok: false;
+    error: {
+        code: 'TOOL_NOT_FOUND' | 'UNAUTHORIZED' | 'UPSTREAM_ERROR' | 'RATE_LIMITED' | 'VALIDATION_ERROR' | 'MCP_ERROR';
+        message: string;
+    };
+    meta: {
+        requestId: string;
+    };
+}
+/**
+ * Union type for invoke responses
+ */
+type InvokeResponse = InvokeSuccessResponse | InvokeErrorResponse;
+/**
+ * Configuration options for Entry
+ */
+interface EntryOptions {
+    /** API key for authentication (starts with "ent_"). Defaults to ENTRYS_API_KEY env var */
+    apiKey?: string;
+    /** Base URL of the entrys gateway. Defaults to ENTRYS_BASE_URL env var or https://api.entrys.dev */
+    baseUrl?: string;
+    /** Optional custom fetch implementation (for testing or custom environments) */
+    fetch?: typeof fetch;
+}
+/**
+ * Options for invoking a tool
+ */
+interface InvokeOptions {
+    /** URL path parameters (e.g., { id: "123" } for /customers/{{id}}) */
+    params?: Record<string, string>;
+    /** Request body/input data */
+    input?: Record<string, unknown>;
+    /** Additional context passed to the tool */
+    context?: Record<string, unknown>;
+}
+/**
+ * Metadata returned with successful invocations
+ */
+interface InvokeMeta {
+    requestId: string;
+    latencyMs: number;
+    redactions: Array<{
+        type: string;
+        count: number;
+    }>;
+}
+/**
+ * Error thrown when a tool invocation fails
+ */
+declare class EntryError extends Error {
+    code: string;
+    requestId: string;
+    constructor(code: string, message: string, requestId: string);
+}
+/**
+ * entrys client for invoking tools
+ *
+ * @example
+ * ```typescript
+ * import Entry from "@entrys/client";
+ *
+ * const entry = new Entry();
+ *
+ * const customer = await entry.invoke("get_customer", {
+ *   params: { id: "123" }
+ * });
+ * ```
+ */
+declare class Entry {
+    private baseUrl;
+    private apiKey;
+    private fetchFn;
+    constructor(options?: EntryOptions);
+    /**
+     * Invoke a registered tool through the gateway
+     *
+     * @param toolName - The name of the tool to invoke (e.g., "get_customer")
+     * @param options - Parameters, input data, and context for the tool
+     * @returns The tool output (with PII automatically redacted)
+     * @throws {EntryError} If the tool invocation fails
+     *
+     * @example
+     * ```typescript
+     * const customer = await agent.invoke("get_customer", {
+     *   params: { id: "123" }
+     * });
+     * ```
+     */
+    invoke<T = unknown>(toolName: string, options?: InvokeOptions): Promise<T>;
+    /**
+     * Invoke a tool and return both output and metadata
+     *
+     * @example
+     * ```typescript
+     * const { output, meta } = await agent.invokeWithMeta("get_customer", {
+     *   params: { id: "123" }
+     * });
+     * console.log(meta.redactions); // PII that was scrubbed
+     * ```
+     */
+    invokeWithMeta<T = unknown>(toolName: string, options?: InvokeOptions): Promise<{
+        output: T;
+        meta: InvokeMeta;
+    }>;
+    /**
+     * Invoke a tool and return the raw response (including error responses)
+     * Use this if you want to handle errors yourself instead of catching exceptions
+     */
+    invokeRaw(toolName: string, options?: InvokeOptions): Promise<InvokeResponse>;
+}
+declare const createClient: (options?: EntryOptions) => Entry;
+declare const AgentGateway: typeof Entry;
+type AgentGatewayOptions = EntryOptions;
+declare const AgentGatewayError: typeof EntryError;
+declare const ATGError: typeof EntryError;
+
+export { ATGError, AgentGateway, AgentGatewayError, type AgentGatewayOptions, Entry, EntryError, type EntryOptions, type InvokeErrorResponse, type InvokeMeta, type InvokeOptions, type InvokeResponse, type InvokeSuccessResponse, type RedactionSummary, createClient, Entry as default };

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Summary of redactions applied to output
+ */
+interface RedactionSummary {
+    type: string;
+    count: number;
+}
+/**
+ * Successful tool invocation response
+ */
+interface InvokeSuccessResponse {
+    ok: true;
+    tool: string;
+    output: unknown;
+    meta: {
+        requestId: string;
+        latencyMs: number;
+        redactions: RedactionSummary[];
+        version?: string;
+        backendType?: string;
+    };
+}
+/**
+ * Error response from tool invocation
+ */
+interface InvokeErrorResponse {
+    ok: false;
+    error: {
+        code: 'TOOL_NOT_FOUND' | 'UNAUTHORIZED' | 'UPSTREAM_ERROR' | 'RATE_LIMITED' | 'VALIDATION_ERROR' | 'MCP_ERROR';
+        message: string;
+    };
+    meta: {
+        requestId: string;
+    };
+}
+/**
+ * Union type for invoke responses
+ */
+type InvokeResponse = InvokeSuccessResponse | InvokeErrorResponse;
+/**
+ * Configuration options for Entry
+ */
+interface EntryOptions {
+    /** API key for authentication (starts with "ent_"). Defaults to ENTRYS_API_KEY env var */
+    apiKey?: string;
+    /** Base URL of the entrys gateway. Defaults to ENTRYS_BASE_URL env var or https://api.entrys.dev */
+    baseUrl?: string;
+    /** Optional custom fetch implementation (for testing or custom environments) */
+    fetch?: typeof fetch;
+}
+/**
+ * Options for invoking a tool
+ */
+interface InvokeOptions {
+    /** URL path parameters (e.g., { id: "123" } for /customers/{{id}}) */
+    params?: Record<string, string>;
+    /** Request body/input data */
+    input?: Record<string, unknown>;
+    /** Additional context passed to the tool */
+    context?: Record<string, unknown>;
+}
+/**
+ * Metadata returned with successful invocations
+ */
+interface InvokeMeta {
+    requestId: string;
+    latencyMs: number;
+    redactions: Array<{
+        type: string;
+        count: number;
+    }>;
+}
+/**
+ * Error thrown when a tool invocation fails
+ */
+declare class EntryError extends Error {
+    code: string;
+    requestId: string;
+    constructor(code: string, message: string, requestId: string);
+}
+/**
+ * entrys client for invoking tools
+ *
+ * @example
+ * ```typescript
+ * import Entry from "@entrys/client";
+ *
+ * const entry = new Entry();
+ *
+ * const customer = await entry.invoke("get_customer", {
+ *   params: { id: "123" }
+ * });
+ * ```
+ */
+declare class Entry {
+    private baseUrl;
+    private apiKey;
+    private fetchFn;
+    constructor(options?: EntryOptions);
+    /**
+     * Invoke a registered tool through the gateway
+     *
+     * @param toolName - The name of the tool to invoke (e.g., "get_customer")
+     * @param options - Parameters, input data, and context for the tool
+     * @returns The tool output (with PII automatically redacted)
+     * @throws {EntryError} If the tool invocation fails
+     *
+     * @example
+     * ```typescript
+     * const customer = await agent.invoke("get_customer", {
+     *   params: { id: "123" }
+     * });
+     * ```
+     */
+    invoke<T = unknown>(toolName: string, options?: InvokeOptions): Promise<T>;
+    /**
+     * Invoke a tool and return both output and metadata
+     *
+     * @example
+     * ```typescript
+     * const { output, meta } = await agent.invokeWithMeta("get_customer", {
+     *   params: { id: "123" }
+     * });
+     * console.log(meta.redactions); // PII that was scrubbed
+     * ```
+     */
+    invokeWithMeta<T = unknown>(toolName: string, options?: InvokeOptions): Promise<{
+        output: T;
+        meta: InvokeMeta;
+    }>;
+    /**
+     * Invoke a tool and return the raw response (including error responses)
+     * Use this if you want to handle errors yourself instead of catching exceptions
+     */
+    invokeRaw(toolName: string, options?: InvokeOptions): Promise<InvokeResponse>;
+}
+declare const createClient: (options?: EntryOptions) => Entry;
+declare const AgentGateway: typeof Entry;
+type AgentGatewayOptions = EntryOptions;
+declare const AgentGatewayError: typeof EntryError;
+declare const ATGError: typeof EntryError;
+
+export { ATGError, AgentGateway, AgentGatewayError, type AgentGatewayOptions, Entry, EntryError, type EntryOptions, type InvokeErrorResponse, type InvokeMeta, type InvokeOptions, type InvokeResponse, type InvokeSuccessResponse, type RedactionSummary, createClient, Entry as default };

package/dist/index.js

@@ -0,0 +1,149 @@
+"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, {
+  ATGError: () => ATGError,
+  AgentGateway: () => AgentGateway,
+  AgentGatewayError: () => AgentGatewayError,
+  Entry: () => Entry,
+  EntryError: () => EntryError,
+  createClient: () => createClient,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var EntryError = class extends Error {
+  code;
+  requestId;
+  constructor(code, message, requestId) {
+    super(message);
+    this.name = "EntryError";
+    this.code = code;
+    this.requestId = requestId;
+  }
+};
+var Entry = class {
+  baseUrl;
+  apiKey;
+  fetchFn;
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? (typeof process !== "undefined" ? process.env?.ENTRYS_API_KEY : void 0);
+    const baseUrl = options.baseUrl ?? (typeof process !== "undefined" ? process.env?.ENTRYS_BASE_URL : void 0) ?? "https://api.entrys.co";
+    if (!apiKey) {
+      throw new Error("Entry: apiKey is required. Pass it in options or set ENTRYS_API_KEY environment variable.");
+    }
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = apiKey;
+    this.fetchFn = options.fetch ?? fetch;
+  }
+  /**
+   * Invoke a registered tool through the gateway
+   * 
+   * @param toolName - The name of the tool to invoke (e.g., "get_customer")
+   * @param options - Parameters, input data, and context for the tool
+   * @returns The tool output (with PII automatically redacted)
+   * @throws {EntryError} If the tool invocation fails
+   * 
+   * @example
+   * ```typescript
+   * const customer = await agent.invoke("get_customer", {
+   *   params: { id: "123" }
+   * });
+   * ```
+   */
+  async invoke(toolName, options) {
+    const result = await this.invokeWithMeta(toolName, options);
+    return result.output;
+  }
+  /**
+   * Invoke a tool and return both output and metadata
+   * 
+   * @example
+   * ```typescript
+   * const { output, meta } = await agent.invokeWithMeta("get_customer", {
+   *   params: { id: "123" }
+   * });
+   * console.log(meta.redactions); // PII that was scrubbed
+   * ```
+   */
+  async invokeWithMeta(toolName, options) {
+    const url = `${this.baseUrl}/v1/invoke/${encodeURIComponent(toolName)}`;
+    const body = {};
+    if (options?.params) body.params = options.params;
+    if (options?.input) body.input = options.input;
+    if (options?.context) body.context = options.context;
+    const response = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey
+      },
+      body: JSON.stringify(body)
+    });
+    const data = await response.json();
+    if (!data.ok) {
+      const errorResult = data;
+      throw new EntryError(
+        errorResult.error.code,
+        errorResult.error.message,
+        errorResult.meta.requestId
+      );
+    }
+    const successResult = data;
+    return {
+      output: successResult.output,
+      meta: successResult.meta
+    };
+  }
+  /**
+   * Invoke a tool and return the raw response (including error responses)
+   * Use this if you want to handle errors yourself instead of catching exceptions
+   */
+  async invokeRaw(toolName, options) {
+    const url = `${this.baseUrl}/v1/invoke/${encodeURIComponent(toolName)}`;
+    const body = {};
+    if (options?.params) body.params = options.params;
+    if (options?.input) body.input = options.input;
+    if (options?.context) body.context = options.context;
+    const response = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey
+      },
+      body: JSON.stringify(body)
+    });
+    return await response.json();
+  }
+};
+var createClient = (options) => new Entry(options);
+var AgentGateway = Entry;
+var AgentGatewayError = EntryError;
+var ATGError = EntryError;
+var index_default = Entry;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ATGError,
+  AgentGateway,
+  AgentGatewayError,
+  Entry,
+  EntryError,
+  createClient
+});

package/dist/index.mjs

@@ -0,0 +1,119 @@
+// src/index.ts
+var EntryError = class extends Error {
+  code;
+  requestId;
+  constructor(code, message, requestId) {
+    super(message);
+    this.name = "EntryError";
+    this.code = code;
+    this.requestId = requestId;
+  }
+};
+var Entry = class {
+  baseUrl;
+  apiKey;
+  fetchFn;
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? (typeof process !== "undefined" ? process.env?.ENTRYS_API_KEY : void 0);
+    const baseUrl = options.baseUrl ?? (typeof process !== "undefined" ? process.env?.ENTRYS_BASE_URL : void 0) ?? "https://api.entrys.co";
+    if (!apiKey) {
+      throw new Error("Entry: apiKey is required. Pass it in options or set ENTRYS_API_KEY environment variable.");
+    }
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = apiKey;
+    this.fetchFn = options.fetch ?? fetch;
+  }
+  /**
+   * Invoke a registered tool through the gateway
+   * 
+   * @param toolName - The name of the tool to invoke (e.g., "get_customer")
+   * @param options - Parameters, input data, and context for the tool
+   * @returns The tool output (with PII automatically redacted)
+   * @throws {EntryError} If the tool invocation fails
+   * 
+   * @example
+   * ```typescript
+   * const customer = await agent.invoke("get_customer", {
+   *   params: { id: "123" }
+   * });
+   * ```
+   */
+  async invoke(toolName, options) {
+    const result = await this.invokeWithMeta(toolName, options);
+    return result.output;
+  }
+  /**
+   * Invoke a tool and return both output and metadata
+   * 
+   * @example
+   * ```typescript
+   * const { output, meta } = await agent.invokeWithMeta("get_customer", {
+   *   params: { id: "123" }
+   * });
+   * console.log(meta.redactions); // PII that was scrubbed
+   * ```
+   */
+  async invokeWithMeta(toolName, options) {
+    const url = `${this.baseUrl}/v1/invoke/${encodeURIComponent(toolName)}`;
+    const body = {};
+    if (options?.params) body.params = options.params;
+    if (options?.input) body.input = options.input;
+    if (options?.context) body.context = options.context;
+    const response = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey
+      },
+      body: JSON.stringify(body)
+    });
+    const data = await response.json();
+    if (!data.ok) {
+      const errorResult = data;
+      throw new EntryError(
+        errorResult.error.code,
+        errorResult.error.message,
+        errorResult.meta.requestId
+      );
+    }
+    const successResult = data;
+    return {
+      output: successResult.output,
+      meta: successResult.meta
+    };
+  }
+  /**
+   * Invoke a tool and return the raw response (including error responses)
+   * Use this if you want to handle errors yourself instead of catching exceptions
+   */
+  async invokeRaw(toolName, options) {
+    const url = `${this.baseUrl}/v1/invoke/${encodeURIComponent(toolName)}`;
+    const body = {};
+    if (options?.params) body.params = options.params;
+    if (options?.input) body.input = options.input;
+    if (options?.context) body.context = options.context;
+    const response = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey
+      },
+      body: JSON.stringify(body)
+    });
+    return await response.json();
+  }
+};
+var createClient = (options) => new Entry(options);
+var AgentGateway = Entry;
+var AgentGatewayError = EntryError;
+var ATGError = EntryError;
+var index_default = Entry;
+export {
+  ATGError,
+  AgentGateway,
+  AgentGatewayError,
+  Entry,
+  EntryError,
+  createClient,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@entrys/client",
+  "version": "0.1.0",
+  "description": "TypeScript client for Entrys - the entry point for agent tool calls",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "entrys",
+    "agent",
+    "ai",
+    "tool",
+    "gateway",
+    "sdk",
+    "llm",
+    "security"
+  ],
+  "author": "Treadie, Inc",
+  "license": "FSL-1.1-MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/treadiehq/entrys.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://entrys.co",
+  "bugs": {
+    "url": "https://github.com/treadiehq/entrys/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  }
+}