swapped-commerce-sdk 1.0.0

package/src/types/index.ts

@@ -0,0 +1,93 @@
+/**
+ * Type exports for Swapped Commerce SDK
+ */
+
+// Common types
+export type {
+  SwappedConfig,
+  RequiredSwappedConfig,
+  ApiResponse,
+  PaginationParams,
+  PaginationResponse,
+  HttpConfig,
+} from './common'
+
+// Currency types
+export type {
+  CurrencyType,
+  CurrencyFlow,
+  Blockchain,
+  Currency,
+} from './currencies'
+
+// Quote types
+export type {
+  MoneyAmount,
+  Fee,
+  Quote,
+  GetQuoteParams,
+  QuoteResponse,
+} from './quotes'
+
+// Payment types
+export type {
+  DepositAddress,
+  Payment,
+  Purchase,
+  PurchaseInput,
+  PreferredPayCurrency,
+  OrderMetadataInput,
+  CreateLinkParams,
+  PaymentLinkResponse,
+  CreateRouteParams,
+  PaymentRouteResponse,
+} from './payments'
+
+// Order types
+export type {
+  OrderInitType,
+  OrderStatus,
+  OrderMetadata,
+  OrderUpdate,
+  Settlement,
+  Order,
+  ListOrdersParams,
+  OrdersResponse,
+  RefundParams,
+  RefundResponse,
+} from './orders'
+
+// Balance types
+export type {
+  Balance,
+  ListBalancesParams,
+  BalancesResponse,
+} from './balances'
+
+// Payout types
+export type {
+  BankDestination,
+  CryptoDestination,
+  PayoutStatus,
+  Payout,
+  CreatePayoutParams,
+  CreatePayoutResponse,
+  PayoutsResponse,
+} from './payouts'
+
+// KYC types
+export type {
+  KYCStatus,
+  Address,
+  DocumentType,
+  Document,
+  KYCStatusResponse,
+  SubmitKYCParams,
+  SubmitKYCResponse,
+} from './kyc'
+
+// Webhook types
+export type {
+  WebhookEventType,
+  WebhookEvent,
+} from './webhooks'

package/src/types/kyc.ts

@@ -0,0 +1,65 @@
+/**
+ * KYC status
+ */
+export type KYCStatus = 'NOT_STARTED' | 'PENDING' | 'APPROVED' | 'REJECTED'
+
+/**
+ * Address information
+ */
+export interface Address {
+  readonly street: string
+  readonly city: string
+  readonly state?: string
+  readonly postalCode: string
+  readonly country: string
+}
+
+/**
+ * Document type
+ */
+export type DocumentType =
+  | 'PASSPORT'
+  | 'DRIVERS_LICENSE'
+  | 'ID_CARD'
+  | 'PROOF_OF_ADDRESS'
+
+/**
+ * Document information
+ */
+export interface Document {
+  readonly type: DocumentType
+  readonly frontImage: string // Base64 or URL
+  readonly backImage?: string
+}
+
+/**
+ * Response for KYC status
+ */
+export interface KYCStatusResponse {
+  readonly customerId: string
+  readonly status: KYCStatus
+  readonly submittedAt?: string
+  readonly reviewedAt?: string
+  readonly rejectionReason?: string
+}
+
+/**
+ * Parameters for submitting KYC
+ */
+export interface SubmitKYCParams {
+  readonly customerId: string
+  readonly firstName: string
+  readonly lastName: string
+  readonly dateOfBirth: string
+  readonly nationality: string
+  readonly address: Address
+  readonly documents: readonly Document[]
+}
+
+/**
+ * Response for submitting KYC
+ */
+export interface SubmitKYCResponse {
+  readonly submissionId: string
+  readonly status: string
+}

package/src/types/orders.ts

