@naturalpay/sdk 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,703 @@
+/**
+ * HTTP client for Natural Server API with JWT caching.
+ */
+interface HTTPClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface RequestOptions {
+    body?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+declare class HTTPClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly jwtCache;
+    constructor(options?: HTTPClientOptions);
+    /**
+     * Get a cached JWT or exchange API key for a new one.
+     */
+    private getJwt;
+    /**
+     * Build URL with query parameters.
+     */
+    private buildUrl;
+    /**
+     * Handle API response and throw appropriate errors.
+     */
+    private handleResponse;
+    /**
+     * Make an authenticated request.
+     */
+    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): Promise<T>;
+}
+
+/**
+ * Base resource class.
+ */
+
+declare abstract class BaseResource {
+    protected readonly http: HTTPClient;
+    constructor(http: HTTPClient);
+}
+
+/**
+ * Payment types.
+ */
+interface Payment {
+    transferId: string;
+    paymentId?: string;
+    status: string;
+    amount?: number;
+    currency: string;
+    recipientEmail?: string;
+    recipientPhone?: string;
+    memo?: string;
+    createdAt?: string;
+    claimLink?: string;
+    counterpartyPartyId?: string;
+    instanceId?: string;
+}
+interface PaymentCreateParams {
+    recipientEmail?: string;
+    recipientPhone?: string;
+    recipientPartyId?: string;
+    amount: number;
+    memo?: string;
+    agentId?: string;
+    customerPartyId?: string;
+    instanceId?: string;
+    idempotencyKey?: string;
+}
+interface CancellationResult {
+    status: string;
+    message: string;
+}
+
+/**
+ * Payments resource.
+ */
+
+declare class PaymentsResource extends BaseResource {
+    /**
+     * Generate idempotency key based on payment details + time window.
+     */
+    private generateIdempotencyKey;
+    /**
+     * Create a payment.
+     *
+     * Must provide exactly one of: recipientEmail, recipientPhone, or recipientPartyId.
+     *
+     * @param params - Payment creation parameters
+     * @returns Payment object with transfer_id, status, etc.
+     */
+    create(params: PaymentCreateParams): Promise<Payment>;
+    /**
+     * Get payment status by transfer ID.
+     *
+     * @param transferId - The transfer ID to look up
+     * @returns Payment object with current status
+     */
+    retrieve(transferId: string): Promise<Payment>;
+    /**
+     * Cancel a pending payment.
+     *
+     * @param transferId - The transfer ID to cancel
+     * @returns Cancellation result with status and message
+     */
+    cancel(transferId: string): Promise<CancellationResult>;
+}
+
+/**
+ * Wallet types.
+ */
+interface AmountInfo {
+    amountMinor: number;
+    amountDollars: string;
+}
+interface BalanceBreakdown {
+    operatingFunded: AmountInfo;
+    operatingAdvanced: AmountInfo;
+    escrowFundedSettled: AmountInfo;
+    escrowAdvanced: AmountInfo;
+    holdsOutbound: AmountInfo;
+}
+interface AssetBalance {
+    assetCode: string;
+    breakdown: BalanceBreakdown;
+    available: AmountInfo;
+    metadata?: Record<string, unknown>;
+}
+interface AccountBalance {
+    walletId: string;
+    balances: AssetBalance[];
+}
+interface DepositParams {
+    amount: number;
+    paymentInstrumentId: string;
+    currency?: string;
+    description?: string;
+    idempotencyKey: string;
+}
+interface DepositResponse {
+    transferId?: string;
+    status: string;
+    amount: number | string;
+    currency: string;
+    estimatedSettlement?: string;
+    error?: string;
+    errorDetails?: string;
+}
+interface WithdrawParams {
+    amount: number;
+    paymentInstrumentId: string;
+    currency?: string;
+    description?: string;
+    idempotencyKey: string;
+}
+interface WithdrawResponse {
+    transferId?: string;
+    status: string;
+    amount: number | string;
+    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(): Promise<AccountBalance>;
+    /**
+     * Initiate a deposit from a linked bank account.
+     *
+     * @param params - Deposit parameters
+     * @returns DepositResponse with transfer status
+     */
+    deposit(params: DepositParams): Promise<DepositResponse>;
+    /**
+     * 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>;
+}
+
+/**
+ * Transaction types.
+ */
+/**
+ * Filter for transaction types in list operations.
+ */
+declare enum TransactionTypeFilter {
+    PAYMENT = "payment",
+    TRANSFER = "transfer",
+    ALL = "all"
+}
+type TransactionType = 'payment_sent' | 'payment_received' | 'deposit' | 'withdrawal';
+type TransactionStatus = 'pending' | 'processing' | 'completed' | 'failed';
+interface Transaction {
+    transactionId: string;
+    type: TransactionType;
+    status: TransactionStatus;
+    amount: number;
+    currency: string;
+    counterparty?: string;
+    memo?: string;
+    createdAt: string;
+    completedAt?: string;
+}
+interface TransactionListParams {
+    limit?: number;
+    customerFilter?: string;
+    offset?: number;
+    agentId?: string;
+    customerPartyId?: string;
+    /** Filter by transaction type (payment, transfer, or all) */
+    type?: TransactionTypeFilter;
+}
+
+/**
+ * Transactions resource.
+ */
+
+declare class TransactionsResource extends BaseResource {
+    /**
+     * List recent transactions.
+     *
+     * @param params - List parameters including agent context
+     * @returns List of Transaction objects
+     */
+    list(params?: TransactionListParams): Promise<Transaction[]>;
+}
+
+/**
+ * Agent types.
+ */
+type AgentStatus = 'ACTIVE' | 'REVOKED';
+interface Agent {
+    agentId: string;
+    id: string;
+    name: string;
+    description?: string;
+    status: AgentStatus;
+    partyId: string;
+    createdAt: string;
+    createdBy: string;
+    updatedAt: string;
+    updatedBy: string;
+}
+interface AgentCreateParams {
+    name: string;
+    partyId: string;
+    description?: string;
+    idempotencyKey?: string;
+}
+interface AgentCreateResponse {
+    agentId: string;
+    name: string;
+    description?: string;
+    status: AgentStatus;
+    partyId: string;
+    createdAt: string;
+    createdBy: string;
+}
+interface AgentUpdateParams {
+    name?: string;
+    description?: string;
+    status?: AgentStatus;
+    idempotencyKey?: string;
+}
+interface AgentUpdateResponse {
+    agentId: string;
+    name: string;
+    description?: string;
+    status: AgentStatus;
+    partyId: string;
+    updatedAt: string;
+    updatedBy: string;
+}
+interface AgentListParams {
+    status?: AgentStatus;
+    partyId?: string;
+    limit?: number;
+    offset?: number;
+}
+interface AgentListResponse {
+    agents: Agent[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+
+/**
+ * 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): 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)
+     */
+    delete(agentId: string): Promise<void>;
+}
+
+/**
+ * Delegation types.
+ */
+type DelegationStatus = 'ACTIVE' | 'SUSPENDED' | 'REVOKED';
+interface Delegation {
+    id: string;
+    handle: string;
+    delegatingPartyId: string;
+    delegatedPartyId: string;
+    permissions: string[];
+    expiresAt?: string;
+    status: string;
+    createdAt: string;
+    createdBy?: string;
+}
+interface DelegationListParams {
+    status?: DelegationStatus;
+    delegatingPartyId?: string;
+    delegatedPartyId?: string;
+}
+interface DelegationListResponse {
+    delegations: Delegation[];
+    total: number;
+}
+interface DelegationCreateParams {
+    delegatingPartyId: string;
+    delegatedPartyId: string;
+    permissions: string[];
+    expiresAt?: string;
+    idempotencyKey?: string;
+}
+interface DelegationUpdateParams {
+    status?: DelegationStatus;
+    permissions?: string[];
+    expiresAt?: string;
+}
+
+/**
+ * Delegations resource.
+ */
+
+declare class DelegationsResource extends BaseResource {
+    /**
+     * List delegations with optional filters.
+     *
+     * @param params - Filter parameters
+     * @returns DelegationListResponse with list of delegations
+     */
+    list(params?: DelegationListParams): Promise<DelegationListResponse>;
+    /**
+     * Get delegation by ID.
+     *
+     * @param delegationId - The delegation handle (dlg_xxx)
+     * @returns Delegation details
+     */
+    get(delegationId: string): Promise<Delegation>;
+    /**
+     * Create a new delegation (party-to-party trust relationship).
+     *
+     * @param params - Delegation creation parameters
+     * @returns Created Delegation
+     */
+    create(params: DelegationCreateParams): Promise<Delegation>;
+    /**
+     * Update an existing delegation.
+     *
+     * @param delegationId - Delegation handle (dlg_xxx)
+     * @param params - Update parameters
+     * @returns Updated Delegation
+     */
+    update(delegationId: string, params: DelegationUpdateParams): Promise<Delegation>;
+    /**
+     * Revoke a delegation (soft delete by setting status to REVOKED).
+     *
+     * @param delegationId - Delegation handle (dlg_xxx)
+     * @returns Revoked Delegation
+     */
+    revoke(delegationId: string): Promise<Delegation>;
+}
+
+/**
+ * Customer types.
+ */
+interface CustomerPartyInfo {
+    id: string;
+    handle?: string;
+    type: string;
+    legalName?: string;
+    displayName?: string;
+    status?: string;
+}
+interface Customer {
+    party: CustomerPartyInfo;
+    delegationId: string;
+    permissions: string[];
+    delegationStatus: string;
+    createdAt: string;
+}
+
+/**
+ * Customers resource.
+ */
+
+declare class CustomersResource extends BaseResource {
+    /**
+     * List customers onboarded by the partner via delegation.
+     *
+     * @returns List of Customer objects with party info and delegation details
+     */
+    list(): Promise<Customer[]>;
+}
+
+/**
+ * Natural Payments SDK client.
+ */
+
+interface NaturalClientOptions extends HTTPClientOptions {
+}
+/**
+ * Natural Payments SDK client.
+ *
+ * @example
+ * ```typescript
+ * import { NaturalClient } from 'naturalpay';
+ *
+ * const client = new NaturalClient({ apiKey: 'pk_sandbox_xxx' });
+ *
+ * // Create a payment
+ * const payment = await client.payments.create({
+ *   recipientEmail: 'alice@example.com',
+ *   amount: 50.00,
+ *   memo: 'For consulting',
+ * });
+ *
+ * // 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, transfers, deposits, and withdrawals. */
+    readonly wallet: WalletResource;
+    /** Transactions API resource. */
+    readonly transactions: TransactionsResource;
+    /** Agents API resource for managing agents. */
+    readonly agents: AgentsResource;
+    /** Delegations API resource for managing party-to-party delegations. */
+    readonly delegations: DelegationsResource;
+    /** Customers API resource for listing customers onboarded via delegation. */
+    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);
+}
+
+/**
+ * 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: 100 });
+ */
+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);
+}
+
+/**
+ * Natural Payments SDK - AI agent payment infrastructure.
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION = "0.0.1";
+
+export { type AccountBalance, type Agent, type AgentCreateParams, type AgentCreateResponse, type AgentListParams, type AgentListResponse, type AgentStatus, type AgentUpdateParams, type AgentUpdateResponse, type AmountInfo, type AssetBalance, AuthenticationError, type BalanceBreakdown, type CancellationResult, type Customer, type CustomerPartyInfo, type Delegation, type DelegationCreateParams, type DelegationListParams, type DelegationListResponse, type DelegationStatus, type DelegationUpdateParams, type DepositParams, type DepositResponse, InsufficientFundsError, InvalidRequestError, type LogLevel, Logger, NaturalClient, type NaturalClientOptions, NaturalError, type Payment, type PaymentCreateParams, PaymentError, RateLimitError, RecipientNotFoundError, ServerError, type Transaction, type TransactionListParams, type TransactionStatus, type TransactionType, TransactionTypeFilter, VERSION, type WithdrawParams, type WithdrawResponse, bindContext, clearContext, configureLogging, getContext, getLogger, logApiCall, logError, logToolCall, runWithContext };