@ngandu-dev/flexpay 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Bernard Ngandu and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# FlexPay TypeScript
+
+![npm](https://img.shields.io/npm/v/@ngandu-dev/flexpay?style=flat-square)
+![npm](https://img.shields.io/npm/dt/@ngandu-dev/flexpay?style=flat-square)
+[![Quality](https://github.com/ngandu-dev/flexpay/actions/workflows/quality.yml/badge.svg?branch=main)](https://github.com/ngandu-dev/flexpay/actions/workflows/quality.yml)
+[![Tests](https://github.com/ngandu-dev/flexpay/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/ngandu-dev/flexpay/actions/workflows/test.yml)
+![GitHub](https://img.shields.io/github/license/ngandu-dev/flexpay?style=flat-square)
+
+For privacy reasons, FlexPay's original documentation cannot be shared without written permission.
+For credentials and implementation details, contact [FlexPay](https://flexpay.cd).
+
+## Features
+
+- Typed mobile-money and card payment requests
+- Transaction status checks and callback validation
+- Development and production API environments
+- ESM and CommonJS distributions with TypeScript declarations
+
+## Requirements
+
+- Node.js 24 or newer
+
+## Installation
+
+Add the TypeScript client to your application's dependencies:
+
+```bash
+npm install @ngandu-dev/flexpay
+```
+
+## Quick start
+
+### Authentication
+
+- **Step 1**. Contact FlexPay to get a Merchant Account
+  You will receive a Merchant Form to complete in order to provide your business details and preferred Cash out Wallet or Banking Details.
+- **Step 2**. Once the paperwork is completed, you will be issued with Live and Sandbox Accounts (Merchant Code and Authorization token)
+
+Then use these credentials to authenticate your client
+
+```ts
+import { Client as Flexpay } from "@ngandu-dev/flexpay";
+
+const flexpay = new Flexpay("merchant_code", "token", "dev"); // use "prod" for production
+```
+
+## Usage
+
+### Create a Payment Request
+
+```typescript
+import type { CardRequest, MobileRequest } from "@ngandu-dev/flexpay";
+
+const mobile = {
+  amount: 10, // 10 USD
+  currency: "USD",
+  phone: "243999999999",
+  reference: "mobile_order_12345",
+  description: "your_transaction_description",
+  callbackUrl: "https://example.com/flexpay/callback",
+} satisfies MobileRequest;
+
+const card = {
+  amount: 10, // 10 USD
+  currency: "USD",
+  reference: "card_order_12345",
+  description: "your_transaction_description",
+  callbackUrl: "https://example.com/flexpay/callback",
+  approveUrl: "https://example.com/flexpay/approved",
+  cancelUrl: "https://example.com/flexpay/cancelled",
+  declineUrl: "https://example.com/flexpay/declined",
+  homeUrl: "https://example.com",
+} satisfies CardRequest;
+```
+
+> **Note**: we highly recommend your `callbacks` urls to be unique for each transaction.
+
+### Mobile Payment
+Once called, Flexpay will send a payment request to the user's mobile money account, and the user will have to confirm the payment on their phone.
+after that the payment will be processed and the callback url will be called with the transaction details.
+
+```typescript
+const mobileResponse = await flexpay.pay(mobile);
+```
+
+### Visa Card Payment
+You can set up card payment via VPOS features, which is typically used for online payments.
+it's a gateway that allows you to accept payments from your customers using their credit cards.
+
+```typescript
+const cardResponse = await flexpay.pay(card);
+// redirect to cardResponse.url to complete the payment
+```
+
+#### **handling callback (callbackUrl, approveUrl, cancelUrl, declineUrl)**
+Flexpay will send a POST request to the defined callbackUrl and the response will contain the transaction details.
+you can use the following code to validate the incoming payload.
+
+```typescript
+const webhook = flexpay.handleCallback(req.body);
+flexpay.isSuccessful(webhook); // true or false
+```
+
+### Check Transaction state
+You don't trust webhook ? you can always check the transaction state by providing the order number.
+
+```typescript
+if (!mobileResponse.orderNumber) {
+  throw new Error("FlexPay did not return an order number");
+}
+
+const tx = await flexpay.check(mobileResponse.orderNumber);
+flexpay.isSuccessful(tx); // true or false
+```
+
+## Migrating to `@ngandu-dev/flexpay`
+
+Replace the dependency and every import with `@ngandu-dev/flexpay`. Version 2 is a clean package
+move and does not provide an alias for the old scope.
+
+## Development
+
+Install dependencies with `bun install`, then run `bun run quality` before opening a pull request.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete contribution workflow.
+
+## Testing
+
+Run `bun run test` for the test suite or `bun run test:coverage` for a coverage report.
+
+## Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) and follow our
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+Please report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+Released under the [MIT License](LICENSE).
+
+## Contributors
+
+<a href="https://github.com/ngandu-dev/flexpay/graphs/contributors" title="Show all contributors">
+  <img src="https://contrib.rocks/image?repo=ngandu-dev/flexpay" alt="Contributors" />
+</a>

package/dist/index.d.mts

@@ -0,0 +1,169 @@
+import * as z from 'zod';
+
+type EnvironmentType = "prod" | "dev";
+declare class Environment {
+    readonly value: EnvironmentType;
+    constructor(value: EnvironmentType);
+    getMobilePaymentUrl(): string;
+    getPayoutUrl(): string;
+    getCheckStatusUrl(orderNumber: string): string;
+    getCardPaymentUrl(): string;
+    private getBaseUrl;
+}
+
+declare enum Status {
+    SUCCESS = 0,// When the request is successfully processed
+    FAILURE = 1
+}
+declare const CurrencySchema: z.ZodEnum<{
+    USD: "USD";
+    CDF: "CDF";
+}>;
+type Currency = z.infer<typeof CurrencySchema>;
+declare const StatusSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+declare const MobileResponseSchema: z.ZodPipe<z.ZodObject<{
+    code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+    message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    provider_reference: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    providerReference: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    reference: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    url: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+}, z.core.$strip>, z.ZodTransform<{
+    code: Status;
+    message: string;
+    orderNumber: string | null;
+    providerReference: string | null;
+    reference: string | null;
+    url: string | null;
+}, {
+    code: Status;
+    message: string;
+    orderNumber?: string | null | undefined;
+    provider_reference?: string | null | undefined;
+    providerReference?: string | null | undefined;
+    reference?: string | null | undefined;
+    url?: string | null | undefined;
+}>>;
+declare const CardResponseSchema: z.ZodObject<{
+    code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+    message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    url: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+}, z.core.$strip>;
+declare const TransactionSchema: z.ZodObject<{
+    amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
+    amountCustomer: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
+    channel: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    createdAt: z.ZodString;
+    currency: z.ZodEnum<{
+        USD: "USD";
+        CDF: "CDF";
+    }>;
+    orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    reference: z.ZodString;
+    status: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+}, z.core.$strip>;
+declare const CheckResponseSchema: z.ZodObject<{
+    code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+    message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    transaction: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
+        amountCustomer: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
+        channel: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+        createdAt: z.ZodString;
+        currency: z.ZodEnum<{
+            USD: "USD";
+            CDF: "CDF";
+        }>;
+        orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+        reference: z.ZodString;
+        status: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+    }, z.core.$strip>, z.ZodNull]>>>;
+}, z.core.$strip>;
+declare const PayoutResponseSchema: z.ZodObject<{
+    code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+    message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+}, z.core.$strip>;
+declare const MobileRequestSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    approveUrl: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    callbackUrl: z.ZodString;
+    cancelUrl: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    currency: z.ZodEnum<{
+        USD: "USD";
+        CDF: "CDF";
+    }>;
+    declineUrl: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    reference: z.ZodString;
+    phone: z.ZodString;
+}, z.core.$strip>;
+declare const CardRequestSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    approveUrl: z.ZodString;
+    callbackUrl: z.ZodString;
+    cancelUrl: z.ZodString;
+    currency: z.ZodEnum<{
+        USD: "USD";
+        CDF: "CDF";
+    }>;
+    declineUrl: z.ZodString;
+    description: z.ZodString;
+    homeUrl: z.ZodString;
+    reference: z.ZodString;
+}, z.core.$strip>;
+declare const PayoutRequestSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    callbackUrl: z.ZodString;
+    currency: z.ZodEnum<{
+        USD: "USD";
+        CDF: "CDF";
+    }>;
+    phone: z.ZodString;
+    reference: z.ZodString;
+}, z.core.$strip>;
+type MobileResponse = z.infer<typeof MobileResponseSchema>;
+type CardResponse = z.infer<typeof CardResponseSchema>;
+type Transaction = z.infer<typeof TransactionSchema>;
+type CheckResponse = z.infer<typeof CheckResponseSchema>;
+type PayoutResponse = z.infer<typeof PayoutResponseSchema>;
+type MobileRequest = z.infer<typeof MobileRequestSchema>;
+type CardRequest = z.infer<typeof CardRequestSchema>;
+type PayoutRequest = z.infer<typeof PayoutRequestSchema>;
+
+declare class Client {
+    private readonly credential;
+    private readonly env;
+    constructor(merchant: string, token: string, env?: EnvironmentType);
+    mobile(request: MobileRequest): Promise<MobileResponse>;
+    card(request: CardRequest): Promise<CardResponse>;
+    pay(request: MobileRequest): Promise<MobileResponse>;
+    pay(request: CardRequest): Promise<CardResponse>;
+    check(orderNumber: string): Promise<CheckResponse>;
+    payout(request: PayoutRequest): Promise<PayoutResponse>;
+    handleCallback(data: unknown): MobileResponse;
+    isSuccessful<T extends {
+        code: Status;
+    }>(response: T): response is T & {
+        code: Status.SUCCESS;
+    };
+    private requestJson;
+    private parseWith;
+}
+
+declare class NetworkException extends Error {
+    readonly status?: number;
+    readonly type?: string;
+    constructor(message: string, type?: string | null, status?: number | null);
+    static create(message: string, type: string, status: number): NetworkException;
+}
+declare class AccountException extends NetworkException {
+}
+declare class ClientException extends NetworkException {
+}
+declare class ServerException extends NetworkException {
+}
+
+export { AccountException, type CardRequest, CardRequestSchema, type CardResponse, CardResponseSchema, type CheckResponse, CheckResponseSchema, Client, ClientException, type Currency, CurrencySchema, Environment, type EnvironmentType, type MobileRequest, MobileRequestSchema, type MobileResponse, MobileResponseSchema, NetworkException, type PayoutRequest, PayoutRequestSchema, type PayoutResponse, PayoutResponseSchema, ServerException, Status, StatusSchema, type Transaction, TransactionSchema };

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+import * as z from 'zod';
+
+type EnvironmentType = "prod" | "dev";
+declare class Environment {
+    readonly value: EnvironmentType;
+    constructor(value: EnvironmentType);
+    getMobilePaymentUrl(): string;
+    getPayoutUrl(): string;
+    getCheckStatusUrl(orderNumber: string): string;
+    getCardPaymentUrl(): string;
+    private getBaseUrl;
+}
+
+declare enum Status {
+    SUCCESS = 0,// When the request is successfully processed
+    FAILURE = 1
+}
+declare const CurrencySchema: z.ZodEnum<{
+    USD: "USD";
+    CDF: "CDF";
+}>;
+type Currency = z.infer<typeof CurrencySchema>;
+declare const StatusSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+declare const MobileResponseSchema: z.ZodPipe<z.ZodObject<{
+    code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+    message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    provider_reference: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    providerReference: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    reference: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    url: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+}, z.core.$strip>, z.ZodTransform<{
+    code: Status;
+    message: string;
+    orderNumber: string | null;
+    providerReference: string | null;
+    reference: string | null;
+    url: string | null;
+}, {
+    code: Status;
+    message: string;
+    orderNumber?: string | null | undefined;
+    provider_reference?: string | null | undefined;
+    providerReference?: string | null | undefined;
+    reference?: string | null | undefined;
+    url?: string | null | undefined;
+}>>;
+declare const CardResponseSchema: z.ZodObject<{
+    code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+    message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    url: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+}, z.core.$strip>;
+declare const TransactionSchema: z.ZodObject<{
+    amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
+    amountCustomer: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
+    channel: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    createdAt: z.ZodString;
+    currency: z.ZodEnum<{
+        USD: "USD";
+        CDF: "CDF";
+    }>;
+    orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+    reference: z.ZodString;
+    status: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+}, z.core.$strip>;
+declare const CheckResponseSchema: z.ZodObject<{
+    code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+    message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    transaction: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
+        amountCustomer: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
+        channel: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+        createdAt: z.ZodString;
+        currency: z.ZodEnum<{
+            USD: "USD";
+            CDF: "CDF";
+        }>;
+        orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+        reference: z.ZodString;
+        status: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+    }, z.core.$strip>, z.ZodNull]>>>;
+}, z.core.$strip>;
+declare const PayoutResponseSchema: z.ZodObject<{
+    code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
+    message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+}, z.core.$strip>;
+declare const MobileRequestSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    approveUrl: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    callbackUrl: z.ZodString;
+    cancelUrl: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    currency: z.ZodEnum<{
+        USD: "USD";
+        CDF: "CDF";
+    }>;
+    declineUrl: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    reference: z.ZodString;
+    phone: z.ZodString;
+}, z.core.$strip>;
+declare const CardRequestSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    approveUrl: z.ZodString;
+    callbackUrl: z.ZodString;
+    cancelUrl: z.ZodString;
+    currency: z.ZodEnum<{
+        USD: "USD";
+        CDF: "CDF";
+    }>;
+    declineUrl: z.ZodString;
+    description: z.ZodString;
+    homeUrl: z.ZodString;
+    reference: z.ZodString;
+}, z.core.$strip>;
+declare const PayoutRequestSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    callbackUrl: z.ZodString;
+    currency: z.ZodEnum<{
+        USD: "USD";
+        CDF: "CDF";
+    }>;
+    phone: z.ZodString;
+    reference: z.ZodString;
+}, z.core.$strip>;
+type MobileResponse = z.infer<typeof MobileResponseSchema>;
+type CardResponse = z.infer<typeof CardResponseSchema>;
+type Transaction = z.infer<typeof TransactionSchema>;
+type CheckResponse = z.infer<typeof CheckResponseSchema>;
+type PayoutResponse = z.infer<typeof PayoutResponseSchema>;
+type MobileRequest = z.infer<typeof MobileRequestSchema>;
+type CardRequest = z.infer<typeof CardRequestSchema>;
+type PayoutRequest = z.infer<typeof PayoutRequestSchema>;
+
+declare class Client {
+    private readonly credential;
+    private readonly env;
+    constructor(merchant: string, token: string, env?: EnvironmentType);
+    mobile(request: MobileRequest): Promise<MobileResponse>;
+    card(request: CardRequest): Promise<CardResponse>;
+    pay(request: MobileRequest): Promise<MobileResponse>;
+    pay(request: CardRequest): Promise<CardResponse>;
+    check(orderNumber: string): Promise<CheckResponse>;
+    payout(request: PayoutRequest): Promise<PayoutResponse>;
+    handleCallback(data: unknown): MobileResponse;
+    isSuccessful<T extends {
+        code: Status;
+    }>(response: T): response is T & {
+        code: Status.SUCCESS;
+    };
+    private requestJson;
+    private parseWith;
+}
+
+declare class NetworkException extends Error {
+    readonly status?: number;
+    readonly type?: string;
+    constructor(message: string, type?: string | null, status?: number | null);
+    static create(message: string, type: string, status: number): NetworkException;
+}
+declare class AccountException extends NetworkException {
+}
+declare class ClientException extends NetworkException {
+}
+declare class ServerException extends NetworkException {
+}
+
+export { AccountException, type CardRequest, CardRequestSchema, type CardResponse, CardResponseSchema, type CheckResponse, CheckResponseSchema, Client, ClientException, type Currency, CurrencySchema, Environment, type EnvironmentType, type MobileRequest, MobileRequestSchema, type MobileResponse, MobileResponseSchema, NetworkException, type PayoutRequest, PayoutRequestSchema, type PayoutResponse, PayoutResponseSchema, ServerException, Status, StatusSchema, type Transaction, TransactionSchema };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var J=Object.create;var R=Object.defineProperty;var L=Object.getOwnPropertyDescriptor;var W=Object.getOwnPropertyNames;var D=Object.getPrototypeOf,F=Object.prototype.hasOwnProperty;var G=(r,t)=>{for(var n in t)R(r,n,{get:t[n],enumerable:!0})},j=(r,t,n,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of W(t))!F.call(r,a)&&a!==n&&R(r,a,{get:()=>t[a],enumerable:!(o=L(t,a))||o.enumerable});return r};var H=(r,t,n)=>(n=r!=null?J(D(r)):{},j(t||!r||!r.__esModule?R(n,"default",{value:r,enumerable:!0}):n,r)),Z=r=>j(R({},"__esModule",{value:!0}),r);var K={};G(K,{AccountException:()=>h,CardRequestSchema:()=>U,CardResponseSchema:()=>C,CheckResponseSchema:()=>x,Client:()=>q,ClientException:()=>d,CurrencySchema:()=>y,Environment:()=>m,MobileRequestSchema:()=>w,MobileResponseSchema:()=>f,NetworkException:()=>i,PayoutRequestSchema:()=>k,PayoutResponseSchema:()=>P,ServerException:()=>S,Status:()=>z,StatusSchema:()=>l,TransactionSchema:()=>v});module.exports=Z(K);var m=class{constructor(t){this.value=t}value;getMobilePaymentUrl(){return`${this.getBaseUrl()}/paymentService`}getPayoutUrl(){return`${this.getBaseUrl()}/merchantPayOutService`}getCheckStatusUrl(t){return`${this.getBaseUrl()}/check/${encodeURIComponent(t)}`}getCardPaymentUrl(){return this.value==="prod"?"https://cardpayment.flexpay.cd/v1.1/pay":"https://beta-cardpayment.flexpay.cd/v1.1/pay"}getBaseUrl(){return this.value==="prod"?"https://backend.flexpay.cd/api/rest/v1":"https://beta-backend.flexpay.cd/api/rest/v1"}};var i=class r extends Error{status;type;constructor(t,n,o){let a=o!=null?`${t} (HTTP ${o}/${n??"unknown"})`:t;super(a),this.name=this.constructor.name,this.status=o??void 0,this.type=n??void 0,Object.setPrototypeOf(this,new.target.prototype)}static create(t,n,o){let a=t.trim()===""?"No message was provided":t;return o===401||o===429?new h(a,n,o):o>=400&&o<=499?new d(a,n,o):o>=500&&o<=599?new S(a,n,o):new r(a,n,o)}},h=class extends i{},d=class extends i{},S=class extends i{};var e=H(require("zod")),z=(n=>(n[n.SUCCESS=0]="SUCCESS",n[n.FAILURE=1]="FAILURE",n))(z||{});var y=e.enum(["USD","CDF"]),O=e.object({merchant:e.string().min(1,"Merchant cannot be empty"),token:e.string().min(1,"The authorization token cannot be empty")}),l=e.union([e.literal(0),e.literal(1),e.literal("0"),e.literal("1")]).transform(r=>Number(r)),N=e.union([e.number().finite(),e.string().trim().min(1).transform(r=>Number(r)).pipe(e.number().finite())]),c=e.union([e.string(),e.null()]).optional(),f=e.object({code:l,message:e.string().optional().default(""),orderNumber:c,provider_reference:c,providerReference:c,reference:c,url:c}).transform(r=>({code:r.code,message:r.message??"",orderNumber:r.orderNumber??null,providerReference:r.providerReference??r.provider_reference??null,reference:r.reference??null,url:r.url??null})),C=e.object({code:l,message:e.string().optional().default(""),orderNumber:c,url:c}),v=e.object({amount:N,amountCustomer:N,channel:c,createdAt:e.string(),currency:y,orderNumber:c,reference:e.string(),status:l}),x=e.object({code:l,message:e.string().optional().default(""),transaction:e.union([v,e.null()]).optional().default(null)}),P=e.object({code:l,message:e.string().optional().default(""),orderNumber:c}),p=e.string().min(1),_=e.object({amount:e.number().gt(0,"The transaction amount should be greater than 0"),approveUrl:p.optional().nullable(),callbackUrl:p,cancelUrl:p.optional().nullable(),currency:y,declineUrl:p.optional().nullable(),description:e.string().optional().nullable(),reference:e.string().min(1,"The transaction reference is mandatory")}),w=_.extend({phone:e.string().length(12,"The phone number should be 12 characters long, eg: 243123456789")}),U=e.object({amount:e.number().gt(0),approveUrl:p,callbackUrl:p,cancelUrl:p,currency:y,declineUrl:p,description:e.string().min(1,"The description must be provided"),homeUrl:p,reference:e.string().min(1).max(25,"The reference must be between 1 and 25 characters")}),k=e.object({amount:e.number().gt(0),callbackUrl:p,currency:y,phone:e.string().length(12,"The phone number should be 12 characters long, eg: 243123456789"),reference:e.string().min(1)});var q=class{credential;env;constructor(t,n,o="dev"){this.credential=O.parse({merchant:t,token:n}),this.env=new m(o)}async mobile(t){let n={...w.parse(t),merchant:this.credential.merchant,type:1},o=await this.requestJson("POST",this.env.getMobilePaymentUrl(),n);return this.parseWith(f,o)}async card(t){let n={...U.parse(t),authorization:`Bearer ${this.credential.token}`,merchant:this.credential.merchant},o=await this.requestJson("POST",this.env.getCardPaymentUrl(),n);return this.parseWith(C,o)}async pay(t){if("phone"in t&&typeof t.phone=="string")return this.mobile(t);if("homeUrl"in t&&typeof t.homeUrl=="string")return this.card(t);throw new Error("Unsupported request shape")}async check(t){let n=await this.requestJson("GET",this.env.getCheckStatusUrl(t));return this.parseWith(x,n)}async payout(t){let n={...k.parse(t),merchant:this.credential.merchant,type:1},o=await this.requestJson("POST",this.env.getPayoutUrl(),n);return this.parseWith(P,o)}handleCallback(t){return this.parseWith(f,t)}isSuccessful(t){return t.code===0}async requestJson(t,n,o){let a={Accept:"application/json",Authorization:`Bearer ${this.credential.token}`,"Content-Type":"application/json"},T=3,B=500;for(let b=0;b<=T;b++)try{let s=await fetch(n,{body:t==="POST"?JSON.stringify(o??{}):void 0,headers:a,method:t}),M=(s.headers.get("content-type")||"").includes("application/json"),u={};if(M)try{u=await s.json()}catch{u={}}if(!s.ok){let g=typeof u=="object"&&u!==null?u:{},A=typeof g.message=="string"?g.message:"",$=typeof g.error=="string"?g.error:"unknown",I=s.status;throw i.create(A,$,I)}return u}catch(s){if(s instanceof h||s instanceof d||s instanceof i&&typeof s.status=="number"&&s.status>=400&&s.status<500)throw s;if(b<T){let E=B*2**b;await new Promise(M=>setTimeout(M,E));continue}throw s instanceof i?s:new i(s instanceof Error?s.message:"Network error")}throw new i("Unexpected request flow")}parseWith(t,n){return t.parse(n)}};0&&(module.exports={AccountException,CardRequestSchema,CardResponseSchema,CheckResponseSchema,Client,ClientException,CurrencySchema,Environment,MobileRequestSchema,MobileResponseSchema,NetworkException,PayoutRequestSchema,PayoutResponseSchema,ServerException,Status,StatusSchema,TransactionSchema});