@@ -0,0 +1,122 @@
+import type { Currency } from './currencies'
+import type { Quote } from './quotes'
+import type { DepositAddress, Payment, Purchase } from './payments'
+
+/**
+ * Order initialization type
+ */
+export type OrderInitType = 'STANDARD' | 'INVOICE' | 'PAYMENT_ROUTE'
+
+/**
+ * Order status
+ */
+export type OrderStatus =
+  | 'PENDING_USER_CREATION'
+  | 'PENDING_CURRENCY_SELECTION'
+  | 'AWAITING_PAYMENT'
+  | 'PAYMENT_CONFIRMED_ACCURATE'
+  | 'PAYMENT_CONFIRMED_UNDERPAID'
+  | 'PAYMENT_CONFIRMED_OVERPAID'
+  | 'COMPLETED'
+  | 'EXPIRED'
+  | 'CANCELLED'
+
+/**
+ * Order metadata
+ */
+export interface OrderMetadata {
+  readonly externalId?: string
+  readonly userId?: string
+  readonly customerId?: string
+  readonly userName?: string
+  readonly customerName?: string
+  readonly userLang?: string
+  readonly customerLang?: string
+  readonly userCountry?: string
+  readonly customerCountry?: string
+  readonly userEmail?: string
+  readonly customerEmail?: string
+  readonly redirectUrl?: string
+}
+
+/**
+ * Order update
+ */
+export interface OrderUpdate {
+  readonly id: string
+  readonly message: string
+  readonly entityType: string
+  readonly authorId: string
+  readonly metadata: Readonly<Record<string, unknown>>
+  readonly timestamp: string
+}
+
+/**
+ * Settlement information
+ */
+export interface Settlement {
+  readonly id: string
+  readonly type: string
+  readonly status: string
+}
+
+/**
+ * Complete order information
+ */
+export interface Order {
+  readonly id: string
+  readonly link: string
+  readonly externalId: string
+  readonly userId: string
+  readonly customerId: string
+  readonly merchant: {
+    readonly id: string
+  }
+  readonly initType: OrderInitType
+  readonly quote: Quote
+  readonly depositAddress: DepositAddress
+  readonly settlements: readonly Settlement[]
+  readonly payments: readonly Payment[]
+  readonly expiresAt: string
+  readonly createdAt: string
+  readonly status: OrderStatus
+  readonly purchase?: Purchase
+  readonly updates: readonly OrderUpdate[]
+  readonly metadata: OrderMetadata
+  readonly preferredPayCurrency?: Currency
+}
+
+/**
+ * Parameters for listing orders
+ */
+export interface ListOrdersParams {
+  readonly page?: number
+  readonly limit?: number
+  readonly searchId?: string
+  readonly startDate?: number
+  readonly endDate?: number
+  readonly type?: OrderInitType
+}
+
+/**
+ * Response for listing orders
+ */
+export interface OrdersResponse {
+  readonly orders: readonly Order[]
+  readonly pagination: import('./common').PaginationResponse
+}
+
+/**
+ * Parameters for refunding an order
+ */
+export interface RefundParams {
+  readonly amount?: string
+  readonly reason?: string
+}
+
+/**
+ * Response for refund operation
+ */
+export interface RefundResponse {
+  readonly refundId: string
+}

package/src/types/payments.ts

