spaark-payapi-sdk 1.5.0 → 1.7.0

package/README.md

@@ -1,9 +1,34 @@
 # spaark-payapi-sdk
 
-TypeScript SDK for Pawapay Mobile Money API (V2). Simplifies integration with Mobile Money operators in Africa.
+TypeScript SDK for Pawapay Mobile Money API (V2). Simplifies integration with Mobile Money operators in Africa (CEMAC region).
 
 [![npm version](https://img.shields.io/npm/v/spaark-payapi-sdk.svg)](https://www.npmjs.com/package/spaark-payapi-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Project Architecture](#project-architecture)
+- [Supported Providers](#supported-providers)
+- [API Reference](#api-reference)
+  - [Initialization](#initialization)
+  - [Transactions](#transactions)
+  - [Toolkit](#toolkit)
+  - [Finances](#finances)
+  - [Webhooks](#webhooks)
+  - [Products](#products)
+  - [Utilities](#utilities)
+- [React Components](#react-components)
+  - [Test Dashboard](#test-dashboard)
+  - [Finance Dashboard](#finance-dashboard)
+- [TypeScript Types](#typescript-types)
+- [Error Handling](#error-handling)
+- [Environment Variables](#environment-variables)
+- [Development](#development)
+- [License](#license)
 
 ## Installation
 
@@ -18,13 +43,24 @@ pnpm add spaark-payapi-sdk
 yarn add spaark-payapi-sdk
 ```
 
-### For React Components
+### For React Components (shadcn/ui)
 
-The SDK includes React components that require additional peer dependencies:
+The SDK includes React components built with shadcn/ui patterns. Install the required peer dependencies:
 
 ```bash
-# Required for React components
-npm install react react-dom lucide-react @radix-ui/react-tabs @radix-ui/react-select @radix-ui/react-dialog
+# Core React dependencies
+npm install react react-dom axios
+
+# shadcn/ui prerequisites (via shadcn CLI)
+pnpm dlx shadcn@latest add button
+pnpm dlx shadcn@latest add tabs
+pnpm dlx shadcn@latest add select
+pnpm dlx shadcn@latest add chart
+pnpm dlx shadcn@latest add skeleton
+pnpm dlx shadcn@latest add spinner
+
+# Or install manually (lucide-react is required for icons)
+npm install lucide-react @radix-ui/react-tabs @radix-ui/react-select @radix-ui/react-dialog recharts @tanstack/react-table
 
 # The following are bundled with the SDK (no need to install):
 # - clsx
@@ -32,6 +68,8 @@ npm install react react-dom lucide-react @radix-ui/react-tabs @radix-ui/react-se
 # - class-variance-authority
 ```
 
+> **Note**: The components use shadcn/ui styling conventions. Make sure your project has Tailwind CSS configured with the shadcn/ui theme variables.
+
 ## Quick Start
 
 ```typescript
@@ -57,24 +95,94 @@ console.log(deposit.depositId, deposit.status);
 
 ## Features
 
-- **Transactions**: Deposits, Payouts, Refunds, Payment Page
-- **Toolkit**: Predict Provider, Active Configuration, Provider Availability
+### Core SDK
+- **Transactions**: Deposits, Payouts, Refunds, Payment Page, Polling
+- **Toolkit**: Predict Provider, Active Configuration, Provider Availability, Public Keys
 - **Finances**: Wallet Balances, Statement Generation
-- **Webhooks**: Signature verification, Event parsing
-- **React Components**: Test dashboard + Finance dashboard
-- **Full TypeScript**: Complete type definitions
+- **Webhooks**: HMAC-SHA256 signature verification, Event parsing
+- **Products**: Product management with domain configuration
+
+### React Components
+- **Test Dashboard**: Interactive SDK testing UI with 4 modes and 6 tabs
+  - **Demo Mode**: Finance Dashboard with mock data (no API key required)
+  - **Demo Expert**: Test Dashboard with simulated API responses (no API key required)
+  - **Sandbox Mode**: Finance Dashboard connected to Pawapay sandbox API
+  - **Production Mode**: Finance Dashboard connected to Pawapay production API
+- **Finance Dashboard**: Transaction analytics with charts and KPIs
+- **Icons**: lucide-react icons throughout the UI
+- **shadcn/ui Components**: Button, Tabs, Select, Card, Input, Table, Skeleton, Spinner
+- **Charts**: Area, Bar, Pie charts with Recharts
 - **i18n**: French/English support
 
+### Developer Experience
+- **Full TypeScript**: Complete type definitions with strict mode
+- **Zod Validation**: Input validation for all requests
+- **Retry Logic**: Exponential backoff with jitter
+- **Logging**: Configurable log levels with sensitive data sanitization
+- **Error Handling**: Typed errors with retryable flag
+
+## Project Architecture
+
+```
+src/
+├── sdk.ts                 # Main SpaarkPayApiSdk class
+├── config.ts              # Configuration validation (Zod)
+├── index.ts               # Main exports
+├── react.tsx              # React components entry point
+│
+├── modules/
+│   ├── transactions.ts    # Deposits, payouts, refunds, polling
+│   ├── products.ts        # Product management
+│   ├── webhooks.ts        # Signature verification, event parsing
+│   ├── utils.ts           # Helpers, availability, prediction
+│   └── finances.ts        # Wallet balances, statements
+│
+├── core/
+│   ├── http-client.ts     # Axios wrapper with interceptors
+│   ├── retry.ts           # Exponential backoff logic
+│   ├── errors.ts          # PawapayError class
+│   └── logger.ts          # Configurable logger
+│
+├── types/
+│   ├── config.ts          # SDK configuration types
+│   ├── transactions.ts    # Transaction types
+│   ├── webhooks.ts        # Webhook event types
+│   ├── toolkit.ts         # Toolkit types
+│   ├── finances.ts        # Finance types
+│   └── products.ts        # Product types
+│
+├── constants/
+│   ├── correspondents.ts  # Provider definitions & limits
+│   └── errors.ts          # Error code definitions
+│
+├── components/
+│   └── SpaarkPaySdkFinanceDashboard.tsx
+│
+├── mocks/
+│   └── webhook-generators.ts  # Test webhook generation
+│
+└── lib/
+    └── utils.ts           # Tailwind merge utility
+```
+
 ## Supported Providers
 
-| Provider | Country | Currency |
-|----------|---------|----------|
-| `MTN_MOMO_CMR` | Cameroon | XAF |
-| `ORANGE_CMR` | Cameroon | XAF |
-| `MTN_MOMO_COG` | Congo | XAF |
-| `AIRTEL_COG` | Congo | XAF |
-| `MTN_MOMO_GAB` | Gabon | XAF |
-| `AIRTEL_GAB` | Gabon | XAF |
+| Provider | Country | Currency | Deposits | Payouts |
+|----------|---------|----------|----------|---------|
+| `MTN_MOMO_CMR` | Cameroon | XAF | 100 - 1,000,000 | 500 - 500,000 |
+| `ORANGE_CMR` | Cameroon | XAF | 100 - 1,000,000 | 500 - 500,000 |
+| `MTN_MOMO_COG` | Congo | XAF | 100 - 1,000,000 | 500 - 500,000 |
+| `AIRTEL_COG` | Congo | XAF | 100 - 1,000,000 | 500 - 500,000 |
+| `MTN_MOMO_GAB` | Gabon | XAF | 100 - 1,000,000 | 500 - 500,000 |
+| `AIRTEL_GAB` | Gabon | XAF | 100 - 1,000,000 | 500 - 500,000 |
+
+### Phone Number Formats
+
+| Country | Format | Example |
+|---------|--------|---------|
+| Cameroon | `237XXXXXXXXX` | 237670000000 |
+| Congo | `242XXXXXXXXX` | 242060000000 |
+| Gabon | `241XXXXXXXX` | 24160000000 |
 
 ## API Reference
 
@@ -84,12 +192,16 @@ console.log(deposit.depositId, deposit.status);
 import { SpaarkPayApiSdk } from 'spaark-payapi-sdk';
 
 const sdk = new SpaarkPayApiSdk({
-  apiKey: process.env.PAWAPAY_API_KEY,
-  environment: 'sandbox', // 'sandbox' | 'production'
-  timeout: 30000,         // Optional: request timeout in ms
-  retries: 3,             // Optional: retry attempts
-  logLevel: 'info',       // Optional: 'debug' | 'info' | 'warn' | 'error' | 'none'
+  apiKey: process.env.PAWAPAY_API_KEY,      // Required
+  environment: 'sandbox',                    // 'sandbox' | 'production'
+  timeout: 30000,                            // Request timeout in ms (default: 30000)
+  retries: 3,                                // Retry attempts (default: 3)
+  logLevel: 'info',                          // 'debug' | 'info' | 'warn' | 'error' | 'none'
 });
+
+// Runtime configuration
+sdk.setLogLevel('debug');
+sdk.setWebhookSecret('whsec_xxxxxxxxxxxx');
 ```
 
 ### Transactions
@@ -102,10 +214,10 @@ const deposit = await sdk.transactions.initiateDeposit({
   currency: 'XAF',
   provider: 'MTN_MOMO_CMR',
   phoneNumber: '237670000000',
-  transactionId: sdk.utils.generateTransactionId(),
-  customerMessage: 'Payment description', // 4-22 chars
-  clientReferenceId: 'order-123',         // Optional
-  metadata: [{ orderId: 'ORD-123' }],     // Optional
+  transactionId: sdk.utils.generateTransactionId(), // UUID v4 required
+  customerMessage: 'Payment description',           // 4-22 chars
+  clientReferenceId: 'order-123',                   // Optional
+  metadata: [{ orderId: 'ORD-123' }],               // Optional
 });
 
 // Response
@@ -153,8 +265,8 @@ const status = await sdk.transactions.checkStatus('transaction-uuid');
 
 ```typescript
 const result = await sdk.transactions.pollUntilComplete('transaction-uuid', {
-  interval: 5000,      // Poll every 5 seconds
-  maxAttempts: 12,     // Max 12 attempts (1 minute)
+  interval: 5000,      // Poll every 5 seconds (default)
+  maxAttempts: 12,     // Max 12 attempts (default)
   onStatusChange: (status) => console.log('Status:', status),
 });
 ```
@@ -177,7 +289,7 @@ const page = await sdk.transactions.createPaymentPage({
   returnUrl: 'https://yoursite.com/payment/complete',
   phoneNumber: '237670000000',                        // Optional
   amountDetails: { amount: 5000, currency: 'XAF' },   // Optional
-  language: 'FR',                                     // Optional
+  language: 'FR',                                     // Optional: 'FR' | 'EN'
   country: 'CMR',                                     // Optional
   reason: 'Ticket purchase',                          // Optional
 });
@@ -208,7 +320,7 @@ const prediction = await sdk.utils.predictProvider('+237 670 000 000');
 ```typescript
 const availability = await sdk.utils.getProviderAvailability({
   country: 'CMR',           // Optional
-  operationType: 'DEPOSIT', // Optional
+  operationType: 'DEPOSIT', // Optional: 'DEPOSIT' | 'PAYOUT' | 'REFUND'
 });
 ```
 
@@ -216,6 +328,7 @@ const availability = await sdk.utils.getProviderAvailability({
 
 ```typescript
 const config = await sdk.utils.getActiveConfiguration();
+// Returns company config, countries, providers, currencies, limits
 ```
 
 #### Check MMO Availability
@@ -225,6 +338,13 @@ const status = await sdk.utils.checkMMOAvailability('MTN_MOMO_CMR');
 // { correspondent: 'MTN_MOMO_CMR', available: true, degraded: false }
 ```
 
+#### Get Public Keys
+
+```typescript
+const keys = await sdk.utils.getPublicKeys();
+// [{ id: 'key-001', key: 'MIIBIjANBgkqhkiG9w0BAQEFAA...' }]
+```
+
 ### Finances
 
 #### Wallet Balances
@@ -245,22 +365,51 @@ const statement = await sdk.finances.generateStatement({
   compressed: true,
 });
 
+// Poll until complete
 const result = await sdk.finances.pollStatementUntilComplete(statement.statementId);
 console.log(result.downloadUrl);
 ```
 
 ### Webhooks
 
+#### Setup
+
 ```typescript
-// Set secret
+// Set webhook secret
 sdk.setWebhookSecret(process.env.PAWAPAY_WEBHOOK_SECRET);
+```
+
+#### Verify Signature
 
-// Verify signature
+```typescript
 const isValid = sdk.webhooks.verifySignature(body, signature);
+```
+
+#### Parse Event
 
-// Parse event
+```typescript
 const event = sdk.webhooks.parseEvent(body);
 
+// Or verify + parse in one step
+const event = sdk.webhooks.constructEvent(body, signature);
+```
+
+#### Event Types
+
+| Event Type | Description |
+|------------|-------------|
+| `deposit.accepted` | Deposit request accepted |
+| `deposit.completed` | Deposit completed successfully |
+| `deposit.failed` | Deposit failed |
+| `payout.accepted` | Payout request accepted |
+| `payout.completed` | Payout completed successfully |
+| `payout.failed` | Payout failed |
+| `refund.completed` | Refund completed successfully |
+| `refund.failed` | Refund failed |
+
+#### Handle Events
+
+```typescript
 switch (event.eventType) {
   case 'deposit.completed':
     console.log('Deposit completed:', event.data.depositId);
@@ -271,20 +420,54 @@ switch (event.eventType) {
   case 'payout.completed':
     console.log('Payout completed:', event.data.payoutId);
     break;
+  case 'payout.failed':
+    console.log('Payout failed:', event.data.failureReason);
+    break;
 }
 ```
 
+### Products
+
+Local product management (in-memory storage):
+
+```typescript
+// Create product
+const product = await sdk.products.create({
+  name: 'Premium Plan',
+  price: 10000,
+  currency: 'XAF',
+  description: 'Monthly subscription',
+});
+
+// Get product
+const product = await sdk.products.get('product-id');
+
+// List products
+const products = await sdk.products.list();
+
+// Update product
+await sdk.products.update('product-id', { price: 12000 });
+
+// Delete product
+await sdk.products.delete('product-id');
+
+// Add/remove domains
+await sdk.products.addDomain({ productId: 'product-id', domain: 'example.com' });
+await sdk.products.removeDomain('product-id', 'example.com');
+```
+
 ### Utilities
 
 ```typescript
-// Generate UUID v4
+// Generate UUID v4 transaction ID
 const txId = sdk.utils.generateTransactionId();
 
-// Validate transaction ID
+// Validate transaction ID format
 const isValid = sdk.utils.validateTransactionId(txId);
 
-// Format phone number
+// Format phone number for country
 const phone = sdk.utils.formatPhoneNumber('670000000', 'CMR');
+// '237670000000'
 
 // Validate phone for provider
 const isValid = sdk.utils.validatePhoneNumber('237670000000', 'MTN_MOMO_CMR');
@@ -292,10 +475,10 @@ const isValid = sdk.utils.validatePhoneNumber('237670000000', 'MTN_MOMO_CMR');
 // Get provider info
 const info = sdk.utils.getCorrespondentInfo('MTN_MOMO_CMR');
 
-// Detect provider from phone
+// Detect provider from phone number
 const provider = sdk.utils.detectCorrespondent('237670000000');
 
-// Get transaction limits
+// Get transaction limits for provider
 const limits = await sdk.utils.getTransactionLimits('MTN_MOMO_CMR');
 ```
 
@@ -303,27 +486,72 @@ const limits = await sdk.utils.getTransactionLimits('MTN_MOMO_CMR');
 
 ### Test Dashboard
 
+Interactive testing UI with **4 operation modes** and 6 tabs (Deposit, Payout, Status, Toolkit, Finances, Webhooks).
+
+#### Dashboard Modes
+
+| Mode | Description | API Key Required |
+|------|-------------|------------------|
+| **Demo** | Finance Dashboard with mock/fake data | No |
+| **Demo Expert** | Test Dashboard with simulated API responses | No |
+| **Sandbox** | Finance Dashboard connected to Pawapay sandbox API | Yes |
+| **Production** | Finance Dashboard connected to Pawapay production API | Yes |
+
 ```tsx
 import { SpaarkPaySdkTestDashboard } from 'spaark-payapi-sdk/react';
 
 export default function TestPage() {
   return (
     <SpaarkPaySdkTestDashboard
-      environment="sandbox"
-      apiBasePath="/api/pawapay"
-      demoMode={false}
+      apiKey="pk_sandbox_xxx"              // Optional: pre-configured API key
+      environment="sandbox"                 // 'sandbox' | 'production'
+      apiBasePath="/api/pawapay"           // Backend proxy route
+      demoMode={false}                      // Start in demo mode (default: false)
       onDepositComplete={(res) => console.log('Deposit:', res)}
       onPayoutComplete={(res) => console.log('Payout:', res)}
       onError={(err) => console.error(err)}
+      className="max-w-6xl mx-auto"
     />
   );
 }
 ```
 
-Use `demoMode={true}` to test without API key.
+**Mode Selection:**
+- Without `apiKey` or `demoMode`: Shows mode selection screen
+- With `demoMode={true}`: Starts directly in Demo mode
+- With `apiKey` + `environment`: Starts in Sandbox or Production mode
+
+#### Backend Proxy Setup (Next.js)
+
+```typescript
+// app/api/pawapay/deposit/route.ts
+import { SpaarkPayApiSdk } from 'spaark-payapi-sdk';
+
+export async function POST(request: Request) {
+  const body = await request.json();
+
+  const sdk = new SpaarkPayApiSdk({
+    apiKey: body.apiKey,
+    environment: body.environment,
+  });
+
+  const result = await sdk.transactions.initiateDeposit({
+    amount: body.amount,
+    currency: body.currency,
+    provider: body.provider,
+    phoneNumber: body.phoneNumber,
+    transactionId: body.transactionId,
+    customerMessage: body.customerMessage,
+  });
+
+  return Response.json(result);
+}
+```
 
 ### Finance Dashboard
 
+Transaction analytics dashboard with KPI cards, filters, pagination, and charts.
+
 ```tsx
 import {
   SpaarkPaySdkFinanceDashboard,
@@ -341,54 +569,140 @@ const transactions: Transaction[] = [
     phoneNumber: '237670000000',
     createdAt: '2025-01-15T10:00:00Z',
   },
-  // ... more transactions
 ];
 
 export default function FinancePage() {
   return (
     <SpaarkPaySdkFinanceDashboard
       transactions={transactions}
-      title="My Finance Dashboard"        // Customizable
-      locale="fr"                          // 'fr' | 'en'
-      onRefresh={() => fetchData()}        // Refresh button handler
-      onTransactionClick={(tx) => {}}      // Row click handler
-      onExpertModeClick={() => {}}         // Expert mode button
-      showExpertMode={true}                // Show/hide expert button
-      isLoading={false}                    // Loading state
+      title="My Finance Dashboard"
+      subtitle="Overview of your transactions"
+      locale="fr"                              // 'fr' | 'en'
+      onRefresh={() => fetchData()}            // Refresh button callback
+      onSettings={() => openSettings()}        // Settings button (gear icon)
+      onAddTransaction={() => openForm()}      // CTA button when no transactions
+      onTransactionClick={(tx) => {}}          // Table row click
+      onExpertModeClick={() => {}}             // Expert mode button
+      showExpertMode={true}
+      isLoading={false}
     />
   );
 }
 ```
 
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `transactions` | `Transaction[]` | Array of transactions to display |
+| `title` | `string` | Dashboard title (default: "Tableau de bord financier") |
+| `subtitle` | `string` | Dashboard subtitle |
+| `locale` | `'fr' \| 'en'` | Language (default: 'fr') |
+| `onRefresh` | `() => void` | Refresh button callback |
+| `onSettings` | `() => void` | Settings button callback (gear icon) |
+| `onAddTransaction` | `() => void` | CTA button callback when no transactions |
+| `onTransactionClick` | `(tx) => void` | Table row click callback |
+| `onExpertModeClick` | `() => void` | Expert mode button callback |
+| `showExpertMode` | `boolean` | Show/hide expert mode button |
+| `isLoading` | `boolean` | Show loading skeletons |
+
 **Features:**
-- 5 KPI cards (Total Volume, Deposits, Payouts, Failed, Refunds)
+
+**Dashboard Tab:**
+- 8 KPI cards: Total Volume, Deposits, Payouts, Refunds, Pending, Completed, Failed, Cancelled
 - Search by transaction ID or phone number
-- Filter by type (deposit/payout/refund) and status
-- Paginated transactions table
-- Copy transaction ID to clipboard
-- i18n support (French/English)
-- Customizable title
-- Expert Mode button integration
+- Dropdown filters for type and status
+- Paginated transactions table with @tanstack/react-table
+- Copy transaction ID button
+- Empty state with CTA button
+
+**Charts Tab:**
+- Area Chart: Volume over time (deposits vs payouts)
+- Bar Chart: Transaction amounts by type
+- Pie Chart: Status distribution (donut style)
 
 ## TypeScript Types
 
 ```typescript
 import type {
+  // SDK Config
   SpaarkPayApiSdkConfig,
+  ResolvedConfig,
+  Environment,
+  LogLevel,
+
+  // Transactions
   DepositRequest,
   DepositResponse,
   PayoutRequest,
   PayoutResponse,
+  RefundRequest,
+  RefundResponse,
   TransactionStatus,
   TransactionStatusResponse,
+  PaymentPageRequest,
+  PaymentPageResponse,
+  PollOptions,
+  FailureReason,
+  DepositFailureCode,
+  PayoutFailureCode,
+
+  // Providers
   Correspondent,
+  CorrespondentInfo,
+  TransactionLimits,
   Currency,
+
+  // Webhooks
+  WebhookEventType,
+  PawapayWebhookEvent,
+  DepositCallbackData,
+  PayoutCallbackData,
+
+  // Toolkit
+  OperationType,
+  OperationStatus,
+  ProviderAvailability,
+  ActiveConfigResponse,
+  PredictProviderResponse,
+  PublicKeyResponse,
+
+  // Finances
+  WalletBalance,
+  StatementRequest,
+  StatementResponse,
+  StatementStatus,
+
+  // Products
+  Product,
+  ProductCreateRequest,
+
+  // React Components
   Transaction,
   TransactionType,
-  // ... and more
+  SpaarkPaySdkFinanceDashboardProps,
+  SpaarkPaySdkTestDashboardProps,
 } from 'spaark-payapi-sdk';
 ```
 
+### Transaction Type (Finance Dashboard)
+
+```typescript
+type Transaction = {
+  id: string;
+  type: 'deposit' | 'payout' | 'refund';
+  amount: number;
+  currency: string;
+  status: 'ACCEPTED' | 'PENDING' | 'ENQUEUED' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'REJECTED';
+  provider: Correspondent;
+  phoneNumber: string;
+  description?: string;
+  createdAt: string;
+  updatedAt?: string;
+  failureReason?: string;
+};
+```
+
 ## Error Handling
 
 ```typescript
@@ -398,22 +712,106 @@ try {
   await sdk.transactions.initiateDeposit({ ... });
 } catch (error) {
   if (error instanceof PawapayError) {
-    console.log(error.code);       // Error code
-    console.log(error.message);    // Human-readable message
-    console.log(error.retryable);  // Whether to retry
-    console.log(error.statusCode); // HTTP status
+    console.log(error.code);         // Error code
+    console.log(error.message);      // Human-readable message
+    console.log(error.retryable);    // Whether to retry
+    console.log(error.statusCode);   // HTTP status code
+    console.log(error.failureReason); // Pawapay failure reason
   }
 }
 ```
 
+### Error Codes
+
+| Code | Description | Retryable |
+|------|-------------|-----------|
+| `VALIDATION_ERROR` | Invalid input data | No |
+| `INVALID_PHONE` | Invalid phone number format | No |
+| `INSUFFICIENT_FUNDS` | Not enough balance | No |
+| `AMOUNT_TOO_LOW` | Below minimum amount | No |
+| `AMOUNT_TOO_HIGH` | Above maximum amount | No |
+| `LIMIT_EXCEEDED` | Daily/monthly limit exceeded | No |
+| `DUPLICATE` | Duplicate transaction ID | No |
+| `MMO_UNAVAILABLE` | Provider is unavailable | Yes |
+| `TIMEOUT` | Request timeout | Yes |
+| `UNAUTHORIZED` | Invalid API key | No |
+| `RATE_LIMITED` | Too many requests | Yes |
+| `SERVER_ERROR` | Pawapay server error | Yes |
+| `NETWORK_ERROR` | Network connectivity issue | Yes |
+| `NOT_FOUND` | Transaction not found | No |
+
 ## Environment Variables
 
 ```bash
+# Required
 PAWAPAY_API_KEY=pk_sandbox_xxxxxxxxxxxx
-PAWAPAY_ENVIRONMENT=sandbox
-PAWAPAY_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx
+
+# Optional
+PAWAPAY_ENVIRONMENT=sandbox              # 'sandbox' | 'production' (default: sandbox)
+PAWAPAY_BASE_URL=https://custom.api.url  # Custom API base URL
+PAWAPAY_CALLBACK_URL=https://...         # Default webhook callback URL
+PAWAPAY_TIMEOUT=30000                    # Request timeout in ms (default: 30000)
+PAWAPAY_RETRIES=3                        # Number of retries (default: 3)
+PAWAPAY_LOG_LEVEL=info                   # 'debug' | 'info' | 'warn' | 'error' | 'none'
+PAWAPAY_WEBHOOK_SECRET=whsec_xxx         # Webhook signature secret
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone repository
+git clone https://github.com/confort-sept-inc/react-spaark-payapi-sdk.git
+cd react-spaark-payapi-sdk
+
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm typecheck
+
+# Lint
+pnpm lint
 ```
 
+### Scripts
+
+| Script | Description |
+|--------|-------------|
+| `pnpm build` | Build with tsup (ESM + CJS + types) |
+| `pnpm dev` | Watch mode for development |
+| `pnpm test` | Run Jest tests |
+| `pnpm test:coverage` | Run tests with coverage |
+| `pnpm typecheck` | TypeScript type checking |
+| `pnpm lint` | ESLint |
+| `pnpm release` | Build, version, and publish |
+
+### Testing
+
+```bash
+# Run all tests
+pnpm test
+
+# Run with coverage (70% threshold)
+pnpm test:coverage
+
+# Run specific test file
+pnpm test src/__tests__/sdk.test.ts
+```
+
+### Project Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.3
+- React 18 or 19 (for components)
+
 ## License
 
 MIT