{"_id":"@domdanao/biller-api-sdk","name":"@domdanao/biller-api-sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@domdanao/biller-api-sdk","version":"1.0.0","description":"JavaScript/TypeScript SDK for the Biller API","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","prepublishOnly":"npm run build","test":"jest","lint":"eslint src/**/*.ts","format":"prettier --write src/**/*.ts"},"keywords":["api","sdk","biller","oauth","typescript","javascript"],"author":{"name":"Biller API Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/biller-api/sdk.git"},"bugs":{"url":"https://github.com/biller-api/sdk/issues"},"homepage":"https://github.com/biller-api/sdk#readme","dependencies":{},"devDependencies":{"@types/jest":"^29.5.0","@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","jest":"^29.5.0","prettier":"^3.0.0","ts-jest":"^29.1.0","typescript":"^5.0.0"},"engines":{"node":">=16.0.0"},"_id":"@domdanao/biller-api-sdk@1.0.0","gitHead":"b4865ba12399e9028176209d7c266fa5095ba67c","_nodeVersion":"24.3.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-UAiqmdq/w1JylLgiWfgLOgevA59Cw5p53mbmgVCfpBeivYP/qPoHQEga6pN3bSgqpkvrzGWkHdg0p4L2+JIgdA==","shasum":"622822dc3c0e5781327df016a167f79407381280","tarball":"https://registry.npmjs.org/@domdanao/biller-api-sdk/-/biller-api-sdk-1.0.0.tgz","fileCount":15,"unpackedSize":38933,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCbKlt1NOR2WUIKvyuAeOb0lQUSiGJIe+nDRiUELqSmWQIhAOJV2h0kRDG7338o41f6nEq0noLfRURCPdckCvq1zy91"}]},"_npmUser":{"name":"domdanao","email":"dom@danao.co"},"directories":{},"maintainers":[{"name":"domdanao","email":"dom@danao.co"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/biller-api-sdk_1.0.0_1755781281886_0.8399437214535701"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-21T13:01:21.746Z","1.0.0":"2025-08-21T13:01:22.065Z","modified":"2025-08-21T13:01:22.360Z"},"maintainers":[{"name":"domdanao","email":"dom@danao.co"}],"description":"JavaScript/TypeScript SDK for the Biller API","homepage":"https://github.com/biller-api/sdk#readme","keywords":["api","sdk","biller","oauth","typescript","javascript"],"repository":{"type":"git","url":"git+https://github.com/biller-api/sdk.git"},"author":{"name":"Biller API Team"},"bugs":{"url":"https://github.com/biller-api/sdk/issues"},"license":"MIT","readme":"# Biller API SDK\n\nA TypeScript/JavaScript SDK for interacting with the Biller API. This SDK provides a convenient interface for managing billers, categories, providers, and OAuth authentication.\n\n## Installation\n\n```bash\nnpm install @biller-api/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { BillerApiClient } from '@biller-api/sdk';\n\n// Initialize the client\nconst client = new BillerApiClient({\n  baseUrl: 'https://your-api-url.com',\n  clientId: 'your-client-id',\n  clientSecret: 'your-client-secret',\n});\n\n// Get an access token\nconst tokenResponse = await client.getAccessToken({\n  grant_type: 'client_credentials',\n  client_id: 'your-client-id',\n  client_secret: 'your-client-secret',\n});\n\n// List all billers\nconst billers = await client.listBillers();\nconsole.log(billers.data);\n```\n\n## Authentication\n\nThe SDK supports OAuth 2.0 authentication with the following grant types:\n\n### Client Credentials Grant\n\n```typescript\nconst tokenResponse = await client.getAccessToken({\n  grant_type: 'client_credentials',\n  client_id: 'your-client-id',\n  client_secret: 'your-client-secret',\n});\n```\n\n### Refresh Token Grant\n\n```typescript\nconst tokenResponse = await client.refreshAccessToken('your-refresh-token');\n```\n\n### Manual Token Setting\n\nIf you already have an access token, you can set it directly:\n\n```typescript\nclient.setAccessToken('your-access-token');\n```\n\n## API Methods\n\n### Billers\n\n#### List Billers\n\n```typescript\n// Get all billers\nconst allBillers = await client.listBillers();\n\n// Filter by status\nconst activeBillers = await client.listBillers({ status: true });\n\n// Filter by provider\nconst providerBillers = await client.listBillers({\n  providerId: 'provider-uuid',\n  page: 1,\n  pageSize: 50\n});\n```\n\n#### Get a Specific Biller\n\n```typescript\nconst biller = await client.getBiller('biller-uuid');\nconsole.log(biller.data);\n```\n\n#### Create a Biller\n\n```typescript\nconst newBiller = await client.createBiller({\n  short_name: 'ACME',\n  long_name: 'ACME Corporation',\n  description: 'Utility provider',\n  status: true,\n  logo: 'https://example.com/logo.png',\n  data_fields: {},\n  service_charge: 10.5,\n  remarks: 'Additional information',\n  metadata: {},\n  category_id: 'category-uuid',\n  provider_id: 'provider-uuid',\n});\n```\n\n#### Update a Biller\n\n```typescript\nconst updatedBiller = await client.updateBiller('biller-uuid', {\n  long_name: 'Updated Corporation Name',\n  service_charge: 12.0,\n});\n```\n\n#### Delete a Biller\n\n```typescript\nawait client.deleteBiller('biller-uuid');\n```\n\n### Categories\n\n#### List Categories\n\n```typescript\nconst categories = await client.listCategories({ status: true });\n```\n\n#### Get a Category\n\n```typescript\nconst category = await client.getCategory('category-uuid');\n```\n\n#### Create a Category\n\n```typescript\nconst newCategory = await client.createCategory({\n  name: 'Utilities',\n  description: 'Utility service providers',\n  status: true,\n  logo: 'https://example.com/utilities-logo.png',\n  metadata: {},\n});\n```\n\n#### Update a Category\n\n```typescript\nconst updatedCategory = await client.updateCategory('category-uuid', {\n  name: 'Updated Category Name',\n  status: false,\n});\n```\n\n#### Delete a Category\n\n```typescript\nawait client.deleteCategory('category-uuid');\n```\n\n### Providers\n\n#### List Providers\n\n```typescript\nconst providers = await client.listProviders({ status: true });\n```\n\n#### Get a Provider\n\n```typescript\nconst provider = await client.getProvider('provider-uuid');\n```\n\n#### Create a Provider\n\n```typescript\nconst newProvider = await client.createProvider({\n  name: 'Utility Corp',\n  description: 'Major utility provider',\n  status: true,\n  logo: 'https://example.com/provider-logo.png',\n  metadata: {},\n});\n```\n\n#### Update a Provider\n\n```typescript\nconst updatedProvider = await client.updateProvider('provider-uuid', {\n  name: 'Updated Provider Name',\n  status: true,\n});\n```\n\n#### Delete a Provider\n\n```typescript\nawait client.deleteProvider('provider-uuid');\n```\n\n## OAuth Methods\n\n### Token Introspection\n\nCheck if a token is valid and get its information:\n\n```typescript\nconst tokenInfo = await client.introspectToken('your-access-token');\nif (tokenInfo.active) {\n  console.log('Token is valid:', tokenInfo);\n}\n```\n\n### Token Revocation\n\nRevoke a refresh token:\n\n```typescript\nawait client.revokeToken('your-refresh-token');\n```\n\n## Error Handling\n\nThe SDK throws `BillerApiError` for API errors:\n\n```typescript\nimport { BillerApiClient, BillerApiError } from '@biller-api/sdk';\n\ntry {\n  const biller = await client.getBiller('non-existent-id');\n} catch (error) {\n  if (error instanceof BillerApiError) {\n    console.log('API Error:', error.message);\n    console.log('Status Code:', error.statusCode);\n    console.log('Details:', error.details);\n  }\n}\n```\n\n## Configuration Options\n\n```typescript\nconst client = new BillerApiClient({\n  baseUrl: 'https://your-api-url.com',           // Required: Base URL of the API\n  clientId: 'your-client-id',                    // Optional: OAuth client ID\n  clientSecret: 'your-client-secret',            // Optional: OAuth client secret\n  accessToken: 'your-access-token',              // Optional: Pre-existing access token\n  timeout: 10000,                                // Optional: Request timeout in ms (default: 10000)\n});\n```\n\n## TypeScript Support\n\nThe SDK is written in TypeScript and provides full type definitions:\n\n```typescript\nimport {\n  Biller,\n  Category,\n  Provider,\n  NewBiller,\n  BillerQueryParams,\n  TokenResponse\n} from '@biller-api/sdk';\n\n// All types are fully typed for better development experience\n```\n\n## Pagination\n\nList methods support pagination:\n\n```typescript\nconst response = await client.listBillers({\n  page: 1,\n  pageSize: 50\n});\n\nconsole.log('Total items:', response.pagination.total);\nconsole.log('Current page:', response.pagination.page);\nconsole.log('Total pages:', response.pagination.totalPages);\nconsole.log('Data:', response.data);\n```\n\n## Development\n\n### Building\n\n```bash\nnpm run build\n```\n\n### Testing\n\n```bash\nnpm test\n```\n\n### Linting\n\n```bash\nnpm run lint\n```\n\n## Examples\n\nSee the `examples/` directory for more comprehensive usage examples:\n\n- [Basic Usage](./examples/basic-usage.ts)\n- [Authentication](./examples/authentication.ts)\n- [Error Handling](./examples/error-handling.ts)\n- [Pagination](./examples/pagination.ts)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor issues and questions, please open an issue on [GitHub](https://github.com/biller-api/sdk/issues).","readmeFilename":"README.md","_rev":"1-aed2d49a662b676beabb387a9864ecf1"}