@sardis/ramp 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,416 @@
+/**
+ * Type definitions for Sardis Fiat Ramp.
+ */
+type FundingMethod = 'bank' | 'card' | 'crypto';
+interface BankAccount {
+    accountHolderName: string;
+    accountNumber: string;
+    routingNumber: string;
+    accountType?: 'checking' | 'savings';
+    bankName?: string;
+    swiftCode?: string;
+    iban?: string;
+    bankAddress?: string;
+}
+interface MerchantAccount {
+    name: string;
+    bankAccount: BankAccount;
+    merchantId?: string;
+    category?: string;
+}
+interface ACHDetails {
+    accountNumber: string;
+    routingNumber: string;
+    bankName: string;
+    accountHolder: string;
+    reference: string;
+}
+interface WireDetails {
+    accountNumber: string;
+    routingNumber: string;
+    swiftCode: string;
+    bankName: string;
+    bankAddress: string;
+    accountHolder: string;
+    reference: string;
+}
+interface FundingResult {
+    type: 'crypto' | 'fiat';
+    depositAddress?: string;
+    chain?: string;
+    token?: string;
+    paymentLink?: string;
+    achInstructions?: ACHDetails;
+    wireInstructions?: WireDetails;
+    estimatedArrival?: Date;
+    feePercent?: number;
+    transferId?: string;
+}
+interface WithdrawalResult {
+    txHash: string;
+    payoutId: string;
+    estimatedArrival: Date;
+    fee: number;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+}
+interface PaymentResult {
+    status: 'completed' | 'pending_approval' | 'failed';
+    paymentId?: string;
+    merchantReceived?: number;
+    fee?: number;
+    txHash?: string;
+    approvalRequest?: Record<string, unknown>;
+    error?: string;
+}
+interface RampConfig {
+    /** Sardis API key (required) */
+    sardisKey: string;
+    /** Bridge API key (required) */
+    bridgeKey: string;
+    /** Environment - sandbox for testing, production for live (default: sandbox) */
+    environment?: 'sandbox' | 'production';
+    /** Default chain for new wallets */
+    defaultChain?: string;
+    /** Custom Sardis API URL (optional, for enterprise deployments) */
+    sardisUrl?: string;
+    /** Custom Bridge API URL (optional, for testing) */
+    bridgeUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface Wallet {
+    id: string;
+    address: string;
+    chain: string;
+    balance?: string;
+    policy?: string;
+}
+
+/**
+ * Sardis Fiat Ramp - Bridge integration for fiat on/off ramp.
+ */
+
+declare class SardisFiatRamp {
+    private readonly sardisKey;
+    private readonly bridgeKey;
+    private readonly bridgeUrl;
+    private readonly sardisUrl;
+    constructor(config: RampConfig);
+    private sardisRequest;
+    private bridgeRequest;
+    getWallet(walletId: string): Promise<Wallet>;
+    /**
+     * Fund a Sardis wallet from fiat sources.
+     *
+     * @example
+     * ```typescript
+     * const result = await ramp.fundWallet({
+     *   walletId: 'wallet_123',
+     *   amountUsd: 100,
+     *   method: 'bank'
+     * })
+     * console.log(result.achInstructions?.routingNumber)
+     * ```
+     */
+    fundWallet(params: {
+        walletId: string;
+        amountUsd: number;
+        method: FundingMethod;
+    }): Promise<FundingResult>;
+    /**
+     * Withdraw from Sardis wallet to bank account.
+     *
+     * @example
+     * ```typescript
+     * const result = await ramp.withdrawToBank({
+     *   walletId: 'wallet_123',
+     *   amountUsd: 50,
+     *   bankAccount: {
+     *     accountHolderName: 'John Doe',
+     *     accountNumber: '1234567890',
+     *     routingNumber: '021000021'
+     *   }
+     * })
+     * ```
+     */
+    withdrawToBank(params: {
+        walletId: string;
+        amountUsd: number;
+        bankAccount: BankAccount;
+    }): Promise<WithdrawalResult>;
+    /**
+     * Pay merchant in USD from crypto wallet.
+     *
+     * @example
+     * ```typescript
+     * const result = await ramp.payMerchantFiat({
+     *   walletId: 'wallet_123',
+     *   amountUsd: 99.99,
+     *   merchant: {
+     *     name: 'ACME Corp',
+     *     bankAccount: { ... }
+     *   }
+     * })
+     * ```
+     */
+    payMerchantFiat(params: {
+        walletId: string;
+        amountUsd: number;
+        merchant: MerchantAccount;
+    }): Promise<PaymentResult>;
+    /**
+     * Get status of a funding transfer.
+     */
+    getFundingStatus(transferId: string): Promise<unknown>;
+    /**
+     * Get status of a bank withdrawal.
+     */
+    getWithdrawalStatus(payoutId: string): Promise<unknown>;
+    private chainToBridge;
+}
+
+/**
+ * Sardis Onramper Integration
+ *
+ * Onramper is a fiat on-ramp aggregator that provides access to
+ * 100+ payment providers (Moonpay, Transak, Ramp, Simplex, etc.)
+ * through a single API/widget integration.
+ *
+ * @see https://docs.onramper.com
+ */
+interface OnramperConfig {
+    /** Onramper API key */
+    apiKey: string;
+    /** Sardis API key for wallet operations */
+    sardisKey: string;
+    /** Environment mode */
+    mode?: 'sandbox' | 'production';
+    /** Custom Sardis API URL */
+    sardisUrl?: string;
+    /** Default fiat currency */
+    defaultFiat?: string;
+    /** Default crypto */
+    defaultCrypto?: string;
+}
+interface OnramperQuote {
+    id: string;
+    provider: string;
+    providerLogo?: string;
+    sourceAmount: number;
+    sourceCurrency: string;
+    destinationAmount: number;
+    destinationCurrency: string;
+    rate: number;
+    fees: {
+        network: number;
+        provider: number;
+        total: number;
+    };
+    paymentMethod: string;
+    estimatedTime: string;
+    kycRequired: boolean;
+    expiresAt: string;
+}
+interface OnramperTransaction {
+    id: string;
+    externalId?: string;
+    provider: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed' | 'expired';
+    sourceAmount: number;
+    sourceCurrency: string;
+    destinationAmount: number;
+    destinationCurrency: string;
+    destinationAddress: string;
+    paymentMethod: string;
+    txHash?: string;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    failureReason?: string;
+}
+interface OnramperWidgetOptions {
+    /** Wallet address to receive crypto */
+    walletAddress: string;
+    /** Network/chain */
+    network?: string;
+    /** Fiat currency (default: USD) */
+    fiatCurrency?: string;
+    /** Crypto currency (default: USDC) */
+    cryptoCurrency?: string;
+    /** Fiat amount */
+    fiatAmount?: number;
+    /** Crypto amount */
+    cryptoAmount?: number;
+    /** Payment method filter */
+    paymentMethod?: 'creditCard' | 'debitCard' | 'bankTransfer' | 'applePay' | 'googlePay';
+    /** Color theme */
+    color?: string;
+    /** Dark mode */
+    darkMode?: boolean;
+    /** Supported providers filter */
+    onlyProviders?: string[];
+    /** Excluded providers */
+    excludeProviders?: string[];
+    /** Country filter (ISO 3166-1 alpha-2) */
+    country?: string;
+    /** Language */
+    language?: string;
+    /** Skip KYC intro */
+    skipIntro?: boolean;
+    /** Redirect URL after completion */
+    redirectUrl?: string;
+    /** Partner context for tracking */
+    partnerContext?: string;
+}
+interface SupportedAsset {
+    code: string;
+    name: string;
+    network: string;
+    symbol: string;
+    decimals: number;
+    minAmount: number;
+    maxAmount: number;
+}
+interface SupportedFiat {
+    code: string;
+    name: string;
+    symbol: string;
+    minAmount: number;
+    maxAmount: number;
+}
+declare class SardisOnramper {
+    private readonly apiKey;
+    private readonly sardisKey;
+    private readonly sardisUrl;
+    private readonly mode;
+    private readonly defaultFiat;
+    private readonly defaultCrypto;
+    constructor(config: OnramperConfig);
+    private onramperRequest;
+    private sardisRequest;
+    /**
+     * Get supported fiat currencies
+     */
+    getSupportedFiats(): Promise<SupportedFiat[]>;
+    /**
+     * Get supported crypto assets
+     */
+    getSupportedCryptos(network?: string): Promise<SupportedAsset[]>;
+    /**
+     * Get supported payment methods for a country
+     */
+    getSupportedPaymentMethods(country: string): Promise<string[]>;
+    /**
+     * Get quotes from all available providers
+     */
+    getQuotes(params: {
+        sourceCurrency: string;
+        destinationCurrency: string;
+        amount: number;
+        type?: 'fiat' | 'crypto';
+        paymentMethod?: string;
+        country?: string;
+        network?: string;
+    }): Promise<OnramperQuote[]>;
+    /**
+     * Get the best quote (lowest total cost)
+     */
+    getBestQuote(params: {
+        sourceCurrency: string;
+        destinationCurrency: string;
+        amount: number;
+        type?: 'fiat' | 'crypto';
+        paymentMethod?: string;
+        country?: string;
+        network?: string;
+    }): Promise<OnramperQuote | null>;
+    /**
+     * Generate widget URL for embedding or redirect
+     *
+     * @example
+     * ```typescript
+     * const url = onramper.getWidgetUrl({
+     *   walletAddress: '0x...',
+     *   fiatCurrency: 'USD',
+     *   cryptoCurrency: 'USDC',
+     *   fiatAmount: 100,
+     *   network: 'base',
+     * })
+     * window.open(url, '_blank')
+     * ```
+     */
+    getWidgetUrl(options: OnramperWidgetOptions): string;
+    /**
+     * Generate widget HTML for iframe embedding
+     */
+    getWidgetIframe(options: OnramperWidgetOptions & {
+        width?: string;
+        height?: string;
+    }): string;
+    /**
+     * Get transaction status by Onramper transaction ID
+     */
+    getTransaction(transactionId: string): Promise<OnramperTransaction>;
+    /**
+     * List transactions for a wallet address
+     */
+    listTransactions(walletAddress: string, options?: {
+        limit?: number;
+        offset?: number;
+        status?: OnramperTransaction['status'];
+    }): Promise<OnramperTransaction[]>;
+    /**
+     * Fund a Sardis wallet via Onramper widget
+     *
+     * Returns a widget URL that, when used, will deposit crypto
+     * directly to the Sardis wallet.
+     */
+    fundWallet(params: {
+        walletId: string;
+        fiatAmount?: number;
+        fiatCurrency?: string;
+        cryptoCurrency?: string;
+        paymentMethod?: string;
+        redirectUrl?: string;
+    }): Promise<{
+        widgetUrl: string;
+        walletAddress: string;
+        network: string;
+    }>;
+    /**
+     * Get best quote for funding a Sardis wallet
+     */
+    getWalletFundingQuote(params: {
+        walletId: string;
+        fiatAmount: number;
+        fiatCurrency?: string;
+        paymentMethod?: string;
+    }): Promise<OnramperQuote | null>;
+    /**
+     * Verify webhook signature from Onramper
+     */
+    verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
+    /**
+     * Parse webhook payload
+     */
+    parseWebhookPayload(payload: string): {
+        event: 'transaction.created' | 'transaction.completed' | 'transaction.failed';
+        transaction: OnramperTransaction;
+    };
+    private mapNetwork;
+}
+declare function createOnramper(config: OnramperConfig): SardisOnramper;
+
+/**
+ * Custom error classes for Sardis Fiat Ramp.
+ */
+declare class PolicyViolation extends Error {
+    constructor(message: string);
+}
+declare class RampError extends Error {
+    code: string;
+    details?: Record<string, unknown>;
+    constructor(message: string, code: string, details?: Record<string, unknown>);
+}
+
+export { type ACHDetails, type BankAccount, type FundingMethod, type FundingResult, type MerchantAccount, type OnramperConfig, type OnramperQuote, type OnramperTransaction, type OnramperWidgetOptions, type PaymentResult, PolicyViolation, type RampConfig, RampError, SardisFiatRamp, SardisOnramper, type SupportedAsset, type SupportedFiat, type Wallet, type WireDetails, type WithdrawalResult, createOnramper };