@zuora/agent-toolkit 0.0.1-alpha.0

package/dist/shared/resources/bundle-catalog.json

@@ -0,0 +1,289 @@
+{
+  "version": 1,
+  "bundles": {
+    "accounts": {
+      "description": "Customer accounts, contacts, billing profiles, and account summaries.",
+      "examples": [
+        "show account summary",
+        "find account by account number",
+        "update account contact",
+        "cancel customer account"
+      ],
+      "commonObjects": [
+        "Account",
+        "Contact",
+        "BillingProfile"
+      ],
+      "keywords": [
+        "account",
+        "customer",
+        "contact",
+        "billing profile",
+        "summary"
+      ]
+    },
+    "catalog": {
+      "description": "Products, plans, charges, tiers, pricing context, and commerce catalog setup.",
+      "examples": [
+        "show latest product",
+        "create product",
+        "update product charge",
+        "inspect pricing tiers"
+      ],
+      "commonObjects": [
+        "Product",
+        "Plan",
+        "Charge",
+        "Tier"
+      ],
+      "keywords": [
+        "product",
+        "catalog",
+        "plan",
+        "charge",
+        "price",
+        "tier"
+      ]
+    },
+    "subscriptions": {
+      "description": "Subscription lookup, previews, creation, changes, renewal, and cancellation.",
+      "examples": [
+        "show subscription",
+        "preview subscription change",
+        "create subscription",
+        "cancel subscription"
+      ],
+      "commonObjects": [
+        "Subscription",
+        "RatePlan",
+        "OrderAction"
+      ],
+      "keywords": [
+        "subscription",
+        "renewal",
+        "preview",
+        "amendment",
+        "cancel"
+      ]
+    },
+    "orders": {
+      "description": "Order preview and order lifecycle operations for subscription commerce changes.",
+      "examples": [
+        "preview order",
+        "create order",
+        "show order",
+        "cancel order"
+      ],
+      "commonObjects": [
+        "Order",
+        "OrderAction",
+        "OrderLineItem"
+      ],
+      "keywords": [
+        "order",
+        "order action",
+        "preview",
+        "subscription change"
+      ]
+    },
+    "billing": {
+      "description": "Invoices, bill runs, billing documents, credit memos, debit memos, and billing previews.",
+      "examples": [
+        "create bill run",
+        "check bill run status",
+        "show latest invoice",
+        "post bill run",
+        "generate billing documents"
+      ],
+      "commonObjects": [
+        "Invoice",
+        "BillRun",
+        "CreditMemo",
+        "DebitMemo",
+        "BillingPreview"
+      ],
+      "keywords": [
+        "invoice",
+        "bill run",
+        "billing",
+        "credit memo",
+        "debit memo",
+        "billing preview",
+        "pdf"
+      ]
+    },
+    "payments": {
+      "description": "Payments, payment runs, refunds, payment methods, and payment schedules.",
+      "examples": [
+        "show payment",
+        "refund payment",
+        "create payment run",
+        "inspect payment method"
+      ],
+      "commonObjects": [
+        "Payment",
+        "PaymentRun",
+        "Refund",
+        "PaymentMethod"
+      ],
+      "keywords": [
+        "payment",
+        "refund",
+        "payment method",
+        "payment run",
+        "settlement"
+      ]
+    },
+    "usage": {
+      "description": "Usage upload, usage query, chargeable events, and metered consumption operations.",
+      "examples": [
+        "upload usage",
+        "query usage records",
+        "inspect chargeable events"
+      ],
+      "commonObjects": [
+        "Usage",
+        "ChargeableEvent"
+      ],
+      "keywords": [
+        "usage",
+        "meter",
+        "consumption",
+        "chargeable event",
+        "upload"
+      ]
+    },
+    "revenue": {
+      "description": "Revenue reporting, journal runs, revenue schedules, and accounting recognition workflows.",
+      "examples": [
+        "show revenue schedule",
+        "run revenue report",
+        "check journal run status"
+      ],
+      "commonObjects": [
+        "RevenueSchedule",
+        "JournalRun",
+        "RevenueContract"
+      ],
+      "keywords": [
+        "revenue",
+        "journal",
+        "recognition",
+        "revenue schedule"
+      ]
+    },
+    "finance": {
+      "description": "Accounting periods, accounting codes, sequence sets, and finance configuration.",
+      "examples": [
+        "list accounting periods",
+        "close accounting period",
+        "show accounting code settings",
+        "update sequence set"
+      ],
+      "commonObjects": [
+        "AccountingPeriod",
+        "AccountingCode",
+        "SequenceSet"
+      ],
+      "keywords": [
+        "accounting",
+        "finance",
+        "period",
+        "sequence",
+        "trial balance"
+      ]
+    },
+    "workflows": {
+      "description": "Workflow discovery, execution, task status, and workflow monitoring.",
+      "examples": [
+        "list workflows",
+        "run workflow",
+        "check workflow task status"
+      ],
+      "commonObjects": [
+        "Workflow",
+        "WorkflowRun",
+        "WorkflowTask"
+      ],
+      "keywords": [
+        "workflow",
+        "task",
+        "automation",
+        "run",
+        "monitor"
+      ]
+    },
+    "query": {
+      "description": "Object Query, GraphQL Query, Data Query, metadata discovery, query jobs, and result retrieval.",
+      "examples": [
+        "manage_data_queries: query aggregations result like: how many active billing accounts",
+        "zuora_graphql__query: describe product object fields",
+        "zuora_graphql__query in sync mode: query nested subscription details",
+        "use query_objects for Object Query: simple object lookups, one primary object, small result sets, or object metadata and field discovery",
+        "use manage_data_queries: SQL-style reporting, joins, aggregations, or large read-only exports",
+        "use manage_data_queries for Data Query job status and result metadata",
+        "use download_query_result for completed Data Query result file downloads when a jobId is available",
+        "use zuora_graphql__query for nested related records in one response when the tenant exposes the needed graph schema",
+        "manage_data_queries: submit data query",
+        "manage_data_queries: check query job status"
+      ],
+      "commonObjects": [
+        "DataQueryJob",
+        "ObjectMetadata",
+        "QueryResult"
+      ],
+      "keywords": [
+        "query",
+        "data query",
+        "object",
+        "graphql",
+        "metadata",
+        "sql",
+        "job",
+        "result"
+      ]
+    },
+    "admin": {
+      "description": "Settings, custom fields, custom objects, feature configuration, and system health.",
+      "examples": [
+        "list custom fields",
+        "create custom object record",
+        "show tenant settings",
+        "check system health"
+      ],
+      "commonObjects": [
+        "CustomField",
+        "CustomObject",
+        "TenantSetting"
+      ],
+      "keywords": [
+        "admin",
+        "settings",
+        "custom field",
+        "custom object",
+        "tenant",
+        "health"
+      ]
+    },
+    "files": {
+      "description": "SDK-native file artifact downloads and bounded local artifact reads.",
+      "examples": [
+        "download data query result file",
+        "read downloaded file preview",
+        "inspect exported jsonl result"
+      ],
+      "commonObjects": [
+        "FileArtifact",
+        "DownloadedFile"
+      ],
+      "keywords": [
+        "file",
+        "download",
+        "artifact",
+        "jsonl",
+        "csv",
+        "result url"
+      ]
+    }
+  }
+}

