@zuora/agent-toolkit 0.0.1-alpha.0

package/dist/async-jobs-Dd8Jafv0.d.ts

@@ -0,0 +1,532 @@
+type McpTool = {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+    outputSchema?: JsonSchema;
+    _meta?: Record<string, unknown>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+        title?: string;
+    };
+};
+type McpResourceContent = {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+};
+type McpReadResourceResult = {
+    contents: McpResourceContent[];
+};
+
+type EventSanitizerLimits = {
+    maxDepth: number;
+    maxArrayLength: number;
+    maxObjectKeys: number;
+    maxStringLength: number;
+};
+
+type ZuoraEnvironment = "sandbox" | "production";
+type ZuoraSafetyMode = "readOnly" | "writeEnabled";
+type ZuoraToolOperation = "read" | "write";
+type ZuoraRiskLevel = "low" | "medium" | "high";
+/**
+ * Well-known Zuora bundle names. Provided for autocompletion in
+ * `ToolSelection.bundles` and `ZuoraToolkitConfiguration.bundles`.
+ *
+ * The `string & {}` tail widens the type to accept any string (so new
+ * server-side bundles are never rejected) while preserving IDE autocomplete
+ * for the known literal members.
+ *
+ * `ZuoraToolDefinition.meta.bundle` is plain `string` — the server value
+ * is passed through as-is with no normalisation or fallback.
+ */
+type ZuoraBundleName = "accounts" | "catalog" | "subscriptions" | "orders" | "billing" | "payments" | "usage" | "revenue" | "finance" | "workflows" | "query" | "admin" | (string & {});
+type ZuoraAsyncOperationMeta = {
+    /** Operation on the polling MCP tool. Omitted when pollingTool is the standalone poll target. */
+    pollingOperation?: string;
+    /** Source MCP tool for cross-tool polling, or standalone poll tool when pollingOperation is omitted. */
+    pollingTool?: string;
+    jobIdPath: string;
+    statusPath: string;
+    pollingArgs?: Record<string, string>;
+    terminalStatuses: {
+        success: string[];
+        failure: string[];
+        canceled?: string[];
+    };
+    recommendedPollIntervalMs?: number;
+    defaultTimeoutMs?: number;
+    maxPollAttempts?: number;
+};
+type ZuoraServicePermission = {
+    scope: string;
+    name: string;
+};
+type ZuoraToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    meta: {
+        bundle: string;
+        access: ZuoraToolOperation;
+        riskLevel: ZuoraRiskLevel;
+        asyncOperation?: ZuoraAsyncOperationMeta;
+        /** Present on multi-op merged tools (splitOperations: false). Keyed by operation name. Used at
+         *  call time to look up the async meta for the operation the LLM actually invoked. */
+        asyncOperations?: Record<string, ZuoraAsyncOperationMeta>;
+        /** Per-operation access levels for merged tools. Used at call time to enforce the correct access for the invoked operation. */
+        operationAccess?: Record<string, ZuoraToolOperation>;
+        /** Per-operation risk levels for merged tools. Used at call time to enforce the correct risk for the invoked operation. */
+        operationRiskLevel?: Record<string, ZuoraRiskLevel>;
+        requiredServicePermissions: ZuoraServicePermission[];
+        limitations: string[];
+        sourceName: string;
+        /** Present on split multi-operation tools — MCP input field auto-injected at call time. */
+        operationSelector?: string;
+        /** Present on split multi-operation tools — the underlying MCP operation name. */
+        operationName?: string;
+    };
+};
+type NativeToolMetadataConfig = {
+    enabled?: boolean;
+    operationAccess?: ZuoraToolOperation;
+    riskLevel?: ZuoraRiskLevel;
+    description?: string;
+};
+type NativeFileToolsConfig = {
+    enabled?: boolean;
+    bundleName?: string;
+    tools?: {
+        downloadFile?: NativeToolMetadataConfig;
+        readDownloadedFile?: NativeToolMetadataConfig;
+        downloadQueryResult?: NativeToolMetadataConfig;
+        downloadZuoraFile?: NativeToolMetadataConfig;
+        extractDownloadedArchive?: NativeToolMetadataConfig;
+        readResource?: NativeToolMetadataConfig;
+    };
+    rootDir?: string;
+    userHomeDir?: string;
+    requireRootUnderUserHome?: boolean;
+    allowOverwrite?: boolean;
+    maxDownloadBytes?: number;
+    maxReadBytes?: number;
+    maxReadLines?: number;
+    maxExtractedFiles?: number;
+    maxExtractedBytes?: number;
+    downloadTimeoutMs?: number;
+    allowedProtocols?: string[];
+    allowedHosts?: string[];
+    allowedUrlPrefixes?: string[];
+    zuoraDownloadHosts?: string[];
+    allowZuoraAuthenticatedDownload?: boolean;
+    allowS3PresignedDownload?: boolean;
+    allowArchiveExtraction?: boolean;
+};
+type NativeFileApprovalMetadata = {
+    source: "native";
+    nativeToolType: "fileArtifacts";
+    filesystemRoot: string;
+    sideEffects: Array<"networkRead" | "localFileWrite" | "localFileRead">;
+    urlHost?: string;
+    urlProtocol?: string;
+    urlPath?: string;
+    urlKind?: string;
+    outputRelativePath?: string;
+    artifactId?: string;
+    relativePath?: string;
+};
+type NativeToolApprovalMetadata = NativeFileApprovalMetadata;
+type ToolkitBundleName = string;
+type ZuoraBundleDefinition = {
+    name: ToolkitBundleName;
+    description: string;
+    examples: string[];
+    commonObjects: string[];
+    keywords: string[];
+    toolCount: number;
+    readToolCount: number;
+    writeToolCount: number;
+    tools: ZuoraToolDefinition[];
+};
+type JsonSchema = {
+    type?: string;
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    required?: string[];
+    enum?: string[];
+    description?: string;
+    additionalProperties?: boolean | JsonSchema;
+    [key: string]: unknown;
+};
+type ZuoraAuthConfig = {
+    type: "oauthClientCredentials";
+    clientId: string;
+    clientSecret: string;
+    scope?: string;
+} | {
+    type: "accessToken";
+    accessToken: string;
+};
+type ZuoraTenantAuthConfig = {
+    enabled: true;
+    tenantId: string;
+    tokenId: string;
+    userId: string;
+} | {
+    enabled?: false;
+};
+type EnabledZuoraTenantAuthConfig = Extract<ZuoraTenantAuthConfig, {
+    enabled: true;
+}>;
+type BundleConfiguration = {
+    include?: string[];
+    exclude?: string[];
+};
+type ZuoraToolkitConfiguration = {
+    mode?: ZuoraSafetyMode;
+    bundles?: Partial<Record<ZuoraBundleName, boolean | BundleConfiguration>>;
+    tools?: Record<string, boolean>;
+    context?: Record<string, string | undefined>;
+    splitOperations?: boolean;
+};
+type ToolSelection = {
+    bundles?: ZuoraBundleName[];
+    include?: string[];
+    exclude?: string[];
+    mode?: ZuoraSafetyMode;
+};
+type ZuoraExecutionRequestMetadata = {
+    requestId?: string;
+    zuoraRequestId?: string;
+    environment?: ZuoraEnvironment;
+    tenantId?: string;
+    entityIds?: string[];
+    orgIds?: string[];
+};
+type ZuoraToolExecutionResult<TData = unknown> = {
+    toolName: string;
+    data: TData;
+    riskLevel?: ZuoraRiskLevel;
+    requestId?: string;
+    request?: ZuoraExecutionRequestMetadata;
+    warnings?: string[];
+};
+type ZuoraMcpClient = {
+    initialize?: () => Promise<void>;
+    listTools: () => Promise<McpTool[]>;
+    callTool: (name: string, input: Record<string, unknown>) => Promise<ZuoraToolExecutionResult>;
+    readResource?: (uri: string) => Promise<McpReadResourceResult>;
+    getTenantId?: () => string | undefined;
+    getSensitiveValues?: () => readonly string[];
+    close?: () => Promise<void>;
+};
+type ZuoraConnectionConfigBase = {
+    tokenEndpoint?: string;
+    tokenAuthMethod?: "client_secret_post" | "client_secret_basic";
+    headers?: Record<string, string | undefined>;
+    entityIds?: string | string[];
+    orgIds?: string | string[];
+    zuoraVersion?: string;
+    protocolVersion?: string;
+};
+type ZuoraTenantAuthConnectionConfig = ZuoraConnectionConfigBase & {
+    tenantAuth: EnabledZuoraTenantAuthConfig;
+};
+type ZuoraStandardConnectionConfig = ZuoraConnectionConfigBase & {
+    tenantAuth?: Exclude<ZuoraTenantAuthConfig, EnabledZuoraTenantAuthConfig>;
+};
+type ZuoraConnectionConfig = ZuoraStandardConnectionConfig | ZuoraTenantAuthConnectionConfig;
+declare const ApprovalPolicyPreset: {
+    readonly Off: "off";
+    readonly AllWrites: "all_writes";
+    readonly HighRisk: "high_risk";
+    readonly ProductionWrites: "production_writes";
+    readonly ProductionHighRisk: "production_high_risk";
+};
+type ApprovalPolicyPresetValue = (typeof ApprovalPolicyPreset)[keyof typeof ApprovalPolicyPreset];
+type ApprovalPolicyResult = "not_required" | "deny" | {
+    decision: "not_required" | "deny";
+    reason?: string;
+};
+type ApprovalPolicyHandler = (request: ApprovalRequest) => ApprovalPolicyResult | Promise<ApprovalPolicyResult>;
+type ApprovalPolicy = ApprovalPolicyPresetValue | ApprovalPolicyHandler;
+type ApprovalRequest = {
+    tool: ZuoraToolDefinition;
+    input: Record<string, unknown>;
+    environment: ZuoraEnvironment;
+    /** Present only for SDK-native tools (e.g. download_file). Undefined for MCP-sourced tools. */
+    native?: NativeToolApprovalMetadata;
+};
+type ZuoraToolkitEventName = "tool.called" | "tool.completed" | "tool.failed" | "approval.requested"
+/**
+ * Internal name used when emitting the approval outcome from
+ * `enforceApproval()`.  It is normalised to the `"approval.decided"` type
+ * by `normalizeToolkitEvent()` before being delivered to observers.
+ * @see ZuoraToolkitEventType
+ */
+ | "approval.resolved" | "approval.decided" | "metadata.loaded" | "async.poll.checked" | "observability.sink_failed"
+/**
+ * Emitted by framework adapters (e.g. the Agents SDK adapter) after
+ * `execute()` finishes post-processing the raw MCP result. The `metadata`
+ * field carries the actual response the LLM receives, which may differ from
+ * the raw `callTool` output (e.g. async-job directives, download hints).
+ * Consumers can subscribe to this event to audit what the LLM was told.
+ */
+ | "agent.tool.response";
+/**
+ * The canonical event type delivered to `onEvent` / `emit` sinks.
+ *
+ * Note the asymmetry with `ZuoraToolkitEventName`: the internal name
+ * `"approval.resolved"` is normalised to `"approval.decided"` before
+ * delivery.  Consumers should match on `type`, not `name`, when they need
+ * a stable identifier for approval-outcome events.
+ */
+type ZuoraToolkitEventType = "tool.called" | "tool.completed" | "tool.failed" | "approval.requested" | "approval.decided" | "metadata.loaded" | "async.poll.checked" | "observability.sink_failed" | "agent.tool.response";
+type ZuoraToolkitApprovalDecision = "allow" | "deny";
+type ZuoraToolkitApprovalStatus = "requested" | "rejected" | "not_required";
+type ZuoraToolkitEventError = {
+    code: string;
+    category: string;
+    recoverable: boolean;
+    retryable?: boolean;
+    requestId?: string;
+    message?: string;
+};
+type ZuoraToolExecutionPhase = "primary" | "async_poll";
+type ZuoraToolkitEvent = {
+    type: ZuoraToolkitEventType;
+    name: ZuoraToolkitEventName;
+    timestamp: string;
+    toolName?: string;
+    access?: ZuoraToolOperation;
+    bundle?: string;
+    executionPhase?: ZuoraToolExecutionPhase;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    requestId?: string;
+    zuoraRequestId?: string;
+    riskLevel?: ZuoraRiskLevel;
+    latencyMs?: number;
+    environment?: ZuoraEnvironment;
+    tenantId?: string;
+    entityIds?: string[];
+    orgIds?: string[];
+    approvalDecision?: ZuoraToolkitApprovalDecision;
+    approvalStatus?: ZuoraToolkitApprovalStatus;
+    error?: ZuoraToolkitEventError;
+    metadata?: Record<string, unknown>;
+};
+type ZuoraToolkitLogger = {
+    debug?: (message: string, event?: ZuoraToolkitEvent) => void;
+    info?: (message: string, event?: ZuoraToolkitEvent) => void;
+    warn?: (message: string, event?: ZuoraToolkitEvent) => void;
+    error?: (message: string, event?: ZuoraToolkitEvent) => void;
+};
+type ZuoraAgentToolkitConfigBase = {
+    baseUrl: string;
+    configuration?: ZuoraToolkitConfiguration;
+    approvalPolicy?: ApprovalPolicy;
+    /**
+     * SDK-internal overrides for native file download/read infrastructure.
+     * Auto-enabled when the query bundle is configured — agents never set this.
+     */
+    nativeFileTools?: NativeFileToolsConfig;
+    observability?: {
+        logger?: ZuoraToolkitLogger;
+        emit?: (event: ZuoraToolkitEvent) => void | Promise<void>;
+        onEvent?: (event: ZuoraToolkitEvent) => void;
+        /**
+         * When true, tool.called/tool.completed/tool.failed events include
+         * sanitized input and output payloads. Defaults to false.
+         */
+        includePayloads?: boolean;
+        /**
+         * Limits applied when sanitizing event metadata fields.
+         * Use `resolveEventSanitizerLimits(process.env)` to populate from
+         * environment variables, or supply explicit values.
+         * Defaults to built-in conservative limits when omitted.
+         */
+        sanitizerLimits?: EventSanitizerLimits;
+    };
+};
+type ZuoraAgentToolkitEnvSource = true | {
+    env?: Record<string, string | undefined>;
+};
+type ZuoraAgentToolkitEnvConfig = Omit<ZuoraAgentToolkitConfigBase, "baseUrl"> & {
+    env: ZuoraAgentToolkitEnvSource;
+};
+type ZuoraAgentToolkitConfig = (ZuoraAgentToolkitConfigBase & {
+    auth: ZuoraAuthConfig;
+    connection?: ZuoraConnectionConfig;
+}) | (ZuoraAgentToolkitConfigBase & {
+    auth?: ZuoraAuthConfig;
+    connection: ZuoraTenantAuthConnectionConfig;
+});
+type ZuoraAgentToolkitConfigInput = ZuoraAgentToolkitConfig | ZuoraAgentToolkitEnvConfig;
+/**
+ * Terminal state of a completed async job.
+ */
+type ZuoraAsyncJobTerminalState = "success" | "failure" | "canceled";
+/**
+ * Configuration for which status strings are considered terminal for each outcome.
+ */
+type ZuoraAsyncJobTerminalStatuses = {
+    success: string[];
+    failure: string[];
+    canceled?: string[];
+};
+/**
+ * Rich resolution of the current async job status returned by resolveAsyncJobStatusDetails.
+ */
+type ZuoraAsyncJobStatusResolution = {
+    /** Raw status string extracted from the tool result, if any. */
+    status: string | undefined;
+    /** True if the job has reached a terminal state. */
+    isTerminal: boolean;
+    /** The resolved terminal state, or undefined if not yet terminal. */
+    terminalState: ZuoraAsyncJobTerminalState | undefined;
+};
+/**
+ * Options for waitForJob() — all fields override the async meta defaults.
+ */
+type ZuoraWaitForJobOptions = {
+    /**
+     * Maximum number of polling attempts before giving up.
+     * Overrides asyncMeta.maxPollAttempts.
+     */
+    maxPollAttempts?: number;
+    /**
+     * Interval in milliseconds between polling attempts.
+     * Overrides asyncMeta.recommendedPollIntervalMs.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Absolute timeout in milliseconds from when waitForJob() was called.
+     * Overrides asyncMeta.defaultTimeoutMs.
+     *
+     * **Note:** the timeout is checked at the start of each loop iteration,
+     * before the poll is issued. A value of `0` will therefore cause
+     * `waitForJob` to throw `ASYNC_JOB_TIMEOUT` immediately without ever
+     * making a poll attempt.
+     */
+    timeoutMs?: number;
+    /**
+     * Custom terminal status sets. When provided, overrides the terminal statuses
+     * defined in the async operation meta.
+     */
+    terminalStatuses?: ZuoraAsyncJobTerminalStatuses;
+};
+
+type BuildAsyncJobResultContext = {
+    sourceToolName: string;
+    operationSelector?: string;
+    /** Split operation names registered for sourceToolName. */
+    sourceOperationNames?: string[];
+};
+type ZuoraAsyncJobResult = {
+    toolName: string;
+    status: "pending";
+    jobId: string;
+    /** Resolved toolkit tool name to call when polling or auto-waiting. */
+    pollingToolName: string;
+    /** Original MCP pollingOperation metadata, when present. */
+    pollingOperation?: string;
+    pollingArgs?: Record<string, string>;
+    /** Dot-path to the status field in the poll result (e.g. "data.status"). Populated from asyncMeta.statusPath at job-start time. */
+    statusPath?: string;
+    /** Terminal status sets for this job. Populated from asyncMeta.terminalStatuses at job-start time. */
+    terminalStatuses?: ZuoraAsyncJobTerminalStatuses;
+    recommendedPollIntervalMs?: number;
+    maxPollAttempts?: number;
+    defaultTimeoutMs?: number;
+};
+/**
+ * Default terminal statuses applied when the async operation meta does not
+ * specify its own terminal status sets and no override is provided to waitForJob.
+ */
+declare const DEFAULT_ASYNC_JOB_TERMINAL_STATUSES: ZuoraAsyncJobTerminalStatuses;
+/**
+ * Returns `true` when `data` is a `ZuoraAsyncJobResult` — a pending async job
+ * result produced by `ToolkitCore.callTool()` via `buildAsyncJobResult()`.
+ *
+ * The check requires `status === "pending"`, a non-empty `jobId` string, and
+ * at least one of `pollingToolName` or `pollingOperation`. Those routing fields
+ * are only present on data shaped by `buildAsyncJobResult` — plain API responses
+ * that happen to contain a job-ID-like field will not pass this guard.
+ */
+declare const isAsyncJobResult: (data: unknown) => data is ZuoraAsyncJobResult;
+/**
+ * Builds a structured async-pending result to return to the agent when a tool
+ * call produces a job that requires polling.
+ *
+ * @throws ZuoraAgentToolkitError with TOOL_EXECUTION_ERROR if jobIdPath
+ *   resolves to undefined or null on the raw result.
+ */
+declare function buildAsyncJobResult(result: ZuoraToolExecutionResult, asyncMeta: ZuoraAsyncOperationMeta, context: BuildAsyncJobResultContext): ZuoraAsyncJobResult;
+/**
+ * Returns true when the given status string matches any status in the success,
+ * failure, or canceled sets of the provided terminal statuses config.
+ *
+ * The comparison is case-insensitive.
+ */
+declare function matchesAsyncJobTerminalStatus(status: string, statuses: ZuoraAsyncJobTerminalStatuses): boolean;
+/**
+ * Resolves the terminal state ("success" | "failure" | "canceled") for the
+ * given status string against the provided terminal statuses config.
+ *
+ * Returns undefined when the status has not yet reached a terminal state.
+ */
+declare function resolveAsyncJobTerminalState(status: string, statuses: ZuoraAsyncJobTerminalStatuses): ZuoraAsyncJobTerminalState | undefined;
+/**
+ * Returns true when the given async job result has reached a terminal state
+ * according to the provided terminal statuses config.
+ *
+ * The job is considered terminal only when a non-null, non-empty status string
+ * is present in the result data and that status matches one of the terminal sets.
+ */
+declare function isAsyncJobTerminal(result: ZuoraToolExecutionResult, statusPath: string, statuses: ZuoraAsyncJobTerminalStatuses): boolean;
+/**
+ * Extracts the current job status string from a polling tool result.
+ *
+ * @param result - The result returned by the polling tool.
+ * @param statusPath - Dot-path to the status field within result.data,
+ *   e.g. "status" or "job.state". Paths are normalized at parse time by
+ *   parseAsyncOperationMeta, so callers within the SDK should always pass
+ *   already-normalized paths here.
+ * @returns The extracted status string, or undefined if not present.
+ */
+declare function resolveAsyncJobStatus(result: ZuoraToolExecutionResult, statusPath: string): string | undefined;
+/**
+ * Extracts the job ID from a ZuoraAsyncJobResult embedded inside a tool
+ * execution result, or returns the jobId directly from a ZuoraAsyncJobResult.
+ *
+ * Supports two calling patterns:
+ *   - resolveAsyncJobId(asyncJobResult)
+ *   - resolveAsyncJobId(toolResult, jobIdPath)
+ */
+declare function resolveAsyncJobId(result: ZuoraAsyncJobResult | ZuoraToolExecutionResult, jobIdPath?: string): string | undefined;
+/**
+ * Extracts the name of the next polling tool from a ZuoraAsyncJobResult.
+ * Returns undefined if result is not a ZuoraAsyncJobResult.
+ *
+ * pollingToolName is always set on ZuoraAsyncJobResult (resolved at job-start
+ * time by resolveAsyncJobPollingToolNameFromMeta), so it is returned directly.
+ */
+declare function resolveAsyncJobPollingToolName(result: ZuoraAsyncJobResult | ZuoraToolExecutionResult): string | undefined;
+/**
+ * Returns a rich ZuoraAsyncJobStatusResolution describing the current status
+ * of an async job, including whether it has reached a terminal state and what
+ * the terminal state is.
+ *
+ * @param result - The result returned by the polling tool.
+ * @param statusPath - Dot-path to the status field (e.g. "data.status").
+ * @param terminalStatuses - Terminal status configuration to match against.
+ */
+declare function resolveAsyncJobStatusDetails(result: ZuoraToolExecutionResult, statusPath: string, terminalStatuses: ZuoraAsyncJobTerminalStatuses): ZuoraAsyncJobStatusResolution;
+
+export { type ApprovalPolicy as A, resolveAsyncJobId as B, resolveAsyncJobPollingToolName as C, DEFAULT_ASYNC_JOB_TERMINAL_STATUSES as D, resolveAsyncJobStatus as E, resolveAsyncJobStatusDetails as F, resolveAsyncJobTerminalState as G, type NativeFileApprovalMetadata as N, type ToolSelection as T, type ZuoraToolDefinition as Z, type ZuoraAgentToolkitConfigInput as a, type ZuoraToolExecutionResult as b, type ZuoraAsyncJobResult as c, type ZuoraToolkitEvent as d, type ZuoraAgentToolkitConfig as e, type ZuoraMcpClient as f, type ZuoraBundleDefinition as g, type ZuoraBundleName as h, type ZuoraWaitForJobOptions as i, ApprovalPolicyPreset as j, type ApprovalPolicyPresetValue as k, type ApprovalRequest as l, type NativeFileToolsConfig as m, type NativeToolApprovalMetadata as n, type NativeToolMetadataConfig as o, type ToolkitBundleName as p, type ZuoraAsyncJobStatusResolution as q, type ZuoraAsyncJobTerminalState as r, type ZuoraAsyncJobTerminalStatuses as s, type ZuoraSafetyMode as t, type ZuoraToolkitConfiguration as u, type ZuoraToolkitLogger as v, buildAsyncJobResult as w, isAsyncJobResult as x, isAsyncJobTerminal as y, matchesAsyncJobTerminalStatus as z };