{"id":30584068,"url":"https://github.com/sorybarry223/timilo","last_synced_at":"2025-08-29T09:02:59.812Z","repository":{"id":300642624,"uuid":"1006653501","full_name":"sorybarry223/timilo","owner":"sorybarry223","description":"A lightweight TypeScript SDK for Orange Money Web Payment. Easily create payment links with your Orange credentials. Designed to simplify integration and boost developer productivity. Community contributions welcome!","archived":false,"fork":false,"pushed_at":"2025-07-06T08:35:32.000Z","size":520,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-06T09:32:30.974Z","etag":null,"topics":["nodejs","orange","orange-money","payment","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sorybarry223.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T18:18:08.000Z","updated_at":"2025-07-06T08:35:35.000Z","dependencies_parsed_at":"2025-06-22T21:40:54.548Z","dependency_job_id":null,"html_url":"https://github.com/sorybarry223/timilo","commit_stats":null,"previous_names":["sorybarry223/timilo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sorybarry223/timilo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sorybarry223%2Ftimilo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sorybarry223%2Ftimilo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sorybarry223%2Ftimilo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sorybarry223%2Ftimilo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sorybarry223","download_url":"https://codeload.github.com/sorybarry223/timilo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sorybarry223%2Ftimilo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272658781,"owners_count":24971604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nodejs","orange","orange-money","payment","typescript"],"created_at":"2025-08-29T09:02:57.045Z","updated_at":"2025-08-29T09:02:59.796Z","avatar_url":"https://github.com/sorybarry223.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Orange Money SDK\n\n\u003e **Disclaimer:** This is not an official SDK from Orange. This is a side project created to simplify Orange Money Web Payment integration. Ensure compliance with Orange Money's terms of service.\n\nAn easy-to-use SDK for integrating Orange Money Web Payment in your applications.\n\n---\n\n## Overview\n\nThis SDK allows you to create Orange Money payment links seamlessly by handling authentication and request signing. It requires you to provide your own Orange Money credentials and configure URLs for payment flow and notifications.\n\n---\n\n## Prerequisites\n\nBefore using the SDK, you must have an Orange Money developer account and obtain the following credentials from Orange Money:\n\n- **BASIC_TOKEN**: Your OAuth basic authentication token (for the initial token request)\n- **TOKEN_URL**: URL to request OAuth access token (usually `https://api.orange.com/oauth/v1/token`)\n- **merchantKey**: Your merchant secret key used to sign requests\n- **paymentUrl**: URL to create payment requests (usually `https://api.orange.com/orange-money-webpay/dev/v1/webpayment`)\n\n\n\n---\n\n## Options\n\n| Option        | Type    | Description                                                                                      |\n|---------------|---------|------------------------------------------------------------------------------------------------|\n| `basicToken`  | `string`| OAuth basic token for initial authentication                                                    |\n| `tokenUrl`    | `string`| URL to request OAuth access token                                                               |\n| `paymentUrl`  | `string`| Orange Money API endpoint to create payment links                                               |\n| `merchantKey` | `string`| Your merchant secret key used to sign payment requests                                          |\n| `orderId`     | `string`| Unique identifier for each payment transaction                                                  |\n| `totalPrice`  | `number`| Amount to be paid (in the smallest currency unit, e.g., cents)                                 |\n| `currency`    | `string`| Currency code for the payment (e.g., 'XOF', 'USD', 'EUR'). Defaults to 'XOF' if not provided |\n| `returnUrl`   | `string`| URL where customers are redirected after a successful payment                                   |\n| `cancelUrl`   | `string`| URL where customers are redirected after cancelling a payment                                   |\n| `notifUrl`    | `string`| Backend URL where Orange Money sends asynchronous payment notifications       \n\n\u003e **Important:** The `notifUrl` is crucial for receiving asynchronous transaction results. Make sure it is publicly accessible and secured.                   |\n\n---\n\n## Installation\n\n### Download the pre-built SDK\n\nYou can download the `dist/` directory from the repository and copy it directly into your project. This contains the pre-built SDK files.\n\nImport it in your code as:\n\n```ts\nimport { OrangeMoney } from './dist';\n```\n\n### Clone the full repository (for development)\n\n```bash\ngit clone https://github.com/sorybarry223/timilo.git\ncd timilo\nnpm install\nnpm run build\n```\n\nAfter building, use the `dist/` directory or link the package locally.\n\n\n---\n\n## Usage Example\n\n```ts\nimport { OrangeMoney } from './dist';\n\nconst sdk = new OrangeMoney({\n  basicToken: 'your_basic_token_here',\n  tokenUrl: 'https://api.orange.com/oauth/v1/token',\n  paymentUrl: 'https://api.orange.com/orange-money-webpay/dev/v1/webpayment',\n});\n\nasync function testPayment() {\n  try {\n    const result = await sdk.createPaymentLink({\n      merchantKey: 'your_merchant_key',\n      orderId: 'ORDER_001',         // Must be unique for each transaction\n      totalPrice: 1000,             // Amount in smallest currency unit\n      currency: 'XOF',\n      returnUrl: 'https://example.com/success',\n      cancelUrl: 'https://example.com/cancel',\n      notifUrl: 'https://example.com/notify',\n    });\n\n    console.log('✅ Payment link:', result.payment_url);\n    console.log('🔔 Notification token:', result.notif_token);\n  } catch (error) {\n    console.error('❌ Error:', error);\n  }\n}\n\ntestPayment();\n```\n\n---\n\n## Testing\n\nThis SDK includes a comprehensive test suite to ensure reliability and correctness. The testing architecture follows best practices with unit tests, integration tests, and proper mocking.\n\n### Test Structure\n\n```\ntests/\n├── __mocks__/\n│   └── axios.ts          # Mock for HTTP requests\n├── unit/\n│   ├── auth.test.ts      # Authentication module tests\n│   ├── payment.test.ts   # Payment module tests\n│   └── types.test.ts     # Type definitions tests\n├── integration/\n│   └── sdk.test.ts       # End-to-end SDK tests\n└── setup.ts              # Global test configuration\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests in watch mode (for development)\nnpm run test:watch\n\n# Run tests with coverage report\nnpm run test:coverage\n\n# Run tests in CI mode\nnpm run test:ci\n```\n\n### Test Coverage\n\nThe test suite covers:\n\n#### Unit Tests (`tests/unit/`)\n\n- **`auth.test.ts`**: Tests the authentication module\n  - ✅ Successful token retrieval\n  - ✅ Error handling for invalid responses\n  - ✅ Network error handling\n  - ✅ Empty response handling\n\n- **`payment.test.ts`**: Tests the payment link generation\n  - ✅ Successful payment link creation\n  - ✅ Default currency handling\n  - ✅ Error handling for missing response fields\n  - ✅ Network error handling\n  - ✅ Invalid response handling\n\n- **`types.test.ts`**: Tests TypeScript type definitions\n  - ✅ Type structure validation\n  - ✅ Optional field handling\n  - ✅ Type compatibility checks\n\n#### Integration Tests (`tests/integration/`)\n\n- **`sdk.test.ts`**: Tests the complete SDK flow\n  - ✅ SDK instantiation\n  - ✅ Complete payment flow (token → payment link)\n  - ✅ Error propagation\n  - ✅ Real-world data scenarios\n\n### Test Configuration\n\nThe project uses Jest with TypeScript support:\n\n- **Jest Configuration**: `jest.config.js`\n- **TypeScript Support**: `ts-jest` preset\n- **Mocking**: Axios HTTP requests are mocked\n- **Coverage**: Reports coverage for all source files\n\n### Adding New Tests\n\nWhen adding new functionality:\n\n1. **Unit Tests**: Add tests in `tests/unit/` for individual modules\n2. **Integration Tests**: Add tests in `tests/integration/` for complete flows\n3. **Mocks**: Update `tests/__mocks__/` if new dependencies need mocking\n4. **Types**: Add type tests in `tests/unit/types.test.ts` for new interfaces\n\n### Example Test Pattern\n\n```ts\nimport { jest, describe, it, expect, beforeEach } from '@jest/globals';\nimport axios from 'axios';\n\n// Mock axios\njest.mock('axios');\nconst mockedAxios = axios as jest.Mocked\u003ctypeof axios\u003e;\n\ndescribe('Your Module', () =\u003e {\n  beforeEach(() =\u003e {\n    jest.clearAllMocks();\n  });\n\n  it('should handle success case', async () =\u003e {\n    // Arrange\n    const mockResponse = { data: { success: true } };\n    mockedAxios.post.mockResolvedValueOnce(mockResponse);\n\n    // Act\n    const result = await yourFunction();\n\n    // Assert\n    expect(result).toBeDefined();\n    expect(mockedAxios.post).toHaveBeenCalledWith(/* expected args */);\n  });\n});\n```\n\n---\n\n## Important Notes\n\n- **Unique orderId**: Each transaction must have a unique `orderId`. Reusing it results in errors such as HTTP 403 Forbidden.\n\n- **Notification URL (notifUrl)**: This URL must be publicly accessible for Orange Money to send payment status notifications.\n\n- **Keep credentials secure**: Never expose your `merchantKey`, `basicToken`, or other sensitive information in public repositories.\n\n- **Token Management**: The SDK handles OAuth token requests and refreshes automatically. Ensure the tokens and URLs remain valid.\n\n- **Error Handling**: Always handle errors gracefully when calling SDK methods.\n\n---\n\n## Support\n\nIf you encounter issues or have questions, please open an issue on the GitHub repository or contact your Orange Money account manager.\n\n## License\n\nMIT License © 2025 Sory BARRY\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsorybarry223%2Ftimilo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsorybarry223%2Ftimilo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsorybarry223%2Ftimilo/lists"}