Kobana Node.js SDK

Node.js SDK client for the Kobana API - Financial automation platform for Brazil.

Installation

npm install kobana

Quick Start

Global Configuration

import { Kobana } from 'kobana';

// Configure once at application startup
Kobana.configure({
  apiToken: 'your-api-token',
  environment: 'sandbox', // or 'production'
});

// Create a PIX charge
const pix = await Kobana.charge.pix.create({
  amount: 1000, // R$ 10.00 in cents
  customerPersonName: 'John Doe',
  customerCnpjCpf: '12345678901',
});

console.log(pix.qrCode);
console.log(pix.copyPaste);

Multi-Client Configuration

For multi-tenant applications or when you need multiple configurations:

import { KobanaClient } from 'kobana';

const client = new KobanaClient({
  apiToken: 'tenant-specific-token',
  environment: 'production',
});

const billets = await client.charge.bankBillet.all({ page: 1, perPage: 20 });

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiToken | string | (required) | Your Kobana API token | | environment | 'sandbox' | 'production' | 'sandbox' | API environment | | apiVersion | 'v1' | 'v2' | 'v1' | API version | | customHeaders | object | {} | Additional HTTP headers | | debug | boolean | false | Enable debug mode |

Available Resources

Charge Resources

PIX

// Create a PIX charge
const pix = await Kobana.charge.pix.create({
  amount: 5000, // R$ 50.00
  customerPersonName: 'Customer Name',
  customerCnpjCpf: '12345678901',
  description: 'Payment for order #123',
});

// Find a PIX charge by ID
const pixCharge = await Kobana.charge.pix.find(123);

// List PIX charges
const charges = await Kobana.charge.pix.all({
  page: 1,
  perPage: 50,
  status: 'pending',
});

// Check status
if (pix.isPaid()) {
  console.log('Payment received!');
}

Bank Billet (Boleto)

// Create a bank billet
const billet = await Kobana.charge.bankBillet.create({
  amount: 10000, // R$ 100.00
  expireAt: '2024-12-31',
  customerPersonName: 'Customer Name',
  customerCnpjCpf: '12345678901',
  customerAddress: 'Av Paulista, 1000',
  customerCityName: 'Sao Paulo',
  customerState: 'SP',
  customerZipcode: '01310100',
  customerNeighborhood: 'Bela Vista',
});

// Find a billet by ID
const found = await Kobana.charge.bankBillet.find(456);

// List billets with filters
const billets = await Kobana.charge.bankBillet.all({
  status: 'opened',
  expireFrom: '2024-01-01',
  expireTo: '2024-12-31',
});

Financial Resources

Bank Billet Account

// Create a bank billet account
const account = await Kobana.financial.bankBilletAccount.create({
  bankContractSlug: 'bradesco-bs-9',
  agencyNumber: '1234',
  accountNumber: '12345',
  accountDigit: '6',
  beneficiaryName: 'My Company',
  beneficiaryCnpjCpf: '12345678000199',
});

// List accounts
const accounts = await Kobana.financial.bankBilletAccount.all();

// Request homologation
await account.askHomologation();

// Validate after homologation
await account.validate();

// Set as default account
await account.setDefault();

Resource Methods

All resources support the following methods:

| Method | Description | |--------|-------------| | create(attributes) | Create a new resource | | find(id) | Find a resource by ID | | all(params) | List all resources with pagination | | findBy(params) | Find first matching resource | | findOrCreateBy(params, attributes) | Find or create a resource |

Instance methods:

| Method | Description | |--------|-------------| | save() | Save a new or update existing resource | | update(attributes) | Update resource with new attributes | | delete() | Delete the resource |

Error Handling

import {
  KobanaError,
  APIError,
  UnauthorizedError,
  ResourceNotFoundError,
  ValidationError,
} from 'kobana';

try {
  const pix = await Kobana.charge.pix.create({ amount: 1000 });
} catch (error) {
  if (error instanceof UnauthorizedError) {
    console.error('Invalid API token');
  } else if (error instanceof ValidationError) {
    console.error('Validation errors:', error.errors);
  } else if (error instanceof APIError) {
    console.error(`API error ${error.status}:`, error.errors);
  } else if (error instanceof KobanaError) {
    console.error('Kobana error:', error.message);
  }
}

TypeScript Support

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

import type {
  PixChargeCreateParams,
  BankBilletCreateParams,
  BankBilletAccountCreateParams,
} from 'kobana';

const params: PixChargeCreateParams = {
  amount: 1000,
  customerPersonName: 'John Doe',
};

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests once
npm run test:run

# Type check
npm run typecheck

# Build
npm run build

License

MIT