@armor/zuora-mcp 1.0.1

package/.env.example

@@ -0,0 +1,16 @@
+# Zuora OAuth Configuration
+# Required: OAuth2 Client ID (create at Zuora Admin > Settings > Administration > OAuth Clients)
+ZUORA_CLIENT_ID=your-oauth-client-id
+
+# Required: OAuth2 Client Secret
+ZUORA_CLIENT_SECRET=your-oauth-client-secret
+
+# Required: Zuora base URL for your environment
+# Production US:  https://rest.zuora.com
+# Sandbox US:     https://rest.apisandbox.zuora.com
+# Production EU:  https://rest.eu.zuora.com
+# Sandbox EU:     https://rest.sandbox.eu.zuora.com
+ZUORA_BASE_URL=https://rest.apisandbox.zuora.com
+
+# Optional: Enable debug logging (true/false)
+DEBUG=false

package/README.md

@@ -0,0 +1,246 @@
+# Zuora MCP Server
+
+A Model Context Protocol (MCP) server that enables Claude to interact with Zuora's billing platform. Query accounts, invoices, subscriptions, payments, and execute ZOQL queries directly from Claude Code.
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20+
+- Zuora OAuth credentials (create at Zuora Admin > Settings > Administration > OAuth Clients)
+- npm access to the `@armor` scope (see [npm Setup](#npm-setup))
+
+### Install from npm (Recommended)
+
+```bash
+npm install -g @armor/zuora-mcp
+```
+
+Then add to your Claude Code MCP config (`~/.claude/.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "zuora": {
+      "command": "zuora-mcp",
+      "env": {
+        "ZUORA_CLIENT_ID": "your-client-id",
+        "ZUORA_CLIENT_SECRET": "your-client-secret",
+        "ZUORA_BASE_URL": "https://rest.apisandbox.zuora.com"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code and the Zuora tools will be available.
+
+### npm Setup
+
+One-time setup to access the `@armor` npm scope:
+
+```bash
+# Get your npm access token from the team lead or npm admin
+echo "//registry.npmjs.org/:_authToken=<YOUR_NPM_TOKEN>" >> ~/.npmrc
+```
+
+### Install from Source (Alternative)
+
+```bash
+git clone git@github.com:armor/zuora-mcp.git
+cd zuora-mcp
+npm install
+npm run build
+```
+
+When installing from source, point to the built file in your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "zuora": {
+      "command": "node",
+      "args": ["/path/to/zuora-mcp/dist/index.js"],
+      "env": {
+        "ZUORA_CLIENT_ID": "your-client-id",
+        "ZUORA_CLIENT_SECRET": "your-client-secret",
+        "ZUORA_BASE_URL": "https://rest.apisandbox.zuora.com"
+      }
+    }
+  }
+}
+```
+
+### Configuration
+
+Required environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `ZUORA_CLIENT_ID` | OAuth2 client ID |
+| `ZUORA_CLIENT_SECRET` | OAuth2 client secret |
+| `ZUORA_BASE_URL` | One of the Zuora base URLs (see below) |
+
+Optional variables:
+
+| Variable | Description |
+|----------|-------------|
+| `DEBUG` | Set to `true` for verbose logging |
+
+#### Zuora Base URLs
+
+| Environment | URL |
+|-------------|-----|
+| US Production | `https://rest.zuora.com` |
+| US Sandbox | `https://rest.apisandbox.zuora.com` |
+| EU Production | `https://rest.eu.zuora.com` |
+| EU Sandbox | `https://rest.sandbox.eu.zuora.com` |
+
+### Getting Zuora OAuth Credentials
+
+1. Log into Zuora (production or sandbox)
+2. Navigate to **Settings > Administration > Manage Users**
+3. Select your user or create a service account
+4. Go to **OAuth Clients** tab and create a new client
+5. Copy the **Client ID** and **Client Secret** (secret is shown only once)
+
+## Available Tools
+
+### Account Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_account` | Get account details by key (ID or account number) |
+| `get_account_summary` | Get comprehensive account summary with balances, subscriptions, invoices, and payments |
+
+### Invoice Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_invoice` | Get invoice details including line items |
+| `list_invoices` | List invoices for an account with pagination |
+
+### Subscription Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_subscription` | Get subscription details with rate plans and charges |
+| `list_subscriptions` | List all subscriptions for an account |
+
+### Payment Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_payment` | Get payment details |
+| `list_payments` | List payments with optional account filter and pagination |
+
+### ZOQL Query Tools
+
+| Tool | Description |
+|------|-------------|
+| `execute_zoql_query` | Execute a ZOQL query for ad-hoc data retrieval |
+| `continue_zoql_query` | Continue paginated ZOQL results using queryLocator |
+
+### Product Catalog
+
+| Tool | Description |
+|------|-------------|
+| `list_products` | List products with rate plans and pricing |
+
+## Upgrading
+
+```bash
+npm update -g @armor/zuora-mcp
+```
+
+## Development
+
+```bash
+npm run dev        # Run with tsx (no build required)
+npm run build      # Build TypeScript to dist/
+npm run lint       # Run ESLint
+npm run typecheck  # Type check without building
+npm test           # Build and run tests
+npm run clean      # Remove dist/
+```
+
+### Debug Mode
+
+Set `DEBUG=true` to enable verbose logging to stderr:
+
+```bash
+DEBUG=true npm start
+```
+
+Debug output goes to stderr to avoid corrupting the stdio JSON-RPC transport.
+
+### Release Process
+
+This project uses semantic-release with branch-based publishing:
+
+| Branch | npm Tag | Description |
+|--------|---------|-------------|
+| `dev` | `alpha` | Development pre-releases |
+| `stage` | `beta` | Staging pre-releases |
+| `main` | `latest` | Production releases |
+
+Merging to any of these branches triggers the CD pipeline which:
+1. Runs lint, typecheck, build, and tests
+2. Determines the next version from commit messages
+3. Creates a GitHub release with notes
+4. Publishes to npm with the appropriate tag
+
+#### Commit Convention
+
+Follow conventional commits for automatic version bumps:
+
+| Prefix | Version Bump |
+|--------|--------------|
+| `feat:` | Minor (1.x.0) |
+| `fix:` | Patch (1.0.x) |
+| `breaking:` | Major (x.0.0) |
+
+## Architecture
+
+```
+src/
+├── index.ts            # MCP server entry point
+├── config.ts           # Zod-validated environment configuration
+├── token-manager.ts    # OAuth2 token lifecycle (refresh, coalescing)
+├── zuora-client.ts     # Zuora REST API client with resilience
+├── tools.ts            # Tool definitions, Zod schemas, handlers
+└── types.ts            # TypeScript interfaces
+```
+
+### Authentication
+
+Uses OAuth 2.0 Client Credentials flow:
+- Tokens are stored in memory only (not persisted)
+- Proactive refresh 60 seconds before expiry
+- Promise coalescing prevents duplicate refresh requests under concurrency
+- Automatic 401 retry with token refresh
+
+### Resilience
+
+- Exponential backoff with jitter on 429/502/503/504
+- Idempotent methods (GET, PUT, DELETE) retry on transport failures
+- POST requests are NOT retried on HTTP errors (financial safety)
+- 20-second request timeout with AbortController
+
+### Security
+
+- All inputs validated with Zod schemas
+- Sensitive fields (card numbers, bank accounts) redacted from debug logs
+- Bearer tokens scrubbed from error messages
+- OAuth credentials never logged
+- Base URL validated against known Zuora endpoints at startup
+
+## Version History
+
+### v1.0.0
+
+- Initial release with 11 read-only tools
+- OAuth 2.0 authentication with token lifecycle management
+- Account, invoice, subscription, payment, and ZOQL query support
+- Product catalog access
+- Resilient HTTP client with retry and backoff

package/dist/config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Configuration management for Zuora MCP Server
+ * Security-first: No hardcoded values, all from environment
+ */
+import { z } from "zod";
+declare const configSchema: z.ZodObject<{
+    zuoraClientId: z.ZodString;
+    zuoraClientSecret: z.ZodString;
+    zuoraBaseUrl: z.ZodEffects<z.ZodString, string, string>;
+    debug: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    zuoraClientId: string;
+    zuoraClientSecret: string;
+    zuoraBaseUrl: string;
+    debug: boolean;
+}, {
+    zuoraClientId: string;
+    zuoraClientSecret: string;
+    zuoraBaseUrl: string;
+    debug?: boolean | undefined;
+}>;
+export type Config = z.infer<typeof configSchema>;
+export declare function loadConfig(): Config;
+export declare function validateConfig(): void;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;EAoBhB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,wBAAgB,UAAU,IAAI,MAAM,CAkBnC;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/config.js

@@ -0,0 +1,56 @@
+/**
+ * Configuration management for Zuora MCP Server
+ * Security-first: No hardcoded values, all from environment
+ */
+import { config as dotenvConfig } from "dotenv";
+import { z } from "zod";
+// Load .env files with quiet mode to prevent stdout corruption of JSON-RPC.
+// Precedence: process env > .env.local > .env
+// Base .env does NOT use override so process-level env vars take precedence.
+// .env.local uses override so it can override both .env and process env for local dev.
+dotenvConfig({ path: ".env", quiet: true });
+dotenvConfig({ path: ".env.local", override: true, quiet: true });
+const VALID_ZUORA_BASE_URLS = new Set([
+    "https://rest.zuora.com",
+    "https://rest.apisandbox.zuora.com",
+    "https://rest.eu.zuora.com",
+    "https://rest.sandbox.eu.zuora.com",
+]);
+const configSchema = z.object({
+    zuoraClientId: z
+        .string()
+        .min(1, "ZUORA_CLIENT_ID is required")
+        .describe("OAuth2 client ID from Zuora Admin"),
+    zuoraClientSecret: z
+        .string()
+        .min(1, "ZUORA_CLIENT_SECRET is required")
+        .describe("OAuth2 client secret"),
+    zuoraBaseUrl: z
+        .string()
+        .url("ZUORA_BASE_URL must be a valid URL")
+        .refine((url) => VALID_ZUORA_BASE_URLS.has(url.replace(/\/$/, "")), {
+        message: `ZUORA_BASE_URL must be one of: ${[...VALID_ZUORA_BASE_URLS].join(", ")}`,
+    })
+        .describe("Zuora REST API base URL"),
+    debug: z.boolean().default(false).describe("Enable debug logging"),
+});
+export function loadConfig() {
+    const rawConfig = {
+        zuoraClientId: process.env.ZUORA_CLIENT_ID,
+        zuoraClientSecret: process.env.ZUORA_CLIENT_SECRET,
+        zuoraBaseUrl: process.env.ZUORA_BASE_URL?.replace(/\/$/, ""),
+        debug: process.env.DEBUG === "true",
+    };
+    const result = configSchema.safeParse(rawConfig);
+    if (!result.success) {
+        const errors = result.error.errors
+            .map((e) => `  - ${e.path.join(".")}: ${e.message}`)
+            .join("\n");
+        throw new Error(`Configuration validation failed:\n${errors}`);
+    }
+    return result.data;
+}
+export function validateConfig() {
+    loadConfig();
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,4EAA4E;AAC5E,8CAA8C;AAC9C,6EAA6E;AAC7E,uFAAuF;AACvF,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAC5C,YAAY,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAElE,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,wBAAwB;IACxB,mCAAmC;IACnC,2BAA2B;IAC3B,mCAAmC;CACpC,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,6BAA6B,CAAC;SACrC,QAAQ,CAAC,mCAAmC,CAAC;IAChD,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,iCAAiC,CAAC;SACzC,QAAQ,CAAC,sBAAsB,CAAC;IACnC,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,GAAG,CAAC,oCAAoC,CAAC;SACzC,MAAM,CACL,CAAC,GAAG,EAAE,EAAE,CAAC,qBAAqB,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAC1D;QACE,OAAO,EAAE,kCAAkC,CAAC,GAAG,qBAAqB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;KACnF,CACF;SACA,QAAQ,CAAC,yBAAyB,CAAC;IACtC,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC;CACnE,CAAC,CAAC;AAIH,MAAM,UAAU,UAAU;IACxB,MAAM,SAAS,GAAG;QAChB,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe;QAC1C,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB;QAClD,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QAC5D,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,MAAM;KACpC,CAAC;IAEF,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAEjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACnD,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,qCAAqC,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,UAAU,EAAE,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Zuora MCP Server
+ *
+ * A Model Context Protocol server for Zuora billing operations.
+ * Provides account, invoice, subscription, payment, and ZOQL query tools.
+ *
+ * Features:
+ * - OAuth 2.0 authentication with automatic token lifecycle
+ * - Account and billing entity read operations
+ * - ZOQL query support with pagination
+ * - Product catalog access
+ * - Resilient HTTP client with retry and backoff
+ *
+ * Security:
+ * - No hardcoded credentials
+ * - Input validation with Zod schemas
+ * - Sensitive data redaction in logs
+ * - OAuth token promise coalescing for concurrency safety
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Zuora MCP Server
+ *
+ * A Model Context Protocol server for Zuora billing operations.
+ * Provides account, invoice, subscription, payment, and ZOQL query tools.
+ *
+ * Features:
+ * - OAuth 2.0 authentication with automatic token lifecycle
+ * - Account and billing entity read operations
+ * - ZOQL query support with pagination
+ * - Product catalog access
+ * - Resilient HTTP client with retry and backoff
+ *
+ * Security:
+ * - No hardcoded credentials
+ * - Input validation with Zod schemas
+ * - Sensitive data redaction in logs
+ * - OAuth token promise coalescing for concurrency safety
+ */
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { loadConfig } from "./config.js";
+import { ZuoraClient } from "./zuora-client.js";
+import { toolRegistrations, ToolHandlers } from "./tools.js";
+const SERVER_NAME = "zuora-mcp";
+function getServerVersion() {
+    try {
+        const packageJsonPath = new URL("../package.json", import.meta.url);
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        if (typeof packageJson.version === "string" &&
+            packageJson.version.length) {
+            return packageJson.version;
+        }
+    }
+    catch {
+        // Fall through to safe default.
+    }
+    return "0.0.0";
+}
+function toCallToolResult(result) {
+    const structuredContent = {
+        success: result.success,
+        message: result.message,
+    };
+    if (result.data !== undefined) {
+        structuredContent.data = result.data;
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(structuredContent, null, 2),
+            },
+        ],
+        structuredContent,
+        isError: !result.success,
+    };
+}
+async function main() {
+    // Validate configuration before starting
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (error) {
+        console.error("Configuration error:", error instanceof Error ? error.message : error);
+        console.error("\nRequired environment variables:");
+        console.error("  ZUORA_CLIENT_ID     - OAuth2 client ID from Zuora Admin");
+        console.error("  ZUORA_CLIENT_SECRET - OAuth2 client secret");
+        console.error("  ZUORA_BASE_URL      - Zuora API base URL (e.g., https://rest.test.zuora.com)");
+        console.error("\nOptional:");
+        console.error("  DEBUG=true          - Enable debug logging");
+        process.exit(1);
+    }
+    const client = new ZuoraClient(config);
+    const handlers = new ToolHandlers(client);
+    // Create MCP server
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: getServerVersion(),
+    });
+    // Register tools for MCP capability advertisement (tool listing).
+    // Dispatch is handled by the setRequestHandler override below.
+    for (const registration of toolRegistrations) {
+        server.registerTool(registration.name, {
+            description: registration.description,
+            inputSchema: registration.inputSchema,
+        }, async (args) => {
+            // Stub: actual dispatch is handled by setRequestHandler below.
+            const result = await registration.invoke(handlers, args);
+            return toCallToolResult(result);
+        });
+    }
+    // Map-based dispatch with protocol-level error handling.
+    // This overrides the SDK's default CallToolRequest handler to provide
+    // proper McpError responses for unknown tools and invalid parameters.
+    const registrationByName = new Map(toolRegistrations.map((registration) => [
+        registration.name,
+        registration,
+    ]));
+    server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const registration = registrationByName.get(name);
+        if (!registration) {
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+        if (config.debug) {
+            console.error(`[${SERVER_NAME}] Tool called: ${registration.name}`, args);
+        }
+        let validatedArgs;
+        try {
+            validatedArgs = registration.inputSchema.parse(args);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for ${registration.name}: ${message}`);
+        }
+        try {
+            const result = await registration.invoke(handlers, validatedArgs);
+            return toCallToolResult(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toCallToolResult({
+                success: false,
+                message: `Unhandled tool error: ${message}`,
+            });
+        }
+    });
+    // Connect via stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    if (config.debug) {
+        console.error(`[${SERVER_NAME}] Server started successfully`);
+        console.error(`[${SERVER_NAME}] Connected to ${config.zuoraBaseUrl}`);
+        console.error(`[${SERVER_NAME}] Tools registered: ${toolRegistrations.length}`);
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG7D,MAAM,WAAW,GAAG,WAAW,CAAC;AAEhC,SAAS,gBAAgB;IACvB,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CACb,CAAC;QAC3B,IACE,OAAO,WAAW,CAAC,OAAO,KAAK,QAAQ;YACvC,WAAW,CAAC,OAAO,CAAC,MAAM,EAC1B,CAAC;YACD,OAAO,WAAW,CAAC,OAAO,CAAC;QAC7B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAkB;IAK1C,MAAM,iBAAiB,GAA4B;QACjD,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,iBAAiB,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IACvC,CAAC;IAED,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;aACjD;SACF;QACD,iBAAiB;QACjB,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,yCAAyC;IACzC,IAAI,MAAqC,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,GAAG,UAAU,EAAE,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CACX,sBAAsB,EACtB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAC/C,CAAC;QACF,OAAO,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACnD,OAAO,CAAC,KAAK,CACX,2DAA2D,CAC5D,CAAC;QACF,OAAO,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAC9D,OAAO,CAAC,KAAK,CACX,gFAAgF,CACjF,CAAC;QACF,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC7B,OAAO,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IAE1C,oBAAoB;IACpB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,gBAAgB,EAAE;KAC5B,CAAC,CAAC;IAEH,kEAAkE;IAClE,+DAA+D;IAC/D,KAAK,MAAM,YAAY,IAAI,iBAAiB,EAAE,CAAC;QAC7C,MAAM,CAAC,YAAY,CACjB,YAAY,CAAC,IAAI,EACjB;YACE,WAAW,EAAE,YAAY,CAAC,WAAW;YACrC,WAAW,EAAE,YAAY,CAAC,WAAW;SACtC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,+DAA+D;YAC/D,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACzD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC,CACF,CAAC;IACJ,CAAC;IAED,yDAAyD;IACzD,sEAAsE;IACtE,sEAAsE;IACtE,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAChC,iBAAiB,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC;QACtC,YAAY,CAAC,IAAI;QACjB,YAAY;KACb,CAAC,CACH,CAAC;IAEF,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAC7B,qBAAqB,EACrB,KAAK,EAAE,OAAO,EAAE,EAAE;QAChB,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;QACjD,MAAM,YAAY,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAElD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,cAAc,EACxB,iBAAiB,IAAI,EAAE,CACxB,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,CAAC,KAAK,CACX,IAAI,WAAW,kBAAkB,YAAY,CAAC,IAAI,EAAE,EACpD,IAAI,CACL,CAAC;QACJ,CAAC;QAED,IAAI,aAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,aAAa,GAAG,YAAY,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,aAAa,EACvB,yBAAyB,YAAY,CAAC,IAAI,KAAK,OAAO,EAAE,CACzD,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,CACtC,QAAQ,EACR,aAAa,CACd,CAAC;YACF,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,OAAO,gBAAgB,CAAC;gBACtB,OAAO,EAAE,KAAK;gBACd,OAAO,EAAE,yBAAyB,OAAO,EAAE;aAC5C,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CACF,CAAC;IAEF,8BAA8B;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,KAAK,CAAC,IAAI,WAAW,+BAA+B,CAAC,CAAC;QAC9D,OAAO,CAAC,KAAK,CACX,IAAI,WAAW,kBAAkB,MAAM,CAAC,YAAY,EAAE,CACvD,CAAC;QACF,OAAO,CAAC,KAAK,CACX,IAAI,WAAW,uBAAuB,iBAAiB,CAAC,MAAM,EAAE,CACjE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/token-manager.d.ts

@@ -0,0 +1,34 @@
+/**
+ * OAuth 2.0 Token Manager for Zuora API
+ *
+ * Handles token lifecycle with:
+ * - Proactive refresh before expiry (60s buffer)
+ * - Promise coalescing for concurrent refresh requests
+ * - Clean error propagation on auth failures
+ */
+import type { Config } from "./config.js";
+export declare class TokenManager {
+    private static readonly EXPIRY_BUFFER_MS;
+    private static readonly TOKEN_REQUEST_TIMEOUT_MS;
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly tokenUrl;
+    private readonly debug;
+    private tokenData;
+    private refreshPromise;
+    constructor(config: Config);
+    private log;
+    /**
+     * Get a valid access token. Refreshes proactively before expiry.
+     * Concurrent callers coalesce onto a single refresh request.
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Force a token refresh. Called when a 401 is received mid-session,
+     * indicating the token expired between the validity check and the API call.
+     */
+    forceRefresh(): Promise<string>;
+    private isTokenValid;
+    private fetchNewToken;
+}
+//# sourceMappingURL=token-manager.d.ts.map

package/dist/token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../src/token-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAQ1C,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAU;IAE1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAEhC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,cAAc,CAAgC;gBAE1C,MAAM,EAAE,MAAM;IAO1B,OAAO,CAAC,GAAG;IAMX;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBvC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAKrC,OAAO,CAAC,YAAY;YAON,aAAa;CAsD5B"}

package/dist/token-manager.js

@@ -0,0 +1,103 @@
+/**
+ * OAuth 2.0 Token Manager for Zuora API
+ *
+ * Handles token lifecycle with:
+ * - Proactive refresh before expiry (60s buffer)
+ * - Promise coalescing for concurrent refresh requests
+ * - Clean error propagation on auth failures
+ */
+export class TokenManager {
+    static EXPIRY_BUFFER_MS = 60_000;
+    static TOKEN_REQUEST_TIMEOUT_MS = 10_000;
+    clientId;
+    clientSecret;
+    tokenUrl;
+    debug;
+    tokenData = null;
+    refreshPromise = null;
+    constructor(config) {
+        this.clientId = config.zuoraClientId;
+        this.clientSecret = config.zuoraClientSecret;
+        this.tokenUrl = `${config.zuoraBaseUrl}/oauth/token`;
+        this.debug = config.debug;
+    }
+    log(message) {
+        if (this.debug) {
+            console.error(`[TokenManager] ${message}`);
+        }
+    }
+    /**
+     * Get a valid access token. Refreshes proactively before expiry.
+     * Concurrent callers coalesce onto a single refresh request.
+     */
+    async getAccessToken() {
+        if (this.isTokenValid()) {
+            return this.tokenData.accessToken;
+        }
+        // Coalesce concurrent refresh calls into one network request
+        if (!this.refreshPromise) {
+            this.log("Token expired or missing, fetching new token");
+            this.refreshPromise = this.fetchNewToken().finally(() => {
+                this.refreshPromise = null;
+            });
+        }
+        else {
+            this.log("Awaiting in-flight token refresh");
+        }
+        return this.refreshPromise;
+    }
+    /**
+     * Force a token refresh. Called when a 401 is received mid-session,
+     * indicating the token expired between the validity check and the API call.
+     */
+    async forceRefresh() {
+        this.tokenData = null;
+        return this.getAccessToken();
+    }
+    isTokenValid() {
+        return (this.tokenData !== null &&
+            Date.now() < this.tokenData.expiresAt - TokenManager.EXPIRY_BUFFER_MS);
+    }
+    async fetchNewToken() {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), TokenManager.TOKEN_REQUEST_TIMEOUT_MS);
+        try {
+            const response = await fetch(this.tokenUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: new URLSearchParams({
+                    client_id: this.clientId,
+                    client_secret: this.clientSecret,
+                    grant_type: "client_credentials",
+                }).toString(),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "unknown");
+                throw new Error(`OAuth token request failed (${response.status}): ${errorText}`);
+            }
+            const data = (await response.json());
+            this.tokenData = {
+                accessToken: data.access_token,
+                expiresAt: Date.now() + data.expires_in * 1000,
+            };
+            this.log(`Token acquired, expires in ${data.expires_in}s (scope: ${data.scope})`);
+            return this.tokenData.accessToken;
+        }
+        catch (error) {
+            // Scrub credentials from any error messages using global regex
+            const message = error instanceof Error ? error.message : String(error);
+            const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const sanitized = message
+                .replace(new RegExp(escapeRegex(this.clientId), "g"), "[CLIENT_ID]")
+                .replace(new RegExp(escapeRegex(this.clientSecret), "g"), "[CLIENT_SECRET]");
+            throw new Error(`Token acquisition failed: ${sanitized}`);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+//# sourceMappingURL=token-manager.js.map