@dryinov8/zumbopay-ts 1.0.0

package/dist/client-CO8dBkq7.d.ts

@@ -0,0 +1,188 @@
+type MobileOperator = 'mpesa' | 'emola' | 'mkesh' | 'unknown';
+type PaymentStatus = 'pending' | 'processing' | 'success' | 'succeeded' | 'completed' | 'failed' | 'declined' | 'cancelled' | 'expired' | 'disabled';
+interface ZumboPayWallets {
+    mpesa?: string;
+    emola?: string;
+    mkesh?: string;
+    card?: string;
+    [key: string]: string | undefined;
+}
+interface ZumboPayConfig {
+    /**
+     * ZumboPay Secret API Key
+     */
+    apiKey: string;
+    /**
+     * ZumboPay Merchant ID
+     */
+    merchantId: string;
+    /**
+     * Base API URL (defaults to https://zumbopay.com/api/public/v1)
+     */
+    baseUrl?: string;
+    /**
+     * Webhook signing secret for HMAC verification
+     */
+    webhookSecret?: string;
+    /**
+     * Pre-configured Wallet UUIDs for specific channels
+     */
+    wallets?: ZumboPayWallets;
+    /**
+     * Global kill-switch / activation toggle.
+     * If false, all checkout and STK push operations are gracefully silenced
+     * and return a disabled status without making external network calls.
+     * Defaults to true (or checks process.env.ZUMBOPAY_ENABLED when available).
+     */
+    enabled?: boolean;
+    /**
+     * Request timeout in milliseconds (defaults to 15000)
+     */
+    timeout?: number;
+}
+interface StkPushRequest {
+    /**
+     * Amount in Principal currency units (e.g. 150.00 MZN)
+     */
+    amount: number;
+    /**
+     * Mozambican phone number (Vodacom, Movitel, or Tmcel)
+     */
+    phone: string;
+    /**
+     * Commercial transaction reference / order ID
+     */
+    reference?: string;
+    /**
+     * Customer full name
+     */
+    customerName?: string;
+    /**
+     * Specific Wallet UUID (optional, will be auto-resolved from phone if omitted)
+     */
+    walletId?: string;
+    /**
+     * Description / note
+     */
+    description?: string;
+}
+interface StkPushResponse {
+    success: boolean;
+    status: PaymentStatus;
+    reference: string | null;
+    message: string;
+    raw?: Record<string, unknown>;
+}
+interface CheckoutRequest {
+    /**
+     * Amount in Principal currency units (e.g. 500.00 MZN)
+     */
+    amount: number;
+    /**
+     * Payment title / product name
+     */
+    title: string;
+    /**
+     * Currency code (defaults to MZN)
+     */
+    currency?: string;
+    /**
+     * Commercial transaction reference / order ID
+     */
+    reference?: string;
+    /**
+     * Return URL after successful payment
+     */
+    returnUrl?: string;
+    /**
+     * Cancel URL if user aborts
+     */
+    cancelUrl?: string;
+    /**
+     * Allowed payment channels (defaults to ['card', 'mpesa', 'emola', 'mkesh'])
+     */
+    channels?: string[];
+    /**
+     * Specific Wallet UUID
+     */
+    walletId?: string;
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+interface CheckoutResponse {
+    success: boolean;
+    checkoutUrl: string | null;
+    reference: string | null;
+    message: string;
+    raw?: Record<string, unknown>;
+}
+interface TransactionStatusResponse {
+    success: boolean;
+    status: PaymentStatus;
+    paid: boolean;
+    reference: string;
+    amount?: number;
+    currency?: string;
+    channel?: string;
+    paidAt?: string | null;
+    raw?: Record<string, unknown>;
+}
+interface WalletItem {
+    id: string;
+    wallet_code?: string;
+    name?: string;
+    method?: string;
+    currency?: string;
+    balance?: number;
+    is_active?: boolean;
+}
+
+declare class ZumboPayClient {
+    private readonly config;
+    private cachedWallets;
+    private walletsCacheExpiresAt;
+    constructor(config: ZumboPayConfig);
+    /**
+     * Returns whether the ZumboPay client is currently active.
+     * If false, all mutations (STK push, checkouts) are gracefully silenced.
+     */
+    isEnabled(): boolean;
+    /**
+     * Programmatically enable or disable the gateway (kill-switch toggle).
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Returns configured base URL.
+     */
+    getBaseUrl(): string;
+    /**
+     * Resolves a valid Wallet UUID for a given operator or channel.
+     */
+    resolveWalletId(channel: 'mpesa' | 'emola' | 'mkesh' | 'card'): Promise<string | undefined>;
+    /**
+     * Resolves the proper wallet ID for a Mozambican phone number.
+     */
+    resolveWalletIdForPhone(phone: string): Promise<string | undefined>;
+    /**
+     * Initiates a direct STK Push prompt to a mobile phone (M-Pesa, e-Mola, mKesh).
+     */
+    stkPush(request: StkPushRequest): Promise<StkPushResponse>;
+    /**
+     * Creates a Hosted Checkout URL for credit/debit card & multicanal payments.
+     */
+    createCheckout(request: CheckoutRequest): Promise<CheckoutResponse>;
+    /**
+     * Queries status of an existing charge/checkout transaction.
+     */
+    getStatus(referenceOrId: string): Promise<TransactionStatusResponse>;
+    /**
+     * Lists all wallets associated with the merchant account (cached for 10 minutes).
+     */
+    listWallets(): Promise<WalletItem[]>;
+    private getHeaders;
+    private fetchWithTimeout;
+}
+
+export { type CheckoutRequest as C, type MobileOperator as M, type PaymentStatus as P, type StkPushRequest as S, type TransactionStatusResponse as T, type WalletItem as W, ZumboPayClient as Z, type CheckoutResponse as a, type StkPushResponse as b, type ZumboPayConfig as c, type ZumboPayWallets as d };

package/dist/index.d.mts

@@ -0,0 +1,35 @@
+import { M as MobileOperator } from './client-CO8dBkq7.mjs';
+export { C as CheckoutRequest, a as CheckoutResponse, P as PaymentStatus, S as StkPushRequest, b as StkPushResponse, T as TransactionStatusResponse, W as WalletItem, Z as ZumboPayClient, c as ZumboPayConfig, d as ZumboPayWallets } from './client-CO8dBkq7.mjs';
+
+/**
+ * Normalizes any Mozambican telephone string into the standard 12-digit format `258XXXXXXXXX`.
+ * Removes spaces, hyphens, parentheses, and prefixes (+258, 258, 0).
+ */
+declare function normalizePhone(phone: string): string;
+/**
+ * Detects mobile network operator from phone number:
+ * - Vodacom (M-Pesa): 84, 85
+ * - Movitel (e-Mola): 86, 87
+ * - Tmcel (mKesh): 82, 83
+ */
+declare function detectOperator(phone: string): MobileOperator;
+/**
+ * Returns human-readable label for a mobile operator.
+ */
+declare function getOperatorLabel(operator: MobileOperator): string;
+/**
+ * Validates whether the number is a valid 9-digit Mozambican mobile number (with or without 258).
+ */
+declare function isValidMozPhone(phone: string): boolean;
+
+/**
+ * Validates HMAC-SHA256 webhook signature sent by ZumboPay.
+ * Resists timing attacks using constant-time buffer comparison.
+ *
+ * @param rawBody - Raw body string or Buffer from the webhook request
+ * @param receivedSignature - Signature sent in `X-Signature`, `Signature`, or `X-ZumboPay-Signature` header
+ * @param secret - Webhook secret configured in ZumboPay dashboard
+ */
+declare function verifyWebhookSignature(rawBody: string | Buffer, receivedSignature: string, secret: string): boolean;
+
+export { MobileOperator, detectOperator, getOperatorLabel, isValidMozPhone, normalizePhone, verifyWebhookSignature };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { M as MobileOperator } from './client-CO8dBkq7.js';
+export { C as CheckoutRequest, a as CheckoutResponse, P as PaymentStatus, S as StkPushRequest, b as StkPushResponse, T as TransactionStatusResponse, W as WalletItem, Z as ZumboPayClient, c as ZumboPayConfig, d as ZumboPayWallets } from './client-CO8dBkq7.js';
+
+/**
+ * Normalizes any Mozambican telephone string into the standard 12-digit format `258XXXXXXXXX`.
+ * Removes spaces, hyphens, parentheses, and prefixes (+258, 258, 0).
+ */
+declare function normalizePhone(phone: string): string;
+/**
+ * Detects mobile network operator from phone number:
+ * - Vodacom (M-Pesa): 84, 85
+ * - Movitel (e-Mola): 86, 87
+ * - Tmcel (mKesh): 82, 83
+ */
+declare function detectOperator(phone: string): MobileOperator;
+/**
+ * Returns human-readable label for a mobile operator.
+ */
+declare function getOperatorLabel(operator: MobileOperator): string;
+/**
+ * Validates whether the number is a valid 9-digit Mozambican mobile number (with or without 258).
+ */
+declare function isValidMozPhone(phone: string): boolean;
+
+/**
+ * Validates HMAC-SHA256 webhook signature sent by ZumboPay.
+ * Resists timing attacks using constant-time buffer comparison.
+ *
+ * @param rawBody - Raw body string or Buffer from the webhook request
+ * @param receivedSignature - Signature sent in `X-Signature`, `Signature`, or `X-ZumboPay-Signature` header
+ * @param secret - Webhook secret configured in ZumboPay dashboard
+ */
+declare function verifyWebhookSignature(rawBody: string | Buffer, receivedSignature: string, secret: string): boolean;
+
+export { MobileOperator, detectOperator, getOperatorLabel, isValidMozPhone, normalizePhone, verifyWebhookSignature };

package/dist/index.js

@@ -0,0 +1,400 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ZumboPayClient: () => ZumboPayClient,
+  detectOperator: () => detectOperator,
+  getOperatorLabel: () => getOperatorLabel,
+  isValidMozPhone: () => isValidMozPhone,
+  normalizePhone: () => normalizePhone,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/phone.ts
+function normalizePhone(phone) {
+  let cleaned = phone.replace(/\D/g, "");
+  if (cleaned.startsWith("0")) {
+    cleaned = cleaned.slice(1);
+  }
+  if (cleaned.length === 9) {
+    cleaned = "258" + cleaned;
+  }
+  return cleaned;
+}
+function detectOperator(phone) {
+  const normalized = normalizePhone(phone);
+  if (normalized.length !== 12 || !normalized.startsWith("258")) {
+    return "unknown";
+  }
+  const prefix = normalized.slice(3, 5);
+  if (prefix === "84" || prefix === "85") {
+    return "mpesa";
+  }
+  if (prefix === "86" || prefix === "87") {
+    return "emola";
+  }
+  if (prefix === "82" || prefix === "83") {
+    return "mkesh";
+  }
+  return "unknown";
+}
+function getOperatorLabel(operator) {
+  switch (operator) {
+    case "mpesa":
+      return "Vodacom M-Pesa";
+    case "emola":
+      return "Movitel e-Mola";
+    case "mkesh":
+      return "Tmcel mKesh";
+    default:
+      return "Desconhecida";
+  }
+}
+function isValidMozPhone(phone) {
+  return detectOperator(phone) !== "unknown";
+}
+
+// src/webhook.ts
+var import_node_crypto = __toESM(require("crypto"));
+function verifyWebhookSignature(rawBody, receivedSignature, secret) {
+  if (!receivedSignature || !secret) {
+    return false;
+  }
+  const cleanReceived = receivedSignature.replace(/^(sha256=|v1=)/i, "").trim();
+  try {
+    const expected = import_node_crypto.default.createHmac("sha256", secret).update(typeof rawBody === "string" ? rawBody : rawBody.toString("utf8")).digest("hex");
+    const expectedBuf = Buffer.from(expected, "hex");
+    const receivedBuf = Buffer.from(cleanReceived, "hex");
+    if (expectedBuf.length !== receivedBuf.length) {
+      return false;
+    }
+    return import_node_crypto.default.timingSafeEqual(expectedBuf, receivedBuf);
+  } catch {
+    return false;
+  }
+}
+
+// src/client.ts
+var ZumboPayClient = class {
+  config;
+  cachedWallets = null;
+  walletsCacheExpiresAt = 0;
+  constructor(config) {
+    const envWallets = {};
+    let defaultEnabled = true;
+    if (typeof process !== "undefined" && process?.env) {
+      if (process.env.ZUMBOPAY_ENABLED !== void 0) {
+        defaultEnabled = process.env.ZUMBOPAY_ENABLED === "true" || process.env.ZUMBOPAY_ENABLED === "1";
+      }
+      if (process.env.ZUMBOPAY_WALLET_MPESA) {
+        envWallets.mpesa = process.env.ZUMBOPAY_WALLET_MPESA;
+      }
+      if (process.env.ZUMBOPAY_WALLET_EMOLA) {
+        envWallets.emola = process.env.ZUMBOPAY_WALLET_EMOLA;
+      }
+      if (process.env.ZUMBOPAY_WALLET_MKESH) {
+        envWallets.mkesh = process.env.ZUMBOPAY_WALLET_MKESH;
+      }
+      if (process.env.ZUMBOPAY_WALLET_CARD) {
+        envWallets.card = process.env.ZUMBOPAY_WALLET_CARD;
+      }
+    }
+    this.config = {
+      apiKey: config.apiKey,
+      merchantId: config.merchantId,
+      baseUrl: config.baseUrl?.replace(/\/+$/, "") || "https://zumbopay.com/api/public/v1",
+      webhookSecret: config.webhookSecret,
+      wallets: {
+        ...envWallets,
+        ...config.wallets || {}
+      },
+      enabled: config.enabled !== void 0 ? config.enabled : defaultEnabled,
+      timeout: config.timeout || 15e3
+    };
+  }
+  /**
+   * Returns whether the ZumboPay client is currently active.
+   * If false, all mutations (STK push, checkouts) are gracefully silenced.
+   */
+  isEnabled() {
+    return Boolean(this.config.enabled);
+  }
+  /**
+   * Programmatically enable or disable the gateway (kill-switch toggle).
+   */
+  setEnabled(enabled) {
+    this.config.enabled = enabled;
+  }
+  /**
+   * Returns configured base URL.
+   */
+  getBaseUrl() {
+    return this.config.baseUrl;
+  }
+  /**
+   * Resolves a valid Wallet UUID for a given operator or channel.
+   */
+  async resolveWalletId(channel) {
+    if (this.config.wallets[channel]) {
+      return this.config.wallets[channel];
+    }
+    const wallets = await this.listWallets();
+    const match = wallets.find(
+      (w) => w.is_active !== false && (w.method?.toLowerCase() === channel || w.wallet_code?.toLowerCase().includes(channel) || w.name?.toLowerCase().includes(channel))
+    );
+    if (match) {
+      return match.id;
+    }
+    const active = wallets.find((w) => w.is_active !== false);
+    return active?.id;
+  }
+  /**
+   * Resolves the proper wallet ID for a Mozambican phone number.
+   */
+  async resolveWalletIdForPhone(phone) {
+    const operator = detectOperator(phone);
+    if (operator === "unknown") {
+      return void 0;
+    }
+    return this.resolveWalletId(operator);
+  }
+  /**
+   * Initiates a direct STK Push prompt to a mobile phone (M-Pesa, e-Mola, mKesh).
+   */
+  async stkPush(request) {
+    if (!this.isEnabled()) {
+      return {
+        success: false,
+        status: "disabled",
+        reference: null,
+        message: "O gateway de pagamento ZumboPay est\xE1 temporariamente desativado."
+      };
+    }
+    const normalizedPhone = normalizePhone(request.phone);
+    const walletId = request.walletId || await this.resolveWalletIdForPhone(normalizedPhone);
+    const sourceId = request.reference || `stk-${Date.now()}`;
+    const payload = {
+      phone: normalizedPhone,
+      amount: request.amount,
+      wallet_id: walletId,
+      reference: sourceId,
+      customer_name: request.customerName,
+      description: request.description
+    };
+    try {
+      const res = await this.fetchWithTimeout("/charges", {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(payload)
+      });
+      const data = await res.json().catch(() => ({}));
+      if (res.ok) {
+        const status = (data.data?.status || data.status || "pending").toLowerCase();
+        const code = data.code || data.data?.code;
+        const isSuccess = status === "success" || status === "succeeded" || status === "completed" || code === "INS-0";
+        return {
+          success: true,
+          status: isSuccess ? "success" : status,
+          reference: data.data?.reference || sourceId,
+          message: isSuccess ? "Pagamento efetuado com sucesso!" : "Pedido de pagamento enviado para o seu telem\xF3vel. Por favor confirme com o seu PIN.",
+          raw: data
+        };
+      }
+      return {
+        success: false,
+        status: "declined",
+        reference: null,
+        message: data.error?.message || data.message || "O pagamento foi recusado ou expirou no telem\xF3vel.",
+        raw: data
+      };
+    } catch (err) {
+      const error = err;
+      if (error.name === "AbortError" || error.message.includes("timeout")) {
+        return {
+          success: true,
+          status: "pending",
+          reference: sourceId,
+          message: "O pedido foi enviado. Por favor verifique o telem\xF3vel e confirme com o PIN.",
+          raw: { timeout: true }
+        };
+      }
+      return {
+        success: false,
+        status: "failed",
+        reference: null,
+        message: error.message || "Falha na comunica\xE7\xE3o com o ZumboPay."
+      };
+    }
+  }
+  /**
+   * Creates a Hosted Checkout URL for credit/debit card & multicanal payments.
+   */
+  async createCheckout(request) {
+    if (!this.isEnabled()) {
+      return {
+        success: false,
+        checkoutUrl: null,
+        reference: null,
+        message: "O gateway de pagamento ZumboPay est\xE1 temporariamente desativado."
+      };
+    }
+    const walletId = request.walletId || await this.resolveWalletId("card") || await this.resolveWalletId("mpesa");
+    const sourceId = request.reference || `chk-${Date.now()}`;
+    const payload = {
+      title: request.title,
+      amount: request.amount,
+      currency: request.currency || "MZN",
+      channels: request.channels || ["card", "mpesa", "emola", "mkesh"],
+      wallet_id: walletId,
+      reference: sourceId,
+      return_url: request.returnUrl,
+      redirect_url: request.returnUrl,
+      cancel_url: request.cancelUrl,
+      metadata: request.metadata
+    };
+    try {
+      const res = await this.fetchWithTimeout("/checkouts", {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(payload)
+      });
+      const data = await res.json().catch(() => ({}));
+      if (res.ok) {
+        const checkoutUrl = data.data?.checkout_url || data.checkout_url || data.data?.url || data.url || null;
+        return {
+          success: true,
+          checkoutUrl,
+          reference: data.data?.reference || sourceId,
+          message: "Sess\xE3o de checkout criada com sucesso.",
+          raw: data
+        };
+      }
+      return {
+        success: false,
+        checkoutUrl: null,
+        reference: null,
+        message: data.error?.message || data.message || "N\xE3o foi poss\xEDvel gerar a p\xE1gina de checkout.",
+        raw: data
+      };
+    } catch (err) {
+      const error = err;
+      return {
+        success: false,
+        checkoutUrl: null,
+        reference: null,
+        message: error.message || "Erro de conex\xE3o ao criar checkout."
+      };
+    }
+  }
+  /**
+   * Queries status of an existing charge/checkout transaction.
+   */
+  async getStatus(referenceOrId) {
+    const res = await this.fetchWithTimeout(
+      `/charges/${encodeURIComponent(referenceOrId)}`,
+      {
+        method: "GET",
+        headers: this.getHeaders()
+      }
+    );
+    const data = await res.json().catch(() => ({}));
+    const payload = data.data || data;
+    const status = (payload.status || "pending").toLowerCase();
+    const isPaid = status === "success" || status === "succeeded" || status === "completed" || payload.is_paid === true;
+    return {
+      success: res.ok,
+      status,
+      paid: isPaid,
+      reference: payload.reference || referenceOrId,
+      amount: payload.amount,
+      currency: payload.currency || "MZN",
+      channel: payload.channel,
+      paidAt: payload.paid_at || payload.updated_at || null,
+      raw: data
+    };
+  }
+  /**
+   * Lists all wallets associated with the merchant account (cached for 10 minutes).
+   */
+  async listWallets() {
+    const now = Date.now();
+    if (this.cachedWallets && now < this.walletsCacheExpiresAt) {
+      return this.cachedWallets;
+    }
+    try {
+      const res = await this.fetchWithTimeout("/wallets", {
+        method: "GET",
+        headers: this.getHeaders()
+      });
+      if (res.ok) {
+        const data = await res.json();
+        this.cachedWallets = data.data || data || [];
+        this.walletsCacheExpiresAt = now + 10 * 60 * 1e3;
+        return this.cachedWallets;
+      }
+      return [];
+    } catch {
+      return [];
+    }
+  }
+  getHeaders() {
+    return {
+      Authorization: `Bearer ${this.config.apiKey}`,
+      "X-Merchant-Id": this.config.merchantId,
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+  }
+  async fetchWithTimeout(endpoint, options) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeout);
+    const url = `${this.config.baseUrl}${endpoint}`;
+    try {
+      return await fetch(url, {
+        ...options,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ZumboPayClient,
+  detectOperator,
+  getOperatorLabel,
+  isValidMozPhone,
+  normalizePhone,
+  verifyWebhookSignature
+});
+//# sourceMappingURL=index.js.map