@sikka/aps 0.0.1

package/dist/index.mjs

@@ -0,0 +1,2741 @@
+// src/types.ts
+var APSException = class extends Error {
+  constructor(error) {
+    super(error.message);
+    this.name = "APSException";
+    this.code = error.code;
+    this.statusCode = error.statusCode;
+    this.rawResponse = error.rawResponse;
+  }
+};
+
+// src/utils.ts
+import crypto from "crypto";
+var noopLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+function generateHMAC(data, secret) {
+  return crypto.createHmac("sha256", secret).update(data).digest("base64");
+}
+function verifyHMAC(data, signature, secret) {
+  const expectedSignature = generateHMAC(data, secret);
+  return expectedSignature === signature;
+}
+function buildQueryString(params) {
+  return Object.entries(params).filter(([_, value]) => value !== void 0 && value !== null && value !== "").sort((a, b) => a[0].localeCompare(b[0])).map(([key, value]) => `${key}=${value}`).join("&");
+}
+function getBaseUrl(environment) {
+  if (environment === "production") {
+    return "https://checkout.payfort.com";
+  }
+  return "https://sbcheckout.payfort.com";
+}
+function getHostedCheckoutUrl(environment) {
+  if (environment === "production") {
+    return "https://checkout.payfort.com/FortAPI/paymentPage";
+  }
+  return "https://sbcheckout.payfort.com/FortAPI/paymentPage";
+}
+function getApiUrl(environment) {
+  if (environment === "production") {
+    return "https://paymentservices.payfort.com";
+  }
+  return "https://sbpaymentservices.payfort.com";
+}
+function generateOrderId() {
+  return `order_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var RateLimiter = class {
+  constructor(maxRequests = 100, windowMs = 6e4) {
+    this.requests = [];
+    this.maxRequests = maxRequests;
+    this.windowMs = windowMs;
+  }
+  /**
+   * Check if a request can be made
+   */
+  canMakeRequest() {
+    const now = Date.now();
+    this.requests = this.requests.filter((time) => now - time < this.windowMs);
+    return this.requests.length < this.maxRequests;
+  }
+  /**
+   * Record a request
+   */
+  recordRequest() {
+    this.requests.push(Date.now());
+  }
+  /**
+   * Get time until next request is allowed (in ms)
+   */
+  getTimeUntilNextRequest() {
+    if (this.canMakeRequest()) {
+      return 0;
+    }
+    const oldestRequest = Math.min(...this.requests);
+    return this.windowMs - (Date.now() - oldestRequest);
+  }
+  /**
+   * Wait until a request can be made
+   */
+  async waitForSlot() {
+    const waitTime = this.getTimeUntilNextRequest();
+    if (waitTime > 0) {
+      await sleep(waitTime);
+    }
+  }
+};
+var globalRateLimiter = null;
+function getRateLimiter(maxRequests, windowMs) {
+  if (!globalRateLimiter) {
+    globalRateLimiter = new RateLimiter(maxRequests, windowMs);
+  }
+  return globalRateLimiter;
+}
+async function makeRequest(url, body, options = {}) {
+  const {
+    timeout = DEFAULT_TIMEOUT,
+    maxRetries = DEFAULT_MAX_RETRIES,
+    retryDelayMs = 1e3,
+    logger = noopLogger,
+    idempotencyKey
+  } = options;
+  const rateLimiter = getRateLimiter();
+  if (!rateLimiter.canMakeRequest()) {
+    logger.warn?.("Rate limit reached, waiting for slot...");
+    await rateLimiter.waitForSlot();
+  }
+  let lastError = null;
+  const startTime = Date.now();
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (idempotencyKey) {
+    headers["Idempotency-Key"] = idempotencyKey;
+  }
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      logger.debug?.(`APS Request (attempt ${attempt + 1}/${maxRetries + 1}):`, { url, body });
+      rateLimiter.recordRequest();
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        if (response.status === 429) {
+          const retryAfter = response.headers.get("Retry-After");
+          const waitTime = retryAfter ? parseInt(retryAfter) * 1e3 : retryDelayMs * Math.pow(2, attempt);
+          logger.warn?.(`Rate limited (429), waiting ${waitTime}ms before retry...`);
+          await sleep(waitTime);
+          continue;
+        }
+        if (response.status >= 500 && attempt < maxRetries) {
+          const delay = retryDelayMs * Math.pow(2, attempt);
+          logger.warn?.(`Server error (${response.status}), retrying in ${delay}ms...`);
+          await sleep(delay);
+          continue;
+        }
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+      const data = await response.json();
+      const duration = Date.now() - startTime;
+      logger.info?.(`APS Response (${duration}ms):`, {
+        responseCode: data.response_code,
+        status: data.status
+      });
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (error instanceof Error && error.name === "AbortError") {
+        logger.error?.(`Request timed out after ${timeout}ms`);
+        throw new Error(`Request timed out after ${timeout}ms`);
+      }
+      logger.error?.(`Request failed (attempt ${attempt + 1}):`, lastError.message);
+      if (attempt < maxRetries) {
+        const delay = retryDelayMs * Math.pow(2, attempt);
+        await sleep(delay);
+        continue;
+      }
+    }
+  }
+  logger.error?.("Request failed after all retries:", lastError?.message);
+  throw lastError || new Error("Request failed after retries");
+}
+function validateRequiredFields(fields, required) {
+  const missing = required.filter((field) => {
+    const value = fields[field];
+    return value === void 0 || value === null || value === "";
+  });
+  if (missing.length > 0) {
+    throw new Error(`Missing required fields: ${missing.join(", ")}`);
+  }
+}
+function validateEmail(email) {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(email);
+}
+function validateCardNumber(cardNumber) {
+  const cleaned = cardNumber.replace(/\D/g, "");
+  if (cleaned.length < 13 || cleaned.length > 19) {
+    return false;
+  }
+  let sum = 0;
+  let shouldDouble = false;
+  for (let i = cleaned.length - 1; i >= 0; i--) {
+    let digit = parseInt(cleaned.charAt(i), 10);
+    if (shouldDouble) {
+      digit *= 2;
+      if (digit > 9) {
+        digit -= 9;
+      }
+    }
+    sum += digit;
+    shouldDouble = !shouldDouble;
+  }
+  return sum % 10 === 0;
+}
+function validateExpiryDate(month, year) {
+  const expiryMonth = parseInt(month, 10);
+  const expiryYear = parseInt(year.length === 2 ? `20${year}` : year, 10);
+  if (expiryMonth < 1 || expiryMonth > 12) {
+    return false;
+  }
+  const now = /* @__PURE__ */ new Date();
+  const currentYear = now.getFullYear();
+  const currentMonth = now.getMonth() + 1;
+  if (expiryYear < currentYear) {
+    return false;
+  }
+  if (expiryYear === currentYear && expiryMonth < currentMonth) {
+    return false;
+  }
+  return true;
+}
+function validateCVV(cvv) {
+  return /^\d{3,4}$/.test(cvv);
+}
+
+// src/modules/payment-links.ts
+import crypto2 from "crypto";
+var PaymentLinksModule = class {
+  constructor(config, options) {
+    this.config = config;
+    this.options = options;
+  }
+  /**
+   * Create a new payment link using APS Payment Links API
+   */
+  async create(options) {
+    try {
+      validateRequiredFields(options, ["order"]);
+      validateRequiredFields(options.order, ["amount", "currency"]);
+      if (options.order.customer?.email) {
+        if (!validateEmail(options.order.customer.email)) {
+          throw new Error("Invalid customer email format");
+        }
+      }
+      const orderId = options.order.id || `order_${Date.now()}`;
+      const amount = options.order.amount;
+      const currency = options.order.currency || this.config.currency;
+      const requestBody = {
+        service_command: "PAYMENT_LINK",
+        access_code: this.config.accessCode,
+        merchant_identifier: this.config.merchantId,
+        merchant_reference: orderId,
+        amount: amount.toString(),
+        currency,
+        language: this.config.language || "en",
+        customer_email: options.order.customer?.email || "customer@example.com",
+        notification_type: "NONE"
+      };
+      if (options.order.description) {
+        requestBody.order_description = options.order.description;
+      }
+      if (options.order.customer?.name) {
+        requestBody.customer_name = options.order.customer.name;
+      }
+      if (options.order.customer?.phone) {
+        requestBody.customer_phone = options.order.customer.phone;
+      }
+      if (options.recurring) {
+        requestBody.link_command = "AUTHORIZATION";
+      } else {
+        requestBody.link_command = "PURCHASE";
+      }
+      if (options.allowedPaymentMethods && options.allowedPaymentMethods.length > 0) {
+        requestBody.payment_option = options.allowedPaymentMethods[0];
+      }
+      if (options.tokenValidityHours && options.tokenValidityHours > 0) {
+        const expiryDate = /* @__PURE__ */ new Date();
+        expiryDate.setHours(expiryDate.getHours() + options.tokenValidityHours);
+        const year = expiryDate.getFullYear();
+        const month = String(expiryDate.getMonth() + 1).padStart(2, "0");
+        const day = String(expiryDate.getDate()).padStart(2, "0");
+        const hours = String(expiryDate.getHours()).padStart(2, "0");
+        const minutes = String(expiryDate.getMinutes()).padStart(2, "0");
+        const seconds = String(expiryDate.getSeconds()).padStart(2, "0");
+        requestBody.request_expiry_date = `${year}-${month}-${day}T${hours}:${minutes}:${seconds}+00:00`;
+      }
+      requestBody.signature = this.generateSignature(requestBody);
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeApiRequest(`${apiUrl}/FortAPI/paymentApi`, requestBody);
+      const isSuccess = response.status?.toString() === "20" || response.response_code?.toString() === "00000" || response.response_code?.toString() === "48000" || response.response_message?.toLowerCase() === "success";
+      if (!isSuccess) {
+        throw new APSException({
+          code: response.response_code?.toString() || "PAYMENT_LINK_ERROR",
+          message: response.response_message || "Failed to create payment link",
+          rawResponse: response
+        });
+      }
+      return {
+        url: response.payment_link,
+        linkId: response.payment_link_id,
+        orderId,
+        expiresAt: requestBody.request_expiry_date ? new Date(requestBody.request_expiry_date) : void 0,
+        rawResponse: response
+      };
+    } catch (error) {
+      if (error instanceof APSException) {
+        throw error;
+      }
+      const apsError = {
+        code: "PAYMENT_LINK_ERROR",
+        message: error instanceof Error ? error.message : "Failed to create payment link",
+        rawResponse: error
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * 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
+   */
+  generateSignature(params) {
+    const sortedKeys = Object.keys(params).sort();
+    const concatenated = sortedKeys.map((key) => `${key}=${params[key]}`).join("");
+    const signatureString = `${this.config.requestSecret}${concatenated}${this.config.requestSecret}`;
+    return crypto2.createHash("sha256").update(signatureString).digest("hex").toUpperCase();
+  }
+  /**
+   * Make API request to APS with timeout and retry support
+   */
+  async makeApiRequest(url, body, idempotencyKey) {
+    return makeRequest(url, body, {
+      timeout: this.options.timeout,
+      maxRetries: this.options.maxRetries,
+      logger: this.options.logger,
+      idempotencyKey
+    });
+  }
+  /**
+   * Generate a payment link URL (alias for create)
+   */
+  async generateUrl(options) {
+    const response = await this.create(options);
+    return response.url;
+  }
+};
+
+// src/modules/hosted-checkout.ts
+import crypto3 from "crypto";
+var HostedCheckoutModule = class {
+  constructor(config, _options) {
+    this.config = config;
+  }
+  /**
+   * Create a hosted checkout session
+   */
+  async create(checkoutOptions) {
+    try {
+      validateRequiredFields(checkoutOptions, ["order"]);
+      validateRequiredFields(checkoutOptions.order, ["amount", "currency"]);
+      if (checkoutOptions.order.customer?.email) {
+        if (!validateEmail(checkoutOptions.order.customer.email)) {
+          throw new Error("Invalid customer email format");
+        }
+      }
+      const orderId = checkoutOptions.order.id || generateOrderId();
+      const amount = checkoutOptions.order.amount;
+      const currency = checkoutOptions.order.currency || this.config.currency;
+      const params = {
+        command: "PURCHASE",
+        access_code: this.config.accessCode,
+        merchant_identifier: this.config.merchantId,
+        merchant_reference: orderId,
+        amount: amount.toString(),
+        currency,
+        language: this.config.language || "en",
+        customer_email: checkoutOptions.order.customer?.email || "customer@example.com"
+        // Required by APS
+      };
+      if (checkoutOptions.order.description) {
+        params.order_description = checkoutOptions.order.description;
+      }
+      if (checkoutOptions.order.customer?.email) {
+        params.customer_email = checkoutOptions.order.customer.email;
+      }
+      if (checkoutOptions.order.customer?.name) {
+        params.customer_name = checkoutOptions.order.customer.name;
+      }
+      if (checkoutOptions.order.customer?.phone) {
+        params.customer_phone = checkoutOptions.order.customer.phone;
+      }
+      if (checkoutOptions.order.customer?.billingAddress) {
+        const addr = checkoutOptions.order.customer.billingAddress;
+        if (addr.street) params.billing_address = addr.street;
+        if (addr.city) params.billing_city = addr.city;
+        if (addr.state) params.billing_state = addr.state;
+        if (addr.country) params.billing_country = addr.country;
+        if (addr.postalCode) params.billing_postal_code = addr.postalCode;
+      }
+      if (checkoutOptions.successUrl) {
+        params.return_url = checkoutOptions.successUrl;
+      } else if (checkoutOptions.failureUrl) {
+        params.return_url = checkoutOptions.failureUrl;
+      } else if (checkoutOptions.cancelUrl) {
+        params.return_url = checkoutOptions.cancelUrl;
+      }
+      if (checkoutOptions.allowedPaymentMethods && checkoutOptions.allowedPaymentMethods.length > 0) {
+        params.payment_option = String(checkoutOptions.allowedPaymentMethods[0]);
+      }
+      if (checkoutOptions.hideShipping) {
+        params.hide_shipping = "YES";
+      }
+      if (checkoutOptions.metadata) {
+        for (const [key, value] of Object.entries(checkoutOptions.metadata)) {
+          params[`merchant_param_${key}`] = value;
+        }
+      }
+      const sortedKeys = Object.keys(params).sort();
+      const concatenated = sortedKeys.map((key) => `${key}=${params[key]}`).join("");
+      const signatureString = `${this.config.requestSecret}${concatenated}${this.config.requestSecret}`;
+      params.signature = crypto3.createHash("sha256").update(signatureString).digest("hex");
+      const checkoutUrl = getHostedCheckoutUrl(this.config.environment);
+      const status = "pending";
+      return {
+        transactionId: orderId,
+        orderId,
+        status,
+        amount,
+        currency,
+        redirectForm: {
+          url: checkoutUrl,
+          method: "POST",
+          params
+        },
+        rawResponse: params
+      };
+    } catch (error) {
+      const apsError = {
+        code: "HOSTED_CHECKOUT_ERROR",
+        message: error instanceof Error ? error.message : "Failed to create hosted checkout",
+        rawResponse: error
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * Get the redirect URL for hosted checkout
+   */
+  async getRedirectUrl(options) {
+    const response = await this.create(options);
+    if (response.redirectForm) {
+      return response.redirectForm.url;
+    }
+    throw new APSException({
+      code: "NO_REDIRECT_URL",
+      message: "No redirect URL available"
+    });
+  }
+};
+
+// src/modules/custom-payment-page.ts
+import crypto4 from "crypto";
+var CustomPaymentPageModule = class {
+  constructor(config, options) {
+    this.config = config;
+    this.options = options;
+  }
+  /**
+   * Get tokenization form data
+   * This form should be submitted from the frontend to APS
+   */
+  getTokenizationForm(options) {
+    const merchantRef = options.merchantReference || `token_${Date.now()}`;
+    const params = {
+      service_command: "TOKENIZATION",
+      language: this.config.language || "en",
+      merchant_identifier: this.config.merchantId,
+      access_code: this.config.accessCode,
+      return_url: options.returnUrl,
+      merchant_reference: merchantRef
+    };
+    if (options.cardNumber) {
+      params.card_number = options.cardNumber;
+    }
+    if (options.expiryDate) {
+      params.expiry_date = options.expiryDate;
+    }
+    if (options.cardSecurityCode) {
+      params.card_security_code = options.cardSecurityCode;
+    }
+    if (options.cardHolderName) {
+      params.card_holder_name = options.cardHolderName;
+    }
+    const sortedKeys = Object.keys(params).sort();
+    const concatenated = sortedKeys.map((key) => `${key}=${params[key]}`).join("");
+    const signatureString = `${this.config.requestSecret}${concatenated}${this.config.requestSecret}`;
+    params.signature = crypto4.createHash("sha256").update(signatureString).digest("hex");
+    const url = getHostedCheckoutUrl(this.config.environment);
+    return {
+      url,
+      method: "POST",
+      params
+    };
+  }
+  /**
+   * Get create token form data (for saving cards without charging)
+   */
+  getCreateTokenForm(options) {
+    const merchantRef = options.merchantReference || `createtoken_${Date.now()}`;
+    const params = {
+      service_command: "CREATE_TOKEN",
+      language: this.config.language || "en",
+      merchant_identifier: this.config.merchantId,
+      access_code: this.config.accessCode,
+      return_url: options.returnUrl,
+      merchant_reference: merchantRef
+    };
+    if (options.cardNumber) {
+      params.card_number = options.cardNumber;
+    }
+    if (options.expiryDate) {
+      params.expiry_date = options.expiryDate;
+    }
+    if (options.cardHolderName) {
+      params.card_holder_name = options.cardHolderName;
+    }
+    const sortedKeys = Object.keys(params).sort();
+    const concatenated = sortedKeys.map((key) => `${key}=${params[key]}`).join("");
+    const signatureString = `${this.config.requestSecret}${concatenated}${this.config.requestSecret}`;
+    params.signature = crypto4.createHash("sha256").update(signatureString).digest("hex");
+    const url = getHostedCheckoutUrl(this.config.environment);
+    return {
+      url,
+      method: "POST",
+      params
+    };
+  }
+  /**
+   * Charge using a token received from tokenization
+   * This is a server-to-server call
+   */
+  async chargeWithToken(options) {
+    try {
+      validateRequiredFields(options, ["order", "tokenName", "customerEmail"]);
+      validateRequiredFields(options.order, ["amount", "currency"]);
+      if (!validateEmail(options.customerEmail)) {
+        throw new Error("Invalid customer email format");
+      }
+      const orderId = options.order.id || generateOrderId();
+      const amount = options.order.amount;
+      const currency = options.order.currency;
+      const requestBody = {
+        command: "PURCHASE",
+        access_code: this.config.accessCode,
+        merchant_identifier: this.config.merchantId,
+        merchant_reference: orderId,
+        amount: amount.toString(),
+        currency,
+        language: this.config.language || "en",
+        customer_email: options.customerEmail,
+        token_name: options.tokenName
+      };
+      if (options.order.description) {
+        requestBody.order_description = options.order.description;
+      }
+      if (options.customerName) {
+        requestBody.customer_name = options.customerName;
+      }
+      if (options.customerPhone) {
+        requestBody.customer_phone = options.customerPhone;
+      }
+      if (options.returnUrl) {
+        requestBody.return_url = options.returnUrl;
+      }
+      const sortedKeys = Object.keys(requestBody).sort();
+      const concatenated = sortedKeys.map((key) => `${key}=${requestBody[key]}`).join("");
+      const signatureString = `${this.config.requestSecret}${concatenated}${this.config.requestSecret}`;
+      requestBody.signature = crypto4.createHash("sha256").update(signatureString).digest("hex");
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeApiRequest(`${apiUrl}/FortAPI/paymentApi`, requestBody);
+      const isSuccess = response.status?.toString() === "20" || response.response_code?.toString() === "00000" || response.response_message?.toLowerCase() === "success";
+      if (!isSuccess) {
+        if (response["3ds_url"] || response.acs_url) {
+          return {
+            transactionId: response.fort_id || orderId,
+            orderId,
+            status: "pending",
+            amount,
+            currency,
+            authenticationUrl: response["3ds_url"] || response.acs_url,
+            redirectForm: {
+              url: response["3ds_url"] || response.acs_url,
+              method: "POST",
+              params: response
+            },
+            message: response.response_message,
+            rawResponse: response
+          };
+        }
+        throw new APSException({
+          code: response.response_code?.toString() || "PAYMENT_ERROR",
+          message: response.response_message || "Payment failed",
+          rawResponse: response
+        });
+      }
+      return {
+        transactionId: response.fort_id || orderId,
+        orderId,
+        status: "captured",
+        amount,
+        currency,
+        paymentMethod: response.payment_option,
+        message: response.response_message,
+        rawResponse: response
+      };
+    } catch (error) {
+      if (error instanceof APSException) {
+        throw error;
+      }
+      const apsError = {
+        code: "CUSTOM_PAYMENT_ERROR",
+        message: error instanceof Error ? error.message : "Failed to process payment",
+        rawResponse: error
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * Alias for chargeWithToken for backwards compatibility
+   */
+  async charge(options) {
+    if (options.cardToken) {
+      return this.chargeWithToken({
+        order: options.order,
+        tokenName: options.cardToken,
+        customerEmail: options.order.customer?.email || "customer@example.com",
+        returnUrl: options.returnUrl
+      });
+    }
+    throw new APSException({
+      code: "MISSING_TOKEN",
+      message: "Card token is required. Use getTokenizationForm() to collect card details first."
+    });
+  }
+  /**
+   * Make API request to APS with timeout and retry support
+   */
+  async makeApiRequest(url, body, idempotencyKey) {
+    return makeRequest(url, body, {
+      timeout: this.options.timeout,
+      maxRetries: this.options.maxRetries,
+      logger: this.options.logger,
+      idempotencyKey
+    });
+  }
+};
+
+// src/modules/tokenization.ts
+var TokenizationModule = class {
+  constructor(config, options) {
+    this.config = config;
+    this.options = options;
+  }
+  /**
+   * Tokenize card details
+   */
+  async create(options) {
+    try {
+      validateRequiredFields(options, ["cardNumber", "expiryMonth", "expiryYear", "cvv"]);
+      if (!validateCardNumber(options.cardNumber)) {
+        throw new APSException({
+          code: "INVALID_CARD",
+          message: "Invalid card number format",
+          rawResponse: {}
+        });
+      }
+      if (!validateExpiryDate(options.expiryMonth, options.expiryYear)) {
+        throw new APSException({
+          code: "INVALID_EXPIRY",
+          message: "Invalid or expired card",
+          rawResponse: {}
+        });
+      }
+      if (!validateCVV(options.cvv)) {
+        throw new APSException({
+          code: "INVALID_CVV",
+          message: "Invalid CVV format",
+          rawResponse: {}
+        });
+      }
+      const params = {
+        command: "tokenize",
+        access_code: this.config.accessCode,
+        merchant_id: this.config.merchantId,
+        language: this.config.language,
+        response_format: "json"
+      };
+      params.card_number = options.cardNumber;
+      params.expiry_month = options.expiryMonth;
+      params.expiry_year = options.expiryYear;
+      params.cvv = options.cvv;
+      if (options.cardholderName) {
+        params.card_holder_name = options.cardholderName;
+      }
+      const signatureString = buildQueryString(params);
+      params.signature = generateHMAC(signatureString, this.config.requestSecret);
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeTokenizeRequest(`${apiUrl}/tokenize`, params);
+      if (response.response_code?.toString() !== "00") {
+        throw new APSException({
+          code: response.response_code?.toString() || "TOKENIZE_ERROR",
+          message: response.response_message || "Failed to tokenize card",
+          rawResponse: response
+        });
+      }
+      return {
+        token: response.card_token,
+        last4: options.cardNumber.slice(-4),
+        brand: this.detectCardBrand(options.cardNumber),
+        expiryMonth: options.expiryMonth,
+        expiryYear: options.expiryYear
+      };
+    } catch (error) {
+      if (error instanceof APSException) {
+        throw error;
+      }
+      const apsError = {
+        code: "TOKENIZE_ERROR",
+        message: error instanceof Error ? error.message : "Failed to tokenize card",
+        rawResponse: error
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * Verify a token (check if it's still valid)
+   */
+  async verify(token) {
+    try {
+      const params = {
+        command: "verify_token",
+        access_code: this.config.accessCode,
+        merchant_id: this.config.merchantId,
+        card_token: token,
+        response_format: "json"
+      };
+      const signatureString = buildQueryString(params);
+      params.signature = generateHMAC(signatureString, this.config.requestSecret);
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeTokenizeRequest(`${apiUrl}/verify_token`, params);
+      return response.response_code?.toString() === "00";
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Delete/Invalidate a token
+   */
+  async delete(token) {
+    try {
+      const params = {
+        command: "delete_token",
+        access_code: this.config.accessCode,
+        merchant_id: this.config.merchantId,
+        card_token: token,
+        response_format: "json"
+      };
+      const signatureString = buildQueryString(params);
+      params.signature = generateHMAC(signatureString, this.config.requestSecret);
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeTokenizeRequest(`${apiUrl}/delete_token`, params);
+      return response.response_code?.toString() === "00";
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * List saved cards for a customer
+   * @param customerId - Customer identifier (email or user ID)
+   */
+  async list(customerId) {
+    try {
+      const params = {
+        command: "get_cards",
+        access_code: this.config.accessCode,
+        merchant_id: this.config.merchantId,
+        customer_email: customerId,
+        response_format: "json"
+      };
+      const signatureString = buildQueryString(params);
+      params.signature = generateHMAC(signatureString, this.config.requestSecret);
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeTokenizeRequest(`${apiUrl}/get_cards`, params);
+      const cards = [];
+      if (response.cards && Array.isArray(response.cards)) {
+        for (const card of response.cards) {
+          cards.push({
+            token: card.card_token,
+            last4: card.last4_digits || "****",
+            brand: card.card_brand || this.detectCardBrand(card.card_number || ""),
+            expiryMonth: card.expiry_month,
+            expiryYear: card.expiry_year,
+            cardholderName: card.card_holder_name,
+            isDefault: card.is_default === "true" || card.is_default === true
+          });
+        }
+      }
+      return {
+        customerId,
+        cards,
+        total: cards.length
+      };
+    } catch (error) {
+      if (error instanceof APSException) {
+        throw error;
+      }
+      const apsError = {
+        code: "LIST_CARDS_ERROR",
+        message: error instanceof Error ? error.message : "Failed to list saved cards",
+        rawResponse: error
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * Detect card brand from card number
+   */
+  detectCardBrand(cardNumber) {
+    const number = cardNumber.replace(/\D/g, "");
+    if (/^4/.test(number)) return "visa";
+    if (/^5[1-5]/.test(number)) return "mastercard";
+    if (/^3[47]/.test(number)) return "amex";
+    if (/^6(?:011|5)/.test(number)) return "discover";
+    if (/^(?:2131|1800|35)/.test(number)) return "jcb";
+    if (/^9792/.test(number)) return "troy";
+    return "unknown";
+  }
+  /**
+   * Make tokenization API request with timeout and retry support
+   */
+  async makeTokenizeRequest(url, params) {
+    const data = await makeRequest(url, params, {
+      timeout: this.options.timeout,
+      maxRetries: this.options.maxRetries,
+      logger: this.options.logger
+    });
+    if (data.response_code?.toString() !== "00" && data.response_code?.toString() !== "0") {
+      throw new APSException({
+        code: data.response_code?.toString() || "TOKENIZE_ERROR",
+        message: data.response_message || "Tokenization request failed",
+        rawResponse: data
+      });
+    }
+    return data;
+  }
+};
+
+// src/modules/payments.ts
+var PaymentsModule = class {
+  constructor(config, options) {
+    this.config = config;
+    this.options = options;
+  }
+  /**
+   * Capture an authorized payment
+   */
+  async capture(options) {
+    try {
+      validateRequiredFields(options, ["transactionId"]);
+      const params = {
+        command: "capture",
+        access_code: this.config.accessCode,
+        merchant_id: this.config.merchantId,
+        transaction_id: options.transactionId,
+        response_format: "json"
+      };
+      if (options.amount) {
+        params.amount = options.amount.toString();
+      }
+      const signatureString = buildQueryString(params);
+      params.signature = generateHMAC(signatureString, this.config.requestSecret);
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeApiRequest(`${apiUrl}/capture`, params);
+      const status = this.mapResponseStatus(response);
+      return {
+        captureId: response.transaction_id || options.transactionId,
+        transactionId: options.transactionId,
+        amount: options.amount || parseInt(response.amount) || 0,
+        status,
+        message: response.response_message,
+        rawResponse: response
+      };
+    } catch (error) {
+      const apsError = {
+        code: "CAPTURE_ERROR",
+        message: error instanceof Error ? error.message : "Failed to capture payment",
+        rawResponse: error
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * Refund a payment (full or partial)
+   */
+  async refund(options) {
+    try {
+      validateRequiredFields(options, ["transactionId"]);
+      const params = {
+        command: "refund",
+        access_code: this.config.accessCode,
+        merchant_id: this.config.merchantId,
+        transaction_id: options.transactionId,
+        response_format: "json"
+      };
+      if (options.amount) {
+        params.amount = options.amount.toString();
+      }
+      if (options.reason) {
+        params.refund_reason = options.reason;
+      }
+      const signatureString = buildQueryString(params);
+      params.signature = generateHMAC(signatureString, this.config.requestSecret);
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeApiRequest(`${apiUrl}/refund`, params);
+      const status = this.mapResponseStatus(response);
+      return {
+        refundId: response.transaction_id || `refund_${Date.now()}`,
+        transactionId: options.transactionId,
+        amount: options.amount || parseInt(response.amount) || 0,
+        status,
+        message: response.response_message,
+        rawResponse: response
+      };
+    } catch (error) {
+      const apsError = {
+        code: "REFUND_ERROR",
+        message: error instanceof Error ? error.message : "Failed to process refund",
+        rawResponse: error
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * Void an authorized transaction
+   */
+  async void(options) {
+    try {
+      validateRequiredFields(options, ["transactionId"]);
+      const params = {
+        command: "void",
+        access_code: this.config.accessCode,
+        merchant_id: this.config.merchantId,
+        transaction_id: options.transactionId,
+        response_format: "json"
+      };
+      if (options.reason) {
+        params.void_reason = options.reason;
+      }
+      const signatureString = buildQueryString(params);
+      params.signature = generateHMAC(signatureString, this.config.requestSecret);
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeApiRequest(`${apiUrl}/void`, params);
+      const status = this.mapResponseStatus(response);
+      return {
+        voidId: response.transaction_id || `void_${Date.now()}`,
+        transactionId: options.transactionId,
+        status,
+        message: response.response_message,
+        rawResponse: response
+      };
+    } catch (error) {
+      const apsError = {
+        code: "VOID_ERROR",
+        message: error instanceof Error ? error.message : "Failed to void transaction",
+        rawResponse: error
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * Query transaction status
+   */
+  async query(options) {
+    try {
+      if (!options.transactionId && !options.orderId) {
+        throw new Error("Either transactionId or orderId is required");
+      }
+      const params = {
+        command: "query_transaction",
+        access_code: this.config.accessCode,
+        merchant_id: this.config.merchantId,
+        response_format: "json"
+      };
+      if (options.transactionId) {
+        params.transaction_id = options.transactionId;
+      }
+      if (options.orderId) {
+        params.merchant_order_id = options.orderId;
+      }
+      const signatureString = buildQueryString(params);
+      params.signature = generateHMAC(signatureString, this.config.requestSecret);
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeApiRequest(`${apiUrl}/query_transaction`, params);
+      return {
+        transactionId: response.transaction_id,
+        orderId: response.merchant_order_id,
+        amount: parseInt(response.amount) || 0,
+        currency: response.currency,
+        status: this.mapResponseStatus(response),
+        paymentMethod: response.payment_option,
+        createdAt: response.transaction_date,
+        rawResponse: response
+      };
+    } catch (error) {
+      const apsError = {
+        code: "QUERY_ERROR",
+        message: error instanceof Error ? error.message : "Failed to query transaction",
+        rawResponse: error
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * Map APS response code to transaction status
+   */
+  mapResponseStatus(response) {
+    const code = response.response_code?.toString() || "";
+    const status = response.status?.toUpperCase();
+    if (code === "00" || code === "0") {
+      if (status === "CAPTURED") return "captured";
+      if (status === "AUTHORIZED") return "authorized";
+      return "captured";
+    }
+    if (code === "03" || status === "AUTHORIZED") {
+      return "authorized";
+    }
+    if (status === "PENDING" || status === "3DS") {
+      return "pending";
+    }
+    if (status === "VOIDED" || response.void_status === "true") {
+      return "voided";
+    }
+    if (status === "REFUNDED" || response.refund_status === "true") {
+      return "refunded";
+    }
+    if (status === "CANCELLED" || status === "CANCELED") {
+      return "cancelled";
+    }
+    if (status === "FAILED" || code !== "00") {
+      return "failed";
+    }
+    return "pending";
+  }
+  /**
+   * Make API request to APS with timeout and retry support
+   */
+  async makeApiRequest(url, params, idempotencyKey) {
+    const data = await makeRequest(url, params, {
+      timeout: this.options.timeout,
+      maxRetries: this.options.maxRetries,
+      logger: this.options.logger,
+      idempotencyKey
+    });
+    if (data.response_code?.toString() !== "00" && data.response_code?.toString() !== "0") {
+      throw new APSException({
+        code: data.response_code?.toString() || "API_ERROR",
+        message: data.response_message || "API request failed",
+        rawResponse: data
+      });
+    }
+    return data;
+  }
+};
+
+// src/modules/webhooks.ts
+var WebhooksModule = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Verify webhook signature
+   */
+  verifySignature(payload, signature) {
+    return verifyHMAC(payload, signature, this.config.responseSecret);
+  }
+  /**
+   * Construct a webhook event from raw payload
+   */
+  constructEvent(payload) {
+    try {
+      const eventType = this.mapEventType(payload);
+      const status = this.mapStatus(payload.status);
+      return {
+        id: payload.transaction_id || `evt_${Date.now()}`,
+        type: eventType,
+        timestamp: payload.transaction_date ? new Date(payload.transaction_date) : /* @__PURE__ */ new Date(),
+        data: {
+          transactionId: payload.transaction_id,
+          orderId: payload.merchant_order_id,
+          amount: parseInt(payload.amount) || 0,
+          currency: payload.currency,
+          status,
+          paymentMethod: payload.payment_option,
+          metadata: payload.metadata
+        },
+        rawPayload: payload
+      };
+    } catch (error) {
+      const apsError = {
+        code: "WEBHOOK_PARSE_ERROR",
+        message: error instanceof Error ? error.message : "Failed to parse webhook event",
+        rawResponse: payload
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * Map APS event to webhook event type
+   */
+  mapEventType(payload) {
+    const status = payload.status?.toUpperCase();
+    const command = payload.command;
+    if (command === "refund") {
+      if (status === "SUCCESS" || payload.response_code === "00") {
+        return "refund.success";
+      }
+      return "refund.failed";
+    }
+    switch (status) {
+      case "SUCCESS":
+      case "CAPTURED":
+      case "COMPLETED":
+        return "payment.success";
+      case "FAILED":
+      case "DECLINED":
+        return "payment.failed";
+      case "PENDING":
+      case "3DS":
+        return "payment.pending";
+      default:
+        return "payment.pending";
+    }
+  }
+  /**
+   * Map APS status to transaction status
+   */
+  mapStatus(status) {
+    if (!status) return "pending";
+    const upperStatus = status.toUpperCase();
+    switch (upperStatus) {
+      case "SUCCESS":
+      case "CAPTURED":
+      case "COMPLETED":
+        return "captured";
+      case "AUTHORIZED":
+        return "authorized";
+      case "PENDING":
+      case "3DS":
+        return "pending";
+      case "FAILED":
+      case "DECLINED":
+        return "failed";
+      case "VOIDED":
+        return "voided";
+      case "REFUNDED":
+        return "refunded";
+      case "CANCELLED":
+      case "CANCELED":
+        return "cancelled";
+      default:
+        return "pending";
+    }
+  }
+  /**
+   * Verify and construct event in one step
+   */
+  safeConstructEvent(payload, signature) {
+    if (!this.verifySignature(payload, signature)) {
+      throw new APSException({
+        code: "INVALID_SIGNATURE",
+        message: "Webhook signature verification failed",
+        statusCode: 401
+      });
+    }
+    const parsedPayload = typeof payload === "string" ? JSON.parse(payload) : payload;
+    return this.constructEvent(parsedPayload);
+  }
+};
+
+// src/modules/recurring.ts
+var RecurringModule = class {
+  constructor(config, options) {
+    this.config = config;
+    this.options = options;
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async process(options) {
+    try {
+      validateRequiredFields(options, ["tokenName", "agreementId", "customerEmail"]);
+      validateRequiredFields(options.order, ["id", "amount", "currency"]);
+      const params = {
+        command: "PURCHASE",
+        access_code: this.config.accessCode,
+        merchant_identifier: this.config.merchantId,
+        merchant_reference: options.order.id,
+        amount: Math.round(options.order.amount).toString(),
+        currency: options.order.currency,
+        eci: "RECURRING",
+        language: this.config.language,
+        customer_email: options.customerEmail,
+        token_name: options.tokenName,
+        agreement_id: options.agreementId,
+        response_format: "json"
+      };
+      if (options.order.description) {
+        params.order_description = options.order.description;
+      }
+      if (options.customerName) {
+        params.customer_name = options.customerName;
+      }
+      if (options.customerPhone) {
+        params.phone_number = options.customerPhone;
+      }
+      if (options.statementDescriptor) {
+        params.statement_descriptor = options.statementDescriptor;
+      }
+      if (options.paymentOption) {
+        params.payment_option = options.paymentOption;
+      }
+      if (options.settlementReference) {
+        params.settlement_reference = options.settlementReference;
+      }
+      const signatureString = buildQueryString(params);
+      params.signature = generateHMAC(signatureString, this.config.requestSecret);
+      this.options.logger?.info?.("Processing recurring payment", {
+        orderId: options.order.id,
+        amount: options.order.amount,
+        currency: options.order.currency,
+        agreementId: options.agreementId
+      });
+      const apiUrl = getApiUrl(this.config.environment);
+      const response = await this.makeApiRequest(`${apiUrl}/paymentApi`, params);
+      const status = this.mapResponseStatus(response);
+      return {
+        transactionId: response.fort_id || response.transaction_id,
+        orderId: options.order.id,
+        agreementId: options.agreementId,
+        amount: options.order.amount,
+        currency: options.order.currency,
+        status,
+        paymentMethod: response.payment_option,
+        authorizationCode: response.authorization_code,
+        message: response.response_message,
+        rawResponse: response
+      };
+    } catch (error) {
+      this.options.logger?.error?.("Recurring payment failed", { error });
+      const apsError = {
+        code: "RECURRING_ERROR",
+        message: error instanceof Error ? error.message : "Failed to process recurring payment",
+        rawResponse: error
+      };
+      throw new APSException(apsError);
+    }
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async processBatch(payments) {
+    const results = [];
+    for (const payment of payments) {
+      try {
+        const result = await this.process(payment);
+        results.push({
+          success: true,
+          data: result,
+          orderId: payment.order.id
+        });
+      } catch (error) {
+        results.push({
+          success: false,
+          error: error instanceof Error ? error.message : "Unknown error",
+          orderId: payment.order.id
+        });
+      }
+    }
+    return results;
+  }
+  /**
+   * Map APS response code to transaction status
+   */
+  mapResponseStatus(response) {
+    const code = response.response_code?.toString() || "";
+    const status = response.status?.toString();
+    if (code === "14000" || code === "00000" || status === "20") {
+      return "captured";
+    }
+    if (status === "3" || status === "PENDING") {
+      return "pending";
+    }
+    return "failed";
+  }
+  /**
+   * Make API request to APS
+   */
+  async makeApiRequest(url, params) {
+    const data = await makeRequest(url, params, {
+      timeout: this.options.timeout,
+      maxRetries: this.options.maxRetries,
+      logger: this.options.logger
+    });
+    if (data.response_code?.toString() !== "14000" && data.response_code?.toString() !== "00000" && data.status?.toString() !== "20") {
+      throw new APSException({
+        code: data.response_code?.toString() || "API_ERROR",
+        message: data.response_message || "Recurring payment failed",
+        rawResponse: data
+      });
+    }
+    return data;
+  }
+};
+
+// src/client.ts
+var APSClient = class {
+  /**
+   * Create a new APS client instance
+   */
+  constructor(config, options = {}) {
+    if (!config.merchantId) {
+      throw new APSException({
+        code: "MISSING_MERCHANT_ID",
+        message: "Merchant ID is required"
+      });
+    }
+    if (!config.accessCode) {
+      throw new APSException({
+        code: "MISSING_ACCESS_CODE",
+        message: "Access code is required"
+      });
+    }
+    if (!config.requestSecret) {
+      throw new APSException({
+        code: "MISSING_REQUEST_SECRET",
+        message: "Request secret is required"
+      });
+    }
+    if (!config.responseSecret) {
+      throw new APSException({
+        code: "MISSING_RESPONSE_SECRET",
+        message: "Response secret is required"
+      });
+    }
+    this.config = {
+      ...config,
+      environment: config.environment ?? "sandbox",
+      currency: config.currency ?? "USD",
+      language: config.language ?? "en"
+    };
+    this.options = {
+      logger: options.logger ?? (this.config.environment === "sandbox" ? noopLogger : noopLogger),
+      timeout: options.timeout ?? 3e4,
+      maxRetries: options.maxRetries ?? 3,
+      enableLogging: options.enableLogging ?? this.config.environment === "sandbox"
+    };
+    this.paymentLinks = new PaymentLinksModule(this.config, this.options);
+    this.hostedCheckout = new HostedCheckoutModule(this.config, this.options);
+    this.customPaymentPage = new CustomPaymentPageModule(this.config, this.options);
+    this.tokens = new TokenizationModule(this.config, this.options);
+    this.payments = new PaymentsModule(this.config, this.options);
+    this.webhooks = new WebhooksModule(this.config);
+    this.recurring = new RecurringModule(this.config, this.options);
+  }
+  /**
+   * Get the base URL for redirects
+   */
+  getBaseUrl() {
+    return getBaseUrl(this.config.environment);
+  }
+  /**
+   * Get the API URL for server-to-server calls
+   */
+  getApiUrl() {
+    return getApiUrl(this.config.environment);
+  }
+  /**
+   * Verify a webhook signature
+   */
+  verifyWebhookSignature(payload, signature) {
+    return this.webhooks.verifySignature(payload, signature);
+  }
+  /**
+   * Construct a webhook event from raw payload
+   */
+  constructWebhookEvent(payload) {
+    return this.webhooks.constructEvent(payload);
+  }
+  /**
+   * Get the logger instance
+   */
+  getLogger() {
+    return this.options.logger;
+  }
+  /**
+   * Set a custom logger
+   */
+  setLogger(logger) {
+    this.options.logger = logger;
+  }
+};
+
+// src/constants.ts
+var TestCards = {
+  /**
+   * Visa test cards
+   */
+  VISA: {
+    /** Successful payment */
+    SUCCESS: "4111111111111111",
+    /** Declined payment */
+    DECLINED: "4000000000000002",
+    /** Insufficient funds */
+    INSUFFICIENT_FUNDS: "4000000000009995",
+    /** Lost card */
+    LOST_CARD: "4000000000009987",
+    /** Stolen card */
+    STOLEN_CARD: "4000000000009979",
+    /** Expired card */
+    EXPIRED_CARD: "4000000000009961",
+    /** Invalid CVV */
+    INVALID_CVV: "4000000000000127",
+    /** 3D Secure required */
+    REQUIRES_3DS: "4000000000003220"
+  },
+  /**
+   * Mastercard test cards
+   */
+  MASTERCARD: {
+    /** Successful payment */
+    SUCCESS: "5100000000000008",
+    /** Declined payment */
+    DECLINED: "5400000000000003",
+    /** Insufficient funds */
+    INSUFFICIENT_FUNDS: "5400000000000094",
+    /** 3D Secure required */
+    REQUIRES_3DS: "5400000000000094"
+  },
+  /**
+   * MADA (Saudi Arabia) test cards
+   */
+  MADA: {
+    /** Successful payment */
+    SUCCESS: "5297410000000002",
+    /** Declined payment */
+    DECLINED: "5297410000000010",
+    /** 3D Secure required */
+    REQUIRES_3DS: "5297410000000028"
+  },
+  /**
+   * American Express test cards
+   */
+  AMEX: {
+    /** Successful payment */
+    SUCCESS: "371449635398431",
+    /** Declined payment */
+    DECLINED: "378282246310005"
+  },
+  /**
+   * Test card defaults
+   */
+  DEFAULTS: {
+    /** Default expiry month (MM) */
+    EXPIRY_MONTH: "12",
+    /** Default expiry year (YY) */
+    EXPIRY_YEAR: "25",
+    /** Default CVV */
+    CVV: "123",
+    /** Default cardholder name */
+    CARDHOLDER_NAME: "Test User"
+  }
+};
+var ResponseCodes = {
+  // Success Codes
+  /** Transaction successful */
+  SUCCESS: "00000",
+  /** Payment link created successfully */
+  PAYMENT_LINK_SUCCESS: "48000",
+  /** Recurring payment successful */
+  RECURRING_SUCCESS: "14000",
+  // Authentication & Security
+  /** 3D Secure authentication failed */
+  AUTHENTICATION_FAILED: "10030",
+  /** 3D Secure not enrolled */
+  NOT_ENROLLED_3DS: "10031",
+  /** Signature mismatch */
+  SIGNATURE_MISMATCH: "00008",
+  /** Invalid access code */
+  INVALID_ACCESS_CODE: "00009",
+  /** Invalid merchant identifier */
+  INVALID_MERCHANT_ID: "00010",
+  // Card Errors
+  /** Card expired */
+  CARD_EXPIRED: "10035",
+  /** Invalid card number */
+  INVALID_CARD_NUMBER: "10036",
+  /** Invalid CVV */
+  INVALID_CVV: "10037",
+  /** Card not supported */
+  CARD_NOT_SUPPORTED: "10038",
+  /** Lost card */
+  LOST_CARD: "10039",
+  /** Stolen card */
+  STOLEN_CARD: "10040",
+  /** Restricted card */
+  RESTRICTED_CARD: "10041",
+  /** Card blocked */
+  CARD_BLOCKED: "10042",
+  /** Invalid expiry date */
+  INVALID_EXPIRY: "10043",
+  // Transaction Errors
+  /** Transaction declined */
+  DECLINED: "14001",
+  /** Insufficient funds */
+  INSUFFICIENT_FUNDS: "14002",
+  /** Transaction limit exceeded */
+  LIMIT_EXCEEDED: "14003",
+  /** Invalid transaction */
+  INVALID_TRANSACTION: "14004",
+  /** Duplicate transaction */
+  DUPLICATE_TRANSACTION: "14005",
+  /** Transaction not allowed */
+  TRANSACTION_NOT_ALLOWED: "14006",
+  /** Transaction expired */
+  TRANSACTION_EXPIRED: "14007",
+  /** Transaction already captured */
+  ALREADY_CAPTURED: "14008",
+  /** Transaction already voided */
+  ALREADY_VOIDED: "14009",
+  /** Transaction already refunded */
+  ALREADY_REFUNDED: "14010",
+  // Amount Errors
+  /** Invalid amount */
+  INVALID_AMOUNT: "15001",
+  /** Amount too small */
+  AMOUNT_TOO_SMALL: "15002",
+  /** Amount too large */
+  AMOUNT_TOO_LARGE: "15003",
+  /** Currency not supported */
+  CURRENCY_NOT_SUPPORTED: "15004",
+  // Parameter Errors
+  /** Missing parameter */
+  MISSING_PARAMETER: "00001",
+  /** Invalid parameter format */
+  INVALID_PARAMETER: "00002",
+  /** Invalid command */
+  INVALID_COMMAND: "00003",
+  /** Invalid language */
+  INVALID_LANGUAGE: "00004",
+  /** Invalid currency */
+  INVALID_CURRENCY: "00005",
+  /** Invalid return URL */
+  INVALID_RETURN_URL: "00006",
+  /** Invalid customer email */
+  INVALID_EMAIL: "00007",
+  /** Parameter value not allowed */
+  PARAMETER_VALUE_NOT_ALLOWED: "00033",
+  // Tokenization Errors
+  /** Token not found */
+  TOKEN_NOT_FOUND: "16001",
+  /** Token expired */
+  TOKEN_EXPIRED: "16002",
+  /** Token already used */
+  TOKEN_ALREADY_USED: "16003",
+  /** Invalid token */
+  INVALID_TOKEN: "16004",
+  // System Errors
+  /** System error */
+  SYSTEM_ERROR: "90001",
+  /** Service unavailable */
+  SERVICE_UNAVAILABLE: "90002",
+  /** Timeout */
+  TIMEOUT: "90003",
+  /** Database error */
+  DATABASE_ERROR: "90004",
+  /** Internal error */
+  INTERNAL_ERROR: "90005"
+};
+var ErrorCategories = {
+  /** Success - no error */
+  SUCCESS: "success",
+  /** Card-related errors (expired, invalid, blocked) */
+  CARD_ERROR: "card_error",
+  /** Authentication errors (3DS, signature) */
+  AUTHENTICATION_ERROR: "authentication_error",
+  /** Transaction errors (declined, insufficient funds) */
+  TRANSACTION_ERROR: "transaction_error",
+  /** Amount/currency errors */
+  AMOUNT_ERROR: "amount_error",
+  /** Parameter validation errors */
+  VALIDATION_ERROR: "validation_error",
+  /** Tokenization errors */
+  TOKEN_ERROR: "token_error",
+  /** System/technical errors */
+  SYSTEM_ERROR: "system_error",
+  /** Errors that can be retried */
+  RETRYABLE: "retryable",
+  /** Errors that should not be retried */
+  NON_RETRYABLE: "non_retryable"
+};
+var ERROR_CODE_TO_CATEGORY = {
+  [ResponseCodes.SUCCESS]: ErrorCategories.SUCCESS,
+  [ResponseCodes.PAYMENT_LINK_SUCCESS]: ErrorCategories.SUCCESS,
+  [ResponseCodes.RECURRING_SUCCESS]: ErrorCategories.SUCCESS,
+  // Card errors
+  [ResponseCodes.CARD_EXPIRED]: ErrorCategories.CARD_ERROR,
+  [ResponseCodes.INVALID_CARD_NUMBER]: ErrorCategories.CARD_ERROR,
+  [ResponseCodes.INVALID_CVV]: ErrorCategories.CARD_ERROR,
+  [ResponseCodes.CARD_NOT_SUPPORTED]: ErrorCategories.CARD_ERROR,
+  [ResponseCodes.LOST_CARD]: ErrorCategories.CARD_ERROR,
+  [ResponseCodes.STOLEN_CARD]: ErrorCategories.CARD_ERROR,
+  [ResponseCodes.RESTRICTED_CARD]: ErrorCategories.CARD_ERROR,
+  [ResponseCodes.CARD_BLOCKED]: ErrorCategories.CARD_ERROR,
+  [ResponseCodes.INVALID_EXPIRY]: ErrorCategories.CARD_ERROR,
+  // Authentication errors
+  [ResponseCodes.AUTHENTICATION_FAILED]: ErrorCategories.AUTHENTICATION_ERROR,
+  [ResponseCodes.NOT_ENROLLED_3DS]: ErrorCategories.AUTHENTICATION_ERROR,
+  [ResponseCodes.SIGNATURE_MISMATCH]: ErrorCategories.AUTHENTICATION_ERROR,
+  [ResponseCodes.INVALID_ACCESS_CODE]: ErrorCategories.AUTHENTICATION_ERROR,
+  [ResponseCodes.INVALID_MERCHANT_ID]: ErrorCategories.AUTHENTICATION_ERROR,
+  // Transaction errors
+  [ResponseCodes.DECLINED]: ErrorCategories.TRANSACTION_ERROR,
+  [ResponseCodes.INSUFFICIENT_FUNDS]: ErrorCategories.TRANSACTION_ERROR,
+  [ResponseCodes.LIMIT_EXCEEDED]: ErrorCategories.TRANSACTION_ERROR,
+  [ResponseCodes.INVALID_TRANSACTION]: ErrorCategories.TRANSACTION_ERROR,
+  [ResponseCodes.DUPLICATE_TRANSACTION]: ErrorCategories.TRANSACTION_ERROR,
+  [ResponseCodes.TRANSACTION_NOT_ALLOWED]: ErrorCategories.TRANSACTION_ERROR,
+  [ResponseCodes.TRANSACTION_EXPIRED]: ErrorCategories.TRANSACTION_ERROR,
+  [ResponseCodes.ALREADY_CAPTURED]: ErrorCategories.TRANSACTION_ERROR,
+  [ResponseCodes.ALREADY_VOIDED]: ErrorCategories.TRANSACTION_ERROR,
+  [ResponseCodes.ALREADY_REFUNDED]: ErrorCategories.TRANSACTION_ERROR,
+  // Amount errors
+  [ResponseCodes.INVALID_AMOUNT]: ErrorCategories.AMOUNT_ERROR,
+  [ResponseCodes.AMOUNT_TOO_SMALL]: ErrorCategories.AMOUNT_ERROR,
+  [ResponseCodes.AMOUNT_TOO_LARGE]: ErrorCategories.AMOUNT_ERROR,
+  [ResponseCodes.CURRENCY_NOT_SUPPORTED]: ErrorCategories.AMOUNT_ERROR,
+  // Validation errors
+  [ResponseCodes.MISSING_PARAMETER]: ErrorCategories.VALIDATION_ERROR,
+  [ResponseCodes.INVALID_PARAMETER]: ErrorCategories.VALIDATION_ERROR,
+  [ResponseCodes.INVALID_COMMAND]: ErrorCategories.VALIDATION_ERROR,
+  [ResponseCodes.INVALID_LANGUAGE]: ErrorCategories.VALIDATION_ERROR,
+  [ResponseCodes.INVALID_CURRENCY]: ErrorCategories.VALIDATION_ERROR,
+  [ResponseCodes.INVALID_RETURN_URL]: ErrorCategories.VALIDATION_ERROR,
+  [ResponseCodes.INVALID_EMAIL]: ErrorCategories.VALIDATION_ERROR,
+  [ResponseCodes.PARAMETER_VALUE_NOT_ALLOWED]: ErrorCategories.VALIDATION_ERROR,
+  // Token errors
+  [ResponseCodes.TOKEN_NOT_FOUND]: ErrorCategories.TOKEN_ERROR,
+  [ResponseCodes.TOKEN_EXPIRED]: ErrorCategories.TOKEN_ERROR,
+  [ResponseCodes.TOKEN_ALREADY_USED]: ErrorCategories.TOKEN_ERROR,
+  [ResponseCodes.INVALID_TOKEN]: ErrorCategories.TOKEN_ERROR,
+  // System errors
+  [ResponseCodes.SYSTEM_ERROR]: ErrorCategories.SYSTEM_ERROR,
+  [ResponseCodes.SERVICE_UNAVAILABLE]: ErrorCategories.SYSTEM_ERROR,
+  [ResponseCodes.TIMEOUT]: ErrorCategories.SYSTEM_ERROR,
+  [ResponseCodes.DATABASE_ERROR]: ErrorCategories.SYSTEM_ERROR,
+  [ResponseCodes.INTERNAL_ERROR]: ErrorCategories.SYSTEM_ERROR
+};
+var RETRYABLE_CODES = [
+  ResponseCodes.TIMEOUT,
+  ResponseCodes.SERVICE_UNAVAILABLE,
+  ResponseCodes.SYSTEM_ERROR,
+  ResponseCodes.INTERNAL_ERROR,
+  ResponseCodes.DATABASE_ERROR
+];
+function categorizeError(code) {
+  return ERROR_CODE_TO_CATEGORY[code] || ErrorCategories.SYSTEM_ERROR;
+}
+function isRetryableError(code) {
+  return RETRYABLE_CODES.includes(code);
+}
+var PaymentMethodCodes = {
+  /** Visa */
+  VISA: "VISA",
+  /** Mastercard */
+  MASTERCARD: "MASTERCARD",
+  /** American Express */
+  AMEX: "AMEX",
+  /** MADA (Saudi Arabia) */
+  MADA: "MADA",
+  /** Apple Pay */
+  APPLE_PAY: "APPLE_PAY",
+  /** STC Pay (Saudi Arabia) */
+  STC_PAY: "STC_PAY",
+  /** KNET (Kuwait) */
+  KNET: "KNET",
+  /** NAPS (Qatar) */
+  NAPS: "NAPS",
+  /** Fawry (Egypt) */
+  FAWRY: "FAWRY",
+  /** Meeza (Egypt) */
+  MEEZA: "MEEZA",
+  /** Sadad (Saudi Arabia) */
+  SADAD: "SADAD",
+  /** Aman (Egypt) */
+  AMAN: "AMAN",
+  /** Tabby (BNPL) */
+  TABBY: "TABBY",
+  /** Tamara (BNPL) */
+  TAMARA: "TAMARA",
+  /** valU (BNPL) */
+  VALU: "VALU"
+};
+var CurrencyCodes = {
+  /** Saudi Riyal */
+  SAR: "SAR",
+  /** UAE Dirham */
+  AED: "AED",
+  /** Kuwaiti Dinar */
+  KWD: "KWD",
+  /** Qatari Riyal */
+  QAR: "QAR",
+  /** Bahraini Dinar */
+  BHD: "BHD",
+  /** Omani Rial */
+  OMR: "OMR",
+  /** Jordanian Dinar */
+  JOD: "JOD",
+  /** Egyptian Pound */
+  EGP: "EGP",
+  /** US Dollar */
+  USD: "USD",
+  /** Euro */
+  EUR: "EUR",
+  /** British Pound */
+  GBP: "GBP"
+};
+var LanguageCodes = {
+  /** English */
+  EN: "en",
+  /** Arabic */
+  AR: "ar"
+};
+var Commands = {
+  /** Purchase (direct charge) */
+  PURCHASE: "PURCHASE",
+  /** Authorization (hold funds) */
+  AUTHORIZATION: "AUTHORIZATION",
+  /** Capture authorized funds */
+  CAPTURE: "CAPTURE",
+  /** Refund a transaction */
+  REFUND: "REFUND",
+  /** Void a transaction */
+  VOID: "VOID",
+  /** Query transaction status */
+  QUERY: "QUERY_TRANSACTION",
+  /** Tokenize a card */
+  TOKENIZATION: "TOKENIZATION",
+  /** Create token */
+  CREATE_TOKEN: "CREATE_TOKEN",
+  /** Verify token */
+  VERIFY_TOKEN: "VERIFY_TOKEN",
+  /** Delete token */
+  DELETE_TOKEN: "DELETE_TOKEN",
+  /** Get saved cards */
+  GET_CARDS: "GET_CARDS",
+  /** Payment link */
+  PAYMENT_LINK: "PAYMENT_LINK"
+};
+var ECIValues = {
+  /** Secure e-commerce with 3DS */
+  SECURE_3DS: "05",
+  /** Non-3DS e-commerce */
+  NON_3DS: "07",
+  /** Recurring payment */
+  RECURRING: "RECURRING",
+  /** Merchant-initiated */
+  MERCHANT_INITIATED: "07"
+};
+var StatusCodes = {
+  /** Success */
+  SUCCESS: "20",
+  /** Pending/3DS required */
+  PENDING: "3",
+  /** Authorized */
+  AUTHORIZED: "02",
+  /** Captured */
+  CAPTURED: "04"
+};
+
+// src/errors.ts
+var ERROR_DETAILS_MAP = {
+  // Success codes
+  [ResponseCodes.SUCCESS]: {
+    message: "Transaction completed successfully.",
+    action: "No action needed. Proceed with order fulfillment.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html"
+  },
+  [ResponseCodes.PAYMENT_LINK_SUCCESS]: {
+    message: "Payment link created successfully.",
+    action: "Share the payment link with your customer via email, SMS, or any channel.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html"
+  },
+  [ResponseCodes.RECURRING_SUCCESS]: {
+    message: "Recurring payment processed successfully.",
+    action: "Payment has been charged. Update subscription status in your system.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html"
+  },
+  // Authentication & Security
+  [ResponseCodes.AUTHENTICATION_FAILED]: {
+    message: "3D Secure authentication failed. The customer could not verify their identity.",
+    action: "Ask the customer to check their 3D Secure password or use a different card. Some banks require SMS verification - ensure customer has network coverage.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#_3d_secure",
+    httpStatus: 402
+  },
+  [ResponseCodes.NOT_ENROLLED_3DS]: {
+    message: "Card is not enrolled in 3D Secure.",
+    action: "The card does not support 3D Secure. You can proceed without 3DS or ask customer to use a different card.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#_3d_secure"
+  },
+  [ResponseCodes.SIGNATURE_MISMATCH]: {
+    message: "Request signature is invalid.",
+    action: "Check that your request_secret is correct and that parameters are being signed in the correct order. Use the SDK's built-in signing methods.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#signature_calculation",
+    httpStatus: 401
+  },
+  [ResponseCodes.INVALID_ACCESS_CODE]: {
+    message: "Invalid access code.",
+    action: "Verify your APS_ACCESS_CODE environment variable matches the value in your APS dashboard under Integration Settings.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#credentials",
+    httpStatus: 401
+  },
+  [ResponseCodes.INVALID_MERCHANT_ID]: {
+    message: "Invalid merchant identifier.",
+    action: "Verify your APS_MERCHANT_ID environment variable matches your APS dashboard. Ensure you're using the correct environment (sandbox vs production).",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#credentials",
+    httpStatus: 401
+  },
+  // Card Errors
+  [ResponseCodes.CARD_EXPIRED]: {
+    message: "The card has expired.",
+    action: "Ask the customer to check the expiry date on their card and enter it correctly, or use a different card.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#card_errors",
+    httpStatus: 402
+  },
+  [ResponseCodes.INVALID_CARD_NUMBER]: {
+    message: "The card number is invalid.",
+    action: "Ask the customer to check their card number and try again. Ensure no spaces or dashes are included.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#card_errors",
+    httpStatus: 402
+  },
+  [ResponseCodes.INVALID_CVV]: {
+    message: "The CVV code is invalid.",
+    action: "Ask the customer to check the CVV on the back of their card (3 digits for Visa/MC, 4 for Amex) and enter it correctly.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#card_errors",
+    httpStatus: 402
+  },
+  [ResponseCodes.CARD_NOT_SUPPORTED]: {
+    message: "This card type is not supported.",
+    action: "The customer is using a card type not accepted by your merchant account. Ask them to use Visa, Mastercard, or MADA.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#payment_methods",
+    httpStatus: 402
+  },
+  [ResponseCodes.LOST_CARD]: {
+    message: "The card has been reported lost.",
+    action: "Do not retry. Ask the customer to use a different card and contact their bank.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#card_errors",
+    httpStatus: 402
+  },
+  [ResponseCodes.STOLEN_CARD]: {
+    message: "The card has been reported stolen.",
+    action: "Do not retry. Ask the customer to use a different card and contact their bank immediately.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#card_errors",
+    httpStatus: 402
+  },
+  [ResponseCodes.RESTRICTED_CARD]: {
+    message: "The card has restrictions that prevent this transaction.",
+    action: "The card may be restricted for online or international use. Ask the customer to contact their bank or use a different card.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#card_errors",
+    httpStatus: 402
+  },
+  [ResponseCodes.CARD_BLOCKED]: {
+    message: "The card has been blocked by the issuing bank.",
+    action: "Ask the customer to contact their bank to unblock the card or use a different card.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#card_errors",
+    httpStatus: 402
+  },
+  [ResponseCodes.INVALID_EXPIRY]: {
+    message: "The expiry date is invalid.",
+    action: "Ask the customer to check the expiry date format (MM/YY) and ensure the card has not expired.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#card_errors",
+    httpStatus: 402
+  },
+  // Transaction Errors
+  [ResponseCodes.DECLINED]: {
+    message: "The transaction was declined by the issuing bank.",
+    action: "Ask the customer to contact their bank or use a different card. The bank does not provide specific reasons for declines.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#declined_transactions",
+    httpStatus: 402
+  },
+  [ResponseCodes.INSUFFICIENT_FUNDS]: {
+    message: "The card has insufficient funds.",
+    action: "Ask the customer to use a different card or payment method, or reduce the transaction amount.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#transaction_errors",
+    httpStatus: 402
+  },
+  [ResponseCodes.LIMIT_EXCEEDED]: {
+    message: "The transaction amount exceeds the card limit.",
+    action: "The transaction may exceed the customer's daily limit or card limit. Ask them to contact their bank or use a different card.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#transaction_errors",
+    httpStatus: 402
+  },
+  [ResponseCodes.INVALID_TRANSACTION]: {
+    message: "The transaction is invalid.",
+    action: "Check that all required parameters are provided correctly. Ensure the amount is valid and currency is supported.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#transaction_errors",
+    httpStatus: 400
+  },
+  [ResponseCodes.DUPLICATE_TRANSACTION]: {
+    message: "A duplicate transaction was detected.",
+    action: "This transaction appears to be a duplicate. Use a unique merchant_reference for each transaction.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#idempotency",
+    httpStatus: 409
+  },
+  [ResponseCodes.TRANSACTION_NOT_ALLOWED]: {
+    message: "This transaction type is not allowed for this merchant.",
+    action: "Your merchant account may not be configured for this transaction type. Contact APS support to enable the required service.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#merchant_setup",
+    httpStatus: 403
+  },
+  [ResponseCodes.TRANSACTION_EXPIRED]: {
+    message: "The transaction has expired.",
+    action: "The authorization window has expired. Create a new transaction.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#transaction_lifecycle",
+    httpStatus: 410
+  },
+  [ResponseCodes.ALREADY_CAPTURED]: {
+    message: "The transaction has already been captured.",
+    action: "This transaction was already captured. Check your records or query the transaction status.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#capture",
+    httpStatus: 409
+  },
+  [ResponseCodes.ALREADY_VOIDED]: {
+    message: "The transaction has already been voided.",
+    action: "This transaction was already voided. No further action can be taken on it.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#void",
+    httpStatus: 409
+  },
+  [ResponseCodes.ALREADY_REFUNDED]: {
+    message: "The transaction has already been refunded.",
+    action: "This transaction was already refunded. Check the refund status for details.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#refund",
+    httpStatus: 409
+  },
+  // Amount Errors
+  [ResponseCodes.INVALID_AMOUNT]: {
+    message: "The transaction amount is invalid.",
+    action: "Ensure the amount is a positive number in the smallest currency unit (e.g., cents, fils). Amount should not contain decimals.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#amount_format",
+    httpStatus: 400
+  },
+  [ResponseCodes.AMOUNT_TOO_SMALL]: {
+    message: "The transaction amount is below the minimum allowed.",
+    action: "The amount is below the minimum transaction limit. Increase the amount or contact APS for limit adjustments.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#amount_limits",
+    httpStatus: 400
+  },
+  [ResponseCodes.AMOUNT_TOO_LARGE]: {
+    message: "The transaction amount exceeds the maximum allowed.",
+    action: "The amount exceeds your merchant transaction limit. Contact APS support to increase your limit.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#amount_limits",
+    httpStatus: 400
+  },
+  [ResponseCodes.CURRENCY_NOT_SUPPORTED]: {
+    message: "The currency is not supported.",
+    action: "Use a supported currency (SAR, AED, USD, EUR, etc.). Check APS documentation for the full list.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#currencies",
+    httpStatus: 400
+  },
+  // Parameter Errors
+  [ResponseCodes.MISSING_PARAMETER]: {
+    message: "A required parameter is missing.",
+    action: "Check that all required parameters are provided. Common missing fields: merchant_reference, amount, currency, customer_email.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#required_parameters",
+    httpStatus: 400
+  },
+  [ResponseCodes.INVALID_PARAMETER]: {
+    message: "A parameter has an invalid format or value.",
+    action: "Check parameter formats: emails must be valid, amounts must be numeric, dates must be in correct format.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#parameter_formats",
+    httpStatus: 400
+  },
+  [ResponseCodes.INVALID_COMMAND]: {
+    message: "The command is invalid or not recognized.",
+    action: "Use a valid command: PURCHASE, AUTHORIZATION, CAPTURE, REFUND, VOID, TOKENIZATION, etc.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#commands",
+    httpStatus: 400
+  },
+  [ResponseCodes.INVALID_LANGUAGE]: {
+    message: "The language code is invalid.",
+    action: 'Use "en" for English or "ar" for Arabic.',
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#language_codes",
+    httpStatus: 400
+  },
+  [ResponseCodes.INVALID_CURRENCY]: {
+    message: "The currency code is invalid.",
+    action: "Use a valid 3-letter ISO currency code (SAR, AED, USD, EUR, etc.).",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#currencies",
+    httpStatus: 400
+  },
+  [ResponseCodes.INVALID_RETURN_URL]: {
+    message: "The return URL is invalid.",
+    action: "Ensure the return_url is a valid HTTPS URL and properly URL-encoded if needed.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#return_url",
+    httpStatus: 400
+  },
+  [ResponseCodes.INVALID_EMAIL]: {
+    message: "The customer email is invalid.",
+    action: "Ensure the customer_email is a valid email format (e.g., customer@example.com).",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#customer_email",
+    httpStatus: 400
+  },
+  [ResponseCodes.PARAMETER_VALUE_NOT_ALLOWED]: {
+    message: "A parameter value is not allowed for your merchant account.",
+    action: "This error often occurs when trying to use tokenization (remember_me) but your merchant account does not have tokenization enabled. Contact APS support to enable tokenization, or set tokenize: false. Other causes: using a payment method not enabled for your account, or an invalid parameter value.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#merchant_setup",
+    httpStatus: 400
+  },
+  // Tokenization Errors
+  [ResponseCodes.TOKEN_NOT_FOUND]: {
+    message: "The card token was not found.",
+    action: "The token may have been deleted or never created. Ask the customer to re-enter their card details.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#tokenization",
+    httpStatus: 404
+  },
+  [ResponseCodes.TOKEN_EXPIRED]: {
+    message: "The card token has expired.",
+    action: "Tokens expire after a period of inactivity. Ask the customer to re-enter their card details.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#token_expiry",
+    httpStatus: 410
+  },
+  [ResponseCodes.TOKEN_ALREADY_USED]: {
+    message: "The token has already been used.",
+    action: "Each token can only be used once for security. Create a new token for this transaction.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#token_usage",
+    httpStatus: 409
+  },
+  [ResponseCodes.INVALID_TOKEN]: {
+    message: "The token is invalid.",
+    action: "Check that the token was properly generated and is being passed correctly.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#tokenization",
+    httpStatus: 400
+  },
+  // System Errors
+  [ResponseCodes.SYSTEM_ERROR]: {
+    message: "A system error occurred.",
+    action: "This is a temporary issue on APS side. Wait a moment and retry the transaction.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#system_errors",
+    httpStatus: 500
+  },
+  [ResponseCodes.SERVICE_UNAVAILABLE]: {
+    message: "The service is temporarily unavailable.",
+    action: "APS is experiencing high load or maintenance. Wait a moment and retry.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#system_errors",
+    httpStatus: 503
+  },
+  [ResponseCodes.TIMEOUT]: {
+    message: "The request timed out.",
+    action: "The request took too long to complete. Check your network connection and retry.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#timeouts",
+    httpStatus: 504
+  },
+  [ResponseCodes.DATABASE_ERROR]: {
+    message: "A database error occurred.",
+    action: "Temporary database issue. Wait a moment and retry the transaction.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#system_errors",
+    httpStatus: 500
+  },
+  [ResponseCodes.INTERNAL_ERROR]: {
+    message: "An internal error occurred.",
+    action: "Unexpected error on APS side. Contact APS support if this persists.",
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#support",
+    httpStatus: 500
+  }
+};
+function getErrorDetails(code) {
+  const details = ERROR_DETAILS_MAP[code];
+  const category = categorizeError(code);
+  const retryable = isRetryableError(code);
+  if (details) {
+    return {
+      code,
+      message: details.message,
+      action: details.action,
+      category,
+      retryable,
+      documentation: details.documentation,
+      httpStatus: details.httpStatus
+    };
+  }
+  return {
+    code,
+    message: `An unknown error occurred (code: ${code}).`,
+    action: "Contact APS support with this error code for assistance.",
+    category: ErrorCategories.SYSTEM_ERROR,
+    retryable: false,
+    documentation: "https://paymentservices.amazon.com/docs/EN/index.html#support",
+    httpStatus: 500
+  };
+}
+function isRetryableError2(code) {
+  return isRetryableError(code);
+}
+function getUserFriendlyMessage(code, includeAction = true) {
+  const details = getErrorDetails(code);
+  if (includeAction) {
+    return `${details.message} ${details.action}`;
+  }
+  return details.message;
+}
+function formatErrorForLogging(code, context) {
+  const details = getErrorDetails(code);
+  const contextStr = context ? ` (${Object.entries(context).map(([k, v]) => `${k}: ${v}`).join(", ")})` : "";
+  return `[APS Error ${code}] ${details.category.toUpperCase()}: ${details.message}${contextStr}`;
+}
+function isSuccessCode(code) {
+  return [
+    ResponseCodes.SUCCESS,
+    ResponseCodes.PAYMENT_LINK_SUCCESS,
+    ResponseCodes.RECURRING_SUCCESS
+  ].includes(code);
+}
+function getErrorCodesByCategory(category) {
+  return Object.entries(ERROR_DETAILS_MAP).filter(([code]) => categorizeError(code) === category).map(([code]) => code);
+}
+function suggestHttpStatus(code) {
+  const details = getErrorDetails(code);
+  return details.httpStatus || 400;
+}
+
+// src/validators.ts
+import crypto5 from "crypto";
+function isValidMerchantReference(reference) {
+  if (!reference || reference.length === 0) {
+    return {
+      valid: false,
+      error: "Merchant reference is required",
+      code: ResponseCodes.MISSING_PARAMETER
+    };
+  }
+  if (reference.length > 40) {
+    return {
+      valid: false,
+      error: "Merchant reference must be 40 characters or less",
+      code: ResponseCodes.INVALID_PARAMETER
+    };
+  }
+  if (!/^[a-zA-Z0-9_-]+$/.test(reference)) {
+    return {
+      valid: false,
+      error: "Merchant reference can only contain letters, numbers, underscores, and hyphens",
+      code: ResponseCodes.INVALID_PARAMETER
+    };
+  }
+  return { valid: true };
+}
+function isValidAmount(amount, _currency) {
+  if (amount === void 0 || amount === null) {
+    return {
+      valid: false,
+      error: "Amount is required",
+      code: ResponseCodes.MISSING_PARAMETER
+    };
+  }
+  if (typeof amount !== "number" || isNaN(amount)) {
+    return {
+      valid: false,
+      error: "Amount must be a valid number",
+      code: ResponseCodes.INVALID_AMOUNT
+    };
+  }
+  if (amount <= 0) {
+    return {
+      valid: false,
+      error: "Amount must be greater than zero",
+      code: ResponseCodes.AMOUNT_TOO_SMALL
+    };
+  }
+  if (!Number.isInteger(amount)) {
+    return {
+      valid: false,
+      error: "Amount must be a whole number (in smallest currency unit, e.g., cents)",
+      code: ResponseCodes.INVALID_AMOUNT
+    };
+  }
+  if (amount > 999999999999) {
+    return {
+      valid: false,
+      error: "Amount exceeds maximum allowed value",
+      code: ResponseCodes.AMOUNT_TOO_LARGE
+    };
+  }
+  return { valid: true };
+}
+function isValidCurrency(currency) {
+  if (!currency || currency.length === 0) {
+    return {
+      valid: false,
+      error: "Currency is required",
+      code: ResponseCodes.MISSING_PARAMETER
+    };
+  }
+  if (!/^[A-Z]{3}$/.test(currency)) {
+    return {
+      valid: false,
+      error: "Currency must be a valid 3-letter ISO code (e.g., SAR, AED, USD)",
+      code: ResponseCodes.INVALID_CURRENCY
+    };
+  }
+  const supportedCurrencies = [
+    "SAR",
+    "AED",
+    "KWD",
+    "QAR",
+    "BHD",
+    "OMR",
+    "JOD",
+    "EGP",
+    "USD",
+    "EUR",
+    "GBP",
+    "CAD",
+    "AUD",
+    "CHF",
+    "SEK",
+    "NOK",
+    "DKK",
+    "NZD",
+    "SGD",
+    "HKD",
+    "JPY",
+    "CNY",
+    "INR"
+  ];
+  if (!supportedCurrencies.includes(currency)) {
+    return {
+      valid: false,
+      error: `Currency ${currency} may not be supported by APS. Supported: ${supportedCurrencies.join(", ")}`,
+      code: ResponseCodes.CURRENCY_NOT_SUPPORTED
+    };
+  }
+  return { valid: true };
+}
+function isValidEmail(email) {
+  if (!email || email.length === 0) {
+    return {
+      valid: false,
+      error: "Email is required",
+      code: ResponseCodes.MISSING_PARAMETER
+    };
+  }
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(email)) {
+    return {
+      valid: false,
+      error: "Please enter a valid email address",
+      code: ResponseCodes.INVALID_EMAIL
+    };
+  }
+  if (email.length > 254) {
+    return {
+      valid: false,
+      error: "Email address is too long",
+      code: ResponseCodes.INVALID_EMAIL
+    };
+  }
+  return { valid: true };
+}
+function isValidCardNumber(cardNumber) {
+  if (!cardNumber || cardNumber.length === 0) {
+    return {
+      valid: false,
+      error: "Card number is required",
+      code: ResponseCodes.MISSING_PARAMETER
+    };
+  }
+  const cleaned = cardNumber.replace(/[\s-]/g, "");
+  if (!/^\d+$/.test(cleaned)) {
+    return {
+      valid: false,
+      error: "Card number can only contain digits",
+      code: ResponseCodes.INVALID_CARD_NUMBER
+    };
+  }
+  if (cleaned.length < 13 || cleaned.length > 19) {
+    return {
+      valid: false,
+      error: "Card number must be between 13 and 19 digits",
+      code: ResponseCodes.INVALID_CARD_NUMBER
+    };
+  }
+  let sum = 0;
+  let shouldDouble = false;
+  for (let i = cleaned.length - 1; i >= 0; i--) {
+    let digit = parseInt(cleaned.charAt(i), 10);
+    if (shouldDouble) {
+      digit *= 2;
+      if (digit > 9) {
+        digit -= 9;
+      }
+    }
+    sum += digit;
+    shouldDouble = !shouldDouble;
+  }
+  if (sum % 10 !== 0) {
+    return {
+      valid: false,
+      error: "Card number is invalid (failed Luhn check)",
+      code: ResponseCodes.INVALID_CARD_NUMBER
+    };
+  }
+  return { valid: true };
+}
+function isValidExpiryDate(month, year) {
+  if (!month || !year) {
+    return {
+      valid: false,
+      error: "Expiry month and year are required",
+      code: ResponseCodes.MISSING_PARAMETER
+    };
+  }
+  const expiryMonth = parseInt(month, 10);
+  let expiryYear = parseInt(year, 10);
+  if (year.length === 2) {
+    expiryYear = 2e3 + expiryYear;
+  }
+  if (isNaN(expiryMonth) || isNaN(expiryYear)) {
+    return {
+      valid: false,
+      error: "Expiry date must be numeric",
+      code: ResponseCodes.INVALID_EXPIRY
+    };
+  }
+  if (expiryMonth < 1 || expiryMonth > 12) {
+    return {
+      valid: false,
+      error: "Expiry month must be between 1 and 12",
+      code: ResponseCodes.INVALID_EXPIRY
+    };
+  }
+  const now = /* @__PURE__ */ new Date();
+  const currentYear = now.getFullYear();
+  const currentMonth = now.getMonth() + 1;
+  if (expiryYear < currentYear) {
+    return {
+      valid: false,
+      error: "Card has expired",
+      code: ResponseCodes.CARD_EXPIRED
+    };
+  }
+  if (expiryYear === currentYear && expiryMonth < currentMonth) {
+    return {
+      valid: false,
+      error: "Card has expired",
+      code: ResponseCodes.CARD_EXPIRED
+    };
+  }
+  if (expiryYear > currentYear + 20) {
+    return {
+      valid: false,
+      error: "Expiry date is too far in the future",
+      code: ResponseCodes.INVALID_EXPIRY
+    };
+  }
+  return { valid: true };
+}
+function isValidCVV(cvv, cardType) {
+  if (!cvv || cvv.length === 0) {
+    return {
+      valid: false,
+      error: "CVV is required",
+      code: ResponseCodes.MISSING_PARAMETER
+    };
+  }
+  if (!/^\d+$/.test(cvv)) {
+    return {
+      valid: false,
+      error: "CVV must contain only digits",
+      code: ResponseCodes.INVALID_CVV
+    };
+  }
+  const expectedLength = cardType?.toLowerCase() === "amex" ? 4 : 3;
+  if (cvv.length !== expectedLength) {
+    return {
+      valid: false,
+      error: `CVV must be ${expectedLength} digits${cardType?.toLowerCase() === "amex" ? " for American Express" : ""}`,
+      code: ResponseCodes.INVALID_CVV
+    };
+  }
+  return { valid: true };
+}
+function isValidReturnUrl(url) {
+  if (!url || url.length === 0) {
+    return {
+      valid: false,
+      error: "Return URL is required",
+      code: ResponseCodes.MISSING_PARAMETER
+    };
+  }
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+      return {
+        valid: false,
+        error: "Return URL must use HTTP or HTTPS protocol",
+        code: ResponseCodes.INVALID_RETURN_URL
+      };
+    }
+    if (url.length > 2048) {
+      return {
+        valid: false,
+        error: "Return URL is too long (max 2048 characters)",
+        code: ResponseCodes.INVALID_RETURN_URL
+      };
+    }
+    return { valid: true };
+  } catch {
+    return {
+      valid: false,
+      error: "Return URL must be a valid URL",
+      code: ResponseCodes.INVALID_RETURN_URL
+    };
+  }
+}
+function isValidSignature(params, signature, secret) {
+  if (!signature || !secret) {
+    return false;
+  }
+  try {
+    const sortedKeys = Object.keys(params).sort();
+    const concatenated = sortedKeys.filter((key) => key !== "signature").map((key) => `${key}=${params[key]}`).join("");
+    const signatureString = `${secret}${concatenated}${secret}`;
+    const expectedSignature = crypto5.createHash("sha256").update(signatureString).digest("hex").toUpperCase();
+    return signature.toUpperCase() === expectedSignature;
+  } catch {
+    return false;
+  }
+}
+function isValidWebhookPayload(payload, signature, secret) {
+  if (!signature) {
+    return {
+      valid: false,
+      error: "Missing signature header",
+      code: ResponseCodes.SIGNATURE_MISMATCH
+    };
+  }
+  if (!secret) {
+    return {
+      valid: false,
+      error: "Secret is required for validation",
+      code: ResponseCodes.SIGNATURE_MISMATCH
+    };
+  }
+  const payloadStr = typeof payload === "string" ? payload : JSON.stringify(payload);
+  const expectedSignature = crypto5.createHmac("sha256", secret).update(payloadStr).digest("base64");
+  if (signature !== expectedSignature) {
+    return {
+      valid: false,
+      error: "Invalid signature",
+      code: ResponseCodes.SIGNATURE_MISMATCH
+    };
+  }
+  return { valid: true };
+}
+function isValidLanguage(language) {
+  if (!language || language.length === 0) {
+    return {
+      valid: false,
+      error: "Language is required",
+      code: ResponseCodes.MISSING_PARAMETER
+    };
+  }
+  const supportedLanguages = ["en", "ar"];
+  if (!supportedLanguages.includes(language.toLowerCase())) {
+    return {
+      valid: false,
+      error: `Language must be one of: ${supportedLanguages.join(", ")}`,
+      code: ResponseCodes.INVALID_LANGUAGE
+    };
+  }
+  return { valid: true };
+}
+function isValidTokenName(tokenName) {
+  if (!tokenName || tokenName.length === 0) {
+    return {
+      valid: false,
+      error: "Token name is required",
+      code: ResponseCodes.MISSING_PARAMETER
+    };
+  }
+  if (tokenName.length < 10 || tokenName.length > 100) {
+    return {
+      valid: false,
+      error: "Token name appears to be invalid (wrong length)",
+      code: ResponseCodes.INVALID_TOKEN
+    };
+  }
+  return { valid: true };
+}
+function isValidPhone(phone) {
+  if (!phone || phone.length === 0) {
+    return { valid: true };
+  }
+  const phoneRegex = /^\+[1-9]\d{7,14}$/;
+  if (!phoneRegex.test(phone.replace(/[\s-]/g, ""))) {
+    return {
+      valid: false,
+      error: "Phone number must be in international format (+1234567890)",
+      code: ResponseCodes.INVALID_PARAMETER
+    };
+  }
+  return { valid: true };
+}
+function isValidDescription(description) {
+  if (!description || description.length === 0) {
+    return { valid: true };
+  }
+  if (description.length > 255) {
+    return {
+      valid: false,
+      error: "Description must be 255 characters or less",
+      code: ResponseCodes.INVALID_PARAMETER
+    };
+  }
+  return { valid: true };
+}
+function isValidCustomerName(name) {
+  if (!name || name.length === 0) {
+    return { valid: true };
+  }
+  if (name.length > 100) {
+    return {
+      valid: false,
+      error: "Customer name must be 100 characters or less",
+      code: ResponseCodes.INVALID_PARAMETER
+    };
+  }
+  return { valid: true };
+}
+function validatePaymentParams(params) {
+  const errors = [];
+  if (params.merchant_reference !== void 0) {
+    const result = isValidMerchantReference(params.merchant_reference);
+    if (!result.valid) {
+      errors.push({ field: "merchant_reference", error: result.error, code: result.code });
+    }
+  }
+  if (params.amount !== void 0) {
+    const result = isValidAmount(params.amount, params.currency);
+    if (!result.valid) {
+      errors.push({ field: "amount", error: result.error, code: result.code });
+    }
+  }
+  if (params.currency !== void 0) {
+    const result = isValidCurrency(params.currency);
+    if (!result.valid) {
+      errors.push({ field: "currency", error: result.error, code: result.code });
+    }
+  }
+  if (params.customer_email !== void 0) {
+    const result = isValidEmail(params.customer_email);
+    if (!result.valid) {
+      errors.push({ field: "customer_email", error: result.error, code: result.code });
+    }
+  }
+  if (params.return_url !== void 0) {
+    const result = isValidReturnUrl(params.return_url);
+    if (!result.valid) {
+      errors.push({ field: "return_url", error: result.error, code: result.code });
+    }
+  }
+  if (params.description !== void 0) {
+    const result = isValidDescription(params.description);
+    if (!result.valid) {
+      errors.push({ field: "description", error: result.error, code: result.code });
+    }
+  }
+  if (params.language !== void 0) {
+    const result = isValidLanguage(params.language);
+    if (!result.valid) {
+      errors.push({ field: "language", error: result.error, code: result.code });
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+var validators = {
+  isValidMerchantReference,
+  isValidAmount,
+  isValidCurrency,
+  isValidEmail,
+  isValidCardNumber,
+  isValidExpiryDate,
+  isValidCVV,
+  isValidReturnUrl,
+  isValidSignature,
+  isValidWebhookPayload,
+  isValidLanguage,
+  isValidTokenName,
+  isValidPhone,
+  isValidDescription,
+  isValidCustomerName,
+  validatePaymentParams
+};
+
+// src/index.ts
+var index_default = APSClient;
+var APS = APSClient;
+export {
+  APS,
+  APSClient,
+  APSException,
+  Commands,
+  CurrencyCodes,
+  CustomPaymentPageModule,
+  ECIValues,
+  ErrorCategories,
+  HostedCheckoutModule,
+  LanguageCodes,
+  PaymentLinksModule,
+  PaymentMethodCodes,
+  PaymentsModule,
+  RecurringModule,
+  ResponseCodes,
+  StatusCodes,
+  TestCards,
+  TokenizationModule,
+  WebhooksModule,
+  categorizeError,
+  isRetryableError2 as checkRetryableError,
+  index_default as default,
+  formatErrorForLogging,
+  getErrorCodesByCategory,
+  getErrorDetails,
+  getUserFriendlyMessage,
+  isRetryableError,
+  isSuccessCode,
+  isValidAmount,
+  isValidCVV,
+  isValidCardNumber,
+  isValidCurrency,
+  isValidCustomerName,
+  isValidDescription,
+  isValidEmail,
+  isValidExpiryDate,
+  isValidLanguage,
+  isValidMerchantReference,
+  isValidPhone,
+  isValidReturnUrl,
+  isValidSignature,
+  isValidTokenName,
+  isValidWebhookPayload,
+  suggestHttpStatus,
+  validatePaymentParams,
+  validators
+};