@zuora/agent-toolkit 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,298 @@
+# @zuora/agent-toolkit
+
+> **Alpha release** — APIs may change before the 1.0 stable release.
+
+Zuora billing operations as callable tools for AI agent frameworks.
+
+Built on the [Zuora MCP server](https://developer.zuora.com). Tool inventory is discovered at runtime from your tenant's MCP endpoint — it is not hardcoded in this package.
+
+## Adapter status
+
+| Subpath | Factory | Status |
+|---|---|---|
+| `@zuora/agent-toolkit/openai` | `createZuoraOpenAIAgentToolkit` | ✅ Implemented |
+| `@zuora/agent-toolkit/openai-agents` | `createZuoraOpenAIAgentsToolkit` | ✅ Implemented |
+| `@zuora/agent-toolkit/langchain` | — | 🚧 Coming soon |
+| `@zuora/agent-toolkit/vercel-ai` | — | 🚧 Coming soon |
+| `@zuora/agent-toolkit/mcp` | — | 🚧 Coming soon |
+
+## Installation
+
+```bash
+npm install @zuora/agent-toolkit
+```
+
+Framework packages are peer dependencies — install only what you use:
+
+```bash
+# OpenAI Chat Completions
+npm install openai
+
+# OpenAI Agents SDK
+npm install @openai/agents
+```
+
+## Credentials
+
+The toolkit authenticates against Zuora using OAuth 2.0 client credentials. You need:
+
+- `ZUORA_BASE_URL` — your Zuora tenant REST API base URL (e.g. `https://rest.apisandbox.zuora.com`)
+- `ZUORA_CLIENT_ID` — OAuth client ID
+- `ZUORA_CLIENT_SECRET` — OAuth client secret
+
+**Use a client scoped to the minimum permissions your agent needs.** Never use admin credentials.
+
+## Usage
+
+### OpenAI Agents SDK
+
+```ts
+import { Agent, run } from "@openai/agents";
+import { createZuoraOpenAIAgentsToolkit } from "@zuora/agent-toolkit/openai-agents";
+
+const toolkit = await createZuoraOpenAIAgentsToolkit({
+  env: true,
+  configuration: { mode: "readOnly", bundles: { query: true } },
+});
+
+const tools = await toolkit.getTools({ bundles: ["query"] });
+const agent = new Agent({ name: "Billing Agent", tools });
+const result = await run(agent, "How many active billing accounts do we have?");
+
+await toolkit.close();
+```
+
+If you already have a Chat Completions toolkit, you can bridge it with `buildAgentsTools`:
+
+```ts
+import { buildAgentsTools } from "@zuora/agent-toolkit/openai-agents";
+import { createZuoraOpenAIAgentToolkit } from "@zuora/agent-toolkit/openai";
+import { tool } from "@openai/agents";
+
+const chatToolkit = await createZuoraOpenAIAgentToolkit({ env: true });
+const tools = await buildAgentsTools(tool, chatToolkit, { bundles: ["query"] });
+```
+
+### OpenAI Chat Completions
+
+```ts
+import OpenAI from "openai";
+import {
+  createZuoraOpenAIAgentToolkit,
+  handleToolCalls,
+} from "@zuora/agent-toolkit/openai";
+
+const toolkit = await createZuoraOpenAIAgentToolkit({
+  env: true,
+  configuration: { mode: "readOnly" },
+});
+
+const client = new OpenAI();
+const tools = await toolkit.getTools({ bundles: ["accounts", "query"] });
+const messages: OpenAI.ChatCompletionMessageParam[] = [
+  { role: "user", content: "List 3 active accounts" },
+];
+
+for (let step = 0; step < 20; step++) {
+  const response = await client.chat.completions.create({
+    model: "gpt-4o",
+    messages,
+    tools,
+  });
+
+  const choice = response.choices[0];
+  if (!choice) break;
+  messages.push(choice.message);
+
+  if (choice.finish_reason === "tool_calls") {
+    const { messages: toolMessages } = await handleToolCalls({ toolkit, response });
+    messages.push(...toolMessages);
+    continue;
+  }
+
+  console.log(choice.message.content);
+  break;
+}
+
+await toolkit.close();
+```
+
+## Configuration
+
+### Safety modes
+
+```ts
+configuration: {
+  mode: "readOnly",      // only read operations (default)
+  // or
+  mode: "writeEnabled",  // read + write operations
+}
+```
+
+### Tool bundles
+
+Select groups of tools by Zuora domain:
+
+```ts
+configuration: {
+  bundles: {
+    accounts: true,
+    subscriptions: true,
+    query: true,
+  },
+}
+```
+
+Available bundles: `accounts`, `catalog`, `subscriptions`, `orders`, `billing`, `payments`, `usage`, `revenue`, `finance`, `workflows`, `query`, `admin`, `files`.
+
+You can also filter at call time via `getTools({ bundles, include, exclude, mode })`.
+
+### Exclude / include specific tools
+
+```ts
+configuration: {
+  bundles: {
+    billing: {
+      exclude: ["create_invoice", "delete_invoice"],
+      // or include: ["list_invoices"]
+    },
+  },
+}
+```
+
+### Split operations
+
+Multi-operation MCP tools are split into per-operation tools by default (`splitOperations: true`), producing names like `manage_data_queries__submit_query`. Set `splitOperations: false` to keep merged tools.
+
+### Approval policy
+
+Gate write / high-risk operations before they reach Zuora. `approvalPolicy` is a **top-level** config field (not inside `configuration`):
+
+```ts
+import { ApprovalPolicyPreset } from "@zuora/agent-toolkit";
+
+const toolkit = await createZuoraOpenAIAgentToolkit({
+  env: true,
+  configuration: { mode: "writeEnabled" },
+  approvalPolicy: ApprovalPolicyPreset.HighRisk,
+  // or a custom handler:
+  // approvalPolicy: async (request) => {
+  //   if (request.tool.meta.riskLevel === "high") return "deny";
+  //   return "not_required";
+  // },
+});
+```
+
+Presets: `Off`, `AllWrites`, `HighRisk`, `ProductionWrites`, `ProductionHighRisk`.
+
+### Context defaults
+
+Pass optional string context keys (for example tenant or entity identifiers) via `configuration.context`. Connection-level `entityIds` / `orgIds` arrays live on `connection` instead:
+
+```ts
+configuration: {
+  context: {
+    tenantId: "…",
+  },
+},
+connection: {
+  entityIds: ["entity-1"],
+  orgIds: ["org-1"],
+},
+```
+
+### Observability
+
+```ts
+observability: {
+  onEvent: (event) => { /* tool.called, tool.completed, approval.*, … */ },
+  logger: { info: console.info, warn: console.warn, error: console.error },
+  includePayloads: false, // default; set true to include sanitized I/O
+}
+```
+
+## Environment variable config
+
+Pass `env: true` to read credentials from the environment automatically:
+
+```ts
+const toolkit = await createZuoraOpenAIAgentToolkit({
+  env: true,
+  configuration: { mode: "readOnly" },
+});
+```
+
+| Variable | Purpose |
+|---|---|
+| `ZUORA_BASE_URL` or `ZUORA_MCP_URL` | Endpoint (required) |
+| `ZUORA_CLIENT_ID` / `ZUORA_CLIENT_SECRET` | OAuth credentials |
+| `ZUORA_TOOLKIT_MODE` | `readOnly` (default) or `writeEnabled` |
+
+You can still pass `baseUrl` + `auth` explicitly instead of `env: true`.
+
+## Lifecycle
+
+Always call `close()` when done:
+
+```ts
+const toolkit = await createZuoraOpenAIAgentToolkit({ env: true });
+try {
+  // use toolkit
+} finally {
+  await toolkit.close();
+}
+```
+
+## Discovery and execution
+
+```ts
+const tools = await toolkit.listTools();           // ZuoraToolDefinition[]
+const def = await toolkit.describeTool("get_account");
+const bundles = await toolkit.listBundles();
+const bundle = await toolkit.describeBundle("subscriptions");
+
+const result = await toolkit.callTool("get_account", { accountKey: "…" });
+// For async tools: await toolkit.waitForJob(toolName, asyncResult, options?)
+```
+
+## Native query / file tools
+
+When the `query` bundle is enabled, the SDK may expose local helpers such as `download_query_result` and `read_downloaded_file` so agents can fetch and preview Data Query artifacts. Artifacts default to `~/.zuora-agent-artifacts`.
+
+## Errors
+
+All SDK errors are `ZuoraAgentToolkitError` with a typed `code`:
+
+| Code | Meaning |
+|---|---|
+| `OAUTH_TOKEN_ERROR` | Authentication or token refresh failed |
+| `TOOL_EXECUTION_ERROR` | MCP tool call failed |
+| `TOOL_NOT_FOUND` | Unknown tool name |
+| `BUNDLE_NOT_FOUND` | Unknown bundle name |
+| `APPROVAL_REJECTED` | Approval policy rejected the operation |
+| `MALFORMED_METADATA` | Server returned incomplete or invalid tool metadata |
+| `ASYNC_JOB_TIMEOUT` | Async job polling timed out |
+
+```ts
+import { ZuoraAgentToolkitError } from "@zuora/agent-toolkit";
+
+try {
+  await handleToolCalls({ toolkit, response });
+} catch (err) {
+  if (err instanceof ZuoraAgentToolkitError && err.code === "APPROVAL_REJECTED") {
+    // handle rejection
+  }
+}
+```
+
+## Examples
+
+Working examples are available in the source repository:
+
+| Example | Description |
+|---|---|
+| `examples/openai/index.ts` | Minimal Chat Completions agent loop |
+| `examples/openai/advanced.ts` | Observability, hooks, async jobs, discovery |
+| `examples/openai/hitl.ts` | Human-in-the-loop via `shouldExecute` |
+| `examples/openai-agents/index.ts` | OpenAI Agents SDK agent |
+| `examples/openai-agents-cli/` | Interactive CLI agent + planner |