@@ -0,0 +1,115 @@
+import type { Currency } from './currencies'
+import type { Quote } from './quotes'
+
+/**
+ * Deposit address for payments
+ */
+export interface DepositAddress {
+  readonly id: string
+  readonly address: string
+  readonly available: boolean
+  readonly memo?: string
+  readonly supportedCurrencies: readonly Currency[]
+}
+
+/**
+ * Payment information
+ */
+export interface Payment {
+  readonly id: string
+  readonly orderId: string
+  readonly receivedAmount: string
+  readonly receivedCurrency: Currency
+  readonly txHash: string
+  readonly confirmedAt: string
+  readonly status: string
+  readonly createdAt: string
+  readonly depositAddress: DepositAddress
+  readonly sourceAddress: string
+  readonly fireblocksTxId?: string
+}
+
+/**
+ * Purchase information
+ */
+export interface Purchase {
+  readonly id: string
+  readonly name: string
+  readonly notes?: string
+  readonly imageUrl?: string
+  readonly price: string
+  readonly currency: Currency
+  readonly rateMerchantOverOrder: string
+}
+
+/**
+ * Purchase object for order creation
+ */
+export interface PurchaseInput {
+  readonly name: string
+  readonly description?: string
+  readonly notes?: string
+  readonly imageUrl?: string
+  readonly price: string
+  readonly currency: string
+}
+
+/**
+ * Preferred payment currency
+ */
+export interface PreferredPayCurrency {
+  readonly symbol: string
+  readonly blockchain: string
+}
+
+/**
+ * Order metadata
+ */
+export interface OrderMetadataInput {
+  readonly externalId?: string
+  readonly customerId?: string
+  readonly customerCountry?: string
+  readonly customerName?: string
+  readonly customerLang?: string
+  readonly customerEmail?: string
+  readonly redirectUrl?: string
+}
+
+/**
+ * Parameters for creating a payment link/order
+ */
+export interface CreateLinkParams {
+  readonly purchase: PurchaseInput
+  readonly metadata?: OrderMetadataInput
+  readonly testMode?: boolean
+  readonly preferredPayCurrency?: PreferredPayCurrency
+}
+
+/**
+ * Response for creating a payment link
+ */
+export interface PaymentLinkResponse {
+  readonly orderId: string
+  readonly paymentLink: string
+}
+
+/**
+ * Parameters for creating a payment route
+ */
+export interface CreateRouteParams {
+  readonly purchaseAmount: string
+  readonly purchaseCurrency: string
+  readonly preferredPayCurrency?: string
+  readonly externalId?: string
+  readonly customerId?: string
+  readonly metadata?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Response for creating a payment route
+ */
+export interface PaymentRouteResponse {
+  readonly orderId: string
+  readonly depositAddress: DepositAddress
+  readonly quote: Quote
+}

package/src/types/payouts.ts

@@ -0,0 +1,68 @@
+import type { Currency } from './currencies'
+
+/**
+ * Bank destination for payouts
+ */
+export interface BankDestination {
+  readonly accountNumber: string
+  readonly routingNumber?: string
+  readonly iban?: string
+  readonly swift?: string
+  readonly accountHolderName: string
+}
+
+/**
+ * Crypto destination for payouts
+ */
+export interface CryptoDestination {
+  readonly address: string
+  readonly blockchain: string
+  readonly memo?: string
+}
+
+/**
+ * Payout status
+ */
+export type PayoutStatus = 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED'
+
+/**
+ * Payout information
+ */
+export interface Payout {
+  readonly id: string
+  readonly amount: string
+  readonly currency: Currency
+  readonly destination: BankDestination | CryptoDestination
+  readonly status: PayoutStatus
+  readonly createdAt: string
+  readonly completedAt?: string
+  readonly failureReason?: string
+}
+
+/**
+ * Parameters for creating a payout
+ */
+export interface CreatePayoutParams {
+  readonly amount: string
+  readonly currency: string
+  readonly destinationType: 'BANK' | 'CRYPTO'
+  readonly destination: BankDestination | CryptoDestination
+  readonly reference?: string
+}
+
+/**
+ * Response for creating a payout
+ */
+export interface CreatePayoutResponse {
+  readonly payoutId: string
+  readonly status: string
+  readonly estimatedArrival: string
+}
+
+/**
+ * Response for listing payouts
+ */
+export interface PayoutsResponse {
+  readonly payouts: readonly Payout[]
+  readonly pagination: import('./common').PaginationResponse
+}

package/src/types/quotes.ts

@@ -0,0 +1,49 @@
+import type { Currency } from './currencies'
+
+/**
+ * Money amount with currency
+ */
+export interface MoneyAmount {
+  readonly amount: string
+  readonly currency: Currency
+}
+
+/**
+ * Fee information
+ */
+export interface Fee {
+  readonly id: string
+  readonly type: string
+  readonly label: string
+  readonly amount: string
+  readonly currency: Currency
+  readonly createdAt: string
+}
+
+/**
+ * Exchange quote
+ */
+export interface Quote {
+  readonly fromAmount: MoneyAmount
+  readonly toAmount: MoneyAmount
+  readonly exchangeRateSnapshotId: string
+  readonly fees: readonly Fee[]
+}
+
+/**
+ * Parameters for getting a quote
+ */
+export interface GetQuoteParams {
+  readonly fromCurrency: string
+  readonly toCurrency: string
+  readonly amount: string
+  readonly amountType: 'FROM' | 'TO'
+}
+
+/**
+ * Response for getting a quote
+ */
+export interface QuoteResponse {
+  readonly quote: Quote
+  readonly expiresAt: string
+}

package/src/types/webhooks.ts

@@ -0,0 +1,31 @@
+import type { OrderStatus } from './orders'
+
+/**
+ * Webhook event types
+ */
+export type WebhookEventType =
+  | 'ORDER_CREATED'
+  | 'PAYMENT_RECEIVED'
+  | 'ORDER_COMPLETED'
+  | 'SETTLEMENT_CREATED'
+  | 'PAYMENT_CONVERSION_SETTLED'
+
+/**
+ * Webhook event payload
+ */
+export interface WebhookEvent {
+  readonly event_type: WebhookEventType
+  readonly order_id: string
+  readonly order_status: OrderStatus
+  readonly merchant_id: string
+  readonly order_purchase_amount: number
+  readonly order_purchase_currency: string
+  readonly order_crypto?: string
+  readonly order_crypto_amount?: number
+  readonly network?: string
+  readonly settlement_id?: string
+  readonly from_amount?: number
+  readonly from_currency?: string
+  readonly from_network?: string
+  readonly to_currency?: string
+}

package/src/utils/errors.ts

@@ -0,0 +1,104 @@
+/**
+ * Base error class for Swapped Commerce SDK
+ */
+export class SwappedError extends Error {
+  public readonly statusCode?: number
+  public readonly code?: string
+  public readonly details?: Readonly<Record<string, unknown>>
+
+  constructor(
+    message: string,
+    statusCode?: number,
+    code?: string,
+    details?: Readonly<Record<string, unknown>>
+  ) {
+    super(message)
+    this.name = 'SwappedError'
+    this.statusCode = statusCode
+    this.code = code
+    this.details = details
+
+    // Maintains proper stack trace for where error was thrown (V8 only)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, SwappedError)
+    }
+  }
+}
+
+/**
+ * Authentication error (401)
+ */
+export class SwappedAuthenticationError extends SwappedError {
+  constructor(message: string = 'Authentication failed') {
+    super(message, 401, 'AUTHENTICATION_ERROR')
+    this.name = 'SwappedAuthenticationError'
+  }
+}
+
+/**
+ * Validation error (400)
+ */
+export class SwappedValidationError extends SwappedError {
+  constructor(
+    message: string,
+    details?: Readonly<Record<string, unknown>>
+  ) {
+    super(message, 400, 'VALIDATION_ERROR', details)
+    this.name = 'SwappedValidationError'
+  }
+}
+
+/**
+ * Rate limit error (429)
+ */
+export class SwappedRateLimitError extends SwappedError {
+  constructor(message: string = 'Rate limit exceeded') {
+    super(message, 429, 'RATE_LIMIT_ERROR')
+    this.name = 'SwappedRateLimitError'
+  }
+}
+
+/**
+ * Not found error (404)
+ */
+export class SwappedNotFoundError extends SwappedError {
+  constructor(resource: string) {
+    super(`${resource} not found`, 404, 'NOT_FOUND_ERROR')
+    this.name = 'SwappedNotFoundError'
+  }
+}
+
+/**
+ * Factory function for authentication errors
+ */
+export function createAuthenticationError(
+  message?: string
+): SwappedAuthenticationError {
+  return new SwappedAuthenticationError(message)
+}
+
+/**
+ * Factory function for validation errors
+ */
+export function createValidationError(
+  message: string,
+  details?: Readonly<Record<string, unknown>>
+): SwappedValidationError {
+  return new SwappedValidationError(message, details)
+}
+
+/**
+ * Factory function for rate limit errors
+ */
+export function createRateLimitError(
+  message?: string
+): SwappedRateLimitError {
+  return new SwappedRateLimitError(message)
+}
+
+/**
+ * Factory function for not found errors
+ */
+export function createNotFoundError(resource: string): SwappedNotFoundError {
+  return new SwappedNotFoundError(resource)
+}