Biller API SDK

A TypeScript/JavaScript SDK for interacting with the Biller API. This SDK provides a convenient interface for managing billers, categories, providers, and OAuth authentication.

Installation

npm install @biller-api/sdk

Quick Start

import { BillerApiClient } from '@biller-api/sdk';

// Initialize the client
const client = new BillerApiClient({
  baseUrl: 'https://your-api-url.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

// Get an access token
const tokenResponse = await client.getAccessToken({
  grant_type: 'client_credentials',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
});

// List all billers
const billers = await client.listBillers();
console.log(billers.data);

Authentication

The SDK supports OAuth 2.0 authentication with the following grant types:

Client Credentials Grant

const tokenResponse = await client.getAccessToken({
  grant_type: 'client_credentials',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
});

Refresh Token Grant

const tokenResponse = await client.refreshAccessToken('your-refresh-token');

Manual Token Setting

If you already have an access token, you can set it directly:

client.setAccessToken('your-access-token');

API Methods

Billers

List Billers

// Get all billers
const allBillers = await client.listBillers();

// Filter by status
const activeBillers = await client.listBillers({ status: true });

// Filter by provider
const providerBillers = await client.listBillers({
  providerId: 'provider-uuid',
  page: 1,
  pageSize: 50
});

Get a Specific Biller

const biller = await client.getBiller('biller-uuid');
console.log(biller.data);

Create a Biller

const newBiller = await client.createBiller({
  short_name: 'ACME',
  long_name: 'ACME Corporation',
  description: 'Utility provider',
  status: true,
  logo: 'https://example.com/logo.png',
  data_fields: {},
  service_charge: 10.5,
  remarks: 'Additional information',
  metadata: {},
  category_id: 'category-uuid',
  provider_id: 'provider-uuid',
});

Update a Biller

const updatedBiller = await client.updateBiller('biller-uuid', {
  long_name: 'Updated Corporation Name',
  service_charge: 12.0,
});

Delete a Biller

await client.deleteBiller('biller-uuid');

Categories

List Categories

const categories = await client.listCategories({ status: true });

Get a Category

const category = await client.getCategory('category-uuid');

Create a Category

const newCategory = await client.createCategory({
  name: 'Utilities',
  description: 'Utility service providers',
  status: true,
  logo: 'https://example.com/utilities-logo.png',
  metadata: {},
});

Update a Category

const updatedCategory = await client.updateCategory('category-uuid', {
  name: 'Updated Category Name',
  status: false,
});

Delete a Category

await client.deleteCategory('category-uuid');

Providers

List Providers

const providers = await client.listProviders({ status: true });

Get a Provider

const provider = await client.getProvider('provider-uuid');

Create a Provider

const newProvider = await client.createProvider({
  name: 'Utility Corp',
  description: 'Major utility provider',
  status: true,
  logo: 'https://example.com/provider-logo.png',
  metadata: {},
});

Update a Provider

const updatedProvider = await client.updateProvider('provider-uuid', {
  name: 'Updated Provider Name',
  status: true,
});

Delete a Provider

await client.deleteProvider('provider-uuid');

OAuth Methods

Token Introspection

Check if a token is valid and get its information:

const tokenInfo = await client.introspectToken('your-access-token');
if (tokenInfo.active) {
  console.log('Token is valid:', tokenInfo);
}

Token Revocation

Revoke a refresh token:

await client.revokeToken('your-refresh-token');

Error Handling

The SDK throws BillerApiError for API errors:

import { BillerApiClient, BillerApiError } from '@biller-api/sdk';

try {
  const biller = await client.getBiller('non-existent-id');
} catch (error) {
  if (error instanceof BillerApiError) {
    console.log('API Error:', error.message);
    console.log('Status Code:', error.statusCode);
    console.log('Details:', error.details);
  }
}

Configuration Options

const client = new BillerApiClient({
  baseUrl: 'https://your-api-url.com',           // Required: Base URL of the API
  clientId: 'your-client-id',                    // Optional: OAuth client ID
  clientSecret: 'your-client-secret',            // Optional: OAuth client secret
  accessToken: 'your-access-token',              // Optional: Pre-existing access token
  timeout: 10000,                                // Optional: Request timeout in ms (default: 10000)
});

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import {
  Biller,
  Category,
  Provider,
  NewBiller,
  BillerQueryParams,
  TokenResponse
} from '@biller-api/sdk';

// All types are fully typed for better development experience

Pagination

List methods support pagination:

const response = await client.listBillers({
  page: 1,
  pageSize: 50
});

console.log('Total items:', response.pagination.total);
console.log('Current page:', response.pagination.page);
console.log('Total pages:', response.pagination.totalPages);
console.log('Data:', response.data);

Development

Building

npm run build

Testing

npm test

Linting

npm run lint

Examples

See the examples/ directory for more comprehensive usage examples:

• Basic Usage
• Authentication
• Error Handling
• Pagination

License

MIT License - see LICENSE file for details.

Support

For issues and questions, please open an issue on GitHub.