@madapay/alefa 0.0.0-stage → 0.1.1

package/dist/index.js

@@ -0,0 +1,595 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+import { ProviderTimeoutError, ProviderUnavailableError, AuthenticationError, PaymentNotFoundError, DuplicatePaymentError, ValidationError, validateCurrency, validateAmount, toNationalFormat, executeWithRetry, WebhookVerificationError } from '@madapay/core';
+
+// src/index.ts
+var PROVIDER = "alefa";
+function safeProviderError(payload) {
+  if (typeof payload !== "object" || payload === null) return {};
+  const p = payload;
+  const out = {};
+  for (const k of ["code", "error", "message", "detail"]) {
+    if (typeof p[k] === "string") out[`provider_${k}`] = p[k].slice(0, 200);
+  }
+  return out;
+}
+async function alefaRequest(opts) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+  const onAbort = () => controller.abort();
+  opts.signal?.addEventListener("abort", onAbort, { once: true });
+  let response;
+  try {
+    response = await opts.fetchImpl(opts.url, {
+      method: opts.method,
+      headers: opts.headers,
+      body: opts.body === void 0 ? void 0 : JSON.stringify(opts.body),
+      signal: controller.signal
+    });
+  } catch {
+    if (opts.signal?.aborted) throw new Error("Operation aborted by caller");
+    const timedOut = controller.signal.aborted;
+    if (opts.uncertainOnFailure || timedOut) {
+      throw new ProviderTimeoutError(
+        timedOut ? `Alefa request timed out after ${opts.timeoutMs}ms` : "Alefa request failed after dispatch; outcome is uncertain (network error)",
+        { timeoutMs: opts.timeoutMs },
+        PROVIDER
+      );
+    }
+    throw new ProviderUnavailableError("Alefa is unreachable", void 0, PROVIDER);
+  } finally {
+    clearTimeout(timer);
+    opts.signal?.removeEventListener("abort", onAbort);
+  }
+  const text = await response.text().catch(() => "");
+  let payload;
+  try {
+    payload = text ? JSON.parse(text) : void 0;
+  } catch {
+    payload = void 0;
+  }
+  if (response.ok) {
+    if (payload === void 0) {
+      throw opts.uncertainOnFailure ? new ProviderTimeoutError(
+        "Alefa returned an unreadable success response; outcome is uncertain",
+        { status: response.status },
+        PROVIDER
+      ) : new ProviderUnavailableError(
+        "Alefa returned an unreadable response",
+        void 0,
+        PROVIDER
+      );
+    }
+    return payload;
+  }
+  const details = { status: response.status, ...safeProviderError(payload) };
+  const s = response.status;
+  if (s === 401 || s === 403) {
+    throw new AuthenticationError("Alefa rejected credentials", details, PROVIDER);
+  }
+  if (s === 404) {
+    throw new PaymentNotFoundError("Alefa payment or resource not found", details, PROVIDER);
+  }
+  if (s === 409) {
+    throw new DuplicatePaymentError(
+      "Alefa idempotency conflict: request reference already processed or conflicting payload",
+      details,
+      PROVIDER
+    );
+  }
+  if (s === 400 || s === 422) {
+    const errorMsg = (typeof payload?.message === "string" ? payload.message : void 0) || "Alefa rejected request validation";
+    throw new ValidationError(errorMsg, "VALIDATION_FAILED", details, PROVIDER);
+  }
+  if (s >= 500) {
+    throw new ProviderUnavailableError(`Alefa service unavailable (HTTP ${s})`, details, PROVIDER);
+  }
+  throw new ProviderUnavailableError(
+    `Alefa returned unexpected status HTTP ${s}`,
+    details,
+    PROVIDER
+  );
+}
+
+// src/status.ts
+function mapAlefaStatus(rawStatus) {
+  if (typeof rawStatus !== "string" || rawStatus.trim() === "") {
+    return { status: "processing", known: false };
+  }
+  const s = rawStatus.trim().toUpperCase();
+  switch (s) {
+    case "CREATED":
+    case "INIT":
+    case "INITIAL":
+      return { status: "created", known: true };
+    case "PENDING":
+    case "WAITING":
+    case "AWAITING_ACTION":
+    case "ACTION_REQUIRED":
+    case "PENDING_ACTION":
+    case "PENDING_CUSTOMER_ACTION":
+      return { status: "pending", known: true };
+    case "PROCESSING":
+    case "IN_PROGRESS":
+    case "IN_FLIGHT":
+      return { status: "processing", known: true };
+    case "SUCCEEDED":
+    case "SUCCESS":
+    case "COMPLETED":
+    case "PAID":
+      return { status: "succeeded", known: true };
+    case "FAILED":
+    case "DECLINED":
+    case "REJECTED":
+    case "ERROR":
+      return { status: "failed", known: true };
+    case "EXPIRED":
+    case "TIMEOUT":
+    case "TIMED_OUT":
+      return { status: "expired", known: true };
+    case "CANCELLED":
+    case "CANCELED":
+      return { status: "cancelled", known: true };
+    default:
+      return { status: "processing", known: false };
+  }
+}
+var ALEFA_CONTRACT_METADATA = {
+  contractVersion: "Alefa Payment Gateway API v1.0.0",
+  reviewDate: "2026-10-31",
+  source: "https://alefa.mg/docs",
+  operatingEntity: "Alefa SAS (Antananarivo, Madagascar)",
+  indicativeCommissionPercent: 2.5,
+  settlementFeeAriary: 0
+};
+var alefaSandboxNumbers = {
+  mvola: "+261340000001",
+  mvola_qr: "+261340000002",
+  mvola_expired: "+261340000003",
+  mvola_failed: "+261340000004",
+  orange_money: "+261320000001",
+  orange_money_ussd: "+261320000002",
+  orange_money_expired: "+261320000003",
+  orange_money_failed: "+261320000004",
+  airtel_money: "+261330000001",
+  airtel_money_redirect: "+261330000002",
+  airtel_money_expired: "+261330000003",
+  airtel_money_failed: "+261330000004"
+};
+var alefaQrActionFixture = {
+  type: "qr_code",
+  qrData: "alefa://pay/tx_alefa_qr_12345?amount=10000&cur=MGA&ref=ORDER-QR-001",
+  qrImageUrl: "https://api.sandbox.alefa.mg/qr/tx_alefa_qr_12345.png",
+  expiresAt: "2026-10-31T20:00:00.000Z"
+};
+var alefaUssdActionFixture = {
+  type: "ussd",
+  ussdCode: "#144*31*654321#",
+  instructions: "Composez #144*31*654321# depuis votre mobile Orange Money et validez avec votre code secret.",
+  expiresAt: "2026-10-31T19:30:00.000Z"
+};
+var alefaRedirectActionFixture = {
+  type: "redirect_url",
+  url: "https://pay.sandbox.alefa.mg/checkout/tx_alefa_red_12345",
+  returnUrl: "https://merchant.mg/checkout/complete"
+};
+function createMockAlefaPaymentResponse(overrides = {}) {
+  return {
+    transactionId: overrides.transactionId ?? `alefa_tx_${Date.now()}`,
+    reference: overrides.reference ?? `ORDER_${Date.now()}`,
+    status: overrides.status ?? "PENDING",
+    amount: overrides.amount ?? 1e4,
+    currency: "MGA",
+    operator: overrides.operator ?? "mvola",
+    customerPhone: overrides.customerPhone ?? "0340000001",
+    checkoutUrl: overrides.checkoutUrl ?? "https://pay.sandbox.alefa.mg/checkout/mock",
+    action: overrides.action ?? alefaQrActionFixture,
+    expiresAt: overrides.expiresAt ?? new Date(Date.now() + 30 * 60 * 1e3).toISOString(),
+    createdAt: overrides.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    updatedAt: overrides.updatedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function createMockAlefaWebhook(payload, secret) {
+  const fullPayload = {
+    eventId: payload.eventId ?? `evt_alefa_${Date.now()}`,
+    eventType: payload.eventType ?? "payment.succeeded",
+    transactionId: payload.transactionId ?? `alefa_tx_${Date.now()}`,
+    reference: payload.reference ?? `ORDER_${Date.now()}`,
+    status: payload.status ?? "SUCCEEDED",
+    amount: payload.amount ?? 1e4,
+    currency: "MGA",
+    operator: payload.operator ?? "mvola",
+    timestamp: payload.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const bodyString = JSON.stringify(fullPayload);
+  const rawBody = new TextEncoder().encode(bodyString);
+  const signature = createHmac("sha256", secret).update(rawBody).digest("hex");
+  return {
+    rawBody,
+    headers: {
+      "content-type": "application/json",
+      "x-alefa-signature": signature,
+      "x-alefa-timestamp": fullPayload.timestamp
+    },
+    payload: fullPayload
+  };
+}
+
+// src/index.ts
+var ALEFA_BASE_URLS = {
+  sandbox: "https://api.sandbox.alefa.mg",
+  production: "https://api.alefa.mg"
+};
+var PROVIDER2 = "alefa";
+var SUPPORTED_METHODS = ["mvola", "orange_money", "airtel_money"];
+var MIN_AMOUNT_MGA = 100;
+var MAX_AMOUNT_MGA = 5e6;
+function validateConfig(config) {
+  if (!config || typeof config.apiKey !== "string" || config.apiKey.trim() === "") {
+    throw new AuthenticationError("Alefa apiKey is required", void 0, PROVIDER2);
+  }
+  if (config.environment !== "sandbox" && config.environment !== "production") {
+    throw new ValidationError(
+      "Alefa environment must be explicitly 'sandbox' or 'production'",
+      "VALIDATION_FAILED",
+      void 0,
+      PROVIDER2
+    );
+  }
+  const baseUrl = (config.baseUrl ?? ALEFA_BASE_URLS[config.environment]).replace(/\/+$/, "");
+  if (!baseUrl.startsWith("https://")) {
+    throw new ValidationError(
+      "Alefa baseUrl must use https",
+      "VALIDATION_FAILED",
+      void 0,
+      PROVIDER2
+    );
+  }
+  const looksSandbox = /sandbox|test|dev/i.test(new URL(baseUrl).hostname);
+  if (config.environment === "production" && looksSandbox) {
+    throw new ValidationError(
+      "Alefa production environment configured with a sandbox base URL",
+      "VALIDATION_FAILED",
+      void 0,
+      PROVIDER2
+    );
+  }
+  if (config.environment === "sandbox" && !looksSandbox) {
+    throw new ValidationError(
+      "Alefa sandbox environment configured with a non-sandbox base URL",
+      "VALIDATION_FAILED",
+      void 0,
+      PROVIDER2
+    );
+  }
+  return baseUrl;
+}
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ValidationError(
+      "Unexpected Alefa response format",
+      "VALIDATION_FAILED",
+      void 0,
+      PROVIDER2
+    );
+  }
+  return value;
+}
+function parseCustomerAction(rawAction) {
+  if (typeof rawAction !== "object" || rawAction === null) return void 0;
+  const a = rawAction;
+  if (a.type === "qr_code" && typeof a.qrData === "string") {
+    return {
+      type: "qr_code",
+      qrData: a.qrData,
+      qrImageUrl: typeof a.qrImageUrl === "string" ? a.qrImageUrl : void 0,
+      expiresAt: typeof a.expiresAt === "string" ? a.expiresAt : void 0
+    };
+  }
+  if (a.type === "ussd" && typeof a.ussdCode === "string") {
+    return {
+      type: "ussd",
+      ussdCode: a.ussdCode,
+      instructions: typeof a.instructions === "string" ? a.instructions : void 0,
+      expiresAt: typeof a.expiresAt === "string" ? a.expiresAt : void 0
+    };
+  }
+  if (a.type === "redirect_url" && typeof a.url === "string") {
+    return {
+      type: "redirect_url",
+      url: a.url,
+      returnUrl: typeof a.returnUrl === "string" ? a.returnUrl : void 0
+    };
+  }
+  return void 0;
+}
+var AlefaPaymentProvider = class {
+  id = PROVIDER2;
+  name = "Alefa";
+  apiKey;
+  webhookSecret;
+  baseUrl;
+  environment;
+  callbackUrl;
+  defaultValidityMinutes;
+  timeoutMs;
+  maxCreationRetries;
+  retryInitialDelayMs;
+  fetchImpl;
+  onUnknownStatus;
+  constructor(config) {
+    this.baseUrl = validateConfig(config);
+    this.apiKey = config.apiKey;
+    this.environment = config.environment;
+    this.webhookSecret = config.webhookSecret;
+    this.callbackUrl = config.callbackUrl;
+    this.defaultValidityMinutes = config.defaultValidityMinutes ?? 30;
+    this.timeoutMs = config.timeoutMs ?? 15e3;
+    this.maxCreationRetries = config.maxCreationRetries ?? 2;
+    this.retryInitialDelayMs = config.retryInitialDelayMs ?? 200;
+    this.fetchImpl = config.fetch ?? ((url, init) => fetch(url, init));
+    this.onUnknownStatus = config.onUnknownStatus;
+  }
+  /** Never exposes credentials or secrets. */
+  toJSON() {
+    return { id: this.id, environment: this.environment, baseUrl: this.baseUrl };
+  }
+  /**
+   * Capability truth table (D-07, ALEFA-01 through ALEFA-04).
+   * QR/USSD customer actions and hosted checkout are enabled.
+   * Direct refunds, payouts, payment links, and fee quotes remain unsupported.
+   */
+  getCapabilities() {
+    return {
+      payment: true,
+      asynchronousConfirmation: true,
+      synchronousConfirmation: false,
+      webhooks: true,
+      polling: true,
+      refunds: false,
+      payouts: false,
+      paymentLinks: false,
+      hostedCheckout: true,
+      feeQuote: false,
+      cancellation: false,
+      customerActions: true,
+      supportedMethods: [...SUPPORTED_METHODS],
+      syncConfirmation: false,
+      asyncConfirmation: true,
+      webhookEvents: true,
+      feeCalculation: false
+    };
+  }
+  headers(extra = {}) {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...extra
+    };
+  }
+  async createPayment(request) {
+    if (!SUPPORTED_METHODS.includes(request.paymentMethod)) {
+      throw new ValidationError(
+        `Alefa does not support payment method '${request.paymentMethod}'. Supported: ${SUPPORTED_METHODS.join(", ")}`,
+        "VALIDATION_FAILED",
+        { method: request.paymentMethod },
+        PROVIDER2
+      );
+    }
+    validateCurrency(request.currency);
+    validateAmount(request.amount, {
+      min: MIN_AMOUNT_MGA,
+      max: MAX_AMOUNT_MGA,
+      providerName: PROVIDER2
+    });
+    if (!request.idempotencyKey) {
+      throw new ValidationError(
+        "Alefa payment creation requires an idempotency key",
+        "VALIDATION_FAILED",
+        void 0,
+        PROVIDER2
+      );
+    }
+    const customerPhone = toNationalFormat(request.customer.phone);
+    const preferredAction = request.providerData?.preferredAction || "auto";
+    const validityMinutes = typeof request.providerData?.validityMinutes === "number" ? request.providerData.validityMinutes : this.defaultValidityMinutes;
+    const body = {
+      amount: request.amount,
+      currency: request.currency,
+      operator: request.paymentMethod,
+      customer: { phone: customerPhone },
+      reference: request.reference,
+      preferredAction,
+      validityMinutes
+    };
+    if (this.callbackUrl) body.callbackUrl = this.callbackUrl;
+    if (request.description) body.description = request.description;
+    if (request.returnUrls) body.returnUrls = request.returnUrls;
+    if (request.metadata) body.metadata = request.metadata;
+    const raw = await executeWithRetry(
+      () => alefaRequest({
+        method: "POST",
+        url: `${this.baseUrl}/api/v1/payments`,
+        headers: this.headers({ "Idempotency-Key": request.idempotencyKey }),
+        body,
+        timeoutMs: this.timeoutMs,
+        fetchImpl: this.fetchImpl,
+        uncertainOnFailure: true
+      }),
+      { maxRetries: this.maxCreationRetries, initialDelayMs: this.retryInitialDelayMs }
+    );
+    const p = asRecord(raw);
+    const providerReference = String(p.transactionId || p.paymentReference || p.id || "");
+    if (!providerReference) {
+      throw new ValidationError(
+        "Alefa response missing transactionId",
+        "VALIDATION_FAILED",
+        void 0,
+        PROVIDER2
+      );
+    }
+    const { status, known } = mapAlefaStatus(p.status);
+    if (!known) {
+      this.onUnknownStatus?.(String(p.status), request.reference);
+    }
+    const action = parseCustomerAction(p.action);
+    return {
+      providerReference,
+      reference: typeof p.reference === "string" ? p.reference : request.reference,
+      amount: typeof p.amount === "number" ? p.amount : request.amount,
+      currency: "MGA",
+      status,
+      paymentMethod: request.paymentMethod,
+      rawProviderStatus: typeof p.status === "string" ? p.status : void 0,
+      checkoutUrl: typeof p.checkoutUrl === "string" ? p.checkoutUrl : void 0,
+      action,
+      expiresAt: typeof p.expiresAt === "string" ? p.expiresAt : void 0
+    };
+  }
+  async getPayment(providerReferenceOrLookup) {
+    let identifier;
+    let isMerchantRef = false;
+    if (typeof providerReferenceOrLookup === "string") {
+      identifier = providerReferenceOrLookup.trim();
+    } else {
+      if (providerReferenceOrLookup.providerReference) {
+        identifier = providerReferenceOrLookup.providerReference.trim();
+      } else if (providerReferenceOrLookup.reference) {
+        identifier = providerReferenceOrLookup.reference.trim();
+        isMerchantRef = true;
+      } else if (providerReferenceOrLookup.id) {
+        identifier = providerReferenceOrLookup.id.trim();
+      } else {
+        throw new ValidationError(
+          "Invalid payment lookup selector",
+          "INVALID_SELECTOR",
+          void 0,
+          PROVIDER2
+        );
+      }
+    }
+    if (!identifier) {
+      throw new ValidationError(
+        "Empty payment identifier provided",
+        "INVALID_SELECTOR",
+        void 0,
+        PROVIDER2
+      );
+    }
+    const url = isMerchantRef ? `${this.baseUrl}/api/v1/payments?reference=${encodeURIComponent(identifier)}` : `${this.baseUrl}/api/v1/payments/${encodeURIComponent(identifier)}`;
+    const raw = await alefaRequest({
+      method: "GET",
+      url,
+      headers: this.headers(),
+      timeoutMs: this.timeoutMs,
+      fetchImpl: this.fetchImpl,
+      uncertainOnFailure: false
+    });
+    const p = asRecord(raw);
+    const providerReference = String(p.transactionId || p.paymentReference || p.id || identifier);
+    const { status, known } = mapAlefaStatus(p.status);
+    if (!known) {
+      this.onUnknownStatus?.(String(p.status), providerReference);
+    }
+    const action = parseCustomerAction(p.action);
+    const operatorMethod = typeof p.operator === "string" && SUPPORTED_METHODS.includes(p.operator) ? p.operator : "mvola";
+    return {
+      providerReference,
+      reference: typeof p.reference === "string" ? p.reference : providerReference,
+      amount: typeof p.amount === "number" ? p.amount : 0,
+      currency: "MGA",
+      status,
+      paymentMethod: operatorMethod,
+      rawProviderStatus: typeof p.status === "string" ? p.status : void 0,
+      checkoutUrl: typeof p.checkoutUrl === "string" ? p.checkoutUrl : void 0,
+      action,
+      expiresAt: typeof p.expiresAt === "string" ? p.expiresAt : void 0
+    };
+  }
+  async verifyWebhook(request) {
+    if (!request || !(request.rawBody instanceof Uint8Array)) {
+      throw new WebhookVerificationError(
+        "Webhook verification requires unmodified rawBody as a Uint8Array (D-04)",
+        void 0,
+        PROVIDER2
+      );
+    }
+    if (!this.webhookSecret) {
+      throw new WebhookVerificationError(
+        "Alefa webhook verification requires a configured webhookSecret",
+        void 0,
+        PROVIDER2
+      );
+    }
+    const headerSig = request.headers["x-alefa-signature"] || request.headers["X-Alefa-Signature"] || request.headers["x-signature"];
+    if (!headerSig || typeof headerSig !== "string") {
+      throw new WebhookVerificationError(
+        "Missing required X-Alefa-Signature header on webhook request",
+        void 0,
+        PROVIDER2
+      );
+    }
+    const timestampHeader = request.headers["x-alefa-timestamp"] || request.headers["X-Alefa-Timestamp"];
+    if (typeof timestampHeader === "string") {
+      const webhookTime = new Date(timestampHeader).getTime();
+      const now = Date.now();
+      const maxDriftMs = 3e5;
+      if (Number.isNaN(webhookTime) || Math.abs(now - webhookTime) > maxDriftMs) {
+        throw new WebhookVerificationError(
+          `Alefa webhook timestamp drift exceeds ${maxDriftMs / 1e3}s tolerance`,
+          void 0,
+          PROVIDER2
+        );
+      }
+    }
+    const computedSig = createHmac("sha256", this.webhookSecret).update(request.rawBody).digest("hex");
+    const expectedBuf = Buffer.from(computedSig, "hex");
+    const actualBuf = Buffer.from(headerSig.trim(), "hex");
+    if (expectedBuf.length !== actualBuf.length || !timingSafeEqual(expectedBuf, actualBuf)) {
+      throw new WebhookVerificationError(
+        "Alefa webhook signature verification failed: invalid HMAC digest",
+        void 0,
+        PROVIDER2
+      );
+    }
+    let payload;
+    try {
+      const text = new TextDecoder().decode(request.rawBody);
+      payload = asRecord(JSON.parse(text));
+    } catch {
+      throw new WebhookVerificationError(
+        "Alefa webhook body is not valid JSON after signature validation",
+        void 0,
+        PROVIDER2
+      );
+    }
+    const transactionId = String(
+      payload.transactionId || payload.paymentReference || payload.id || ""
+    );
+    if (!transactionId) {
+      throw new WebhookVerificationError(
+        "Alefa webhook payload missing transactionId or payment reference",
+        void 0,
+        PROVIDER2
+      );
+    }
+    const { status, known } = mapAlefaStatus(payload.status);
+    if (!known) {
+      this.onUnknownStatus?.(String(payload.status), transactionId);
+    }
+    const eventId = String(payload.eventId || payload.id || `evt_${Date.now()}`);
+    const occurredAt = typeof payload.timestamp === "string" ? payload.timestamp : (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      providerEventId: eventId,
+      providerReference: transactionId,
+      reference: typeof payload.reference === "string" ? payload.reference : void 0,
+      status,
+      occurredAt,
+      rawProviderStatus: typeof payload.status === "string" ? payload.status : void 0
+    };
+  }
+};
+
+export { ALEFA_BASE_URLS, ALEFA_CONTRACT_METADATA, AlefaPaymentProvider, AlefaPaymentProvider as AlefaProvider, alefaQrActionFixture, alefaRedirectActionFixture, alefaRequest, alefaSandboxNumbers, alefaUssdActionFixture, createMockAlefaPaymentResponse, createMockAlefaWebhook, mapAlefaStatus };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map