@sikka/aps 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,2007 @@
+/**
+ * Amazon Payment Services Configuration
+ */
+interface APSConfig {
+    /** Merchant identifier provided by APS */
+    merchantId: string;
+    /** Access code for API authentication */
+    accessCode: string;
+    /** Request secret key for HMAC generation */
+    requestSecret: string;
+    /** Response secret key for HMAC verification */
+    responseSecret: string;
+    /** Environment: 'sandbox' or 'production' */
+    environment?: 'sandbox' | 'production';
+    /** Currency code (e.g., 'USD', 'AED', 'SAR') */
+    currency?: string;
+    /** Language for hosted pages */
+    language?: 'en' | 'ar';
+}
+/**
+ * Logger interface for custom logging implementations
+ */
+interface Logger {
+    /** Log debug messages (for development) */
+    debug?: (message: string, ...args: any[]) => void;
+    /** Log informational messages */
+    info?: (message: string, ...args: any[]) => void;
+    /** Log warning messages */
+    warn?: (message: string, ...args: any[]) => void;
+    /** Log error messages */
+    error?: (message: string, ...args: any[]) => void;
+}
+/**
+ * APS Client options
+ */
+interface APSClientOptions {
+    /** Custom logger instance */
+    logger?: Logger;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Enable request logging (default: false in production) */
+    enableLogging?: boolean;
+}
+/**
+ * Rate limit configuration
+ */
+interface RateLimitConfig {
+    /** Maximum requests per window */
+    maxRequests: number;
+    /** Window duration in milliseconds */
+    windowMs: number;
+}
+/**
+ * Idempotency key options
+ */
+interface IdempotencyOptions {
+    /** Idempotency key for the request */
+    idempotencyKey: string;
+}
+/**
+ * Payment method types supported by APS
+ */
+type PaymentMethod = 'card' | 'apple_pay' | 'mada' | 'stc_pay' | 'knet' | 'naps' | 'fawry' | 'meeza' | 'sadad' | 'aman';
+/**
+ * Transaction status
+ */
+type TransactionStatus = 'pending' | 'authorized' | 'captured' | 'failed' | 'voided' | 'refunded' | 'cancelled';
+/**
+ * Customer information
+ */
+interface Customer {
+    /** Customer email */
+    email?: string;
+    /** Customer name */
+    name?: string;
+    /** Customer phone */
+    phone?: string;
+    /** Billing address */
+    billingAddress?: {
+        street?: string;
+        city?: string;
+        state?: string;
+        country?: string;
+        postalCode?: string;
+    };
+}
+/**
+ * Order/Transaction details
+ */
+interface Order {
+    /** Unique order ID (merchant generated) */
+    id: string;
+    /** Amount in minor units (e.g., cents) */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Order description */
+    description?: string;
+    /** Customer information */
+    customer?: Customer;
+    /** Metadata for the order */
+    metadata?: Record<string, string>;
+}
+/**
+ * Payment link options
+ */
+interface PaymentLinkOptions {
+    /** Order details */
+    order: Order;
+    /** Payment methods to allow */
+    allowedPaymentMethods?: PaymentMethod[];
+    /** URL to redirect after successful payment */
+    successUrl?: string;
+    /** URL to redirect after failed payment */
+    failureUrl?: string;
+    /** URL to redirect after user cancels */
+    cancelUrl?: string;
+    /** Enable recurring payments */
+    recurring?: boolean;
+    /** Token validity in hours */
+    tokenValidityHours?: number;
+    /** Additional parameters */
+    metadata?: Record<string, string>;
+}
+/**
+ * Hosted checkout options
+ */
+interface HostedCheckoutOptions {
+    /** Order details */
+    order: Order;
+    /** Payment methods to allow */
+    allowedPaymentMethods?: PaymentMethod[];
+    /** URL to redirect after successful payment */
+    successUrl?: string;
+    /** URL to redirect after failed payment */
+    failureUrl?: string;
+    /** URL to redirect after user cancels */
+    cancelUrl?: string;
+    /** Hide shipping information */
+    hideShipping?: boolean;
+    /** Additional parameters */
+    metadata?: Record<string, string>;
+}
+/**
+ * Custom payment page options
+ */
+interface CustomPaymentPageOptions {
+    /** Order details */
+    order: Order;
+    /** Payment method to use */
+    paymentMethod: PaymentMethod;
+    /** Card token (if using tokenization) */
+    cardToken?: string;
+    /** 3DS return URL */
+    returnUrl?: string;
+    /** Enable 3DS authentication */
+    enable3DS?: boolean;
+    /** Additional parameters */
+    metadata?: Record<string, string>;
+}
+/**
+ * Card tokenization options
+ */
+interface TokenizeCardOptions {
+    /** Card number */
+    cardNumber: string;
+    /** Expiry month (MM) */
+    expiryMonth: string;
+    /** Expiry year (YY) */
+    expiryYear: string;
+    /** CVV */
+    cvv: string;
+    /** Cardholder name */
+    cardholderName?: string;
+}
+/**
+ * Tokenized card response
+ */
+interface TokenizedCard {
+    /** Card token for future use */
+    token: string;
+    /** Last 4 digits of card */
+    last4: string;
+    /** Card brand */
+    brand: string;
+    /** Expiry month */
+    expiryMonth: string;
+    /** Expiry year */
+    expiryYear: string;
+}
+/**
+ * Saved card for a customer (list response)
+ */
+interface SavedCard {
+    /** Card token */
+    token: string;
+    /** Last 4 digits */
+    last4: string;
+    /** Card brand */
+    brand: string;
+    /** Expiry month */
+    expiryMonth: string;
+    /** Expiry year */
+    expiryYear: string;
+    /** Cardholder name */
+    cardholderName?: string;
+    /** Is this the default card */
+    isDefault?: boolean;
+}
+/**
+ * List saved cards response
+ */
+interface SavedCardsList {
+    /** Customer identifier */
+    customerId: string;
+    /** List of saved cards */
+    cards: SavedCard[];
+    /** Total count */
+    total: number;
+}
+/**
+ * Payment response
+ */
+interface PaymentResponse {
+    /** Transaction ID */
+    transactionId: string;
+    /** Order ID */
+    orderId: string;
+    /** Transaction status */
+    status: TransactionStatus;
+    /** Amount */
+    amount: number;
+    /** Currency */
+    currency: string;
+    /** Payment method used */
+    paymentMethod?: string;
+    /** 3DS URL (if authentication required) */
+    authenticationUrl?: string;
+    /** Form data for redirect (if applicable) */
+    redirectForm?: {
+        url: string;
+        method: 'POST' | 'GET';
+        params: Record<string, string>;
+    };
+    /** Error message if failed */
+    message?: string;
+    /** Raw APS response */
+    rawResponse: Record<string, any>;
+}
+/**
+ * Payment link response
+ */
+interface PaymentLinkResponse {
+    /** Payment link URL */
+    url: string;
+    /** Link ID */
+    linkId: string;
+    /** Order ID */
+    orderId: string;
+    /** Expiry date */
+    expiresAt?: Date;
+    /** Raw APS response */
+    rawResponse: Record<string, any>;
+}
+/**
+ * Refund options
+ */
+interface RefundOptions {
+    /** Original transaction ID */
+    transactionId: string;
+    /** Refund amount (optional for full refund) */
+    amount?: number;
+    /** Refund reason */
+    reason?: string;
+}
+/**
+ * Refund response
+ */
+interface RefundResponse {
+    /** Refund transaction ID */
+    refundId: string;
+    /** Original transaction ID */
+    transactionId: string;
+    /** Refund amount */
+    amount: number;
+    /** Status */
+    status: TransactionStatus;
+    /** Message */
+    message?: string;
+    /** Raw APS response */
+    rawResponse: Record<string, any>;
+}
+/**
+ * Void options
+ */
+interface VoidOptions {
+    /** Transaction ID to void */
+    transactionId: string;
+    /** Void reason */
+    reason?: string;
+}
+/**
+ * Void response
+ */
+interface VoidResponse {
+    /** Void transaction ID */
+    voidId: string;
+    /** Original transaction ID */
+    transactionId: string;
+    /** Status */
+    status: TransactionStatus;
+    /** Message */
+    message?: string;
+    /** Raw APS response */
+    rawResponse: Record<string, any>;
+}
+/**
+ * Capture options
+ */
+interface CaptureOptions {
+    /** Transaction ID to capture */
+    transactionId: string;
+    /** Capture amount (optional for full capture) */
+    amount?: number;
+}
+/**
+ * Capture response
+ */
+interface CaptureResponse {
+    /** Capture transaction ID */
+    captureId: string;
+    /** Original transaction ID */
+    transactionId: string;
+    /** Capture amount */
+    amount: number;
+    /** Status */
+    status: TransactionStatus;
+    /** Message */
+    message?: string;
+    /** Raw APS response */
+    rawResponse: Record<string, any>;
+}
+/**
+ * Query transaction options
+ */
+interface QueryOptions {
+    /** Transaction ID to query */
+    transactionId: string;
+    /** Or order ID */
+    orderId?: string;
+}
+/**
+ * Webhook event types
+ */
+type WebhookEventType = 'payment.success' | 'payment.failed' | 'payment.pending' | 'refund.success' | 'refund.failed' | 'chargeback.created' | 'subscription.renewed' | 'subscription.cancelled';
+/**
+ * Webhook event
+ */
+interface WebhookEvent {
+    /** Event ID */
+    id: string;
+    /** Event type */
+    type: WebhookEventType;
+    /** Event timestamp */
+    timestamp: Date;
+    /** Transaction data */
+    data: {
+        transactionId: string;
+        orderId: string;
+        amount: number;
+        currency: string;
+        status: TransactionStatus;
+        paymentMethod?: string;
+        metadata?: Record<string, any>;
+    };
+    /** Raw webhook payload */
+    rawPayload: Record<string, any>;
+}
+/**
+ * APS Error
+ */
+interface APSError {
+    /** Error code */
+    code: string;
+    /** Error message */
+    message: string;
+    /** HTTP status code */
+    statusCode?: number;
+    /** Raw error response */
+    rawResponse?: Record<string, any>;
+}
+/**
+ * APS Exception class
+ */
+declare class APSException extends Error {
+    code: string;
+    statusCode?: number;
+    rawResponse?: Record<string, any>;
+    constructor(error: APSError);
+}
+/**
+ * Recurring payment options
+ */
+interface RecurringPaymentOptions {
+    /** Order details */
+    order: {
+        /** Unique order ID */
+        id: string;
+        /** Amount in minor units (e.g., cents) */
+        amount: number;
+        /** Currency code */
+        currency: string;
+        /** Order description */
+        description?: string;
+    };
+    /** Card token from previous tokenization */
+    tokenName: string;
+    /** Agreement ID from original transaction */
+    agreementId: string;
+    /** Customer email */
+    customerEmail: string;
+    /** Customer name */
+    customerName?: string;
+    /** Customer phone */
+    customerPhone?: string;
+    /** Statement descriptor for bank statement */
+    statementDescriptor?: string;
+    /** Restrict payment method (e.g., 'VISA', 'MASTERCARD', 'MADA') */
+    paymentOption?: string;
+    /** Settlement reference */
+    settlementReference?: string;
+}
+/**
+ * Recurring payment response
+ */
+interface RecurringPaymentResponse {
+    /** Transaction ID */
+    transactionId: string;
+    /** Order ID */
+    orderId: string;
+    /** Agreement ID used */
+    agreementId: string;
+    /** Amount charged */
+    amount: number;
+    /** Currency */
+    currency: string;
+    /** Transaction status */
+    status: 'captured' | 'failed' | 'pending';
+    /** Payment method used */
+    paymentMethod?: string;
+    /** Authorization code */
+    authorizationCode?: string;
+    /** Response message */
+    message?: string;
+    /** Raw APS response */
+    rawResponse: Record<string, any>;
+}
+
+/**
+ * Payment Links Module
+ *
+ * Create payment links using the official APS Payment Links API.
+ * This is a server-to-server API that returns a payment link URL.
+ *
+ * @example
+ * ```typescript
+ * const link = await aps.paymentLinks.create({
+ *   order: {
+ *     id: 'order_123',
+ *     amount: 10000,
+ *     currency: 'USD',
+ *     description: 'Product purchase'
+ *   },
+ *   customer: {
+ *     email: 'customer@example.com',
+ *     name: 'John Doe'
+ *   }
+ * });
+ *
+ * console.log(link.url); // Payment link to share with customer
+ * ```
+ */
+declare class PaymentLinksModule {
+    private config;
+    private options;
+    constructor(config: Required<APSConfig>, options: Required<Omit<APSClientOptions, 'logger'>> & {
+        logger: Logger;
+    });
+    /**
+     * Create a new payment link using APS Payment Links API
+     */
+    create(options: PaymentLinkOptions): Promise<PaymentLinkResponse>;
+    /**
+     * Generate signature for APS API requests
+     * Following official APS documentation:
+     * 1. Sort all parameters alphabetically
+     * 2. Concatenate as param_name=param_value
+     * 3. Wrap with SHA phrase at beginning and end
+     * 4. Hash with SHA-256
+     */
+    private generateSignature;
+    /**
+     * Make API request to APS with timeout and retry support
+     */
+    private makeApiRequest;
+    /**
+     * Generate a payment link URL (alias for create)
+     */
+    generateUrl(options: PaymentLinkOptions): Promise<string>;
+}
+
+/**
+ * Hosted Checkout Module
+ *
+ * Redirect customers to a hosted checkout page managed by APS.
+ * Handles the entire payment flow including 3DS authentication.
+ *
+ * @example
+ * ```typescript
+ * const checkout = await aps.hostedCheckout.create({
+ *   order: {
+ *     id: 'order_123',
+ *     amount: 10000,
+ *     currency: 'USD'
+ *   },
+ *   successUrl: 'https://yoursite.com/success',
+ *   failureUrl: 'https://yoursite.com/failure',
+ *   tokenize: true // Enable card tokenization for future payments
+ * });
+ *
+ * // Redirect user to checkout.url or use checkout.redirectForm
+ * ```
+ */
+declare class HostedCheckoutModule {
+    private config;
+    constructor(config: Required<APSConfig>, _options: Required<Omit<APSClientOptions, 'logger'>> & {
+        logger: Logger;
+    });
+    /**
+     * Create a hosted checkout session
+     */
+    create(checkoutOptions: HostedCheckoutOptions): Promise<PaymentResponse>;
+    /**
+     * Get the redirect URL for hosted checkout
+     */
+    getRedirectUrl(options: HostedCheckoutOptions): Promise<string>;
+}
+
+/**
+ * Custom Payment Page Module (Non-PCI)
+ *
+ * Process payments with a custom UI while APS handles PCI compliance.
+ * Uses tokenization to securely collect card details without storing them.
+ *
+ * Flow:
+ * 1. Create tokenization form to collect card details
+ * 2. Submit form to APS to get token
+ * 3. Use token to process payment via server-to-server API
+ *
+ * @example
+ * ```typescript
+ * // Step 1: Get tokenization form
+ * const tokenizationForm = aps.customPaymentPage.getTokenizationForm({
+ *   returnUrl: 'https://yoursite.com/token-result'
+ * });
+ *
+ * // Step 2: Submit form (from frontend) to get token
+ * // Token is returned in response as token_name
+ *
+ * // Step 3: Process payment with token
+ * const payment = await aps.customPaymentPage.chargeWithToken({
+ *   order: {
+ *     id: 'order_123',
+ *     amount: 10000,
+ *     currency: 'SAR'
+ *   },
+ *   tokenName: 'token_from_step_2',
+ *   customerEmail: 'customer@example.com'
+ * });
+ * ```
+ */
+declare class CustomPaymentPageModule {
+    private config;
+    private options;
+    constructor(config: Required<APSConfig>, options: Required<Omit<APSClientOptions, 'logger'>> & {
+        logger: Logger;
+    });
+    /**
+     * Get tokenization form data
+     * This form should be submitted from the frontend to APS
+     */
+    getTokenizationForm(options: {
+        returnUrl: string;
+        merchantReference?: string;
+        cardNumber?: string;
+        expiryDate?: string;
+        cardSecurityCode?: string;
+        cardHolderName?: string;
+    }): {
+        url: string;
+        method: 'POST';
+        params: Record<string, string>;
+    };
+    /**
+     * Get create token form data (for saving cards without charging)
+     */
+    getCreateTokenForm(options: {
+        returnUrl: string;
+        merchantReference?: string;
+        cardNumber?: string;
+        expiryDate?: string;
+        cardHolderName?: string;
+    }): {
+        url: string;
+        method: 'POST';
+        params: Record<string, string>;
+    };
+    /**
+     * Charge using a token received from tokenization
+     * This is a server-to-server call
+     */
+    chargeWithToken(options: {
+        order: {
+            id: string;
+            amount: number;
+            currency: string;
+            description?: string;
+        };
+        tokenName: string;
+        customerEmail: string;
+        customerName?: string;
+        customerPhone?: string;
+        returnUrl?: string;
+    }): Promise<PaymentResponse>;
+    /**
+     * Alias for chargeWithToken for backwards compatibility
+     */
+    charge(options: CustomPaymentPageOptions): Promise<PaymentResponse>;
+    /**
+     * Make API request to APS with timeout and retry support
+     */
+    private makeApiRequest;
+}
+
+/**
+ * Tokenization Module
+ *
+ * Securely tokenize card details for future payments without storing sensitive data.
+ * Tokenized cards can be used for recurring payments or one-click checkout.
+ *
+ * @example
+ * ```typescript
+ * // Tokenize a card
+ * const token = await aps.tokens.create({
+ *   cardNumber: '4111111111111111',
+ *   expiryMonth: '12',
+ *   expiryYear: '25',
+ *   cvv: '123',
+ *   cardholderName: 'John Doe'
+ * });
+ *
+ * console.log(token.token); // Use this for future payments
+ * console.log(token.last4); // "1111"
+ * ```
+ */
+declare class TokenizationModule {
+    private config;
+    private options;
+    constructor(config: Required<APSConfig>, options: Required<Omit<APSClientOptions, 'logger'>> & {
+        logger: Logger;
+    });
+    /**
+     * Tokenize card details
+     */
+    create(options: TokenizeCardOptions): Promise<TokenizedCard>;
+    /**
+     * Verify a token (check if it's still valid)
+     */
+    verify(token: string): Promise<boolean>;
+    /**
+     * Delete/Invalidate a token
+     */
+    delete(token: string): Promise<boolean>;
+    /**
+     * List saved cards for a customer
+     * @param customerId - Customer identifier (email or user ID)
+     */
+    list(customerId: string): Promise<SavedCardsList>;
+    /**
+     * Detect card brand from card number
+     */
+    private detectCardBrand;
+    /**
+     * Make tokenization API request with timeout and retry support
+     */
+    private makeTokenizeRequest;
+}
+
+/**
+ * Payments Module
+ *
+ * Manage existing transactions: capture authorized payments, process refunds, void transactions.
+ *
+ * @example
+ * ```typescript
+ * // Capture an authorized payment
+ * const capture = await aps.payments.capture({
+ *   transactionId: 'txn_123',
+ *   amount: 10000 // Optional, defaults to full amount
+ * });
+ *
+ * // Refund a payment
+ * const refund = await aps.payments.refund({
+ *   transactionId: 'txn_123',
+ *   amount: 5000, // Optional, defaults to full refund
+ *   reason: 'Customer request'
+ * });
+ *
+ * // Void an authorization
+ * const voided = await aps.payments.void({
+ *   transactionId: 'txn_123',
+ *   reason: 'Order cancelled'
+ * });
+ *
+ * // Query transaction status
+ * const transaction = await aps.payments.query({ transactionId: 'txn_123' });
+ * ```
+ */
+declare class PaymentsModule {
+    private config;
+    private options;
+    constructor(config: Required<APSConfig>, options: Required<Omit<APSClientOptions, 'logger'>> & {
+        logger: Logger;
+    });
+    /**
+     * Capture an authorized payment
+     */
+    capture(options: CaptureOptions): Promise<CaptureResponse>;
+    /**
+     * Refund a payment (full or partial)
+     */
+    refund(options: RefundOptions): Promise<RefundResponse>;
+    /**
+     * Void an authorized transaction
+     */
+    void(options: VoidOptions): Promise<VoidResponse>;
+    /**
+     * Query transaction status
+     */
+    query(options: QueryOptions): Promise<Record<string, any>>;
+    /**
+     * Map APS response code to transaction status
+     */
+    private mapResponseStatus;
+    /**
+     * Make API request to APS with timeout and retry support
+     */
+    private makeApiRequest;
+}
+
+/**
+ * Webhooks Module
+ *
+ * Verify and parse webhook events from Amazon Payment Services.
+ *
+ * @example
+ * ```typescript
+ * // In your API route handler
+ * app.post('/api/webhooks/aps', (req, res) => {
+ *   const signature = req.headers['x-aps-signature'] as string;
+ *   const payload = req.body;
+ *
+ *   // Verify the webhook signature
+ *   const isValid = aps.webhooks.verifySignature(
+ *     JSON.stringify(payload),
+ *     signature
+ *   );
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   // Construct the event
+ *   const event = aps.webhooks.constructEvent(payload);
+ *
+ *   // Handle the event
+ *   switch (event.type) {
+ *     case 'payment.success':
+ *       // Handle successful payment
+ *       break;
+ *     case 'payment.failed':
+ *       // Handle failed payment
+ *       break;
+ *   }
+ *
+ *   res.send('OK');
+ * });
+ * ```
+ */
+declare class WebhooksModule {
+    private config;
+    constructor(config: Required<APSConfig>);
+    /**
+     * Verify webhook signature
+     */
+    verifySignature(payload: string, signature: string): boolean;
+    /**
+     * Construct a webhook event from raw payload
+     */
+    constructEvent(payload: Record<string, any>): WebhookEvent;
+    /**
+     * Map APS event to webhook event type
+     */
+    private mapEventType;
+    /**
+     * Map APS status to transaction status
+     */
+    private mapStatus;
+    /**
+     * Verify and construct event in one step
+     */
+    safeConstructEvent(payload: string, signature: string): WebhookEvent;
+}
+
+/**
+ * Recurring Payments Module
+ *
+ * Process recurring payments using saved card tokens.
+ * Designed to be called from server-side cron jobs or scheduled tasks.
+ *
+ * @example
+ * ```typescript
+ * // Process a recurring payment (e.g., monthly subscription)
+ * const payment = await aps.recurring.process({
+ *   order: {
+ *     id: 'sub_123_monthly',
+ *     amount: 9900, // $99.00
+ *     currency: 'USD',
+ *     description: 'Monthly Subscription'
+ *   },
+ *   tokenName: 'token_from_original_transaction',
+ *   agreementId: 'agr_12345',
+ *   customerEmail: 'customer@example.com'
+ * });
+ *
+ * // Use in a cron job
+ * // 0 0 1 * * node process-recurring-payments.js
+ * ```
+ */
+declare class RecurringModule {
+    private config;
+    private options;
+    constructor(config: Required<APSConfig>, options: Required<Omit<APSClientOptions, 'logger'>> & {
+        logger: Logger;
+    });
+    /**
+     * Process a recurring payment using a saved token
+     *
+     * This method is designed to be called from server-side code,
+     * typically in a cron job or scheduled task for subscription billing.
+     *
+     * @param options - Recurring payment options
+     * @returns Recurring payment response
+     *
+     * @example
+     * ```typescript
+     * // Monthly subscription charge
+     * const payment = await aps.recurring.process({
+     *   order: {
+     *     id: `sub_${customerId}_${Date.now()}`,
+     *     amount: 2999, // $29.99
+     *     currency: 'USD',
+     *     description: 'Monthly Pro Plan'
+     *   },
+     *   tokenName: savedCard.token,
+     *   agreementId: savedCard.agreementId,
+     *   customerEmail: customer.email,
+     *   customerName: customer.name
+     * });
+     *
+     * if (payment.status === 'captured') {
+     *   await sendInvoice(customer, payment);
+     * } else {
+     *   await notifyPaymentFailed(customer, payment);
+     * }
+     * ```
+     */
+    process(options: RecurringPaymentOptions): Promise<RecurringPaymentResponse>;
+    /**
+     * Process multiple recurring payments in batch
+     *
+     * Useful for processing all due subscriptions at once.
+     * Returns results for all payments, including failures.
+     *
+     * @param payments - Array of recurring payment options
+     * @returns Array of results with success/failure status
+     *
+     * @example
+     * ```typescript
+     * // Process all due subscriptions
+     * const dueSubscriptions = await getDueSubscriptions();
+     *
+     * const results = await aps.recurring.processBatch(
+     *   dueSubscriptions.map(sub => ({
+     *     order: {
+     *       id: `sub_${sub.id}_${Date.now()}`,
+     *       amount: sub.amount,
+     *       currency: sub.currency,
+     *       description: sub.planName
+     *     },
+     *     tokenName: sub.tokenName,
+     *     agreementId: sub.agreementId,
+     *     customerEmail: sub.customerEmail
+     *   }))
+     * );
+     *
+     * // Handle results
+     * const successful = results.filter(r => r.success);
+     * const failed = results.filter(r => !r.success);
+     *
+     * console.log(`Processed: ${successful.length} succeeded, ${failed.length} failed`);
+     * ```
+     */
+    processBatch(payments: RecurringPaymentOptions[]): Promise<Array<{
+        success: boolean;
+        data?: RecurringPaymentResponse;
+        error?: string;
+        orderId: string;
+    }>>;
+    /**
+     * Map APS response code to transaction status
+     */
+    private mapResponseStatus;
+    /**
+     * Make API request to APS
+     */
+    private makeApiRequest;
+}
+
+/**
+ * Amazon Payment Services Client
+ *
+ * A Stripe-like SDK for seamless APS integration
+ *
+ * @example
+ * ```typescript
+ * import APS from 'amazon-payment-services';
+ *
+ * const aps = new APS({
+ *   merchantId: 'your-merchant-id',
+ *   accessCode: 'your-access-code',
+ *   requestSecret: 'your-request-secret',
+ *   responseSecret: 'your-response-secret',
+ *   environment: 'sandbox'
+ * }, {
+ *   logger: console, // Optional: custom logger
+ *   timeout: 30000,  // Optional: request timeout in ms
+ *   maxRetries: 3    // Optional: max retry attempts
+ * });
+ *
+ * // Create a payment link
+ * const link = await aps.paymentLinks.create({
+ *   order: {
+ *     id: 'order_123',
+ *     amount: 10000, // $100.00
+ *     currency: 'USD'
+ *   }
+ * });
+ * ```
+ */
+declare class APSClient {
+    /** Payment Links module */
+    readonly paymentLinks: PaymentLinksModule;
+    /** Hosted Checkout module */
+    readonly hostedCheckout: HostedCheckoutModule;
+    /** Custom Payment Page module */
+    readonly customPaymentPage: CustomPaymentPageModule;
+    /** Tokenization module */
+    readonly tokens: TokenizationModule;
+    /** Payments module (capture, refund, void) */
+    readonly payments: PaymentsModule;
+    /** Webhooks module */
+    readonly webhooks: WebhooksModule;
+    /** Recurring payments module */
+    readonly recurring: RecurringModule;
+    /** Configuration */
+    readonly config: Required<APSConfig>;
+    /** Client options */
+    readonly options: Required<Omit<APSClientOptions, 'logger'>> & {
+        logger: Logger;
+    };
+    /**
+     * Create a new APS client instance
+     */
+    constructor(config: APSConfig, options?: APSClientOptions);
+    /**
+     * Get the base URL for redirects
+     */
+    getBaseUrl(): string;
+    /**
+     * Get the API URL for server-to-server calls
+     */
+    getApiUrl(): string;
+    /**
+     * Verify a webhook signature
+     */
+    verifyWebhookSignature(payload: string, signature: string): boolean;
+    /**
+     * Construct a webhook event from raw payload
+     */
+    constructWebhookEvent(payload: Record<string, any>): any;
+    /**
+     * Get the logger instance
+     */
+    getLogger(): Logger;
+    /**
+     * Set a custom logger
+     */
+    setLogger(logger: Logger): void;
+}
+
+/**
+ * Constants for Amazon Payment Services
+ *
+ * Test cards, response codes, and other constants used throughout the SDK.
+ *
+ * @example
+ * ```typescript
+ * import { TestCards, ResponseCodes, ErrorCategories } from '@sikka/aps';
+ *
+ * // Use test cards in development
+ * const cardNumber = TestCards.VISA.SUCCESS;
+ *
+ * // Check response codes
+ * if (response.response_code === ResponseCodes.SUCCESS) {
+ *   // Payment successful
+ * }
+ * ```
+ */
+/**
+ * Test card numbers for sandbox environment
+ *
+ * These cards can be used in the sandbox environment to simulate different scenarios.
+ *
+ * @example
+ * ```typescript
+ * import { TestCards } from '@sikka/aps';
+ *
+ * // Successful Visa payment
+ * const payment = await aps.tokens.create({
+ *   cardNumber: TestCards.VISA.SUCCESS,
+ *   expiryMonth: '12',
+ *   expiryYear: '25',
+ *   cvv: '123'
+ * });
+ *
+ * // Declined Mastercard
+ * const declined = await aps.tokens.create({
+ *   cardNumber: TestCards.MASTERCARD.DECLINED,
+ *   expiryMonth: '12',
+ *   expiryYear: '25',
+ *   cvv: '123'
+ * });
+ * ```
+ */
+declare const TestCards: {
+    /**
+     * Visa test cards
+     */
+    readonly VISA: {
+        /** Successful payment */
+        readonly SUCCESS: "4111111111111111";
+        /** Declined payment */
+        readonly DECLINED: "4000000000000002";
+        /** Insufficient funds */
+        readonly INSUFFICIENT_FUNDS: "4000000000009995";
+        /** Lost card */
+        readonly LOST_CARD: "4000000000009987";
+        /** Stolen card */
+        readonly STOLEN_CARD: "4000000000009979";
+        /** Expired card */
+        readonly EXPIRED_CARD: "4000000000009961";
+        /** Invalid CVV */
+        readonly INVALID_CVV: "4000000000000127";
+        /** 3D Secure required */
+        readonly REQUIRES_3DS: "4000000000003220";
+    };
+    /**
+     * Mastercard test cards
+     */
+    readonly MASTERCARD: {
+        /** Successful payment */
+        readonly SUCCESS: "5100000000000008";
+        /** Declined payment */
+        readonly DECLINED: "5400000000000003";
+        /** Insufficient funds */
+        readonly INSUFFICIENT_FUNDS: "5400000000000094";
+        /** 3D Secure required */
+        readonly REQUIRES_3DS: "5400000000000094";
+    };
+    /**
+     * MADA (Saudi Arabia) test cards
+     */
+    readonly MADA: {
+        /** Successful payment */
+        readonly SUCCESS: "5297410000000002";
+        /** Declined payment */
+        readonly DECLINED: "5297410000000010";
+        /** 3D Secure required */
+        readonly REQUIRES_3DS: "5297410000000028";
+    };
+    /**
+     * American Express test cards
+     */
+    readonly AMEX: {
+        /** Successful payment */
+        readonly SUCCESS: "371449635398431";
+        /** Declined payment */
+        readonly DECLINED: "378282246310005";
+    };
+    /**
+     * Test card defaults
+     */
+    readonly DEFAULTS: {
+        /** Default expiry month (MM) */
+        readonly EXPIRY_MONTH: "12";
+        /** Default expiry year (YY) */
+        readonly EXPIRY_YEAR: "25";
+        /** Default CVV */
+        readonly CVV: "123";
+        /** Default cardholder name */
+        readonly CARDHOLDER_NAME: "Test User";
+    };
+};
+/**
+ * APS Response Codes
+ *
+ * Complete list of response codes from Amazon Payment Services API.
+ *
+ * @example
+ * ```typescript
+ * import { ResponseCodes } from '@sikka/aps';
+ *
+ * if (response.response_code === ResponseCodes.SUCCESS) {
+ *   // Handle success
+ * } else if (response.response_code === ResponseCodes.INSUFFICIENT_FUNDS) {
+ *   // Handle insufficient funds
+ * }
+ * ```
+ */
+declare const ResponseCodes: {
+    /** Transaction successful */
+    readonly SUCCESS: "00000";
+    /** Payment link created successfully */
+    readonly PAYMENT_LINK_SUCCESS: "48000";
+    /** Recurring payment successful */
+    readonly RECURRING_SUCCESS: "14000";
+    /** 3D Secure authentication failed */
+    readonly AUTHENTICATION_FAILED: "10030";
+    /** 3D Secure not enrolled */
+    readonly NOT_ENROLLED_3DS: "10031";
+    /** Signature mismatch */
+    readonly SIGNATURE_MISMATCH: "00008";
+    /** Invalid access code */
+    readonly INVALID_ACCESS_CODE: "00009";
+    /** Invalid merchant identifier */
+    readonly INVALID_MERCHANT_ID: "00010";
+    /** Card expired */
+    readonly CARD_EXPIRED: "10035";
+    /** Invalid card number */
+    readonly INVALID_CARD_NUMBER: "10036";
+    /** Invalid CVV */
+    readonly INVALID_CVV: "10037";
+    /** Card not supported */
+    readonly CARD_NOT_SUPPORTED: "10038";
+    /** Lost card */
+    readonly LOST_CARD: "10039";
+    /** Stolen card */
+    readonly STOLEN_CARD: "10040";
+    /** Restricted card */
+    readonly RESTRICTED_CARD: "10041";
+    /** Card blocked */
+    readonly CARD_BLOCKED: "10042";
+    /** Invalid expiry date */
+    readonly INVALID_EXPIRY: "10043";
+    /** Transaction declined */
+    readonly DECLINED: "14001";
+    /** Insufficient funds */
+    readonly INSUFFICIENT_FUNDS: "14002";
+    /** Transaction limit exceeded */
+    readonly LIMIT_EXCEEDED: "14003";
+    /** Invalid transaction */
+    readonly INVALID_TRANSACTION: "14004";
+    /** Duplicate transaction */
+    readonly DUPLICATE_TRANSACTION: "14005";
+    /** Transaction not allowed */
+    readonly TRANSACTION_NOT_ALLOWED: "14006";
+    /** Transaction expired */
+    readonly TRANSACTION_EXPIRED: "14007";
+    /** Transaction already captured */
+    readonly ALREADY_CAPTURED: "14008";
+    /** Transaction already voided */
+    readonly ALREADY_VOIDED: "14009";
+    /** Transaction already refunded */
+    readonly ALREADY_REFUNDED: "14010";
+    /** Invalid amount */
+    readonly INVALID_AMOUNT: "15001";
+    /** Amount too small */
+    readonly AMOUNT_TOO_SMALL: "15002";
+    /** Amount too large */
+    readonly AMOUNT_TOO_LARGE: "15003";
+    /** Currency not supported */
+    readonly CURRENCY_NOT_SUPPORTED: "15004";
+    /** Missing parameter */
+    readonly MISSING_PARAMETER: "00001";
+    /** Invalid parameter format */
+    readonly INVALID_PARAMETER: "00002";
+    /** Invalid command */
+    readonly INVALID_COMMAND: "00003";
+    /** Invalid language */
+    readonly INVALID_LANGUAGE: "00004";
+    /** Invalid currency */
+    readonly INVALID_CURRENCY: "00005";
+    /** Invalid return URL */
+    readonly INVALID_RETURN_URL: "00006";
+    /** Invalid customer email */
+    readonly INVALID_EMAIL: "00007";
+    /** Parameter value not allowed */
+    readonly PARAMETER_VALUE_NOT_ALLOWED: "00033";
+    /** Token not found */
+    readonly TOKEN_NOT_FOUND: "16001";
+    /** Token expired */
+    readonly TOKEN_EXPIRED: "16002";
+    /** Token already used */
+    readonly TOKEN_ALREADY_USED: "16003";
+    /** Invalid token */
+    readonly INVALID_TOKEN: "16004";
+    /** System error */
+    readonly SYSTEM_ERROR: "90001";
+    /** Service unavailable */
+    readonly SERVICE_UNAVAILABLE: "90002";
+    /** Timeout */
+    readonly TIMEOUT: "90003";
+    /** Database error */
+    readonly DATABASE_ERROR: "90004";
+    /** Internal error */
+    readonly INTERNAL_ERROR: "90005";
+};
+/**
+ * Error Categories
+ *
+ * Group response codes into categories for easier handling.
+ *
+ * @example
+ * ```typescript
+ * import { ErrorCategories, categorizeError } from '@sikka/aps';
+ *
+ * const category = categorizeError(response.response_code);
+ *
+ * if (category === ErrorCategories.CARD_ERROR) {
+ *   // Ask customer to check card details
+ * } else if (category === ErrorCategories.RETRYABLE) {
+ *   // Can retry the transaction
+ * }
+ * ```
+ */
+declare const ErrorCategories: {
+    /** Success - no error */
+    readonly SUCCESS: "success";
+    /** Card-related errors (expired, invalid, blocked) */
+    readonly CARD_ERROR: "card_error";
+    /** Authentication errors (3DS, signature) */
+    readonly AUTHENTICATION_ERROR: "authentication_error";
+    /** Transaction errors (declined, insufficient funds) */
+    readonly TRANSACTION_ERROR: "transaction_error";
+    /** Amount/currency errors */
+    readonly AMOUNT_ERROR: "amount_error";
+    /** Parameter validation errors */
+    readonly VALIDATION_ERROR: "validation_error";
+    /** Tokenization errors */
+    readonly TOKEN_ERROR: "token_error";
+    /** System/technical errors */
+    readonly SYSTEM_ERROR: "system_error";
+    /** Errors that can be retried */
+    readonly RETRYABLE: "retryable";
+    /** Errors that should not be retried */
+    readonly NON_RETRYABLE: "non_retryable";
+};
+/**
+ * Categorize an error code
+ *
+ * @param code - The APS response code
+ * @returns The error category
+ *
+ * @example
+ * ```typescript
+ * import { categorizeError, ErrorCategories } from '@sikka/aps';
+ *
+ * const category = categorizeError('14002');
+ * console.log(category); // 'transaction_error'
+ *
+ * if (category === ErrorCategories.CARD_ERROR) {
+ *   // Show card error message to customer
+ * }
+ * ```
+ */
+declare function categorizeError(code: string): string;
+/**
+ * Check if an error code is retryable
+ *
+ * @param code - The APS response code
+ * @returns True if the error can be retried
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError } from '@sikka/aps';
+ *
+ * if (isRetryableError(response.response_code)) {
+ *   // Retry the transaction
+ *   await retryPayment();
+ * }
+ * ```
+ */
+declare function isRetryableError$1(code: string): boolean;
+/**
+ * Payment method codes used by APS
+ */
+declare const PaymentMethodCodes: {
+    /** Visa */
+    readonly VISA: "VISA";
+    /** Mastercard */
+    readonly MASTERCARD: "MASTERCARD";
+    /** American Express */
+    readonly AMEX: "AMEX";
+    /** MADA (Saudi Arabia) */
+    readonly MADA: "MADA";
+    /** Apple Pay */
+    readonly APPLE_PAY: "APPLE_PAY";
+    /** STC Pay (Saudi Arabia) */
+    readonly STC_PAY: "STC_PAY";
+    /** KNET (Kuwait) */
+    readonly KNET: "KNET";
+    /** NAPS (Qatar) */
+    readonly NAPS: "NAPS";
+    /** Fawry (Egypt) */
+    readonly FAWRY: "FAWRY";
+    /** Meeza (Egypt) */
+    readonly MEEZA: "MEEZA";
+    /** Sadad (Saudi Arabia) */
+    readonly SADAD: "SADAD";
+    /** Aman (Egypt) */
+    readonly AMAN: "AMAN";
+    /** Tabby (BNPL) */
+    readonly TABBY: "TABBY";
+    /** Tamara (BNPL) */
+    readonly TAMARA: "TAMARA";
+    /** valU (BNPL) */
+    readonly VALU: "VALU";
+};
+/**
+ * Currency codes supported by APS
+ */
+declare const CurrencyCodes: {
+    /** Saudi Riyal */
+    readonly SAR: "SAR";
+    /** UAE Dirham */
+    readonly AED: "AED";
+    /** Kuwaiti Dinar */
+    readonly KWD: "KWD";
+    /** Qatari Riyal */
+    readonly QAR: "QAR";
+    /** Bahraini Dinar */
+    readonly BHD: "BHD";
+    /** Omani Rial */
+    readonly OMR: "OMR";
+    /** Jordanian Dinar */
+    readonly JOD: "JOD";
+    /** Egyptian Pound */
+    readonly EGP: "EGP";
+    /** US Dollar */
+    readonly USD: "USD";
+    /** Euro */
+    readonly EUR: "EUR";
+    /** British Pound */
+    readonly GBP: "GBP";
+};
+/**
+ * Language codes supported by APS
+ */
+declare const LanguageCodes: {
+    /** English */
+    readonly EN: "en";
+    /** Arabic */
+    readonly AR: "ar";
+};
+/**
+ * Transaction commands
+ */
+declare const Commands: {
+    /** Purchase (direct charge) */
+    readonly PURCHASE: "PURCHASE";
+    /** Authorization (hold funds) */
+    readonly AUTHORIZATION: "AUTHORIZATION";
+    /** Capture authorized funds */
+    readonly CAPTURE: "CAPTURE";
+    /** Refund a transaction */
+    readonly REFUND: "REFUND";
+    /** Void a transaction */
+    readonly VOID: "VOID";
+    /** Query transaction status */
+    readonly QUERY: "QUERY_TRANSACTION";
+    /** Tokenize a card */
+    readonly TOKENIZATION: "TOKENIZATION";
+    /** Create token */
+    readonly CREATE_TOKEN: "CREATE_TOKEN";
+    /** Verify token */
+    readonly VERIFY_TOKEN: "VERIFY_TOKEN";
+    /** Delete token */
+    readonly DELETE_TOKEN: "DELETE_TOKEN";
+    /** Get saved cards */
+    readonly GET_CARDS: "GET_CARDS";
+    /** Payment link */
+    readonly PAYMENT_LINK: "PAYMENT_LINK";
+};
+/**
+ * ECI (Electronic Commerce Indicator) values
+ */
+declare const ECIValues: {
+    /** Secure e-commerce with 3DS */
+    readonly SECURE_3DS: "05";
+    /** Non-3DS e-commerce */
+    readonly NON_3DS: "07";
+    /** Recurring payment */
+    readonly RECURRING: "RECURRING";
+    /** Merchant-initiated */
+    readonly MERCHANT_INITIATED: "07";
+};
+/**
+ * Status codes returned by APS
+ */
+declare const StatusCodes: {
+    /** Success */
+    readonly SUCCESS: "20";
+    /** Pending/3DS required */
+    readonly PENDING: "3";
+    /** Authorized */
+    readonly AUTHORIZED: "02";
+    /** Captured */
+    readonly CAPTURED: "04";
+};
+
+/**
+ * Error Handling for Amazon Payment Services
+ *
+ * Provides human-readable error messages, suggested actions, and error categorization
+ * for all APS response codes.
+ *
+ * @example
+ * ```typescript
+ * import { getErrorDetails, isRetryableError } from '@sikka/aps';
+ *
+ * try {
+ *   await aps.paymentLinks.create({...});
+ * } catch (error) {
+ *   if (error instanceof APSException) {
+ *     const details = getErrorDetails(error.code);
+ *     console.log(details.message);      // Human-readable message
+ *     console.log(details.action);       // Suggested action
+ *     console.log(details.category);     // Error category
+ *     console.log(details.documentation); // Link to docs
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Error details interface
+ */
+interface ErrorDetails {
+    /** The error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Suggested action to resolve */
+    action: string;
+    /** Error category */
+    category: string;
+    /** Whether this error can be retried */
+    retryable: boolean;
+    /** Link to APS documentation */
+    documentation: string;
+    /** HTTP status code (if applicable) */
+    httpStatus?: number;
+}
+/**
+ * Get detailed error information for an APS response code
+ *
+ * @param code - The APS response code
+ * @returns Error details with message, action, and documentation link
+ *
+ * @example
+ * ```typescript
+ * import { getErrorDetails } from '@sikka/aps';
+ *
+ * const details = getErrorDetails('14002');
+ * console.log(details.message);    // "The card has insufficient funds."
+ * console.log(details.action);     // "Ask the customer to use a different card..."
+ * console.log(details.retryable);  // false
+ * ```
+ */
+declare function getErrorDetails(code: string): ErrorDetails;
+/**
+ * Check if an error code is retryable
+ *
+ * @param code - The APS response code
+ * @returns True if the error can be safely retried
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError } from '@sikka/aps';
+ *
+ * if (isRetryableError(error.code)) {
+ *   await retryPayment();
+ * }
+ * ```
+ */
+declare function isRetryableError(code: string): boolean;
+/**
+ * Get a user-friendly error message for display
+ *
+ * @param code - The APS response code
+ * @param includeAction - Whether to include the suggested action (default: true)
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * import { getUserFriendlyMessage } from '@sikka/aps';
+ *
+ * const message = getUserFriendlyMessage('14002');
+ * // "The card has insufficient funds. Ask the customer to use a different card..."
+ *
+ * const shortMessage = getUserFriendlyMessage('14002', false);
+ * // "The card has insufficient funds."
+ * ```
+ */
+declare function getUserFriendlyMessage(code: string, includeAction?: boolean): string;
+/**
+ * Format an error for logging
+ *
+ * @param code - The APS response code
+ * @param context - Additional context (order ID, transaction ID, etc.)
+ * @returns Formatted log message
+ *
+ * @example
+ * ```typescript
+ * import { formatErrorForLogging } from '@sikka/aps';
+ *
+ * const logMessage = formatErrorForLogging('14002', {
+ *   orderId: 'order_123',
+ *   customerEmail: 'customer@example.com'
+ * });
+ * // "[APS Error 14002] INSUFFICIENT_FUNDS: The card has insufficient funds. (orderId: order_123)"
+ * ```
+ */
+declare function formatErrorForLogging(code: string, context?: Record<string, string>): string;
+/**
+ * Check if the response code indicates success
+ *
+ * @param code - The APS response code
+ * @returns True if the code indicates success
+ *
+ * @example
+ * ```typescript
+ * import { isSuccessCode } from '@sikka/aps';
+ *
+ * if (isSuccessCode(response.response_code)) {
+ *   // Handle success
+ * }
+ * ```
+ */
+declare function isSuccessCode(code: string): boolean;
+/**
+ * Get all error codes for a category
+ *
+ * @param category - The error category
+ * @returns Array of error codes in that category
+ *
+ * @example
+ * ```typescript
+ * import { getErrorCodesByCategory, ErrorCategories } from '@sikka/aps';
+ *
+ * const cardErrors = getErrorCodesByCategory(ErrorCategories.CARD_ERROR);
+ * // ['10035', '10036', '10037', ...]
+ * ```
+ */
+declare function getErrorCodesByCategory(category: string): string[];
+/**
+ * Suggest HTTP status code for an APS error
+ *
+ * @param code - The APS response code
+ * @returns Suggested HTTP status code
+ *
+ * @example
+ * ```typescript
+ * import { suggestHttpStatus } from '@sikka/aps';
+ *
+ * const status = suggestHttpStatus('14002');
+ * // 402 (Payment Required)
+ * ```
+ */
+declare function suggestHttpStatus(code: string): number;
+
+/**
+ * Validation Utilities for Amazon Payment Services
+ *
+ * Provides validation functions for APS-specific data formats and requirements.
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * // Validate merchant reference
+ * if (!validators.isValidMerchantReference(ref)) {
+ *   throw new Error('Invalid merchant reference format');
+ * }
+ *
+ * // Validate signature
+ * if (!validators.isValidSignature(payload, signature, secret)) {
+ *   throw new Error('Invalid signature');
+ * }
+ * ```
+ */
+/**
+ * Validation result interface
+ */
+interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Error message if validation failed */
+    error?: string;
+    /** Error code if validation failed */
+    code?: string;
+}
+/**
+ * Validate a merchant reference
+ *
+ * APS has specific requirements for merchant_reference:
+ * - Must be unique per transaction
+ * - Max 40 characters
+ * - Alphanumeric and underscores only
+ *
+ * @param reference - The merchant reference to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidMerchantReference('order_123');
+ * if (!result.valid) {
+ *   console.log(result.error); // "Merchant reference must be 40 characters or less"
+ * }
+ * ```
+ */
+declare function isValidMerchantReference(reference: string): ValidationResult;
+/**
+ * Validate an amount for APS
+ *
+ * APS requires amounts in the smallest currency unit (cents, fils)
+ * without decimal points.
+ *
+ * @param amount - The amount to validate
+ * @param currency - The currency code
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * // Valid: 10000 = 100.00 SAR
+ * const result = validators.isValidAmount(10000, 'SAR');
+ *
+ * // Invalid: decimal amounts not allowed
+ * const result2 = validators.isValidAmount(100.50, 'SAR');
+ * ```
+ */
+declare function isValidAmount(amount: number, _currency?: string): ValidationResult;
+/**
+ * Validate a currency code
+ *
+ * @param currency - The currency code to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidCurrency('SAR'); // valid
+ * const result2 = validators.isValidCurrency('INVALID'); // invalid
+ * ```
+ */
+declare function isValidCurrency(currency: string): ValidationResult;
+/**
+ * Validate an email address
+ *
+ * @param email - The email to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidEmail('customer@example.com');
+ * ```
+ */
+declare function isValidEmail(email: string): ValidationResult;
+/**
+ * Validate a card number using Luhn algorithm
+ *
+ * @param cardNumber - The card number to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidCardNumber('4111111111111111');
+ * ```
+ */
+declare function isValidCardNumber(cardNumber: string): ValidationResult;
+/**
+ * Validate expiry date
+ *
+ * @param month - Expiry month (1-12 or 01-12)
+ * @param year - Expiry year (2-digit or 4-digit)
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidExpiryDate('12', '25');
+ * const result2 = validators.isValidExpiryDate('12', '2025');
+ * ```
+ */
+declare function isValidExpiryDate(month: string, year: string): ValidationResult;
+/**
+ * Validate CVV
+ *
+ * @param cvv - The CVV to validate
+ * @param cardType - Optional card type (affects CVV length)
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidCVV('123');     // Visa/MC
+ * const result2 = validators.isValidCVV('1234');   // Amex
+ * ```
+ */
+declare function isValidCVV(cvv: string, cardType?: string): ValidationResult;
+/**
+ * Validate a return URL
+ *
+ * @param url - The URL to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidReturnUrl('https://example.com/result');
+ * ```
+ */
+declare function isValidReturnUrl(url: string): ValidationResult;
+/**
+ * Validate an APS signature
+ *
+ * @param params - The parameters that were signed
+ * @param signature - The signature to validate
+ * @param secret - The secret key used for signing
+ * @returns Whether the signature is valid
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const isValid = validators.isValidSignature(
+ *   params,
+ *   response.signature,
+ *   process.env.APS_RESPONSE_SECRET
+ * );
+ * ```
+ */
+declare function isValidSignature(params: Record<string, string>, signature: string, secret: string): boolean;
+/**
+ * Validate webhook payload
+ *
+ * @param payload - The webhook payload
+ * @param signature - The signature from headers
+ * @param secret - The response secret
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidWebhookPayload(
+ *   req.body,
+ *   req.headers['x-aps-signature'],
+ *   process.env.APS_RESPONSE_SECRET
+ * );
+ *
+ * if (!result.valid) {
+ *   return res.status(401).send('Invalid signature');
+ * }
+ * ```
+ */
+declare function isValidWebhookPayload(payload: Record<string, any>, signature: string, secret: string): ValidationResult;
+/**
+ * Validate language code
+ *
+ * @param language - The language code to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidLanguage('en');
+ * const result2 = validators.isValidLanguage('ar');
+ * ```
+ */
+declare function isValidLanguage(language: string): ValidationResult;
+/**
+ * Validate token name
+ *
+ * @param tokenName - The token name to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidTokenName('token_abc123');
+ * ```
+ */
+declare function isValidTokenName(tokenName: string): ValidationResult;
+/**
+ * Validate phone number
+ *
+ * @param phone - The phone number to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidPhone('+966501234567');
+ * ```
+ */
+declare function isValidPhone(phone: string): ValidationResult;
+/**
+ * Validate order description
+ *
+ * @param description - The description to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidDescription('Premium Plan Subscription');
+ * ```
+ */
+declare function isValidDescription(description: string): ValidationResult;
+/**
+ * Validate customer name
+ *
+ * @param name - The customer name to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.isValidCustomerName('John Doe');
+ * ```
+ */
+declare function isValidCustomerName(name: string): ValidationResult;
+/**
+ * Validate all payment parameters at once
+ *
+ * @param params - The payment parameters to validate
+ * @returns Validation result with all errors
+ *
+ * @example
+ * ```typescript
+ * import { validators } from '@sikka/aps';
+ *
+ * const result = validators.validatePaymentParams({
+ *   merchant_reference: 'order_123',
+ *   amount: 10000,
+ *   currency: 'SAR',
+ *   customer_email: 'customer@example.com'
+ * });
+ *
+ * if (!result.valid) {
+ *   console.log(result.errors);
+ * }
+ * ```
+ */
+declare function validatePaymentParams(params: {
+    merchant_reference?: string;
+    amount?: number;
+    currency?: string;
+    customer_email?: string;
+    return_url?: string;
+    description?: string;
+    language?: string;
+}): {
+    valid: boolean;
+    errors: Array<{
+        field: string;
+        error: string;
+        code: string;
+    }>;
+};
+/**
+ * Export all validators as a namespace
+ */
+declare const validators: {
+    isValidMerchantReference: typeof isValidMerchantReference;
+    isValidAmount: typeof isValidAmount;
+    isValidCurrency: typeof isValidCurrency;
+    isValidEmail: typeof isValidEmail;
+    isValidCardNumber: typeof isValidCardNumber;
+    isValidExpiryDate: typeof isValidExpiryDate;
+    isValidCVV: typeof isValidCVV;
+    isValidReturnUrl: typeof isValidReturnUrl;
+    isValidSignature: typeof isValidSignature;
+    isValidWebhookPayload: typeof isValidWebhookPayload;
+    isValidLanguage: typeof isValidLanguage;
+    isValidTokenName: typeof isValidTokenName;
+    isValidPhone: typeof isValidPhone;
+    isValidDescription: typeof isValidDescription;
+    isValidCustomerName: typeof isValidCustomerName;
+    validatePaymentParams: typeof validatePaymentParams;
+};
+
+/**
+ * Amazon Payment Services SDK
+ *
+ * A Stripe-like developer-friendly SDK for Amazon Payment Services integration.
+ *
+ * @example
+ * ```typescript
+ * import APS from 'amazon-payment-services';
+ *
+ * // Initialize the client
+ * const aps = new APS({
+ *   merchantId: process.env.APS_MERCHANT_ID,
+ *   accessCode: process.env.APS_ACCESS_CODE,
+ *   requestSecret: process.env.APS_REQUEST_SECRET,
+ *   responseSecret: process.env.APS_RESPONSE_SECRET,
+ *   environment: 'sandbox' // or 'production'
+ * });
+ *
+ * // Create a payment link
+ * const link = await aps.paymentLinks.create({
+ *   order: {
+ *     id: 'order_123',
+ *     amount: 10000, // $100.00
+ *     currency: 'USD'
+ *   },
+ *   successUrl: 'https://yoursite.com/success'
+ * });
+ *
+ * // Create hosted checkout
+ * const checkout = await aps.hostedCheckout.create({
+ *   order: { ... },
+ *   successUrl: 'https://yoursite.com/success'
+ * });
+ *
+ * // Tokenize a card
+ * const token = await aps.tokens.create({
+ *   cardNumber: '4111111111111111',
+ *   expiryMonth: '12',
+ *   expiryYear: '25',
+ *   cvv: '123'
+ * });
+ *
+ * // Capture, refund, void payments
+ * await aps.payments.capture({ transactionId: 'txn_123' });
+ * await aps.payments.refund({ transactionId: 'txn_123', amount: 5000 });
+ * await aps.payments.void({ transactionId: 'txn_123' });
+ *
+ * // Handle webhooks
+ * const event = aps.webhooks.constructEvent(payload);
+ * ```
+ */
+
+declare const APS: typeof APSClient;
+
+export { APS, APSClient, type APSClientOptions, type APSConfig, type APSError, APSException, type CaptureOptions, type CaptureResponse, Commands, CurrencyCodes, CustomPaymentPageModule, type CustomPaymentPageOptions, type Customer, ECIValues, ErrorCategories, type ErrorDetails, HostedCheckoutModule, type HostedCheckoutOptions, type IdempotencyOptions, LanguageCodes, type Logger, type Order, type PaymentLinkOptions, type PaymentLinkResponse, PaymentLinksModule, type PaymentMethod, PaymentMethodCodes, type PaymentResponse, PaymentsModule, type QueryOptions, type RateLimitConfig, RecurringModule, type RecurringPaymentOptions, type RecurringPaymentResponse, type RefundOptions, type RefundResponse, ResponseCodes, type SavedCard, type SavedCardsList, StatusCodes, TestCards, TokenizationModule, type TokenizeCardOptions, type TokenizedCard, type TransactionStatus, type ValidationResult, type VoidOptions, type VoidResponse, type WebhookEvent, type WebhookEventType, WebhooksModule, categorizeError, isRetryableError as checkRetryableError, APSClient as default, formatErrorForLogging, getErrorCodesByCategory, getErrorDetails, getUserFriendlyMessage, isRetryableError$1 as isRetryableError, isSuccessCode, isValidAmount, isValidCVV, isValidCardNumber, isValidCurrency, isValidCustomerName, isValidDescription, isValidEmail, isValidExpiryDate, isValidLanguage, isValidMerchantReference, isValidPhone, isValidReturnUrl, isValidSignature, isValidTokenName, isValidWebhookPayload, suggestHttpStatus, validatePaymentParams, validators };