monime-package 1.0.5 → 1.0.7

package/README.md

@@ -5,7 +5,7 @@ Official, lightweight TypeScript SDK for Monime. It provides a typed client for
 
 ![npm version](https://img.shields.io/npm/v/monime-package.svg)
 ![npm downloads](https://img.shields.io/npm/dm/monime-package.svg)
-![TypeScript](https://img.shields.io/badge/TypeScript-4.9-blue.svg)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)
 ![Node.js](https://img.shields.io/badge/Node.js-%3E=14-green.svg)
 ![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)
 
@@ -19,19 +19,23 @@ Package: `monime-package`
 - **[Installation](#installation)**
 - **[Environment Variables](#environment-variables)**
 - **[Quick Start](#quick-start)**
-- **[Client API](#client-api)**
+- **[API Reference](#api-reference)**
+  - **[Financial Accounts](#financial-accounts)**
+  - **[Internal Transfers](#internal-transfers)**
+  - **[Payment Codes](#payment-codes)**
+  - **[Payouts](#payouts)**
+  - **[Financial Transactions](#financial-transactions)**
+  - **[Checkout Sessions](#checkout-sessions)**
 - **[Configuration](#configuration)**
-- **[Examples](#examples)**
+- **[Complete Examples](#complete-examples)**
+- **[TypeScript Types](#typescript-types)**
 - **[Idempotency](#idempotency)**
 - **[Pagination](#pagination)**
 - **[Migration from Old Helpers](#migration-from-old-helpers)**
-- **[Folder Structure](#folder-structure)**
 - **[Error Handling](#error-handling)**
 - **[Security](#security)**
-- **[Versioning](#versioning)**
-- **[Support](#support)**
-- **[Return Types (Appendix)](#return-types-appendix)**
 - **[Contributing](#contributing)**
+- **[Support](#support)**
 - **[License](#license)**
 
 ---
@@ -42,6 +46,10 @@ Package: `monime-package`
 - **Predictable** return shape: `{ success, data?, error? }`
 - **Client-based** auth: set credentials once per instance
 - **Minimal deps** (`axios`) and small surface area
+- **Full API coverage** for all Monime endpoints
+- **Mobile Money support** (Africell, Orange, etc.)
+- **Bank transfers** and digital wallet integrations
+- **Checkout sessions** for hosted payment pages
 
 ---
 
@@ -95,7 +103,7 @@ import { createClient, type DestinationOption } from "monime-package";
 
 ---
 
-## Client API
+## API Reference
 
 All methods return the same envelope:
 
@@ -107,33 +115,84 @@ type Result<T> = {
 };
 ```
 
-The client exposes namespaced APIs under `client.<module>`:
+The client exposes namespaced APIs under `client.<module>`. Below is the complete API reference:
+
+### Financial Accounts
 
-### financialAccount
+Manage digital wallets and financial accounts.
 
 ```ts
+// Create a new financial account
 client.financialAccount.create(name: string): Promise<Result<CreateFinancialAccount>>
+
+// Get account details by ID
 client.financialAccount.get(financialAccountId: string): Promise<Result<GetFinancialAccount>>
+
+// List all financial accounts
 client.financialAccount.getAll(): Promise<Result<AllFinancialAccount>>
 ```
 
-### internalTransfer
+**Parameters:**
+- `name`: Account name (required)
+- `financialAccountId`: Unique account identifier (required)
 
+**Example:**
 ```ts
+// Create account
+const account = await client.financialAccount.create("My Wallet");
+if (account.success) {
+  console.log("Account ID:", account.data.result.id);
+  console.log("Balance:", account.data.result.balance.available.value);
+}
+
+// Get account details
+const details = await client.financialAccount.get("fa-123456");
+```
+
+### Internal Transfers
+
+Transfer funds between your financial accounts.
+
+```ts
+// Create internal transfer
 client.internalTransfer.create(
   sourceAccount: string,
   destinationAccount: string,
   amount: number,
 ): Promise<Result<CreateInternalTransfer>>
 
+// Get transfer details
 client.internalTransfer.get(internalTransferId: string): Promise<Result<InternalTransfer>>
+
+// List all transfers
 client.internalTransfer.getAll(): Promise<Result<AllInternalTransfers>>
+
+// Cancel/delete a transfer
 client.internalTransfer.delete(internalTransferId: string): Promise<{ success: boolean; error?: Error }>
 ```
 
-### paymentCode
+**Parameters:**
+- `sourceAccount`: Source financial account ID (required)
+- `destinationAccount`: Destination financial account ID (required)
+- `amount`: Transfer amount in SLE (required, must be > 0)
+- `internalTransferId`: Transfer ID for get/delete operations (required)
+
+**Example:**
+```ts
+// Transfer 1000 SLE between accounts
+const transfer = await client.internalTransfer.create("fa-source", "fa-dest", 1000);
+if (transfer.success) {
+  console.log("Transfer ID:", transfer.data.result.id);
+  console.log("Status:", transfer.data.result.status);
+}
+```
+
+### Payment Codes
+
+Generate USSD payment codes for mobile money transactions.
 
 ```ts
+// Create payment code
 client.paymentCode.create(
   paymentName: string,
   amount: number,
@@ -142,34 +201,182 @@ client.paymentCode.create(
   phoneNumber: string,
 ): Promise<Result<CreatePaymentCode>>
 
-client.paymentCode.delete(paymentCodeId: string): Promise<{ success: boolean; error?: Error }>
-client.paymentCode.getAll(): Promise<Result<GetAllPaymentCode>>
+// Get payment code details
 client.paymentCode.get(paymentCodeId: string): Promise<Result<GetOne>>
+
+// List all payment codes
+client.paymentCode.getAll(): Promise<Result<GetAllPaymentCode>>
+
+// Delete payment code
+client.paymentCode.delete(paymentCodeId: string): Promise<{ success: boolean; error?: Error }>
 ```
 
-### payout
+**Parameters:**
+- `paymentName`: Description for the payment (required)
+- `amount`: Payment amount in SLE (required, must be > 0)
+- `financialAccount`: Target financial account ID (required)
+- `username`: Customer name (required)
+- `phoneNumber`: Authorized phone number (required)
+- `paymentCodeId`: Payment code ID for get/delete operations (required)
 
+**Example:**
 ```ts
-import type { DestinationOption } from "monime-package";
+// Create USSD payment code
+const paymentCode = await client.paymentCode.create(
+  "Order #12345",
+  5000, // 50.00 SLE
+  "fa-123456",
+  "John Doe",
+  "0771234567"
+);
+
+if (paymentCode.success) {
+  console.log("USSD Code:", paymentCode.data.result.ussdCode);
+  console.log("Expires at:", paymentCode.data.result.expireTime);
+}
+```
 
+### Payouts
+
+Send money to mobile money providers, banks, or wallets.
+
+```ts
+// Create payout
 client.payout.create(
   amount: number,
   destination: DestinationOption,
   sourceAccount: string,
 ): Promise<Result<CreatePayout>>
 
+// List all payouts
 client.payout.get(): Promise<Result<GetAll>>
+
+// Get specific payout
 client.payout.getOne(payoutId: string): Promise<Result<GetOnePayout>>
+
+// Cancel payout
 client.payout.delete(payoutId: string): Promise<{ success: boolean; error?: Error }>
 ```
 
-### financialTransaction
+**Destination Types:**
+```ts
+type DestinationOption = 
+  | { type: "momo"; providerId: "m17" | "m18"; phoneNumber: string }
+  | { type: "bank"; providerId: "b01" | "b02" | "b03"; accountNumber: string }
+  | { type: "wallet"; providerId: "w01" | "w02"; walletId: string };
+```
+
+**Parameters:**
+- `amount`: Payout amount in SLE (required, must be > 0)
+- `destination`: Payout destination (required)
+- `sourceAccount`: Source financial account ID (required)
+- `payoutId`: Payout ID for get/delete operations (required)
+
+**Example:**
+```ts
+// Mobile money payout
+const mobileMoneyPayout = await client.payout.create(
+  10000, // 100.00 SLE
+  { type: "momo", providerId: "m17", phoneNumber: "0771234567" },
+  "fa-123456"
+);
+
+// Bank transfer payout
+const bankPayout = await client.payout.create(
+  50000, // 500.00 SLE
+  { type: "bank", providerId: "b01", accountNumber: "1234567890" },
+  "fa-123456"
+);
+```
+
+### Financial Transactions
+
+Query transaction history and details.
 
 ```ts
+// Get transaction details
 client.financialTransaction.get(transactionId: string): Promise<Result<GetTransaction>>
+
+// List all transactions
 client.financialTransaction.getAll(): Promise<Result<AllTransaction>>
 ```
 
+**Parameters:**
+- `transactionId`: Transaction ID (required)
+
+**Example:**
+```ts
+// Get all transactions
+const transactions = await client.financialTransaction.getAll();
+if (transactions.success) {
+  transactions.data.result.forEach(tx => {
+    console.log(`${tx.type}: ${tx.amount.value} ${tx.amount.currency}`);
+  });
+}
+```
+
+### Checkout Sessions
+
+Create hosted payment pages for seamless customer payments.
+
+```ts
+// Create checkout session
+client.checkoutSession.create(
+  name: string,
+  amount: number,
+  quantity: number,
+  successUrl: string,
+  cancelUrl: string,
+  description?: string,
+  financialAccountId?: string,
+  primaryColor?: string,
+  images?: string[],
+): Promise<Result<CreateCheckout>>
+
+// List all checkout sessions
+client.checkoutSession.get(): Promise<Result<AllCheckout>>
+
+// Get specific checkout session
+client.checkoutSession.getOne(checkoutId: string): Promise<Result<OneCheckout>>
+
+// Delete checkout session
+client.checkoutSession.delete(checkoutId: string): Promise<{ success: boolean; error?: Error }>
+```
+
+**Parameters:**
+- `name`: Product/service name (required)
+- `amount`: Price per item in SLE (required)
+- `quantity`: Number of items (required)
+- `successUrl`: Redirect URL after successful payment (required)
+- `cancelUrl`: Redirect URL when payment is cancelled (required)
+- `description`: Product description (optional)
+- `financialAccountId`: Target account for payments (optional)
+- `primaryColor`: Brand color in hex format (optional)
+- `images`: Product image URLs (optional)
+- `checkoutId`: Checkout session ID for get/delete operations (required)
+
+**Example:**
+```ts
+// Create checkout for e-commerce
+const checkout = await client.checkoutSession.create(
+  "Premium Subscription",
+  2500, // 25.00 SLE per month
+  1,
+  "https://myapp.com/success",
+  "https://myapp.com/cancel",
+  "Monthly premium subscription",
+  "fa-123456",
+  "#3B82F6", // Blue color
+  ["https://myapp.com/images/premium.jpg"]
+);
+
+if (checkout.success) {
+  // Redirect customer to checkout page
+  console.log("Checkout URL:", checkout.data.result.redirectUrl);
+  console.log("Order Number:", checkout.data.result.orderNumber);
+}
+```
+
 ---
 
 ## Configuration
@@ -188,93 +395,206 @@ type ClientOptions = {
 
 ---
 
-## Examples
+## Complete Examples
 
-### Create a financial account
+Here are comprehensive examples showing real-world usage patterns:
 
-```ts
-const account = await client.financialAccount.create("App Wallet");
-if (!account.success) throw account.error;
-console.log(account.data);
-```
-
-### Get account details
+### Complete E-commerce Integration
 
 ```ts
-const details = await client.financialAccount.get(account.data!.result.id);
-console.log(details);
-```
-
-### List financial accounts
+import { createClient, type DestinationOption } from "monime-package";
 
-```ts
-const all = await client.financialAccount.getAll();
-console.log(all.data?.result.length);
-```
+// Initialize client
+const client = createClient({
+  monimeSpaceId: process.env.MONIME_SPACE_ID!,
+  accessToken: process.env.MONIME_ACCESS_TOKEN!,
+});
 
-### Internal transfer
+// Create business account
+const businessAccount = await client.financialAccount.create("E-commerce Store");
+if (!businessAccount.success) {
+  throw new Error(`Failed to create account: ${businessAccount.error?.message}`);
+}
+
+const accountId = businessAccount.data!.result.id;
+console.log(`Created account: ${accountId}`);
+console.log(`Balance: ${businessAccount.data!.result.balance.available.value} SLE`);
+
+// Create checkout session for customer
+const checkout = await client.checkoutSession.create(
+  "Digital Camera",
+  45000, // 450.00 SLE
+  1,
+  "https://store.com/success",
+  "https://store.com/cancel",
+  "Professional DSLR Camera with lens kit",
+  accountId,
+  "#2563EB", // Brand blue
+  ["https://store.com/camera.jpg"]
+);
 
-```ts
-const transfer = await client.internalTransfer.create("acc-src", "acc-dest", 5000);
-if (!transfer.success) console.error(transfer.error);
-else console.log(transfer.data);
+if (checkout.success) {
+  console.log(`Checkout created: ${checkout.data!.result.id}`);
+  console.log(`Payment URL: ${checkout.data!.result.redirectUrl}`);
+  console.log(`Order: ${checkout.data!.result.orderNumber}`);
+}
 ```
 
-### Payment code lifecycle
+### Payment Processing Workflow
 
 ```ts
-// create
-const code = await client.paymentCode.create(
-  "Order-001",
-  5,
-  "financial-account-id",
-  "Alice",
-  "0771234567",
+// 1. Generate USSD payment code for customer
+const paymentCode = await client.paymentCode.create(
+  "Invoice #INV-2024-001",
+  15000, // 150.00 SLE
+  accountId,
+  "Customer Name",
+  "0771234567"
 );
-if (!code.success) console.error(code.error);
-else console.log("Payment code:", code.data);
 
-// get
-const one = await client.paymentCode.get("payment-code-id");
-
-// list
-const codes = await client.paymentCode.getAll();
+if (paymentCode.success) {
+  console.log(`USSD Code: ${paymentCode.data!.result.ussdCode}`);
+  console.log(`Expires: ${paymentCode.data!.result.expireTime}`);
+  
+  // Send USSD code to customer via SMS/email
+  await sendToCustomer(paymentCode.data!.result.ussdCode);
+}
+
+// 2. Monitor payment status
+const checkPaymentStatus = async (codeId: string) => {
+  const status = await client.paymentCode.get(codeId);
+  if (status.success) {
+    console.log(`Payment Status: ${status.data!.result.status}`);
+    return status.data!.result.status === 'completed';
+  }
+  return false;
+};
 
-// delete
-const deleted = await client.paymentCode.delete("payment-code-id");
-console.log(deleted.success);
+// 3. Process payout to supplier after payment received
+const paySupplier = async () => {
+  const payout = await client.payout.create(
+    8000, // 80.00 SLE to supplier
+    {
+      type: "momo",
+      providerId: "m17",
+      phoneNumber: "0779876543"
+    },
+    accountId
+  );
+  
+  if (payout.success) {
+    console.log(`Payout ID: ${payout.data!.result.id}`);
+    console.log(`Status: ${payout.data!.result.status}`);
+    console.log(`Fees: ${payout.data!.result.fees.map(f => `${f.code}: ${f.amount.value}`)}`);
+  }
+};
 ```
 
-### Payouts
+### Multi-Account Management
 
 ```ts
-import type { DestinationOption } from "monime-package";
-
-const destination: DestinationOption = {
-  type: "momo",
-  providerId: "m17", // eg. provider code
-  phoneNumber: "0771234567",
-};
-
-const payout = await client.payout.create(1000, destination, "source-account-id");
-if (!payout.success) console.error(payout.error);
-else console.log("Payout:", payout.data);
-
-// list all payouts
-const payouts = await client.payout.get();
+// Create multiple accounts for different purposes
+const accounts = await Promise.all([
+  client.financialAccount.create("Sales Revenue"),
+  client.financialAccount.create("Operating Expenses"),
+  client.financialAccount.create("Tax Reserve"),
+]);
+
+// Check if all accounts were created successfully
+if (accounts.every(acc => acc.success)) {
+  const [salesAccount, expensesAccount, taxAccount] = accounts.map(acc => acc.data!.result.id);
+  
+  // Distribute revenue: 70% operations, 30% tax reserve
+  const revenue = 100000; // 1000.00 SLE
+  
+  const transfers = await Promise.all([
+    client.internalTransfer.create(salesAccount, expensesAccount, revenue * 0.7),
+    client.internalTransfer.create(salesAccount, taxAccount, revenue * 0.3),
+  ]);
+  
+  transfers.forEach((transfer, index) => {
+    const purpose = index === 0 ? 'operations' : 'tax reserve';
+    if (transfer.success) {
+      console.log(`${purpose} transfer: ${transfer.data!.result.id}`);
+    }
+  });
+}
+```
 
-// get one
-const single = await client.payout.getOne("payout-id");
+### Transaction Monitoring & Reporting
 
-// delete
-const removed = await client.payout.delete("payout-id");
+```ts
+// Get all transactions for reporting
+const transactions = await client.financialTransaction.getAll();
+
+if (transactions.success) {
+  const txs = transactions.data!.result;
+  
+  // Group transactions by type
+  const summary = txs.reduce((acc, tx) => {
+    acc[tx.type] = (acc[tx.type] || 0) + tx.amount.value;
+    return acc;
+  }, {} as Record<string, number>);
+  
+  console.log('Transaction Summary:', summary);
+  
+  // Find large transactions (> 50,000 SLE)
+  const largeTransactions = txs.filter(tx => Math.abs(tx.amount.value) > 50000);
+  console.log(`Large transactions: ${largeTransactions.length}`);
+  
+  // Check account balances after transactions
+  const accountIds = [...new Set(txs.map(tx => tx.financialAccount.id))];
+  
+  for (const accountId of accountIds) {
+    const account = await client.financialAccount.get(accountId);
+    if (account.success) {
+      console.log(`Account ${accountId}: ${account.data!.result.balance.available.value} SLE`);
+    }
+  }
+}
 ```
 
-### Financial transactions
+### Error Handling Best Practices
 
 ```ts
-const tx = await client.financialTransaction.get("transaction-id");
-const txs = await client.financialTransaction.getAll();
+// Robust error handling with retries
+const createTransferWithRetry = async (
+  sourceAccount: string,
+  destinationAccount: string,
+  amount: number,
+  maxRetries = 3
+) => {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const transfer = await client.internalTransfer.create(sourceAccount, destinationAccount, amount);
+    
+    if (transfer.success) {
+      return transfer;
+    }
+    
+    // Log the error
+    console.error(`Transfer attempt ${attempt} failed:`, transfer.error?.message);
+    
+    // Don't retry on validation errors
+    if (transfer.error?.message?.includes('validation')) {
+      throw transfer.error;
+    }
+    
+    // Wait before retrying (exponential backoff)
+    if (attempt < maxRetries) {
+      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
+    }
+  }
+  
+  throw new Error(`Transfer failed after ${maxRetries} attempts`);
+};
+
+// Usage
+try {
+  const transfer = await createTransferWithRetry("fa-source", "fa-dest", 10000);
+  console.log("Transfer successful:", transfer.data!.result.id);
+} catch (error) {
+  console.error("Transfer failed permanently:", error.message);
+}
 ```
 
 ---
@@ -309,38 +629,6 @@ await client.financialAccount.create("name");
 
 ---
 
-## Folder Structure
-
-```
-.
-├── LICENSE
-├── README.md
-├── package.json
-├── tsconfig.json
-├── tsup.config.ts
-├── src
-│   ├── index.ts               # entry point (exports createClient, types)
-│   ├── client.ts              # MonimeClient with namespaced modules
-│   └── modules/
-│       ├── financialAccount/
-│       │   ├── financialAccount.ts
-│       │   └── index.ts
-│       ├── financialTransaction/
-│       │   ├── financialTransaction.ts
-│       │   └── index.ts
-│       ├── internalTransfer/
-│       │   ├── internalTransfer.ts
-│       │   └── index.ts
-│       ├── paymentCode/
-│       │   ├── paymentCode.ts
-│       │   └── index.ts
-│       ├── payout/
-│       │   ├── payout.ts
-│       │   └── index.ts
-│       └── types.ts
-```
-
----
 
 ## Error Handling
 
@@ -368,67 +656,301 @@ This project follows semantic versioning (SemVer). See releases for notable chan
 - File issues and feature requests at the repository: `https://github.com/Walon-Foundation/monime-package/issues`.
 - For production incidents, rotate credentials if you suspect exposure.
 
----
-
-## Return Types (Appendix)
+## TypeScript Types
 
-All result payload types are exported from the package, so you can import them directly:
+All result payload types are exported from the package for complete type safety:
 
 ```ts
 import type {
-  // Financial Account
+  // Core types
+  ClientOptions,
+  
+  // Financial Account types
   CreateFinancialAccount,
   GetFinancialAccount,
   AllFinancialAccount,
 
-  // Internal Transfer
+  // Internal Transfer types
   CreateInternalTransfer,
   InternalTransfer,
   AllInternalTransfers,
 
-  // Payment Code
+  // Payment Code types
   CreatePaymentCode,
   GetAllPaymentCode,
   GetOne,
 
-  // Payout
+  // Payout types
   DestinationOption,
   CreatePayout,
   GetAll,
   GetOnePayout,
 
-  // Financial Transaction
+  // Financial Transaction types
   GetTransaction,
   AllTransaction,
+  
+  // Checkout Session types
+  CreateCheckout,
+  AllCheckout,
+  OneCheckout,
 } from "monime-package";
 ```
 
-- **financialAccount**
-  - `CreateFinancialAccount`: `{ success, messages, result: { id, name, currency, balance, ... } }`
-  - `GetFinancialAccount`: same `result` shape as above
-  - `AllFinancialAccount`: `{ result: Result[], pagination: { count, next } }`
+### Core Type Definitions
+
+#### Result Envelope
+All API responses follow this consistent pattern:
+```ts
+type Result<T> = {
+  success: boolean;
+  data?: T;
+  error?: Error;
+};
+```
+
+#### Client Configuration
+```ts
+type ClientOptions = {
+  monimeSpaceId: string; // Your Monime Space ID
+  accessToken: string;   // Your API access token
+};
+```
+
+#### Destination Options for Payouts
+```ts
+type DestinationOption = 
+  | {
+      type: "momo";
+      providerId: "m17" | "m18"; // MTN, Orange Money
+      phoneNumber: string;
+    }
+  | {
+      type: "bank";
+      providerId: "b01" | "b02" | "b03"; // Bank codes
+      accountNumber: string;
+    }
+  | {
+      type: "wallet";
+      providerId: "w01" | "w02"; // Wallet provider codes
+      walletId: string;
+    };
+```
+
+### Response Type Details
+
+#### Financial Account Types
+```ts
+// Account creation/retrieval response
+interface CreateFinancialAccount {
+  success: boolean;
+  messages: string[];
+  result: {
+    id: string;           // Unique account ID
+    uvan: string;         // Internal identifier
+    name: string;         // Account name
+    currency: string;     // Always "SLE" (Sierra Leone)
+    reference: string;    // Account reference
+    description: string;  // Account description
+    balance: {
+      available: {
+        currency: string;
+        value: number;    // Balance in cents (SLE)
+      };
+    };
+    createTime: string;   // ISO timestamp
+    updateTime: string;   // ISO timestamp
+  };
+}
+```
+
+#### Internal Transfer Types
+```ts
+interface CreateInternalTransfer {
+  success: boolean;
+  messages: string[];
+  result: {
+    id: string;                    // Transfer ID
+    status: string;                // Transfer status
+    amount: {
+      currency: string;
+      value: number;               // Amount in cents
+    };
+    sourceFinancialAccount: { id: string };
+    destinationFinancialAccount: { id: string };
+    financialTransactionReference: string;
+    description: string;
+    failureDetail: {
+      code: string;
+      message: string;
+    };
+    ownershipGraph: {
+      owner: {
+        id: string;
+        type: string;
+        owner: {
+          id: string;
+          type: string;
+        };
+      };
+    };
+    createTime: string;
+    updateTime: string;
+  };
+}
+```
 
-- **internalTransfer**
-  - `CreateInternalTransfer`: `{ result: { id, status, amount, sourceFinancialAccount, destinationFinancialAccount, ... } }`
-  - `InternalTransfer`: same `result` shape for a single transfer
-  - `AllInternalTransfers`: `{ result: Result[], pagination }`
+#### Payment Code Types
+```ts
+interface CreatePaymentCode {
+  success: boolean;
+  messages: string[];
+  result: {
+    id: string;
+    mode: string;              // "recurrent"
+    status: string;            // Payment status
+    name: string;              // Payment name
+    amount: {
+      currency: string;
+      value: number;           // Amount in cents
+    };
+    enable: boolean;
+    expireTime: string;        // ISO timestamp
+    customer: { name: string };
+    ussdCode: string;          // USSD code for payment
+    reference: string;
+    authorizedProviders: string[];
+    authorizedPhoneNumber: string;
+    recurrentPaymentTarget: {
+      expectedPaymentCount: number;
+      expectedPaymentTotal: {
+        currency: string;
+        value: number;
+      };
+    };
+    financialAccountId: string;
+    processedPaymentData: {
+      amount: { currency: string; value: number };
+      orderId: string;
+      paymentId: string;
+      orderNumber: string;
+      channelData: {
+        providerId: string;
+        accountId: string;
+        reference: string;
+      };
+      financialTransactionReference: string;
+    };
+    createTime: string;
+    updateTime: string;
+    ownershipGraph: OwnershipGraph;
+  };
+}
+```
 
-- **paymentCode**
-  - `CreatePaymentCode`: created payment code details
-  - `GetAllPaymentCode`: list of codes with pagination
-  - `GetOne`: details for a specific payment code
+#### Checkout Session Types
+```ts
+interface CreateCheckout {
+  success: boolean;
+  messages: string[];
+  result: {
+    id: string;
+    status: string;
+    name: string;
+    orderNumber: string;       // Generated order number
+    reference: string;
+    description: string;
+    redirectUrl: string;       // Checkout page URL
+    cancelUrl: string;
+    successUrl: string;
+    lineItems: {
+      data: Array<{
+        type: string;
+        id: string;
+        name: string;
+        price: { currency: string; value: number };
+        quantity: number;
+        reference: string;
+        description: string;
+        images: string[];
+      }>;
+    };
+    financialAccountId: string;
+    brandingOptions: {
+      primaryColor: string;
+    };
+    expireTime: string;
+    createTime: string;
+    ownershipGraph: OwnershipGraph;
+  };
+}
+```
 
-- **payout**
-  - `DestinationOption`: union for destination types (`momo`, `bank`, `wallet`)
-  - `CreatePayout`: created payout info with `fees`, `destination`, etc.
-  - `GetAll`: list of payouts with pagination
-  - `GetOnePayout`: details for a specific payout
+#### Common Types
+```ts
+// Pagination for list responses
+interface Pagination {
+  count: number;  // Total count
+  next: string;   // Next page URL/cursor
+}
+
+// Ownership information
+interface OwnershipGraph {
+  owner: {
+    id: string;
+    type: string;
+    owner: {
+      id: string;
+      type: string;
+    };
+  };
+}
+
+// Amount representation
+interface Amount {
+  currency: string; // Always "SLE"
+  value: number;    // Amount in cents (multiply by 100 for SLE)
+}
+```
 
-- **financialTransaction**
-  - `GetTransaction`: details for a transaction (amount, reference, ownershipGraph, ...)
-  - `AllTransaction`: list of transactions with pagination
+### Type Usage Examples
 
-These types mirror Monime API responses and are kept minimal and typed for convenience.
+```ts
+// Type-safe account creation
+const createAccountTyped = async (name: string): Promise<CreateFinancialAccount | null> => {
+  const result = await client.financialAccount.create(name);
+  return result.success ? result.data! : null;
+};
+
+// Type-safe payout with validation
+const createMobileMoneyPayout = async (
+  amount: number,
+  phoneNumber: string,
+  sourceAccount: string
+): Promise<CreatePayout | null> => {
+  const destination: DestinationOption = {
+    type: "momo",
+    providerId: "m17",
+    phoneNumber,
+  };
+  
+  const result = await client.payout.create(amount, destination, sourceAccount);
+  return result.success ? result.data! : null;
+};
+
+// Type-safe transaction processing
+const processTransactions = async (): Promise<void> => {
+  const txResult = await client.financialTransaction.getAll();
+  
+  if (txResult.success && txResult.data) {
+    const transactions: AllTransaction = txResult.data;
+    
+    transactions.result.forEach((tx: GetTransaction['result']) => {
+      console.log(`Transaction ${tx.id}: ${tx.amount.value / 100} ${tx.amount.currency}`);
+    });
+  }
+};
+```
 
 ---