@aura-payments/sdk 2.1.0 → 2.2.0

package/dist/index.d.mts

@@ -558,6 +558,217 @@ declare class Escrows {
     getDispute(escrowId: string, disputeId: string): Promise<Dispute>;
 }
 
+/**
+ * Insights types for the Aura Payments SDK
+ *
+ * Mirrors the platform routes under `app/api/v1/insights/`:
+ *   GET /v1/insights/overview   KPIs for a period, with change vs the prior one
+ *   GET /v1/insights/forecast   ML forecast for a metric (Growth+ gated)
+ *   GET /v1/insights/audit      paginated audit log
+ *
+ * All three wrap their payload in `{data, meta}`, which the client unwraps, so
+ * these types describe the inner payload.
+ *
+ * `POST /v1/insights/audit/export` is not modelled: it returns an async job id
+ * that must be polled and then downloaded — a multi-step flow of its own.
+ */
+/** Period selector shared by the overview and audit routes. */
+type InsightsPeriod = 'today' | '7d' | '30d' | '90d' | 'custom';
+/** A KPI with its change against the previous period. */
+interface MetricValue {
+    value: number;
+    /** Percentage change vs the previous period. */
+    change: number;
+    previousValue: number;
+}
+interface SparklinePoint {
+    /** ISO 8601 datetime. */
+    timestamp: string;
+    value: number;
+}
+interface VolumeBarPoint {
+    label: string;
+    value: number;
+    count: number;
+}
+interface InsightsOverview {
+    /** Resolved window for the requested period; both ISO 8601 datetimes. */
+    period: {
+        start: string;
+        end: string;
+    };
+    metrics: {
+        revenue: MetricValue;
+        transactions: MetricValue;
+        activeEscrows: MetricValue;
+        commissions: MetricValue;
+    };
+    charts: {
+        revenueSparkline: SparklinePoint[];
+        volumeBar: VolumeBarPoint[];
+        /** Fraction between 0 and 1 (e.g. 0.982). */
+        successRate: number;
+    };
+}
+/** Metrics the forecast route can project. */
+type ForecastMetric = 'revenue' | 'transaction_count' | 'escrow_count' | 'commission' | 'avg_transaction_value';
+/** Forecasting algorithms accepted by the route (it validates an enum). */
+type ForecastAlgorithm = 'linear_regression' | 'moving_average' | 'exponential_smoothing' | 'arima' | 'prophet' | 'ensemble';
+type ForecastPeriod = 'daily' | 'weekly' | 'monthly';
+interface ForecastParams {
+    metric: ForecastMetric;
+    algorithm?: ForecastAlgorithm;
+    period?: ForecastPeriod;
+    /** Number of periods to project (1–365). */
+    horizon?: number;
+    includeHistory?: boolean;
+    /** Historical periods to include (1–365). */
+    historyPeriods?: number;
+}
+interface TimeSeriesPoint {
+    /** ISO 8601 datetime. */
+    timestamp: string;
+    value: number;
+    label?: string;
+}
+interface ForecastPoint {
+    /** ISO 8601 date (YYYY-MM-DD). */
+    date: string;
+    predicted: number;
+    /** 5th percentile. */
+    lowerBound: number;
+    /** 95th percentile. */
+    upperBound: number;
+    /** Present when the date is in the past, for accuracy tracking. */
+    actual?: number;
+}
+interface ForecastSeries {
+    metric: ForecastMetric;
+    algorithm: ForecastAlgorithm;
+    period: ForecastPeriod;
+    /** e.g. 0.95 for a 95% confidence interval. */
+    confidenceLevel: number;
+    historical: TimeSeriesPoint[];
+    forecast: ForecastPoint[];
+    accuracy: {
+        mape: number;
+        r2: number;
+        trainingPoints: number;
+    };
+    /** ISO 8601 datetime. */
+    generatedAt: string;
+}
+interface ForecastProjection {
+    predicted: number;
+    lowerBound: number;
+    upperBound: number;
+}
+interface ForecastSummary {
+    currentPeriod: {
+        value: number;
+        isActual: boolean;
+        changeFromPrevious: number;
+    };
+    nextPeriod: ForecastProjection;
+    next30Days: ForecastProjection;
+    next90Days: ForecastProjection;
+    /** A qualitative band, not a number. */
+    modelConfidence: 'high' | 'medium' | 'low';
+    trend: 'up' | 'down' | 'stable';
+}
+interface ForecastResult {
+    forecast: ForecastSeries;
+    summary: ForecastSummary;
+}
+/** Who or what performed an audited action. */
+type AuditActor = 'user' | 'system' | 'api' | 'cron' | 'webhook';
+interface AuditParams {
+    action?: string;
+    actor?: AuditActor;
+    resourceType?: string;
+    resourceId?: string;
+    /** Defaults to `30d` server-side. */
+    range?: InsightsPeriod;
+    /** ISO 8601 datetime; required together with `end` when `range` is `custom`. */
+    start?: string;
+    /** ISO 8601 datetime; required together with `start` when `range` is `custom`. */
+    end?: string;
+    /** 1-based page number. */
+    page?: number;
+    /** Page size, 1–100 (default 50). */
+    limit?: number;
+}
+interface AuditEntry {
+    id: string;
+    action: string;
+    actor: AuditActor;
+    actorId?: string;
+    actorName?: string;
+    resourceType: string;
+    resourceId: string;
+    description: string;
+    amountUsdc?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    /** ISO 8601 datetime. */
+    timestamp: string;
+    /** Checksum linking this entry to the previous one. */
+    checksum: string;
+    previousChecksum?: string;
+    /** Monotonic per-account sequence number; absent on pre-backfill rows. */
+    sequenceNo?: number;
+}
+interface AuditSummary {
+    totalEntries: number;
+    byAction: Record<string, number>;
+    byActor: Record<AuditActor, number>;
+    last24Hours: number;
+    chainIntegrityIssues: number;
+    /** ISO 8601 datetime. */
+    lastVerified?: string;
+}
+interface AuditResult {
+    items: AuditEntry[];
+    total: number;
+    page: number;
+    limit: number;
+    hasMore: boolean;
+    cursor?: string;
+    summary: AuditSummary;
+}
+
+/**
+ * Insights resource for Aura Payments SDK
+ *
+ * Read-only analytics. `POST /v1/insights/audit/export` is intentionally absent:
+ * it returns an async job id that must be polled and then downloaded, which is a
+ * multi-step flow rather than a single call.
+ */
+
+declare class Insights {
+    private client;
+    constructor(client: AuraClient);
+    /**
+     * Revenue, transactions, active escrows and commissions for a period, each
+     * with its change against the prior period.
+     *
+     * The route defaults to `7d`. `start` and `end` are ISO 8601 datetimes and are
+     * both required when `period` is `'custom'`.
+     */
+    overview(period?: InsightsPeriod, start?: string, end?: string): Promise<InsightsOverview>;
+    /**
+     * Forecast a metric over a horizon. Gated to Growth+ plans; lower tiers
+     * surface a 403 `AuraAPIError`.
+     */
+    forecast(params: ForecastParams): Promise<ForecastResult>;
+    /**
+     * Query the account audit log by action, actor, resource and date range.
+     *
+     * The route defaults to `range: '30d'`, `page: 1`, `limit: 50`.
+     */
+    audit(params?: AuditParams): Promise<AuditResult>;
+}
+
 /**
  * Mandate types for Aura Payments SDK.
  *
@@ -807,6 +1018,64 @@ declare class Policies {
     create(params: CreatePolicyParams, idempotencyKey?: string): Promise<AgentPolicy>;
 }
 
+/**
+ * Treasury types for the Aura Payments SDK
+ *
+ * Mirrors `POST /v1/treasury/optimize`, which returns an AI recommendation over
+ * the account's wallet balances and escrow exposure. The route is snake_case and
+ * — unlike the rest of the API — reports balances as JSON **numbers**, not
+ * decimal strings, because it sums Circle balances with `parseFloat` and returns
+ * the raw values. Treat them as display figures, never as settlement amounts.
+ *
+ * `POST /v1/treasury/batch` is deliberately not modelled: it executes 1–10 real
+ * transfers and needs a dedicated confirm/preview flow, not a bare method call.
+ */
+interface TreasuryWallet {
+    id: string;
+    address: string;
+    chain: string;
+    /** USDC balance as a number (see the module note on precision). */
+    balance: number;
+}
+interface TreasuryRecommendation {
+    action: string;
+    reasoning: string;
+    confidence: number;
+}
+interface TreasuryOptimization {
+    /** Total USDC across all non-escrow wallets. */
+    treasury_balance: number;
+    /** USDC locked in funded/locked escrows. */
+    pending_payouts: number;
+    /** `treasury_balance` minus `pending_payouts`. */
+    available: number;
+    active_escrows: number;
+    wallets: TreasuryWallet[];
+    recommendation: TreasuryRecommendation;
+}
+
+/**
+ * Treasury resource for Aura Payments SDK
+ *
+ * Read-only analysis surface. `POST /v1/treasury/batch` (bulk transfers) is
+ * intentionally absent — it moves real money across 1–10 recipients and needs a
+ * dedicated confirm/preview flow rather than a single method call.
+ */
+
+declare class Treasury {
+    private client;
+    constructor(client: AuraClient);
+    /**
+     * Analyze treasury balances, escrow exposure and pending payouts, and return
+     * an AI recommendation. Moves no funds.
+     *
+     * A POST with no body — the platform derives everything from the authenticated
+     * account. Gated to Growth+ plans; lower tiers surface a 403 `AuraAPIError`
+     * with code `feature_not_available`.
+     */
+    optimize(): Promise<TreasuryOptimization>;
+}
+
 /**
  * Wallet types for Aura Payments SDK
  * Public API types for external developers
@@ -1093,11 +1362,208 @@ declare class Webhooks {
      */
     private static computeHmacSignature;
     /**
-     * Constant-time string comparison
+     * Constant-time comparison of two hex signatures.
+     *
+     * Length is compared first because `timingSafeEqual` throws on mismatched
+     * buffers; that only reveals the length of an attacker-supplied signature,
+     * never the contents of the expected one.
      */
     private static secureCompare;
 }
 
