@naturalpay/sdk 0.1.4 → 0.2.1

package/dist/index.d.ts

@@ -1,879 +0,0 @@
-/**
- * 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.
- *
- * Accepts keys matching `sk_ntl_(dev|sandbox|prod)_*`. Throws
- * `InvalidRequestError` for anything else. The return type is a narrowed
- * literal union so callers can discriminate on the env without a second
- * parse.
- */
-declare function parseApiKeyEnv(key: string): 'dev' | 'sandbox' | 'prod';
-/**
- * Validate that a base URL uses HTTPS, with a localhost auto-allow and an
- * `NATURAL_ALLOW_HTTP=1` escape hatch for non-localhost plaintext hosts.
- *
- * Throws `InvalidRequestError` if the URL is not HTTPS and neither escape
- * hatch applies. Runs at client construction, not per-request.
- */
-declare function validateBaseUrl(baseUrl: string): void;
-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;
-    /**
-     * Build URL with query parameters.
-     */
-    private buildUrl;
-    /**
-     * Handle API response and throw appropriate errors.
-     */
-    private handleResponse;
-    /**
-     * 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>;
-    post<T>(path: string, options?: RequestOptions): Promise<T>;
-    put<T>(path: string, options?: RequestOptions): Promise<T>;
-    delete<T>(path: string, options?: RequestOptions): Promise<T>;
-}
-
-/**
- * Base resource class.
- */
-
-declare abstract class BaseResource {
-    protected readonly http: HTTPClient;
-    constructor(http: HTTPClient);
-}
-
-/**
- * Payment types.
- */
-interface PaymentCreateParams {
-    /** Agent ID (agt_xxx) for agent-initiated payments. */
-    agentId?: string;
-    /** Payment amount in minor units (cents). 5000 = $50.00. */
-    amount: number;
-    customerPartyId: string;
-    /** Recipient email, phone number, or party ID (pty_xxx). */
-    recipient: string;
-    /** Payment memo/description. */
-    memo: 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;
-}
-
-/**
- * Transaction types.
- */
-/**
- * Filter for transaction types in list operations.
- */
-declare enum TransactionTypeFilter {
-    PAYMENT = "payment",
-    TRANSFER = "transfer",
-    ALL = "all"
-}
-interface Transaction {
-    transactionId: string;
-    amount: number;
-    currency: string;
-    status: string;
-    description?: string;
-    memo?: string;
-    createdAt: string;
-    updatedAt?: string;
-    isDelegated: boolean;
-    customerName?: string;
-    customerAgentId?: string;
-    senderName?: string;
-    recipientName?: string;
-    transactionType: string;
-    category: string;
-    direction: string;
-    sourcePartyId?: string;
-    destinationPartyId?: string;
-    sourceWalletId?: string;
-    destinationWalletId?: string;
-    /** Internal instance ID (ins_xxx) assigned by server. */
-    instanceId?: string;
-    /** Claim link URL for unclaimed payments. */
-    claimLink?: string;
-}
-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;
-    cursor?: string;
-    agentId?: string;
-    /** Filter by transaction type (payment, transfer, or all) */
-    type?: TransactionTypeFilter;
-    /** Developer's session/conversation ID for observability grouping. */
-    instanceId?: string;
-    /** Trace ID for distributed tracing correlation. */
-    traceId?: string;
-}
-interface TransactionListResponse {
-    transactions: Transaction[];
-    hasMore: boolean;
-    nextCursor?: string | null;
-}
-
-/**
- * Payments resource.
- */
-
-declare class PaymentsResource extends BaseResource {
-    /**
-     * Create a payment.
-     *
-     * @param params - Payment creation parameters
-     * @returns Transaction object with transaction_id (txn_*), status, etc.
-     */
-    create(params: PaymentCreateParams): Promise<Transaction>;
-}
-
-/**
- * Wallet types.
- */
-interface AmountInfo {
-    amountMinor: number;
-}
-interface BalanceBreakdown {
-    operatingFunded: AmountInfo;
-    operatingAdvanced: AmountInfo;
-    escrowFundedSettled: AmountInfo;
-    escrowAdvanced: AmountInfo;
-    holdsOutbound: AmountInfo;
-}
-interface AccountBalance {
-    walletId: string;
-    breakdown: BalanceBreakdown;
-    available: AmountInfo;
-    pendingClaimAmountMinor?: number;
-    pendingClaimCount?: number;
-}
-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. */
-    amount: number;
-    /** ID of the linked bank account (efs_xxx). */
-    externalFundingSourceId: string;
-    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;
-    instructionId?: string;
-    status: string;
-    amount: number;
-    currency: string;
-    estimatedSettlement?: string;
-    kycRequired: boolean;
-    kycStatus?: string;
-    kycSessionUrl?: string;
-    mfaRequired: boolean;
-    mfaChallengeId?: string;
-    mfaExpiresAt?: string;
-    error?: string;
-    errorDetails?: string;
-}
-
-/**
- * Wallet resource.
- */
-
-declare class WalletResource extends BaseResource {
-    /**
-     * Get current wallet balance.
-     *
-     * @returns AccountBalance with available, current, pending amounts
-     */
-    balance(options?: BalanceOptions): Promise<AccountBalance>;
-    /**
-     * Initiate a withdrawal to a linked bank account.
-     *
-     * @param params - Withdrawal parameters
-     * @returns WithdrawResponse with transfer status (may require KYC/MFA)
-     */
-    withdraw(params: WithdrawParams): Promise<WithdrawResponse>;
-}
-
-/**
- * Transactions resource.
- */
-
-declare class TransactionsResource extends BaseResource {
-    /**
-     * Get a transaction by ID.
-     *
-     * @param transactionId - Transaction ID (txn_xxx)
-     * @param params - Optional parameters for observability
-     * @returns Transaction details
-     */
-    get(transactionId: string, params?: TransactionGetParams): Promise<Transaction>;
-    /**
-     * List recent transactions.
-     *
-     * @param params - List parameters including agent context
-     * @returns TransactionListResponse with transactions and pagination info
-     */
-    list(params?: TransactionListParams): Promise<TransactionListResponse>;
-}
-
-/**
- * Agent types.
- */
-type AgentStatus = 'ACTIVE' | 'REVOKED';
-interface TransactionLimits {
-    perTransaction?: number;
-}
-interface Agent {
-    id: string;
-    name: string;
-    description?: string;
-    status: AgentStatus;
-    partyId: string;
-    createdAt?: string;
-    createdBy?: string;
-    updatedAt?: string;
-    updatedBy?: string;
-}
-interface AgentCreateParams {
-    name: string;
-    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;
-interface AgentUpdateParams {
-    name?: string;
-    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;
-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[];
-    hasMore: boolean;
-    nextCursor?: string | null;
-}
-
-/**
- * Agents resource.
- */
-
-declare class AgentsResource extends BaseResource {
-    /**
-     * List agents for the partner.
-     *
-     * @param params - Filter and pagination parameters
-     * @returns AgentListResponse with list of agents
-     */
-    list(params?: AgentListParams): Promise<AgentListResponse>;
-    /**
-     * Get agent by ID.
-     *
-     * @param agentId - The agent ID to retrieve (agt_xxx)
-     * @returns Agent details
-     */
-    get(agentId: string, options?: AgentGetOptions): Promise<Agent>;
-    /**
-     * Create a new agent.
-     *
-     * @param params - Agent creation parameters
-     * @returns AgentCreateResponse with created agent details
-     */
-    create(params: AgentCreateParams): Promise<AgentCreateResponse>;
-    /**
-     * Update an existing agent.
-     *
-     * @param agentId - The agent ID to update (agt_xxx)
-     * @param params - Update parameters
-     * @returns AgentUpdateResponse with updated agent details
-     */
-    update(agentId: string, params: AgentUpdateParams): Promise<AgentUpdateResponse>;
-    /**
-     * Delete an agent.
-     *
-     * @param agentId - The agent ID to delete (agt_xxx)
-     * @param options - Optional observability parameters
-     */
-    delete(agentId: string, options?: AgentDeleteOptions): Promise<void>;
-}
-
-/**
- * Agent delegation types.
- */
-interface AgentDelegation {
-    id: string;
-    agentName?: string;
-    agentId: string;
-    delegationId: string;
-    delegatorPartyId?: string;
-    delegateePartyId?: string;
-    delegatorPartyName?: string;
-    delegateePartyName?: string;
-    permissions: string[];
-    limits?: Record<string, number>;
-    expiresAt?: string;
-    createdAt: string;
-    createdBy?: string;
-    updatedAt: string;
-}
-interface AgentDelegationListParams {
-    delegationId?: string;
-    agentId?: string;
-    delegatorPartyId?: string;
-    delegateePartyId?: string;
-    includeRevoked?: boolean;
-    limit?: number;
-    cursor?: string;
-    /** Developer's session/conversation ID for observability grouping. */
-    instanceId?: string;
-    /** Trace ID for distributed tracing correlation. */
-    traceId?: string;
-}
-interface AgentDelegationListResponse {
-    agentDelegations: AgentDelegation[];
-    hasMore: boolean;
-    nextCursor?: string | null;
-}
-
-/**
- * Agent delegations resource.
- */
-
-declare class DelegationsResource extends BaseResource {
-    /**
-     * List agent delegations with optional filters.
-     *
-     * @param params - Filter parameters
-     * @returns AgentDelegationListResponse with list of agent delegations
-     */
-    list(params?: AgentDelegationListParams): Promise<AgentDelegationListResponse>;
-    /**
-     * Get agent delegation by ID.
-     *
-     * @param agentDelegationId - The agent delegation handle (adl_xxx)
-     * @returns AgentDelegation details
-     */
-    get(agentDelegationId: string): Promise<AgentDelegation>;
-}
-
-/**
- * Customer types.
- */
-interface CustomerPartyInfo {
-    id: string;
-    name: string;
-    email?: string;
-}
-interface Customer {
-    id: string;
-    type: 'party' | 'delegationInvitation';
-    party?: CustomerPartyInfo;
-    email?: string;
-    status: string;
-    permissions: string[];
-    createdAt: string;
-    walletAvailableMinor?: number;
-    walletAvailableDollars?: string;
-    walletAccess: 'granted' | 'denied' | 'noWallet';
-}
-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;
-}
-
-/**
- * Customers resource.
- */
-
-declare class CustomersResource extends BaseResource {
-    /**
-     * List customers who have delegated access to the partner.
-     *
-     * @param params - Pagination parameters
-     * @returns CustomerListResponse with items, hasMore, nextCursor
-     */
-    list(params?: CustomerListParams): Promise<CustomerListResponse>;
-}
-
-/**
- * Natural Payments SDK client.
- */
-
-interface NaturalClientOptions extends HTTPClientOptions {
-}
-/**
- * Natural Payments SDK client.
- *
- * @example
- * ```typescript
- * import { NaturalClient } from '@naturalpay/sdk';
- *
- * const client = new NaturalClient({ apiKey: process.env['NATURAL_API_KEY'] });
- *
- * // Create a payment
- * const payment = await client.payments.create({
- *   agentId: 'agt_xxx',
- *   amount: 5000,
- *   customerPartyId: 'pty_xxx',
- *   recipient: 'alice@example.com',
- *   memo: 'For consulting',
- *   idempotencyKey: 'unique-key-for-this-payment',
- * });
- *
- * // Check balance
- * const balance = await client.wallet.balance();
- * ```
- */
-declare class NaturalClient {
-    private readonly http;
-    /** Payments API resource. */
-    readonly payments: PaymentsResource;
-    /** Wallet API resource for balance and withdrawals. */
-    readonly wallet: WalletResource;
-    /** Transactions API resource. */
-    readonly transactions: TransactionsResource;
-    /** Agents API resource for managing agents. */
-    readonly agents: AgentsResource;
-    /** Agent delegations API resource. */
-    readonly delegations: DelegationsResource;
-    /** Customers API resource for listing parties who delegated access. */
-    readonly customers: CustomersResource;
-    /**
-     * Initialize the Natural client.
-     *
-     * @param options - Client configuration options
-     * @param options.apiKey - API key (defaults to NATURAL_API_KEY env var)
-     * @param options.baseUrl - API base URL (defaults to https://api.natural.co)
-     * @param options.timeout - Request timeout in milliseconds (default: 30000)
-     */
-    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';
-};
-
-/**
- * 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       - Tool name (e.g. "create_payment").
- * @param args       - Raw tool arguments.
- * @param fn         - The function to execute within the context.
- */
-declare function runWithToolCall<T>(toolCallId: ToolCallId, name: string, args: Record<string, unknown>, fn: () => T): T;
-
-/**
- * Structured logging for Natural Payments SDK.
- *
- * Supports two modes:
- * 1. Plain text logging (default, for local development)
- * 2. JSON logging with Datadog correlation (when NATURAL_LOG_FORMAT=json)
- *
- * Features:
- * - Source info: file, line, function on every log (for error grouping)
- * - Context binding for request_id, agent_id, instance_id
- * - Datadog trace correlation fields
- * - AsyncLocalStorage for proper async context isolation
- */
-type LogLevel = 'debug' | 'info' | 'warning' | 'error';
-/**
- * Get the current logging context.
- * Uses AsyncLocalStorage if available, falls back to global context.
- */
-declare function getContext(): Record<string, unknown>;
-/**
- * Bind additional context to current scope (e.g., request_id, agent_id).
- *
- * Values are sanitized to prevent log injection attacks.
- * Updates both AsyncLocalStorage (if active) and global context.
- *
- * @example
- * bindContext({ requestId: 'req_123', agentId: 'agt_456' });
- * logger.info('Processing payment'); // Will include requestId and agentId
- */
-declare function bindContext(context: Record<string, unknown>): void;
-/**
- * Clear all bound context.
- */
-declare function clearContext(): void;
-/**
- * Run a function with isolated logging context.
- *
- * Context bound within the callback is isolated from other async operations.
- * This is the recommended way to set context for request handling.
- *
- * @example
- * await runWithContext({ requestId: 'req_123' }, async () => {
- *   logger.info('Processing request'); // Includes requestId
- *   await doAsyncWork();
- *   logger.info('Request complete'); // Still includes requestId
- * });
- */
-declare function runWithContext<T>(context: Record<string, unknown>, fn: () => T | Promise<T>): T | Promise<T>;
-/**
- * Configure logging for the Natural SDK.
- *
- * @param options - Logging configuration options
- * @param options.level - Log level (debug, info, warning, error)
- * @param options.jsonFormat - Use JSON format (default: auto-detect from NATURAL_LOG_FORMAT env var)
- * @param options.serviceName - Service name for structured logs
- *
- * Environment variables:
- * - NATURAL_LOG_LEVEL: Override log level (DEBUG, INFO, WARNING, ERROR)
- * - NATURAL_LOG_FORMAT: Set to "json" for JSON output, "text" for plain text
- */
-declare function configureLogging(options?: {
-    level?: LogLevel;
-    jsonFormat?: boolean;
-    serviceName?: string;
-}): void;
-/**
- * Logger instance for a specific module/context.
- */
-declare class Logger {
-    private readonly name;
-    constructor(name: string);
-    private log;
-    debug(message: string, extra?: Record<string, unknown>): void;
-    info(message: string, extra?: Record<string, unknown>): void;
-    warning(message: string, extra?: Record<string, unknown>): void;
-    warn(message: string, extra?: Record<string, unknown>): void;
-    error(message: string, extra?: Record<string, unknown>): void;
-}
-/**
- * Get a logger for the given module name.
- *
- * @param name - Module name (e.g., 'naturalpay.http')
- * @returns Logger instance
- *
- * @example
- * const logger = getLogger('naturalpay.payments');
- * logger.info('Payment initiated', { amount: 10000 });
- */
-declare function getLogger(name: string): Logger;
-/**
- * Log an error with full context and exception info.
- */
-declare function logError(logger: Logger, message: string, options?: {
-    error?: Error;
-    statusCode?: number;
-    code?: string;
-    [key: string]: unknown;
-}): void;
-/**
- * Log an API call with standard fields.
- */
-declare function logApiCall(logger: Logger, method: string, path: string, options?: {
-    statusCode?: number;
-    durationMs?: number;
-    error?: Error;
-    [key: string]: unknown;
-}): void;
-/**
- * Log an MCP tool invocation.
- */
-declare function logToolCall(logger: Logger, toolName: string, options?: {
-    success?: boolean;
-    durationMs?: number;
-    error?: Error;
-    [key: string]: unknown;
-}): void;
-
-/**
- * Natural Payments SDK error classes.
- */
-/**
- * Base error for all Natural SDK errors.
- */
-declare class NaturalError extends Error {
-    readonly statusCode?: number;
-    readonly code?: string;
-    constructor(message: string, options?: {
-        statusCode?: number;
-        code?: string;
-    });
-}
-/**
- * Invalid or missing API key.
- */
-declare class AuthenticationError extends NaturalError {
-    constructor(message?: string);
-}
-/**
- * Malformed request parameters.
- */
-declare class InvalidRequestError extends NaturalError {
-    constructor(message: string, code?: string);
-}
-/**
- * Payment-specific failure.
- */
-declare class PaymentError extends NaturalError {
-    constructor(message: string, code?: string);
-}
-/**
- * Not enough balance for payment.
- */
-declare class InsufficientFundsError extends PaymentError {
-    constructor(message?: string);
-}
-/**
- * Invalid recipient.
- */
-declare class RecipientNotFoundError extends PaymentError {
-    constructor(message?: string);
-}
-/**
- * Too many requests.
- */
-declare class RateLimitError extends NaturalError {
-    readonly retryAfter?: number;
-    constructor(message?: string, retryAfter?: number);
-}
-/**
- * Internal server error.
- */
-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.4";
-
-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, NaturalClient, type NaturalClientOptions, NaturalError, type PaymentCreateParams, PaymentError, 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 };