package/dist/index.mjs

@@ -0,0 +1 @@
+var m=class{constructor(t){this.value=t}value;getMobilePaymentUrl(){return`${this.getBaseUrl()}/paymentService`}getPayoutUrl(){return`${this.getBaseUrl()}/merchantPayOutService`}getCheckStatusUrl(t){return`${this.getBaseUrl()}/check/${encodeURIComponent(t)}`}getCardPaymentUrl(){return this.value==="prod"?"https://cardpayment.flexpay.cd/v1.1/pay":"https://beta-cardpayment.flexpay.cd/v1.1/pay"}getBaseUrl(){return this.value==="prod"?"https://backend.flexpay.cd/api/rest/v1":"https://beta-backend.flexpay.cd/api/rest/v1"}};var a=class o extends Error{status;type;constructor(t,n,r){let p=r!=null?`${t} (HTTP ${r}/${n??"unknown"})`:t;super(p),this.name=this.constructor.name,this.status=r??void 0,this.type=n??void 0,Object.setPrototypeOf(this,new.target.prototype)}static create(t,n,r){let p=t.trim()===""?"No message was provided":t;return r===401||r===429?new h(p,n,r):r>=400&&r<=499?new d(p,n,r):r>=500&&r<=599?new S(p,n,r):new o(p,n,r)}},h=class extends a{},d=class extends a{},S=class extends a{};import*as e from"zod";var z=(n=>(n[n.SUCCESS=0]="SUCCESS",n[n.FAILURE=1]="FAILURE",n))(z||{});var y=e.enum(["USD","CDF"]),E=e.object({merchant:e.string().min(1,"Merchant cannot be empty"),token:e.string().min(1,"The authorization token cannot be empty")}),u=e.union([e.literal(0),e.literal(1),e.literal("0"),e.literal("1")]).transform(o=>Number(o)),T=e.union([e.number().finite(),e.string().trim().min(1).transform(o=>Number(o)).pipe(e.number().finite())]),i=e.union([e.string(),e.null()]).optional(),g=e.object({code:u,message:e.string().optional().default(""),orderNumber:i,provider_reference:i,providerReference:i,reference:i,url:i}).transform(o=>({code:o.code,message:o.message??"",orderNumber:o.orderNumber??null,providerReference:o.providerReference??o.provider_reference??null,reference:o.reference??null,url:o.url??null})),C=e.object({code:u,message:e.string().optional().default(""),orderNumber:i,url:i}),j=e.object({amount:T,amountCustomer:T,channel:i,createdAt:e.string(),currency:y,orderNumber:i,reference:e.string(),status:u}),x=e.object({code:u,message:e.string().optional().default(""),transaction:e.union([j,e.null()]).optional().default(null)}),P=e.object({code:u,message:e.string().optional().default(""),orderNumber:i}),c=e.string().min(1),$=e.object({amount:e.number().gt(0,"The transaction amount should be greater than 0"),approveUrl:c.optional().nullable(),callbackUrl:c,cancelUrl:c.optional().nullable(),currency:y,declineUrl:c.optional().nullable(),description:e.string().optional().nullable(),reference:e.string().min(1,"The transaction reference is mandatory")}),w=$.extend({phone:e.string().length(12,"The phone number should be 12 characters long, eg: 243123456789")}),U=e.object({amount:e.number().gt(0),approveUrl:c,callbackUrl:c,cancelUrl:c,currency:y,declineUrl:c,description:e.string().min(1,"The description must be provided"),homeUrl:c,reference:e.string().min(1).max(25,"The reference must be between 1 and 25 characters")}),k=e.object({amount:e.number().gt(0),callbackUrl:c,currency:y,phone:e.string().length(12,"The phone number should be 12 characters long, eg: 243123456789"),reference:e.string().min(1)});var q=class{credential;env;constructor(t,n,r="dev"){this.credential=E.parse({merchant:t,token:n}),this.env=new m(r)}async mobile(t){let n={...w.parse(t),merchant:this.credential.merchant,type:1},r=await this.requestJson("POST",this.env.getMobilePaymentUrl(),n);return this.parseWith(g,r)}async card(t){let n={...U.parse(t),authorization:`Bearer ${this.credential.token}`,merchant:this.credential.merchant},r=await this.requestJson("POST",this.env.getCardPaymentUrl(),n);return this.parseWith(C,r)}async pay(t){if("phone"in t&&typeof t.phone=="string")return this.mobile(t);if("homeUrl"in t&&typeof t.homeUrl=="string")return this.card(t);throw new Error("Unsupported request shape")}async check(t){let n=await this.requestJson("GET",this.env.getCheckStatusUrl(t));return this.parseWith(x,n)}async payout(t){let n={...k.parse(t),merchant:this.credential.merchant,type:1},r=await this.requestJson("POST",this.env.getPayoutUrl(),n);return this.parseWith(P,r)}handleCallback(t){return this.parseWith(g,t)}isSuccessful(t){return t.code===0}async requestJson(t,n,r){let p={Accept:"application/json",Authorization:`Bearer ${this.credential.token}`,"Content-Type":"application/json"},M=3,N=500;for(let f=0;f<=M;f++)try{let s=await fetch(n,{body:t==="POST"?JSON.stringify(r??{}):void 0,headers:p,method:t}),R=(s.headers.get("content-type")||"").includes("application/json"),l={};if(R)try{l=await s.json()}catch{l={}}if(!s.ok){let b=typeof l=="object"&&l!==null?l:{},O=typeof b.message=="string"?b.message:"",B=typeof b.error=="string"?b.error:"unknown",A=s.status;throw a.create(O,B,A)}return l}catch(s){if(s instanceof h||s instanceof d||s instanceof a&&typeof s.status=="number"&&s.status>=400&&s.status<500)throw s;if(f<M){let v=N*2**f;await new Promise(R=>setTimeout(R,v));continue}throw s instanceof a?s:new a(s instanceof Error?s.message:"Network error")}throw new a("Unexpected request flow")}parseWith(t,n){return t.parse(n)}};export{h as AccountException,U as CardRequestSchema,C as CardResponseSchema,x as CheckResponseSchema,q as Client,d as ClientException,y as CurrencySchema,m as Environment,w as MobileRequestSchema,g as MobileResponseSchema,a as NetworkException,k as PayoutRequestSchema,P as PayoutResponseSchema,S as ServerException,z as Status,u as StatusSchema,j as TransactionSchema};

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@ngandu-dev/flexpay",
+  "version": "2.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.mjs",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup --minify",
+    "check:package": "publint --strict && attw --pack .",
+    "dev": "tsup --watch",
+    "format": "biome check --write .",
+    "lint": "biome check .",
+    "prepack": "bun run build",
+    "prepare": "husky",
+    "quality": "bun run lint && bun run typecheck && bun run test && bun run build && bun run check:package",
+    "release": "npm publish --access public",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "version": "changeset version"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ngandu-dev/flexpay.git"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "keywords": [
+    "api",
+    "payment-gateway",
+    "mobile-money"
+  ],
+  "author": "Bernard Ngandu <bernard@ngandu.dev>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ngandu-dev/flexpay/issues"
+  },
+  "homepage": "https://github.com/ngandu-dev/flexpay#readme",
+  "description": "FlexPay API TypeScript client",
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@biomejs/biome": "^2.5.9",
+    "@changesets/cli": "^3.0.1",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@types/node": "^26.2.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "husky": "^9.1.7",
+    "publint": "^0.3.24",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "overrides": {
+    "ajv": "8.18.0",
+    "esbuild": "0.28.1",
+    "fast-uri": "3.1.5",
+    "js-yaml": "4.3.1",
+    "nanoid": "3.3.18",
+    "picomatch": "4.0.5",
+    "postcss": "8.5.26",
+    "rollup": "4.62.4",
+    "vite": "8.2.1"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "bun@1.3.14",
+  "sideEffects": false
+}