@naturalpay/sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,676 @@
+/**
+ * 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, 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;
+}
+
+/**
+ * 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;
+    /** Developer's session/conversation ID for observability grouping. */
+    instanceId?: 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;
+}
+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;
+    /** Developer's session/conversation ID for observability grouping. */
+    instanceId?: 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;
+}
+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;
+    /** Developer's session/conversation ID for observability grouping. */
+    instanceId?: 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;
+    /** Developer's session/conversation ID for observability grouping. */
+    instanceId?: string;
+}
+/** @deprecated Use Agent instead — server returns full resource for all operations. */
+type AgentUpdateResponse = Agent;
+interface AgentListParams {
+    status?: AgentStatus;
+    limit?: number;
+    cursor?: string;
+    /** Developer's session/conversation ID for observability grouping. */
+    instanceId?: string;
+}
+interface AgentGetOptions {
+    /** Developer's session/conversation ID for observability grouping. */
+    instanceId?: string;
+}
+interface AgentDeleteOptions {
+    /** Developer's session/conversation ID for observability grouping. */
+    instanceId?: 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;
+}
+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;
+    /** Developer's session/conversation ID for observability grouping. */
+    instanceId?: 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';
+ *
+ * const client = new NaturalClient({ apiKey: 'sk_ntl_sandbox_xxx' });
+ *
+ * // 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);
+}
+
+/**
+ * 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);
+}
+
+/**
+ * Single source of truth for the SDK version string.
+ */
+declare const VERSION = "0.1.1";
+
+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, runWithContext };