@naturalpay/sdk 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -1,6 +1,52 @@
+/**
+ * Agent config and model usage for LLM observability.
+ *
+ * Tracks static agent configuration (system prompt, tools) and per-request
+ * model usage so the observability service can attribute API calls to
+ * specific LLM sessions.
+ */
+/**
+ * Static agent configuration — set once per client, sent to observability.
+ *
+ * Describes the agent's identity (system prompt and available tools).
+ * Model/provider are per-request and belong in ModelUsage.
+ */
+interface AgentConfig {
+    systemPrompt: string;
+    toolsAvailable: string[];
+}
+interface ModelUsage {
+    model?: string;
+    provider?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    toolsCalled?: string[];
+}
+interface AgentConfigDict {
+    system_prompt: string;
+    tools_available: string[];
+}
+interface ModelUsageDict {
+    model?: string;
+    provider?: string;
+    input_tokens?: number;
+    output_tokens?: number;
+    tools_called?: string[];
+}
+/**
+ * SHA-256 hash for change detection.
+ *
+ * Covers only {system_prompt, tools_available} — model/provider
+ * are dynamic per-request and excluded from the config hash.
+ */
+declare function configHash(cfg: AgentConfig): string;
+declare function agentConfigToDict(cfg: AgentConfig): AgentConfigDict;
+declare function modelUsageToDict(usage: ModelUsage): ModelUsageDict;
+
 /**
  * HTTP client for Natural Server API with JWT caching.
  */
+
 /**
  * Parse an API key and return its environment label.
  *
@@ -22,20 +68,35 @@ interface HTTPClientOptions {
     apiKey?: string;
     baseUrl?: string;
     timeout?: number;
+    agentConfig?: AgentConfig;
+    /** Default model/provider sent with every request as X-Model-Usage. */
+    defaultModelUsage?: Pick<ModelUsage, 'model' | 'provider'>;
+    maxRetries?: number;
 }
 interface RequestOptions {
     body?: Record<string, unknown>;
     params?: Record<string, unknown>;
     headers?: Record<string, string>;
+    modelUsage?: ModelUsage;
 }
 declare class HTTPClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly maxRetries;
     private readonly jwtCache;
+    private readonly agentConfig?;
+    private readonly _defaultModelUsage?;
+    private _configResolved;
+    private _configAttempted;
+    private _registerConfigPromise;
+    private _nextRetryAt;
+    private _retryBackoffMs;
+    private static readonly MAX_RETRY_BACKOFF_MS;
     constructor(options?: HTTPClientOptions);
     /**
      * Get a cached JWT or exchange API key for a new one.
+     * Retries on transient failures (5xx, network) but not on 401.
      */
     private getJwt;
     /**
@@ -47,7 +108,18 @@ declare class HTTPClient {
      */
     private handleResponse;
     /**
-     * Make an authenticated request.
+     * Register agent config with the observability service.
+     *
+     * Called lazily before the first request. Errors are caught and logged,
+     * never thrown.
+     */
+    private registerConfig;
+    /**
+     * Add agent config hash and model usage headers if configured.
+     */
+    private injectModelContextHeaders;
+    /**
+     * Make an authenticated request with automatic retries.
      */
     request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
     get<T>(path: string, options?: Omit<RequestOptions, 'body'>): Promise<T>;
