{"_id":"@afconwave/sdk","_rev":"2-4cb54e7e1f8825ac7b0ac28beddf237f","name":"@afconwave/sdk","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@afconwave/sdk","version":"1.0.0","keywords":["payments","fintech","africa","afconwave","sdk"],"author":{"name":"AfconWave Team"},"license":"MIT","_id":"@afconwave/sdk@1.0.0","maintainers":[{"name":"afconwave","email":"afconwave@gmail.com"}],"dist":{"shasum":"fba508fb4e66b1d7c1d8752230164285490cd00b","tarball":"https://registry.npmjs.org/@afconwave/sdk/-/sdk-1.0.0.tgz","fileCount":6,"integrity":"sha512-SrE5XPAqXAXF94qFMdoHSo8TXK/P3Vd/BP4rtULs193oC2PByfgKfiBwHbGJDdjZH/BLlKVzxowmpH+pSh5eRQ==","signatures":[{"sig":"MEUCIG83dtuIJGtZjBHyPXk92SwjgMsdKYdI57Ecj8AuvlvdAiEAsp5g+0mRpRfEtqsfjy2j6FL/BiDC21sBYeNdD/XryU8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24254},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","gitHead":"144c0f0529dc6265eb356191d14c5e482938d3f9","scripts":{"test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts"},"_npmUser":{"name":"afconwave","email":"afconwave@gmail.com"},"_npmVersion":"10.8.2","description":"Official AfconWave Node.js SDK","directories":{},"_nodeVersion":"20.20.2","dependencies":{"axios":"^1.7.7"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.1.4","typescript":"^5.6.3","@types/node":"^25.6.2"},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.0.0_1778406538347_0.38126441621589713","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@afconwave/sdk","version":"1.1.0","description":"Official AfconWave Node.js SDK — Professional Pan-African payments, payouts, and crypto infrastructure.","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts --clean","test":"vitest run","prepublishOnly":"npm run build"},"keywords":["payments","payouts","fintech","africa","mobile-money","crypto","afconwave","sdk"],"author":{"name":"AfconWave Team","email":"dev@afconwave.com"},"license":"MIT","homepage":"https://docs.afconwave.com/sdks/nodejs","repository":{"type":"git","url":"git+https://github.com/afconwave/afconwave-node.git"},"bugs":{"url":"https://github.com/afconwave/afconwave-node/issues","email":"support@afconwave.com"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"devDependencies":{"@types/node":"^22.10.0","tsup":"^8.3.5","typescript":"^5.6.3","vitest":"^2.1.4"},"dependencies":{"axios":"^1.7.7"},"_id":"@afconwave/sdk@1.1.0","gitHead":"53192c9c12755d48597575e3439df12d5e2f6007","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-a1dgo5tJVvGzTfzqcR7T4M/RbGTf9i7rTvNHgJFzwl2/CVjI9oYHKWmSrZiXvU10t2tsfExiMSaAjFT0n/lMcA==","shasum":"66e1d3dad48fa1f7d0ba5050d17ba8242ac612ab","tarball":"https://registry.npmjs.org/@afconwave/sdk/-/sdk-1.1.0.tgz","fileCount":7,"unpackedSize":29959,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEx2+s7xDlkLTAR9hAAgQstCEYr/wjnQE3NJ5/KX4VlFAiEAjuVms1v9j7i4/2rUG3GEs675SYfioy0aYPHNzjBBI9k="}]},"_npmUser":{"name":"afconwave","email":"afconwave@gmail.com"},"directories":{},"maintainers":[{"name":"afconwave","email":"afconwave@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.1.0_1778537830729_0.21182471102427458"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-10T09:48:58.291Z","modified":"2026-05-11T22:17:11.023Z","1.0.0":"2026-05-10T09:48:58.491Z","1.1.0":"2026-05-11T22:17:10.906Z"},"author":{"name":"AfconWave Team","email":"dev@afconwave.com"},"license":"MIT","keywords":["payments","payouts","fintech","africa","mobile-money","crypto","afconwave","sdk"],"description":"Official AfconWave Node.js SDK — Professional Pan-African payments, payouts, and crypto infrastructure.","maintainers":[{"name":"afconwave","email":"afconwave@gmail.com"}],"readme":"# @afconwave/sdk — Official Node.js / TypeScript SDK\n\n> The official Node.js and TypeScript client library for the AfconWave Payments API.\n\n[![npm version](https://img.shields.io/npm/v/@afconwave/sdk.svg)](https://www.npmjs.com/package/@afconwave/sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)\n\n---\n\n## Features\n\n- ✅ Full **TypeScript** support — typed request payloads and response objects\n- ⚡ **Promise-based** async/await API — clean and readable\n- 🔒 **Secure by default** — API key injected at transport level\n- 🌍 **Payments + Payouts** — single SDK for all money movement\n- 🔔 **Webhook support** — built-in HMAC-SHA256 signature verification\n- 🧪 **Sandbox-ready** — flip between test and live with one config change\n\n---\n\n## Installation\n\n```bash\nnpm install @afconwave/sdk\n# or\nyarn add @afconwave/sdk\n# or\npnpm add @afconwave/sdk\n```\n\n---\n\n## Quick Start\n\n```typescript\nimport { AfconWave } from '@afconwave/sdk';\n\nconst afw = new AfconWave({\n  secretKey: 'sk_test_your_key_here',\n  // baseUrl: 'https://api.afconwave.com/v1' // optional\n});\n```\n\n---\n\n## Usage Guide\n\n### Create a Payment\n\n```typescript\nconst payment = await afw.payments.create({\n  amount: 5000,           // Amount in minor units (e.g., 5000 = 50 XAF)\n  currency: 'XAF',       // ISO 4217: XAF, XOF, NGN, GHS, KES, etc.\n  description: 'Order #1234',\n  callback_url: 'https://yoursite.com/payment/callback',\n  customer: {\n    name: 'Jean Dupont',\n    email: 'jean@example.com',\n    phone: '+237600000000',\n  },\n  metadata: {\n    order_id: 'ORD-1234',\n  },\n});\n\nconsole.log(payment.checkout_url); // Redirect user here\nconsole.log(payment.id);           // e.g., pay_507f191e8180f\n```\n\n### Retrieve a Payment\n\n```typescript\nconst payment = await afw.payments.retrieve('pay_507f191e8180f');\n\nconsole.log(payment.status); // \"pending\" | \"success\" | \"failed\"\nconsole.log(payment.amount);\nconsole.log(payment.paid_at);\n```\n\n### Create a Payout\n\n```typescript\nconst payout = await afw.payouts.create({\n  amount: 10000,\n  currency: 'XAF',\n  reference: 'PAYOUT-REF-001',\n  recipient: {\n    phone: '+237600000001',\n    network: 'MTN',       // \"MTN\" | \"ORANGE\" | \"MOOV\" | \"WAVE\" | \"AIRTEL\"\n    name: 'Marie Kamga',\n  },\n});\n\nconsole.log(payout.status); // \"pending\" | \"success\" | \"failed\" | \"processing\"\n```\n\n### Check Balances\n\n```typescript\nconst balances = await afw.getBalances();\nconsole.log(balances); \n// [{ currency: 'XAF', available_balance: 45000, ... }]\n```\n\n### List Payments\n\n```typescript\nconst result = await afw.payments.list({\n  limit: 20,\n  status: 'success',\n});\n\nconsole.log(result.data);   // Array of PaymentResponse\nconsole.log(result.total);\n```\n\n---\n\n## Webhook Verification\n\nAlways verify that incoming webhooks are from AfconWave by checking the signature:\n\n```typescript\nimport { verifyWebhookSignature } from '@afconwave/sdk';\n\napp.post('/webhooks/afconwave', express.raw({ type: 'application/json' }), (req, res) => {\n  const signature = req.headers['x-afconwave-signature'] as string;\n  const webhookSecret = process.env.AFCONWAVE_WEBHOOK_SECRET!;\n\n  const isValid = verifyWebhookSignature({\n    payload: req.body.toString(),\n    signature,\n    secret: webhookSecret,\n  });\n\n  if (!isValid) {\n    return res.status(400).send('Invalid signature');\n  }\n\n  const event = JSON.parse(req.body.toString());\n\n  switch (event.event) {\n    case 'payment.success':\n      // Fulfill the order\n      console.log('Payment received:', event.data.id);\n      break;\n    case 'payment.failed':\n      // Notify the customer\n      break;\n    case 'payout.success':\n      // Update your records\n      break;\n  }\n\n  res.status(200).send('OK');\n});\n```\n\n---\n\n## Error Handling\n\nThe SDK throws typed errors you can handle by type:\n\n```typescript\nimport { AfconWave, AfconWaveError, AuthError, PaymentError } from '@afconwave/sdk';\n\ntry {\n  const payment = await afw.payments.create({ ... });\n} catch (err) {\n  if (err instanceof AuthError) {\n    console.error('Invalid API Key');\n  } else if (err instanceof PaymentError) {\n    console.error('Payment failed:', err.message, err.code);\n  } else if (err instanceof AfconWaveError) {\n    console.error('API Error:', err.status, err.message);\n  }\n}\n```\n\n---\n\n## Configuration\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `secretKey` | `string` | **required** | Your AfconWave secret API key |\n| `baseUrl` | `string` | `https://api.afconwave.com/v1` | API base URL (override for sandbox) |\n| `timeout` | `number` | `30000` | Request timeout in milliseconds |\n\n---\n\n## Sandbox / Testing\n\nUse test keys prefixed with `sk_test_` to run in sandbox mode. No real money moves.\n\n```typescript\nconst afw = new AfconWave({ secretKey: 'sk_test_...' });\n```\n\nSandbox test cards and phone numbers are listed at [docs.afconwave.com/testing](https://docs.afconwave.com/testing).\n\n---\n\n## TypeScript Support\n\nThis SDK ships with full TypeScript type definitions. All methods are fully typed, including request payloads and response objects:\n\n```typescript\nimport type { Payment, Payout, CreatePaymentPayload } from '@afconwave/sdk';\n```\n\n---\n\n## API Reference\n\nFull API documentation is available at [docs.afconwave.com/api-reference](https://docs.afconwave.com/api-reference).\n\n---\n\n## Contributing\n\n1. Fork the repository on [GitHub](https://github.com/afconwave/sdk-node)\n2. Create your feature branch: `git checkout -b feature/my-feature`\n3. Commit your changes: `git commit -m 'feat: add new feature'`\n4. Push and open a Pull Request\n\n---\n\n## License\n\nMIT © AfconWave\n","readmeFilename":"README.md","homepage":"https://docs.afconwave.com/sdks/nodejs","repository":{"type":"git","url":"git+https://github.com/afconwave/afconwave-node.git"},"bugs":{"url":"https://github.com/afconwave/afconwave-node/issues","email":"support@afconwave.com"}}