@imerchantsolutions/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,749 @@
+interface iMerchantConfig {
+    /** Your iMerchant API key (starts with sk_test_ or sk_live_) */
+    apiKey: string;
+    /** API base URL (defaults to https://api.imerchant.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** API version (default: 'v1') */
+    apiVersion?: string;
+}
+interface RequestOptions {
+    /** Override timeout for this specific request */
+    timeout?: number;
+    /** Idempotency key for safe retries */
+    idempotencyKey?: string;
+}
+interface Amount {
+    /** Amount in minor units (e.g., cents for USD) */
+    value: number;
+    /** Three-letter ISO currency code */
+    currency: string;
+}
+interface Address {
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postalCode: string;
+    country: string;
+}
+interface PaginationParams {
+    /** Number of records to return (max 100) */
+    limit?: number;
+    /** Pagination cursor for next page */
+    cursor?: string;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    hasMore: boolean;
+    cursor?: string;
+    total?: number;
+}
+interface APIError$1 {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type PaymentStatus = 'pending' | 'processing' | 'authorized' | 'captured' | 'failed' | 'cancelled' | 'refunded' | 'partially_refunded';
+type PaymentMethodType = 'card' | 'bank_transfer' | 'apple_pay' | 'google_pay' | 'klarna' | 'afterpay';
+interface CardDetails {
+    /** Last 4 digits of the card */
+    last4: string;
+    /** Card brand (visa, mastercard, amex, etc.) */
+    brand: string;
+    /** Expiry month (1-12) */
+    expMonth: number;
+    /** Expiry year (4 digits) */
+    expYear: number;
+    /** Cardholder name */
+    holderName?: string;
+}
+interface PaymentMethod {
+    type: PaymentMethodType;
+    card?: CardDetails;
+}
+interface Payment {
+    /** Unique payment identifier */
+    id: string;
+    /** Payment amount */
+    amount: Amount;
+    /** Current payment status */
+    status: PaymentStatus;
+    /** Your reference for this payment */
+    reference: string;
+    /** Payment description */
+    description?: string;
+    /** Payment method used */
+    paymentMethod?: PaymentMethod;
+    /** Customer ID if associated */
+    customerId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, string>;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+interface CreatePaymentParams {
+    /** Amount in minor units (e.g., cents) */
+    amount: number;
+    /** Three-letter ISO currency code */
+    currency: string;
+    /** Your unique reference for this payment */
+    reference: string;
+    /** Payment description */
+    description?: string;
+    /** Customer ID to associate with payment */
+    customerId?: string;
+    /** Return URL after payment completion */
+    returnUrl?: string;
+    /** Additional metadata (key-value pairs) */
+    metadata?: Record<string, string>;
+    /** Payment method details for server-side payments */
+    paymentMethod?: {
+        type: PaymentMethodType;
+        encryptedCardNumber?: string;
+        encryptedExpiryMonth?: string;
+        encryptedExpiryYear?: string;
+        encryptedSecurityCode?: string;
+        holderName?: string;
+    };
+}
+interface ListPaymentsParams extends PaginationParams {
+    /** Filter by status */
+    status?: PaymentStatus;
+    /** Filter by customer ID */
+    customerId?: string;
+    /** Filter payments after this date (ISO string) */
+    createdAfter?: string;
+    /** Filter payments before this date (ISO string) */
+    createdBefore?: string;
+}
+interface CapturePaymentParams {
+    /** Amount to capture (defaults to full authorized amount) */
+    amount?: number;
+}
+type RefundStatus = 'pending' | 'processing' | 'completed' | 'failed';
+interface Refund {
+    /** Unique refund identifier */
+    id: string;
+    /** Associated payment ID */
+    paymentId: string;
+    /** Refund amount */
+    amount: Amount;
+    /** Current refund status */
+    status: RefundStatus;
+    /** Reason for refund */
+    reason?: string;
+    /** Additional metadata */
+    metadata?: Record<string, string>;
+    /** ISO timestamp of creation */
+    createdAt: string;
+}
+interface CreateRefundParams {
+    /** Payment ID to refund */
+    paymentId: string;
+    /** Amount to refund in minor units (defaults to full payment amount) */
+    amount?: number;
+    /** Reason for the refund */
+    reason?: string;
+    /** Additional metadata */
+    metadata?: Record<string, string>;
+}
+interface ListRefundsParams extends PaginationParams {
+    /** Filter by payment ID */
+    paymentId?: string;
+    /** Filter by status */
+    status?: RefundStatus;
+}
+interface Customer {
+    /** Unique customer identifier */
+    id: string;
+    /** Customer email address */
+    email: string;
+    /** Customer's first name */
+    firstName?: string;
+    /** Customer's last name */
+    lastName?: string;
+    /** Customer's phone number */
+    phone?: string;
+    /** Billing address */
+    billingAddress?: Address;
+    /** Additional metadata */
+    metadata?: Record<string, string>;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+interface CreateCustomerParams {
+    /** Customer email address */
+    email: string;
+    /** Customer's first name */
+    firstName?: string;
+    /** Customer's last name */
+    lastName?: string;
+    /** Customer's phone number */
+    phone?: string;
+    /** Billing address */
+    billingAddress?: Address;
+    /** Additional metadata */
+    metadata?: Record<string, string>;
+}
+interface UpdateCustomerParams {
+    /** Customer email address */
+    email?: string;
+    /** Customer's first name */
+    firstName?: string;
+    /** Customer's last name */
+    lastName?: string;
+    /** Customer's phone number */
+    phone?: string;
+    /** Billing address */
+    billingAddress?: Address;
+    /** Additional metadata */
+    metadata?: Record<string, string>;
+}
+interface ListCustomersParams extends PaginationParams {
+    /** Filter by email */
+    email?: string;
+    /** Filter customers created after this date */
+    createdAfter?: string;
+    /** Filter customers created before this date */
+    createdBefore?: string;
+}
+type SubscriptionStatus = 'active' | 'paused' | 'cancelled' | 'past_due' | 'trialing';
+type BillingInterval = 'day' | 'week' | 'month' | 'year';
+interface Subscription {
+    /** Unique subscription identifier */
+    id: string;
+    /** Associated customer ID */
+    customerId: string;
+    /** Current subscription status */
+    status: SubscriptionStatus;
+    /** Billing amount */
+    amount: Amount;
+    /** Billing interval */
+    interval: BillingInterval;
+    /** Number of intervals between billings */
+    intervalCount: number;
+    /** Current billing period start */
+    currentPeriodStart: string;
+    /** Current billing period end */
+    currentPeriodEnd: string;
+    /** Whether subscription cancels at period end */
+    cancelAtPeriodEnd: boolean;
+    /** Additional metadata */
+    metadata?: Record<string, string>;
+    /** ISO timestamp of creation */
+    createdAt: string;
+}
+interface CreateSubscriptionParams {
+    /** Customer ID */
+    customerId: string;
+    /** Amount in minor units */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Billing interval */
+    interval: BillingInterval;
+    /** Number of intervals between billings (default: 1) */
+    intervalCount?: number;
+    /** Number of trial days (default: 0) */
+    trialDays?: number;
+    /** Additional metadata */
+    metadata?: Record<string, string>;
+}
+type WebhookEventType = 'payment.created' | 'payment.authorized' | 'payment.captured' | 'payment.failed' | 'payment.cancelled' | 'refund.created' | 'refund.completed' | 'refund.failed' | 'customer.created' | 'customer.updated' | 'subscription.created' | 'subscription.updated' | 'subscription.cancelled' | 'chargeback.created';
+interface WebhookEvent<T = unknown> {
+    /** Unique event identifier */
+    id: string;
+    /** Event type */
+    type: WebhookEventType;
+    /** Event data */
+    data: T;
+    /** ISO timestamp of event creation */
+    createdAt: string;
+}
+interface WebhookPayload {
+    /** Raw request body as string */
+    body: string;
+    /** Signature from imerchant-signature header */
+    signature: string;
+}
+
+declare class HttpClient {
+    private config;
+    constructor(config: iMerchantConfig);
+    private getUrl;
+    private handleResponse;
+    request<T>(method: string, path: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+}
+
+/**
+ * Payments API - Create, retrieve, and manage payments
+ */
+declare class Payments {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new payment
+     *
+     * @example
+     * ```typescript
+     * const payment = await client.payments.create({
+     *   amount: 1000, // $10.00 in cents
+     *   currency: 'usd',
+     *   reference: 'order_123',
+     *   description: 'Test payment',
+     * });
+     * ```
+     */
+    create(params: CreatePaymentParams, options?: RequestOptions): Promise<Payment>;
+    /**
+     * Retrieve a payment by ID
+     *
+     * @example
+     * ```typescript
+     * const payment = await client.payments.retrieve('pay_abc123');
+     * console.log(payment.status);
+     * ```
+     */
+    retrieve(id: string, options?: RequestOptions): Promise<Payment>;
+    /**
+     * List all payments with optional filters
+     *
+     * @example
+     * ```typescript
+     * const { data, hasMore } = await client.payments.list({
+     *   status: 'captured',
+     *   limit: 10,
+     * });
+     * ```
+     */
+    list(params?: ListPaymentsParams, options?: RequestOptions): Promise<PaginatedResponse<Payment>>;
+    /**
+     * Capture an authorized payment
+     *
+     * @example
+     * ```typescript
+     * // Capture full amount
+     * const payment = await client.payments.capture('pay_abc123');
+     *
+     * // Capture partial amount
+     * const payment = await client.payments.capture('pay_abc123', { amount: 500 });
+     * ```
+     */
+    capture(id: string, params?: CapturePaymentParams, options?: RequestOptions): Promise<Payment>;
+    /**
+     * Cancel an authorized payment
+     *
+     * @example
+     * ```typescript
+     * const payment = await client.payments.cancel('pay_abc123');
+     * ```
+     */
+    cancel(id: string, options?: RequestOptions): Promise<Payment>;
+}
+
+/**
+ * Refunds API - Create and manage refunds
+ */
+declare class Refunds {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create a refund for a payment
+     *
+     * @example
+     * ```typescript
+     * // Full refund
+     * const refund = await client.refunds.create({
+     *   paymentId: 'pay_abc123',
+     *   reason: 'Customer request',
+     * });
+     *
+     * // Partial refund
+     * const refund = await client.refunds.create({
+     *   paymentId: 'pay_abc123',
+     *   amount: 500, // $5.00 in cents
+     *   reason: 'Partial return',
+     * });
+     * ```
+     */
+    create(params: CreateRefundParams, options?: RequestOptions): Promise<Refund>;
+    /**
+     * Retrieve a refund by ID
+     *
+     * @example
+     * ```typescript
+     * const refund = await client.refunds.retrieve('ref_abc123');
+     * console.log(refund.status);
+     * ```
+     */
+    retrieve(id: string, options?: RequestOptions): Promise<Refund>;
+    /**
+     * List all refunds with optional filters
+     *
+     * @example
+     * ```typescript
+     * // List all refunds for a payment
+     * const { data } = await client.refunds.list({
+     *   paymentId: 'pay_abc123',
+     * });
+     *
+     * // List refunds by status
+     * const { data } = await client.refunds.list({
+     *   status: 'completed',
+     *   limit: 20,
+     * });
+     * ```
+     */
+    list(params?: ListRefundsParams, options?: RequestOptions): Promise<PaginatedResponse<Refund>>;
+}
+
+/**
+ * Customers API - Create and manage customers
+ */
+declare class Customers {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new customer
+     *
+     * @example
+     * ```typescript
+     * const customer = await client.customers.create({
+     *   email: 'john@example.com',
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     *   metadata: { userId: '12345' },
+     * });
+     * ```
+     */
+    create(params: CreateCustomerParams, options?: RequestOptions): Promise<Customer>;
+    /**
+     * Retrieve a customer by ID
+     *
+     * @example
+     * ```typescript
+     * const customer = await client.customers.retrieve('cus_abc123');
+     * console.log(customer.email);
+     * ```
+     */
+    retrieve(id: string, options?: RequestOptions): Promise<Customer>;
+    /**
+     * Update a customer
+     *
+     * @example
+     * ```typescript
+     * const customer = await client.customers.update('cus_abc123', {
+     *   firstName: 'Jane',
+     *   phone: '+1234567890',
+     * });
+     * ```
+     */
+    update(id: string, params: UpdateCustomerParams, options?: RequestOptions): Promise<Customer>;
+    /**
+     * Delete a customer
+     *
+     * @example
+     * ```typescript
+     * await client.customers.delete('cus_abc123');
+     * ```
+     */
+    delete(id: string, options?: RequestOptions): Promise<void>;
+    /**
+     * List all customers with optional filters
+     *
+     * @example
+     * ```typescript
+     * const { data, hasMore } = await client.customers.list({
+     *   limit: 20,
+     * });
+     *
+     * // Search by email
+     * const { data } = await client.customers.list({
+     *   email: 'john@example.com',
+     * });
+     * ```
+     */
+    list(params?: ListCustomersParams, options?: RequestOptions): Promise<PaginatedResponse<Customer>>;
+}
+
+interface ListSubscriptionsParams extends PaginationParams {
+    /** Filter by customer ID */
+    customerId?: string;
+    /** Filter by status */
+    status?: SubscriptionStatus;
+}
+/**
+ * Subscriptions API - Create and manage recurring billing
+ */
+declare class Subscriptions {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new subscription
+     *
+     * @example
+     * ```typescript
+     * const subscription = await client.subscriptions.create({
+     *   customerId: 'cus_abc123',
+     *   amount: 2999, // $29.99 in cents
+     *   currency: 'usd',
+     *   interval: 'month',
+     * });
+     * ```
+     */
+    create(params: CreateSubscriptionParams, options?: RequestOptions): Promise<Subscription>;
+    /**
+     * Retrieve a subscription by ID
+     *
+     * @example
+     * ```typescript
+     * const subscription = await client.subscriptions.retrieve('sub_abc123');
+     * console.log(subscription.status);
+     * ```
+     */
+    retrieve(id: string, options?: RequestOptions): Promise<Subscription>;
+    /**
+     * Cancel a subscription
+     *
+     * @example
+     * ```typescript
+     * // Cancel immediately
+     * const subscription = await client.subscriptions.cancel('sub_abc123');
+     *
+     * // Cancel at end of billing period
+     * const subscription = await client.subscriptions.cancel('sub_abc123', {
+     *   atPeriodEnd: true,
+     * });
+     * ```
+     */
+    cancel(id: string, params?: {
+        atPeriodEnd?: boolean;
+    }, options?: RequestOptions): Promise<Subscription>;
+    /**
+     * Pause a subscription
+     *
+     * @example
+     * ```typescript
+     * const subscription = await client.subscriptions.pause('sub_abc123');
+     * ```
+     */
+    pause(id: string, options?: RequestOptions): Promise<Subscription>;
+    /**
+     * Resume a paused subscription
+     *
+     * @example
+     * ```typescript
+     * const subscription = await client.subscriptions.resume('sub_abc123');
+     * ```
+     */
+    resume(id: string, options?: RequestOptions): Promise<Subscription>;
+    /**
+     * List all subscriptions with optional filters
+     *
+     * @example
+     * ```typescript
+     * // List all active subscriptions
+     * const { data } = await client.subscriptions.list({
+     *   status: 'active',
+     * });
+     *
+     * // List subscriptions for a customer
+     * const { data } = await client.subscriptions.list({
+     *   customerId: 'cus_abc123',
+     * });
+     * ```
+     */
+    list(params?: ListSubscriptionsParams, options?: RequestOptions): Promise<PaginatedResponse<Subscription>>;
+}
+
+/**
+ * Webhooks utility class for verifying webhook signatures
+ */
+declare class Webhooks {
+    /**
+     * Verify webhook signature and parse the event
+     *
+     * @example
+     * ```typescript
+     * // Express.js example
+     * app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const signature = req.headers['imerchant-signature'] as string;
+     *
+     *   try {
+     *     const event = iMerchant.webhooks.verify({
+     *       body: req.body.toString(),
+     *       signature,
+     *     }, process.env.WEBHOOK_SECRET);
+     *
+     *     switch (event.type) {
+     *       case 'payment.captured':
+     *         // Handle successful payment
+     *         break;
+     *       case 'payment.failed':
+     *         // Handle failed payment
+     *         break;
+     *     }
+     *
+     *     res.json({ received: true });
+     *   } catch (err) {
+     *     res.status(400).send('Invalid signature');
+     *   }
+     * });
+     * ```
+     *
+     * @param payload - The webhook payload containing body and signature
+     * @param secret - Your webhook signing secret
+     * @returns The verified and parsed webhook event
+     * @throws {WebhookSignatureError} If signature verification fails
+     */
+    static verify<T = unknown>(payload: WebhookPayload, secret: string): WebhookEvent<T>;
+    /**
+     * Compute HMAC-SHA256 signature
+     * Uses Node.js crypto module (available in Node.js environments)
+     */
+    private static computeSignature;
+    /**
+     * Timing-safe string comparison to prevent timing attacks
+     */
+    private static secureCompare;
+    /**
+     * Async signature verification using Web Crypto API
+     * Use this in environments that support Web Crypto
+     *
+     * @example
+     * ```typescript
+     * const event = await iMerchant.webhooks.verifyAsync(payload, secret);
+     * ```
+     */
+    static verifyAsync<T = unknown>(payload: WebhookPayload, secret: string): Promise<WebhookEvent<T>>;
+}
+
+/**
+ * iMerchant SDK Client
+ *
+ * The main entry point for interacting with the iMerchant API.
+ *
+ * @example
+ * ```typescript
+ * import { iMerchant } from '@imerchant/sdk';
+ *
+ * const client = new iMerchant({
+ *   apiKey: 'sk_test_your_api_key',
+ * });
+ *
+ * // Create a payment
+ * const payment = await client.payments.create({
+ *   amount: 1000,
+ *   currency: 'usd',
+ *   reference: 'order_123',
+ * });
+ *
+ * // Create a customer
+ * const customer = await client.customers.create({
+ *   email: 'john@example.com',
+ *   firstName: 'John',
+ * });
+ *
+ * // Create a subscription
+ * const subscription = await client.subscriptions.create({
+ *   customerId: customer.id,
+ *   amount: 2999,
+ *   currency: 'usd',
+ *   interval: 'month',
+ * });
+ * ```
+ */
+declare class iMerchant {
+    /**
+     * Payments API for creating and managing payments
+     */
+    readonly payments: Payments;
+    /**
+     * Refunds API for creating and managing refunds
+     */
+    readonly refunds: Refunds;
+    /**
+     * Customers API for creating and managing customers
+     */
+    readonly customers: Customers;
+    /**
+     * Subscriptions API for managing recurring billing
+     */
+    readonly subscriptions: Subscriptions;
+    /**
+     * Static webhook utilities for signature verification
+     */
+    static readonly webhooks: typeof Webhooks;
+    private readonly http;
+    /**
+     * Create a new iMerchant client
+     *
+     * @param config - Client configuration
+     * @param config.apiKey - Your iMerchant API key (required)
+     * @param config.baseUrl - API base URL (optional, defaults to https://api.imerchant.com)
+     * @param config.timeout - Request timeout in ms (optional, defaults to 30000)
+     * @param config.apiVersion - API version (optional, defaults to 'v1')
+     */
+    constructor(config: iMerchantConfig);
+}
+
+/**
+ * Base error class for all iMerchant SDK errors
+ */
+declare class iMerchantError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when API request fails
+ */
+declare class APIError extends iMerchantError {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, statusCode: number, code: string, details?: Record<string, unknown>);
+}
+/**
+ * Error thrown when authentication fails
+ */
+declare class AuthenticationError extends iMerchantError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when a resource is not found
+ */
+declare class NotFoundError extends APIError {
+    constructor(resource: string, id: string);
+}
+/**
+ * Error thrown when request validation fails
+ */
+declare class ValidationError extends APIError {
+    readonly errors: Record<string, string[]>;
+    constructor(message: string, errors: Record<string, string[]>);
+}
+/**
+ * Error thrown when rate limit is exceeded
+ */
+declare class RateLimitError extends APIError {
+    readonly retryAfter?: number;
+    constructor(retryAfter?: number);
+}
+/**
+ * Error thrown when webhook signature verification fails
+ */
+declare class WebhookSignatureError extends iMerchantError {
+    constructor(message?: string);
+}
+
+export { APIError, type APIError$1 as APIErrorType, type Address, type Amount, AuthenticationError, type BillingInterval, type CapturePaymentParams, type CardDetails, type CreateCustomerParams, type CreatePaymentParams, type CreateRefundParams, type CreateSubscriptionParams, type Customer, Customers, type ListCustomersParams, type ListPaymentsParams, type ListRefundsParams, NotFoundError, type PaginatedResponse, type PaginationParams, type Payment, type PaymentMethod, type PaymentMethodType, type PaymentStatus, Payments, RateLimitError, type Refund, type RefundStatus, Refunds, type RequestOptions, type Subscription, type SubscriptionStatus, Subscriptions, type UpdateCustomerParams, ValidationError, type WebhookEvent, type WebhookEventType, type WebhookPayload, WebhookSignatureError, Webhooks, iMerchant, type iMerchantConfig, iMerchantError };