@@ -73,16 +145,24 @@ interface PaymentCreateParams {
     agentId?: string;
     /** Payment amount in minor units (cents). 5000 = $50.00. */
     amount: number;
-    customerPartyId: string;
+    /** Sender party ID (pty_xxx). Omit to send from your own wallet; provide for delegated payments on behalf of a customer. */
+    customerPartyId?: string;
     /** Recipient email, phone number, or party ID (pty_xxx). */
     recipient: string;
-    /** Payment memo/description. */
-    memo: string;
+    /**
+     * Human-readable description of the payment's purpose. Required for all SDK
+     * callers. For agent-initiated payments, write a rich rationale (≥20 chars
+     * recommended) so the user can confidently approve and the audit trail is
+     * legible.
+     */
+    description: string;
     /** Currency code (default: USD). */
     currency?: string;
     idempotencyKey: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 
 /**
@@ -101,8 +181,9 @@ interface Transaction {
     amount: number;
     currency: string;
     status: string;
+    escalationId?: string;
+    disputeId?: string;
     description?: string;
-    memo?: string;
     createdAt: string;
     updatedAt?: string;
     isDelegated: boolean;
@@ -110,6 +191,8 @@ interface Transaction {
     customerAgentId?: string;
     senderName?: string;
     recipientName?: string;
+    initiatorName?: string;
+    initiatorIsAgent?: boolean;
     transactionType: string;
     category: string;
     direction: string;
@@ -117,7 +200,7 @@ interface Transaction {
     destinationPartyId?: string;
     sourceWalletId?: string;
     destinationWalletId?: string;
-    /** Internal instance ID (ins_xxx) assigned by server. */
+    /** Present on payment creation responses when agent instance metadata was supplied. */
     instanceId?: string;
     /** Claim link URL for unclaimed payments. */
     claimLink?: string;
@@ -125,8 +208,12 @@ interface Transaction {
 interface TransactionGetParams {
     /** Customer party ID (pty_xxx) for delegated transaction lookup. */
     customerPartyId?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface TransactionListParams {
     limit?: number;
@@ -136,6 +223,8 @@ interface TransactionListParams {
     type?: TransactionTypeFilter;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface TransactionListResponse {
     transactions: Transaction[];
@@ -166,9 +255,9 @@ interface AmountInfo {
 interface BalanceBreakdown {
     operatingFunded: AmountInfo;
     operatingAdvanced: AmountInfo;
-    escrowFundedSettled: AmountInfo;
-    escrowAdvanced: AmountInfo;
-    holdsOutbound: AmountInfo;
+    pendingIn: AmountInfo;
+    pendingOut: AmountInfo;
+    held: AmountInfo;
 }
 interface AccountBalance {
     walletId: string;
@@ -180,8 +269,12 @@ interface AccountBalance {
 interface BalanceOptions {
     /** Customer party ID (pty_xxx) when acting on behalf of customer. */
     customerPartyId?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface WithdrawParams {
     /** Withdrawal amount in minor units (cents). 5000 = $50.00. */
@@ -191,6 +284,12 @@ interface WithdrawParams {
     currency?: string;
     description?: string;
     idempotencyKey: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
+    /** Developer's session/conversation ID for observability grouping. */
+    instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface WithdrawResponse {
     transferId?: string;
@@ -274,8 +373,12 @@ interface AgentCreateParams {
     description?: string;
     limits?: TransactionLimits;
     idempotencyKey?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 /** @deprecated Use Agent instead — server returns full resource for all operations. */
 type AgentCreateResponse = Agent;
@@ -284,8 +387,12 @@ interface AgentUpdateParams {
     description?: string;
     status?: AgentStatus;
     idempotencyKey?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 /** @deprecated Use Agent instead — server returns full resource for all operations. */
 type AgentUpdateResponse = Agent;
@@ -293,16 +400,28 @@ interface AgentListParams {
     status?: AgentStatus;
     limit?: number;
     cursor?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface AgentGetOptions {
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface AgentDeleteOptions {
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface AgentListResponse {
     agents: Agent[];
@@ -382,6 +501,8 @@ interface AgentDelegationListParams {
     cursor?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface AgentDelegationListResponse {
     agentDelegations: AgentDelegation[];
@@ -420,9 +541,8 @@ interface CustomerPartyInfo {
 }
 interface Customer {
     id: string;
-    type: 'party' | 'delegationInvitation';
+    type: 'party';
     party?: CustomerPartyInfo;
-    email?: string;
     status: string;
     permissions: string[];
     createdAt: string;
@@ -430,17 +550,34 @@ interface Customer {
     walletAvailableDollars?: string;
     walletAccess: 'granted' | 'denied' | 'noWallet';
 }
+interface PendingInvitation {
+    id: string;
+    type: 'delegationInvitation';
+    email?: string;
+    status: string;
+    permissions: string[];
+    createdAt: string;
+}
 interface CustomerListParams {
     limit?: number;
     cursor?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface CustomerListResponse {
     items: Customer[];
     hasMore: boolean;
     nextCursor?: string | null;
 }
+interface PendingInvitationListResponse {
+    items: PendingInvitation[];
+    hasMore: boolean;
+    nextCursor?: string | null;
+}
 
 /**
  * Customers resource.
@@ -448,12 +585,16 @@ interface CustomerListResponse {
 
 declare class CustomersResource extends BaseResource {
     /**
-     * List customers who have delegated access to the partner.
+     * List active customers who have delegated access to the partner.
      *
-     * @param params - Pagination parameters
-     * @returns CustomerListResponse with items, hasMore, nextCursor
+     * Returns only accepted delegations. Use {@link listInvitations} for pending
+     * invitations that have not yet been accepted.
      */
     list(params?: CustomerListParams): Promise<CustomerListResponse>;
+    /**
+     * List pending customer invitations you've sent that have not yet been accepted.
+     */
+    listInvitations(params?: CustomerListParams): Promise<PendingInvitationListResponse>;
 }
 
 /**
@@ -477,7 +618,7 @@ interface NaturalClientOptions extends HTTPClientOptions {
  *   amount: 5000,
  *   customerPartyId: 'pty_xxx',
  *   recipient: 'alice@example.com',
- *   memo: 'For consulting',
+ *   description: 'For consulting',
  *   idempotencyKey: 'unique-key-for-this-payment',
  * });
  *
@@ -510,6 +651,73 @@ declare class NaturalClient {
     constructor(options?: NaturalClientOptions);
 }
 
+/** Branded string types for observability IDs */
+type InstanceId = string & {
+    readonly __brand: 'InstanceId';
+};
+type TraceId = string & {
+    readonly __brand: 'TraceId';
+};
+type ToolCallId = string & {
+    readonly __brand: 'ToolCallId';
+};
+
+/**
+ * Natural's canonical tool-name vocabulary.
+ *
+ * These are the names Natural recognizes on the `X-Tool-Call` header and
+ * displays in admin audit views. The `runWithToolCall` helper accepts only
+ * these names, so callers typing a custom label get a TypeScript error at the
+ * call site — the SDK is the single source of truth.
+ *
+ * When Natural adds or renames a tool, update this constant in the same
+ * change. Callers with their own caller-side metadata should use the
+ * `developer_context` field instead.
+ */
+declare const NATURAL_TOOL_NAMES: {
+    readonly CREATE_PAYMENT: "create_payment";
+    readonly GET_PAYMENT_STATUS: "get_payment_status";
+    readonly GET_ACCOUNT_BALANCE: "get_account_balance";
+    readonly LIST_TRANSACTIONS: "list_transactions";
+    readonly LIST_AGENTS: "list_agents";
+    readonly LIST_CUSTOMERS: "list_customers";
+    readonly LIST_CUSTOMER_INVITATIONS: "list_customer_invitations";
+};
+type NaturalToolName = (typeof NATURAL_TOOL_NAMES)[keyof typeof NATURAL_TOOL_NAMES];
+
+/**
+ * Tool call context for MCP server -> HTTP layer communication.
+ *
+ * The MCP server sets tool call data (id + name + arguments) before invoking
+ * SDK methods. The HTTP layer reads it and sends the X-Tool-Call header to the
+ * BFF for audit/observability. Direct SDK users never interact with this module.
+ */
+
+/**
+ * Generate a unique tool call ID with the `tc_` prefix.
+ */
+declare function generateToolCallId(): ToolCallId;
+/**
+ * Get the base64-encoded X-Tool-Call header value, or undefined if not in
+ * a tool call context.
+ *
+ * If the full header (with arguments) exceeds 16 KB, the arguments are
+ * omitted and a warning is logged.
+ */
+declare function getToolCallHeader(): string | undefined;
+/**
+ * Run a function within a tool call context. The HTTP layer will automatically
+ * pick up the tool call data and send it as the X-Tool-Call header.
+ *
+ * @param toolCallId - Unique ID for this invocation (tc_<uuid>).
+ * @param name       - Canonical Natural tool name (see `NATURAL_TOOL_NAMES`).
+ *                     Custom caller-side labels are not accepted here; use the
+ *                     `developer_context` field for caller-side metadata.
+ * @param args       - Raw tool arguments.
+ * @param fn         - The function to execute within the context.
+ */
+declare function runWithToolCall<T>(toolCallId: ToolCallId, name: NaturalToolName, args: Record<string, unknown>, fn: () => T): T;
+
 /**
  * Structured logging for Natural Payments SDK.
  *
@@ -684,10 +892,38 @@ declare class RateLimitError extends NaturalError {
 declare class ServerError extends NaturalError {
     constructor(message?: string);
 }
+/**
+ * Webhook signature verification failed.
+ */
+declare class WebhookVerificationError extends NaturalError {
+    constructor(message: string);
+}
+
+/**
+ * Webhook signature verification using Standard Webhooks HMAC-SHA256.
+ */
+interface VerifyWebhookOptions {
+    toleranceInSeconds?: number;
+}
+/**
+ * Verify a webhook signature using Standard Webhooks HMAC-SHA256.
+ *
+ * The body must be the raw request body — not a parsed and re-serialized
+ * JSON object, as whitespace or key ordering differences would produce a
+ * different signature.
+ *
+ * @param body - Raw request body (string, Buffer, or Uint8Array)
+ * @param headers - Request headers containing webhook-id, webhook-timestamp, webhook-signature
+ * @param secret - Signing secret (with or without whsec_ prefix)
+ * @param options - Optional configuration (toleranceInSeconds)
+ * @returns Parsed JSON payload
+ * @throws WebhookVerificationError on any verification failure
+ */
+declare function verifyWebhookSignature(body: string | Buffer | Uint8Array, headers: Record<string, string> | Headers, secret: string, options?: VerifyWebhookOptions): unknown;
 
 /**
  * Single source of truth for the SDK version string.
  */
-declare const VERSION = "0.1.3";
+declare const VERSION = "0.1.4";
 
-export { type AccountBalance, type Agent, type AgentCreateParams, type AgentCreateResponse, type AgentDelegation, type AgentDelegationListParams, type AgentDelegationListResponse, type AgentDeleteOptions, type AgentGetOptions, type AgentListParams, type AgentListResponse, type AgentStatus, type AgentUpdateParams, type AgentUpdateResponse, type AmountInfo, AuthenticationError, type BalanceBreakdown, type Customer, type CustomerListParams, type CustomerListResponse, type CustomerPartyInfo, InsufficientFundsError, InvalidRequestError, type LogLevel, Logger, NaturalClient, type NaturalClientOptions, NaturalError, type PaymentCreateParams, PaymentError, RateLimitError, RecipientNotFoundError, ServerError, type Transaction, type TransactionGetParams, type TransactionListParams, type TransactionListResponse, TransactionTypeFilter, VERSION, type WithdrawParams, type WithdrawResponse, bindContext, clearContext, configureLogging, getContext, getLogger, logApiCall, logError, logToolCall, parseApiKeyEnv, runWithContext, validateBaseUrl };
+export { type AccountBalance, type Agent, type AgentConfig, type AgentConfigDict, type AgentCreateParams, type AgentCreateResponse, type AgentDelegation, type AgentDelegationListParams, type AgentDelegationListResponse, type AgentDeleteOptions, type AgentGetOptions, type AgentListParams, type AgentListResponse, type AgentStatus, type AgentUpdateParams, type AgentUpdateResponse, type AmountInfo, AuthenticationError, type BalanceBreakdown, type Customer, type CustomerListParams, type CustomerListResponse, type CustomerPartyInfo, type InstanceId, InsufficientFundsError, InvalidRequestError, type LogLevel, Logger, type ModelUsage, type ModelUsageDict, NATURAL_TOOL_NAMES, NaturalClient, type NaturalClientOptions, NaturalError, type NaturalToolName, type PaymentCreateParams, PaymentError, type PendingInvitation, type PendingInvitationListResponse, RateLimitError, RecipientNotFoundError, ServerError, type ToolCallId, type TraceId, type Transaction, type TransactionGetParams, type TransactionListParams, type TransactionListResponse, TransactionTypeFilter, VERSION, type VerifyWebhookOptions, WebhookVerificationError, type WithdrawParams, type WithdrawResponse, agentConfigToDict, bindContext, clearContext, configHash, configureLogging, generateToolCallId, getContext, getLogger, getToolCallHeader, logApiCall, logError, logToolCall, modelUsageToDict, parseApiKeyEnv, runWithContext, runWithToolCall, validateBaseUrl, verifyWebhookSignature };