@mopay/node-sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,132 @@
+export type PaymentFrequency = "ONCE" | "MONTHLY" | "ANNUALLY";
+export type PaymentMethod = "mpesa" | "ecocash" | "card" | "none" | (string & {});
+export type RedirectStatus = "success" | "failed" | "cancelled" | (string & {});
+export type SessionStatus = "CREATED" | "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELLED" | "EXPIRED" | (string & {});
+export type TransactionStatus = "success" | "failed" | "cancelled" | null | (string & {});
+export type FetchLike = (input: string | URL | globalThis.Request, init?: globalThis.RequestInit) => Promise<globalThis.Response>;
+export interface MoPayConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetch?: FetchLike;
+    userAgent?: string;
+    checkout?: CheckoutOptions;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+}
+export interface CreatePaymentSessionParams {
+    amount: string | number;
+    reference: string;
+    redirectUrl: string;
+    description?: string;
+    customerEmail?: string;
+    customerName?: string;
+    paymentFrequency?: PaymentFrequency;
+    productName?: string;
+    productDetails?: string;
+    productImage?: string;
+    payWhatYouWant?: boolean;
+    minimumAmount?: string | number;
+}
+export interface CreatePaymentSessionResponse {
+    success: true;
+    sessionId: string;
+    paymentUrl: string;
+    checkoutUrl?: string;
+    checkout_url?: string;
+    checkoutToken?: string;
+    checkout_token?: string;
+    reference: string;
+    amount: string;
+}
+export interface Session {
+    id: string;
+    sessionId: string;
+    amount: string;
+    reference: string;
+    transactionStatus: TransactionStatus;
+    redirectUrl: string;
+    status: SessionStatus;
+    selectedPaymentMethod?: PaymentMethod | null;
+    transactionId?: string | null;
+    createdAt?: string;
+    completedAt?: string | null;
+    [key: string]: unknown;
+}
+export interface RetrieveSessionResponse {
+    success: true;
+    session: Session;
+}
+export interface ErrorResponse {
+    success?: false;
+    error?: string;
+    message?: string;
+    code?: string;
+    [key: string]: unknown;
+}
+export interface VerifiedRedirect {
+    status: RedirectStatus;
+    reference?: string;
+    transactionId?: string;
+    sessionId: string;
+    amount?: string;
+    paymentMethod?: PaymentMethod;
+    error?: string;
+    raw: Record<string, string>;
+}
+export type CheckoutMode = "popup" | "dialog" | "redirect";
+export type CheckoutStatus = "success" | "failed" | "cancelled" | "pending" | (string & {});
+export interface CheckoutMessage {
+    type?: string;
+    status?: CheckoutStatus;
+    sessionId?: string;
+    transactionId?: string;
+    reference?: string;
+    amount?: string;
+    paymentMethod?: PaymentMethod;
+    error?: string;
+    raw: unknown;
+}
+export interface CheckoutOptions {
+    mode?: CheckoutMode;
+    target?: Window;
+    popupName?: string;
+    width?: number;
+    height?: number;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    resizable?: boolean;
+    closeButtonLabel?: string;
+    onOpen?: (checkout: CheckoutHandle) => void;
+    onClose?: () => void;
+    onMessage?: (message: CheckoutMessage) => void;
+    onSuccess?: (message: CheckoutMessage) => void;
+    onFailed?: (message: CheckoutMessage) => void;
+    onCancel?: (message: CheckoutMessage) => void;
+    onPending?: (message: CheckoutMessage) => void;
+}
+export interface CheckoutHandle {
+    mode: CheckoutMode;
+    close: () => void;
+}
+export interface MoPayCheckoutOpenOptions extends CheckoutOptions {
+    checkoutUrl?: string;
+    checkout_url?: string;
+    checkoutToken?: string;
+    checkout_token?: string;
+    baseUrl?: string;
+    allowedOrigin?: string;
+    allowedOrigins?: string[];
+}
+export interface CheckoutFlowOptions extends CheckoutOptions, RequestOptions {
+    onSessionCreated?: (session: CreatePaymentSessionResponse) => void;
+}
+export interface WaitForSessionOptions extends RequestOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+    terminalStatuses?: SessionStatus[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,8 @@
+import type { CreatePaymentSessionParams, VerifiedRedirect } from "./types.js";
+export declare function applyMixins(derivedCtor: any, baseCtors: any[]): void;
+export declare function isValidReference(reference: string): boolean;
+export declare function formatAmount(amount: string | number): string;
+export declare function validateCreatePaymentSessionParams(params: CreatePaymentSessionParams): void;
+export declare function serializeCreatePaymentSessionParams(params: CreatePaymentSessionParams): Record<string, string | boolean>;
+export declare function parseRedirect(input: string | URL | URLSearchParams | Record<string, string>): VerifiedRedirect;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE/E,wBAAgB,WAAW,CAAC,WAAW,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,IAAI,CAcpE;AAID,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAe5D;AAED,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,0BAA0B,GAAG,IAAI,CAsB3F;AAED,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,0BAA0B,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CA0BlC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,gBAAgB,CA2B9G"}

package/dist/utils.js

@@ -0,0 +1,125 @@
+import { MoPayValidationError } from "./errors.js";
+export function applyMixins(derivedCtor, baseCtors) {
+    baseCtors.forEach((baseCtor) => {
+        Object.getOwnPropertyNames(baseCtor.prototype).forEach((name) => {
+            if (name === "constructor" || Object.prototype.hasOwnProperty.call(derivedCtor.prototype, name)) {
+                return;
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(baseCtor.prototype, name);
+            if (descriptor) {
+                Object.defineProperty(derivedCtor.prototype, name, descriptor);
+            }
+        });
+    });
+}
+const REFERENCE_PATTERN = /^[A-Za-z0-9]+$/;
+export function isValidReference(reference) {
+    return REFERENCE_PATTERN.test(reference);
+}
+export function formatAmount(amount) {
+    if (typeof amount === "number") {
+        if (!Number.isFinite(amount) || amount <= 0) {
+            throw new MoPayValidationError("amount must be a positive number");
+        }
+        return amount.toFixed(2);
+    }
+    const trimmed = amount.trim();
+    if (!/^\d+(\.\d{1,2})?$/.test(trimmed) || Number(trimmed) <= 0) {
+        throw new MoPayValidationError("amount must be a positive decimal string");
+    }
+    return trimmed;
+}
+export function validateCreatePaymentSessionParams(params) {
+    formatAmount(params.amount);
+    if (!params.reference || !isValidReference(params.reference)) {
+        throw new MoPayValidationError("reference must contain only letters and numbers, with no spaces or symbols");
+    }
+    try {
+        new URL(params.redirectUrl);
+    }
+    catch (error) {
+        if (error instanceof MoPayValidationError) {
+            throw error;
+        }
+        throw new MoPayValidationError("redirectUrl must be a valid absolute URL");
+    }
+    if (params.minimumAmount !== undefined) {
+        formatAmount(params.minimumAmount);
+    }
+}
+export function serializeCreatePaymentSessionParams(params) {
+    validateCreatePaymentSessionParams(params);
+    const body = {
+        amount: formatAmount(params.amount),
+        reference: params.reference,
+        redirectUrl: params.redirectUrl,
+    };
+    addOptional(body, "description", params.description);
+    addOptional(body, "customerEmail", params.customerEmail);
+    addOptional(body, "customerName", params.customerName);
+    addOptional(body, "paymentFrequency", params.paymentFrequency);
+    addOptional(body, "productName", params.productName);
+    addOptional(body, "productDetails", params.productDetails);
+    addOptional(body, "productImage", params.productImage);
+    if (params.payWhatYouWant !== undefined) {
+        body.payWhatYouWant = params.payWhatYouWant;
+    }
+    if (params.minimumAmount !== undefined) {
+        body.minimumAmount = formatAmount(params.minimumAmount);
+    }
+    return body;
+}
+export function parseRedirect(input) {
+    const params = toSearchParams(input);
+    const raw = Object.fromEntries(params.entries());
+    const status = params.get("status");
+    const sessionId = params.get("sessionId");
+    if (!status) {
+        throw new MoPayValidationError("redirect is missing status");
+    }
+    if (!sessionId) {
+        throw new MoPayValidationError("redirect is missing sessionId");
+    }
+    const redirect = {
+        status,
+        sessionId,
+        raw,
+    };
+    addOptionalRedirectValue(redirect, "reference", params.get("reference"));
+    addOptionalRedirectValue(redirect, "transactionId", params.get("transactionId"));
+    addOptionalRedirectValue(redirect, "amount", params.get("amount"));
+    addOptionalRedirectValue(redirect, "paymentMethod", params.get("paymentMethod"));
+    addOptionalRedirectValue(redirect, "error", params.get("error"));
+    return redirect;
+}
+function addOptional(body, key, value) {
+    if (value !== undefined) {
+        body[key] = value;
+    }
+}
+function optional(value) {
+    return value === null || value === "" ? undefined : value;
+}
+function addOptionalRedirectValue(redirect, key, value) {
+    const parsed = optional(value);
+    if (parsed !== undefined) {
+        redirect[key] = parsed;
+    }
+}
+function toSearchParams(input) {
+    if (input instanceof URLSearchParams) {
+        return input;
+    }
+    if (input instanceof URL) {
+        return input.searchParams;
+    }
+    if (typeof input === "string") {
+        try {
+            return new URL(input).searchParams;
+        }
+        catch {
+            return new URLSearchParams(input.startsWith("?") ? input.slice(1) : input);
+        }
+    }
+    return new URLSearchParams(input);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mopay/node-sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the MoPay payment API.",
+  "type": "module",
+  "source": "src/index.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "unpkg": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "prepack": "pnpm run build",
+    "prepublishOnly": "pnpm test"
+  },
+  "keywords": [
+    "mopay",
+    "payments",
+    "lesotho",
+    "mpesa",
+    "ecocash",
+    "fintech"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^4.9.5"
+  }
+}