+/**
+ * Withdrawal types for the Aura Payments SDK
+ *
+ * Mirrors the platform routes under `app/api/v1/withdrawals/`:
+ *   GET  /v1/withdrawals            list (returns the whole {withdrawals,pagination} wrapper)
+ *   GET  /v1/withdrawals/:id        get
+ *   POST /v1/withdrawals/estimate   fee/net-amount preview (no money moves)
+ *   GET  /v1/withdrawals/limits     KYC-tier limits ({success,data} — SDK returns `data`)
+ *   POST /v1/withdrawals/validate   destination address validation (no money moves)
+ *
+ * `POST /v1/withdrawals` (create) is deliberately NOT modelled here: the route is
+ * behind `stepUpGuard({maxAge:'5m'})`, which an API-key client cannot satisfy.
+ */
+/** Blockchain networks accepted by the withdrawal routes. */
+type WithdrawalChain = 'ARC' | 'ETH' | 'BASE' | 'ARB' | 'MATIC';
+/** Where the funds land: a CEX deposit address or a self-custody wallet. */
+type WithdrawalDestinationType = 'exchange' | 'wallet';
+/** Platform fee configuration applied to the withdrawal. */
+type WithdrawalFeeConfig = 'FREE' | 'GAS_ONLY' | 'STANDARD';
+/** Exchange hint used for deposit-address heuristics and warnings. */
+type WithdrawalExchange = 'binance' | 'coinbase' | 'kraken' | 'other';
+/** Withdrawal lifecycle: pending → submitted → confirmed | failed (or cancelled). */
+type WithdrawalStatus = 'pending' | 'submitted' | 'confirmed' | 'failed' | 'cancelled';
+/** Classification of a destination address. */
+type WithdrawalAddressType = 'eoa' | 'contract' | 'unknown';
+/** Split of the platform fee into its gas-coverage and margin components. */
+interface WithdrawalFeeBreakdown {
+    gasComponent: string;
+    platformComponent: string;
+}
+interface Withdrawal {
+    id: string;
+    status: WithdrawalStatus;
+    amount: string;
+    netAmount: string;
+    platformFee: string;
+    destinationAddress: string;
+    chain: WithdrawalChain;
+    exchange?: WithdrawalExchange;
+    circleTransferId?: string;
+    txHash?: string;
+    estimatedConfirmation?: string;
+    confirmedAt?: string;
+    failureReason?: string;
+    feeBreakdown?: WithdrawalFeeBreakdown;
+    createdAt: string;
+}
+interface ListWithdrawalsParams {
+    /** Page size. The route clamps this to a maximum of 100 (default 50). */
+    limit?: number;
+    offset?: number;
+    status?: WithdrawalStatus;
+    chain?: WithdrawalChain;
+    /** ISO 8601 datetime. */
+    fromDate?: string;
+    /** ISO 8601 datetime. */
+    toDate?: string;
+}
+interface ListWithdrawalsResponse {
+    withdrawals: Withdrawal[];
+    pagination: {
+        limit: number;
+        offset: number;
+        count: number;
+        hasMore: boolean;
+    };
+}
+/**
+ * Estimate request.
+ *
+ * `exchange` is REQUIRED by the route whenever `destinationType` is `'exchange'`
+ * (the route validates a discriminated union), and is ignored for `'wallet'`.
+ * `sourceChain` defaults to `ARC`; a source ≠ destination pair is bridged via CCTP
+ * and only the supported routes (ARC → BASE/ETH/SOL) are accepted.
+ */
+interface EstimateWithdrawalParams {
+    walletId: string;
+    /** USDC amount, up to 6 decimals (e.g. "100.00"). */
+    amount: string;
+    destinationType: WithdrawalDestinationType;
+    /** EVM address: 0x + 40 hex chars. */
+    destinationAddress: string;
+    chain: WithdrawalChain;
+    exchange?: WithdrawalExchange;
+    sourceChain?: WithdrawalChain;
+    feeConfig?: WithdrawalFeeConfig;
+}
+interface WithdrawalEstimate {
+    requestedAmount: string;
+    platformFee: string;
+    /** Only set for cross-chain (CCTP) transfers. */
+    bridgeFee: string | null;
+    networkFee: string;
+    totalFees: string;
+    netAmount: string;
+    /** ISO 8601 datetime. */
+    estimatedConfirmationTime: string;
+    estimatedMinutes: number;
+    chain: WithdrawalChain;
+    sourceChain: WithdrawalChain;
+    needsBridge: boolean;
+    destinationType: WithdrawalDestinationType;
+    feeBreakdown: WithdrawalFeeBreakdown & {
+        bridgeComponent: string | null;
+    };
+}
+interface WithdrawalLimits {
+    kycTier: string;
+    limits: {
+        daily: string;
+        monthly: string;
+        perTransaction: string;
+        minimum: string;
+    };
+    used: {
+        daily: string;
+        monthly: string;
+    };
+    remaining: {
+        daily: string;
+        monthly: string;
+    };
+}
+interface ValidateWithdrawalParams {
+    /** EVM address: 0x + 40 hex chars. */
+    address: string;
+    chain: WithdrawalChain;
+    /** When provided, the response includes a `feePreview`. */
+    amount?: string;
+    feeConfig?: WithdrawalFeeConfig;
+}
+/** Fee preview returned by `validate` when an `amount` was supplied. */
+interface WithdrawalFeePreview {
+    requestedAmount: string;
+    fixedFee: string;
+    percentageFee: string;
+    totalFee: string;
+    netAmount: string;
+    breakdown: WithdrawalFeeBreakdown;
+}
+interface WithdrawalValidation {
+    isValid: boolean;
+    chain: WithdrawalChain;
+    addressType: WithdrawalAddressType;
+    detectedExchange?: WithdrawalExchange;
+    warnings: string[];
+    checksumAddress?: string;
+    /** `null` unless `amount` was passed to `validate`. */
+    feePreview?: WithdrawalFeePreview | null;
+}
+
+/**
+ * Withdrawals resource for Aura Payments SDK
+ *
+ * Read + estimate surface only. `POST /v1/withdrawals` (create) is intentionally
+ * absent: the platform route is guarded by `stepUpGuard({maxAge:'5m'})`, which
+ * requires a session younger than five minutes. An API-key client can never
+ * satisfy that, so exposing create here would ship a method that always 401s.
+ */
+
+declare class Withdrawals {
+    private client;
+    constructor(client: AuraClient);
+    /**
+     * Get a single withdrawal, including status, fees, destination and tx hash.
+     */
+    get(withdrawalId: string): Promise<Withdrawal>;
+    /**
+     * List withdrawals for the account, most recent first.
+     *
+     * Returns the whole `{withdrawals, pagination}` envelope — this route does not
+     * use the `{success,data}` wrapper, so pagination metadata is preserved.
+     */
+    list(params?: ListWithdrawalsParams): Promise<ListWithdrawalsResponse>;
+    /**
+     * Preview fees and net amount for a withdrawal WITHOUT creating it.
+     *
+     * `params.exchange` is required by the route when `destinationType` is
+     * `'exchange'`; cross-chain estimates (source ≠ destination) add a CCTP
+     * bridge fee and only the supported routes are accepted.
+     */
+    estimate(params: EstimateWithdrawalParams): Promise<WithdrawalEstimate>;
+    /**
+     * Get the account's KYC-tier withdrawal limits and remaining allowance.
+     */
+    limits(): Promise<WithdrawalLimits>;
+    /**
+     * Validate a destination address for a chain. Moves no funds; when `amount` is
+     * supplied the response also carries a fee preview.
+     */
+    validate(params: ValidateWithdrawalParams): Promise<WithdrawalValidation>;
+}
+
 /**
  * Aura Payments SDK Client
  * Main entry point for interacting with the Aura Payments Platform API
@@ -1151,6 +1617,9 @@ declare class AuraClient {
     readonly agents: Agents;
     readonly policies: Policies;
     readonly mandates: Mandates;
+    readonly withdrawals: Withdrawals;
+    readonly treasury: Treasury;
+    readonly insights: Insights;
     constructor(config: AuraClientConfig);
     /**
      * Normalize the base URL so resource paths like `/v1/escrow` reach the
@@ -1289,4 +1758,4 @@ declare function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries?: number,
  */
 declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutMessage?: string): Promise<T>;
 