package/dist/shared/toolkit-core.d.ts

@@ -0,0 +1,73 @@
+import { d as ZuoraToolkitEvent, e as ZuoraAgentToolkitConfig, f as ZuoraMcpClient, T as ToolSelection, Z as ZuoraToolDefinition, g as ZuoraBundleDefinition, h as ZuoraBundleName, b as ZuoraToolExecutionResult, c as ZuoraAsyncJobResult, i as ZuoraWaitForJobOptions } from '../async-jobs-Dd8Jafv0.js';
+
+type InternalToolkitEvent = Omit<ZuoraToolkitEvent, "type" | "timestamp"> & Partial<Pick<ZuoraToolkitEvent, "type" | "timestamp">>;
+
+declare abstract class ToolkitCore<T> {
+    protected readonly config: ZuoraAgentToolkitConfig;
+    protected mcpClient: ZuoraMcpClient;
+    private catalogTools;
+    private _initialized;
+    private readonly sanitizerLimits;
+    private readonly nativeFileArtifactTools;
+    private readonly nativeQueryResultDownloadTools;
+    private readonly nativeZuoraFileDownloadTools;
+    private readonly restClient;
+    private nativeToolRegistry;
+    constructor(config: ZuoraAgentToolkitConfig);
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    listTools(selection?: ToolSelection): Promise<ZuoraToolDefinition[]>;
+    /**
+     * Returns framework-native tool objects for the given selection.
+     *
+     * @param selection - Optional filter (bundles, mode) to narrow the catalog.
+     * @param maxTools - When provided and greater than zero, limits the result to
+     *   the first `maxTools` entries after filtering. Values ≤ 0 are treated as
+     *   no-limit. Does not affect `loadFollowUpTools()`, which always searches
+     *   the full catalog.
+     */
+    getTools(selection?: ToolSelection, maxTools?: number): Promise<T[]>;
+    listBundles(): Promise<ZuoraBundleDefinition[]>;
+    describeBundle(name: ZuoraBundleName): Promise<ZuoraBundleDefinition>;
+    describeTool(name: string): Promise<ZuoraToolDefinition | undefined>;
+    callTool(operationName: string, input: Record<string, unknown>): Promise<ZuoraToolExecutionResult>;
+    /**
+     * Polls an async job to completion using the polling operation specified in
+     * the async job result. Returns the final polling tool execution result when
+     * the job reaches a terminal state.
+     *
+     * Polling stops when:
+     * - A terminal status is matched (success, failure, or canceled)
+     * - The maximum number of poll attempts is exhausted
+     * - The absolute timeout is exceeded
+     *
+     * @param toolName - The name of the tool that started the async job. Used for
+     *   observability context only.
+     * @param asyncResult - The pending async job result from an initial tool call.
+     * @param options - Optional overrides for polling behavior.
+     * @throws ZuoraAgentToolkitError with ASYNC_JOB_TIMEOUT if the job does not
+     *   reach a terminal state within the configured limits.
+     */
+    waitForJob(toolName: string, asyncResult: ZuoraAsyncJobResult, options?: ZuoraWaitForJobOptions): Promise<ZuoraToolExecutionResult>;
+    protected abstract convertTools(tools: ZuoraToolDefinition[]): T[];
+    /**
+     * Returns the full normalized tool catalog after initialization.
+     *
+     * @internal For use by adapter subclasses only (e.g. to implement
+     * follow-up tool resolution against the full catalog). Do not call
+     * from outside the class hierarchy.
+     */
+    protected getNormalizedTools(): ZuoraToolDefinition[];
+    private resolveSplitOperations;
+    private warnIfNotInitialized;
+    protected emit(event: InternalToolkitEvent): void;
+    /**
+     * Fetches a Data Query job result to extract the dataFile download URL.
+     * Called by NativeQueryResultDownloadTools to resolve the presigned S3 URL
+     * for a completed query job before handing off to downloadFile.
+     */
+    private fetchQueryResultForDownload;
+    private createEventContext;
+}
+
+export { ToolkitCore };