-export { type Agent, type AgentBalance, type AgentPolicy, type AgentRiskTier, type AgentStatus, type AgentStatusResponse, type AgentType, Agents, type ApproveMandateParams, AuraAPIError, AuraAuthenticationError, AuraClient, type AuraClientConfig, AuraError, AuraFaucetUnavailableError, AuraNetworkError, AuraNotFoundError, AuraRateLimitError, AuraTimeoutError, AuraValidationError, type Chain, type ConfigureWebhookParams, type CreateAgentParams, type CreateAgentResponse, type CreateDisputeParams, type CreateEscrowParams, type CreateEscrowResponse, type CreatePolicyParams, type CreateWalletParams, type Dispute, type DisputeStatus, type Escrow, type EscrowListItem, type EscrowSortBy, type EscrowSplitInput, type EscrowSplitResponse, type EscrowState, Escrows, type EvaluatePolicyParams, type EvaluatePolicyResponse, type FreezeAgentParams, type FundEscrowParams, type InitialPolicyInput, type ListAgentsParams, type ListAgentsResponse, type ListEscrowsParams, type ListEscrowsResponse, type ListMandatesParams, type ListMandatesResponse, type ListPoliciesResponse, type ListWalletsParams, type ListWalletsResponse, type Mandate, type MandateDecisionMethod, type MandateIntent, type MandateIntentKind, MandateSignature, type MandateStatus, Mandates, type MerchantDestinationType, type MerchantRule, type MerchantRuleInput, type MerchantRuleType, type OwnerType, Policies, type PolicyDecision, type ReceiveAndSplitFundingRequired, type ReceiveAndSplitParams, type ReceiveAndSplitResult, type ReceiveAndSplitStage, type RefundEscrowParams, type RejectMandateParams, type ReleaseEscrowParams, type RequestTestnetFundsParams, type RequestTestnetFundsResponse, type SpendingLimit, type SpendingLimitInput, type SpendingLimitType, type SplitRole, type TokenBalance, type Transfer, type TransferParams, type UnfreezeAgentParams, type UnlockType, type UpdateAgentParams, type ValidateWebhookSignatureOptions, type Wallet, type WalletBalance, type WalletOwnerType, Wallets, type WebhookConfig, type WebhookEvent, type WebhookEventType, type WebhookValidationResult, Webhooks, calculateBackoff, generateIdempotencyKey, isAuraAPIError, isAuraError, isAuraFaucetUnavailableError, isAuraNetworkError, isAuraTimeoutError, isRetryableError, retryWithBackoff, withTimeout };
+export { type Agent, type AgentBalance, type AgentPolicy, type AgentRiskTier, type AgentStatus, type AgentStatusResponse, type AgentType, Agents, type ApproveMandateParams, type AuditActor, type AuditEntry, type AuditParams, type AuditResult, type AuditSummary, AuraAPIError, AuraAuthenticationError, AuraClient, type AuraClientConfig, AuraError, AuraFaucetUnavailableError, AuraNetworkError, AuraNotFoundError, AuraRateLimitError, AuraTimeoutError, AuraValidationError, type Chain, type ConfigureWebhookParams, type CreateAgentParams, type CreateAgentResponse, type CreateDisputeParams, type CreateEscrowParams, type CreateEscrowResponse, type CreatePolicyParams, type CreateWalletParams, type Dispute, type DisputeStatus, type Escrow, type EscrowListItem, type EscrowSortBy, type EscrowSplitInput, type EscrowSplitResponse, type EscrowState, Escrows, type EstimateWithdrawalParams, type EvaluatePolicyParams, type EvaluatePolicyResponse, type ForecastAlgorithm, type ForecastMetric, type ForecastParams, type ForecastPeriod, type ForecastPoint, type ForecastProjection, type ForecastResult, type ForecastSeries, type ForecastSummary, type FreezeAgentParams, type FundEscrowParams, type InitialPolicyInput, Insights, type InsightsOverview, type InsightsPeriod, type ListAgentsParams, type ListAgentsResponse, type ListEscrowsParams, type ListEscrowsResponse, type ListMandatesParams, type ListMandatesResponse, type ListPoliciesResponse, type ListWalletsParams, type ListWalletsResponse, type ListWithdrawalsParams, type ListWithdrawalsResponse, type Mandate, type MandateDecisionMethod, type MandateIntent, type MandateIntentKind, MandateSignature, type MandateStatus, Mandates, type MerchantDestinationType, type MerchantRule, type MerchantRuleInput, type MerchantRuleType, type MetricValue, type OwnerType, Policies, type PolicyDecision, type ReceiveAndSplitFundingRequired, type ReceiveAndSplitParams, type ReceiveAndSplitResult, type ReceiveAndSplitStage, type RefundEscrowParams, type RejectMandateParams, type ReleaseEscrowParams, type RequestTestnetFundsParams, type RequestTestnetFundsResponse, type SparklinePoint, type SpendingLimit, type SpendingLimitInput, type SpendingLimitType, type SplitRole, type TimeSeriesPoint, type TokenBalance, type Transfer, type TransferParams, Treasury, type TreasuryOptimization, type TreasuryRecommendation, type TreasuryWallet, type UnfreezeAgentParams, type UnlockType, type UpdateAgentParams, type ValidateWebhookSignatureOptions, type ValidateWithdrawalParams, type VolumeBarPoint, type Wallet, type WalletBalance, type WalletOwnerType, Wallets, type WebhookConfig, type WebhookEvent, type WebhookEventType, type WebhookValidationResult, Webhooks, type Withdrawal, type WithdrawalAddressType, type WithdrawalChain, type WithdrawalDestinationType, type WithdrawalEstimate, type WithdrawalExchange, type WithdrawalFeeBreakdown, type WithdrawalFeeConfig, type WithdrawalFeePreview, type WithdrawalLimits, type WithdrawalStatus, type WithdrawalValidation, Withdrawals, calculateBackoff, generateIdempotencyKey, isAuraAPIError, isAuraError, isAuraFaucetUnavailableError, isAuraNetworkError, isAuraTimeoutError, isRetryableError, retryWithBackoff, withTimeout };