kobana 0.1.0

package/README.md

@@ -0,0 +1,230 @@
+# Kobana Node.js SDK
+
+Node.js SDK client for the [Kobana API](https://kobana.com.br) - Financial automation platform for Brazil.
+
+## Installation
+
+```bash
+npm install kobana
+```
+
+## Quick Start
+
+### Global Configuration
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+// 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)
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+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:
+
+```typescript
+import type {
+  PixChargeCreateParams,
+  BankBilletCreateParams,
+  BankBilletAccountCreateParams,
+} from 'kobana';
+
+const params: PixChargeCreateParams = {
+  amount: 1000,
+  customerPersonName: 'John Doe',
+};
+```
+
+## Development
+
+```bash
+# 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

package/dist/index.d.mts

@@ -0,0 +1,443 @@
+type Environment = 'sandbox' | 'production';
+type ApiVersion = 'v1' | 'v2';
+interface ConfigurationOptions {
+    apiToken: string;
+    environment?: Environment;
+    apiVersion?: ApiVersion;
+    customHeaders?: Record<string, string>;
+    debug?: boolean;
+}
+interface ConfigurationInterface {
+    apiToken: string;
+    environment: Environment;
+    apiVersion: ApiVersion;
+    customHeaders: Record<string, string>;
+    debug: boolean;
+    getBaseUrl(): string;
+    getHeaders(): Record<string, string>;
+}
+
+declare class Configuration implements ConfigurationInterface {
+    apiToken: string;
+    environment: Environment;
+    apiVersion: ApiVersion;
+    customHeaders: Record<string, string>;
+    debug: boolean;
+    constructor(options: ConfigurationOptions);
+    getBaseUrl(): string;
+    getHeaders(): Record<string, string>;
+    toString(): string;
+    toJSON(): Record<string, unknown>;
+}
+
+interface ApiResponse<T> {
+    data: T;
+    status: number;
+    headers: Record<string, string>;
+}
+interface ApiErrorResponse {
+    errors?: Array<{
+        message: string;
+        field?: string;
+        code?: string;
+    }>;
+    error?: string;
+    message?: string;
+}
+interface PaginationParams {
+    page?: number;
+    perPage?: number;
+}
+interface RequestOptions {
+    idempotencyKey?: string;
+    multipart?: boolean;
+}
+
+declare class Connection {
+    private axiosInstance;
+    private configuration;
+    constructor(configuration: Configuration);
+    private getAxiosInstance;
+    request<T>(method: 'get' | 'post' | 'put' | 'patch' | 'delete', url: string, data?: Record<string, unknown>, options?: RequestOptions): Promise<ApiResponse<T>>;
+    get<T>(url: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<ApiResponse<T>>;
+    post<T>(url: string, data?: Record<string, unknown>, options?: RequestOptions): Promise<ApiResponse<T>>;
+    put<T>(url: string, data?: Record<string, unknown>, options?: RequestOptions): Promise<ApiResponse<T>>;
+    patch<T>(url: string, data?: Record<string, unknown>, options?: RequestOptions): Promise<ApiResponse<T>>;
+    delete<T>(url: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    private handleError;
+}
+
+type ResourceAttributes = Record<string, unknown>;
+interface ResourceMeta {
+    id?: string | number;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+interface BankBilletAccountAttributes extends ResourceMeta {
+    bankContractSlug?: string;
+    nextOurNumber?: string;
+    agencyNumber?: string;
+    agencyDigit?: string;
+    accountNumber?: string;
+    accountDigit?: string;
+    extra1?: string;
+    extra1Digit?: string;
+    extra2?: string;
+    extra2Digit?: string;
+    beneficiaryName?: string;
+    beneficiaryCnpjCpf?: string;
+    beneficiaryAddress?: string;
+    name?: string;
+    status?: string;
+    homologatedAt?: string;
+    nextRemittanceNumber?: number;
+    configuration?: Record<string, unknown>;
+}
+interface BankBilletAccountCreateParams {
+    bankContractSlug: string;
+    nextOurNumber?: string;
+    agencyNumber: string;
+    agencyDigit?: string;
+    accountNumber: string;
+    accountDigit?: string;
+    extra1?: string;
+    extra1Digit?: string;
+    extra2?: string;
+    extra2Digit?: string;
+    beneficiaryName?: string;
+    beneficiaryCnpjCpf?: string;
+    beneficiaryAddress?: string;
+    name?: string;
+    configuration?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface BankBilletAccountListParams {
+    page?: number;
+    perPage?: number;
+    [key: string]: unknown;
+}
+interface BankBilletAttributes extends ResourceMeta {
+    amount?: number;
+    expireAt?: string;
+    customerPersonName?: string;
+    customerCnpjCpf?: string;
+    customerState?: string;
+    customerCityName?: string;
+    customerZipcode?: string;
+    customerAddress?: string;
+    customerNeighborhood?: string;
+    customerAddressNumber?: string;
+    customerAddressComplement?: string;
+    customerPhoneNumber?: string;
+    customerEmail?: string;
+    bankBilletAccountId?: number;
+    ourNumber?: string;
+    status?: string;
+    shippingStatus?: string;
+    meta?: Record<string, unknown>;
+    notes?: string;
+    instructions?: string;
+    demonstrative?: string;
+    acceptAfterDueDateDays?: number;
+    fineType?: number;
+    finePercentage?: number;
+    fineValue?: number;
+    interestType?: number;
+    interestDailyPercentage?: number;
+    interestDailyValue?: number;
+    interestMonthlyPercentage?: number;
+    discountType?: number;
+    discountLimitDate?: string;
+    discountValue?: number;
+    discountPercentage?: number;
+    discount2Type?: number;
+    discount2LimitDate?: string;
+    discount2Value?: number;
+    discount2Percentage?: number;
+    discount3Type?: number;
+    discount3LimitDate?: string;
+    discount3Value?: number;
+    discount3Percentage?: number;
+    guarantor?: Record<string, unknown>;
+    splitRules?: Array<Record<string, unknown>>;
+    pixEnabled?: boolean;
+}
+interface BankBilletCreateParams {
+    amount: number;
+    expireAt: string;
+    customerPersonName: string;
+    customerCnpjCpf: string;
+    customerState?: string;
+    customerCityName?: string;
+    customerZipcode?: string;
+    customerAddress?: string;
+    customerNeighborhood?: string;
+    customerAddressNumber?: string;
+    customerAddressComplement?: string;
+    customerPhoneNumber?: string;
+    customerEmail?: string;
+    bankBilletAccountId?: number;
+    meta?: Record<string, unknown>;
+    notes?: string;
+    instructions?: string;
+    demonstrative?: string;
+    acceptAfterDueDateDays?: number;
+    fineType?: number;
+    finePercentage?: number;
+    fineValue?: number;
+    interestType?: number;
+    interestDailyPercentage?: number;
+    interestDailyValue?: number;
+    interestMonthlyPercentage?: number;
+    discountType?: number;
+    discountLimitDate?: string;
+    discountValue?: number;
+    discountPercentage?: number;
+    pixEnabled?: boolean;
+    [key: string]: unknown;
+}
+interface BankBilletListParams {
+    page?: number;
+    perPage?: number;
+    status?: string;
+    customerCnpjCpf?: string;
+    ourNumber?: string;
+    createdFrom?: string;
+    createdTo?: string;
+    expireFrom?: string;
+    expireTo?: string;
+    paidFrom?: string;
+    paidTo?: string;
+    [key: string]: unknown;
+}
+interface PixChargeAttributes extends ResourceMeta {
+    amount?: number;
+    expireAt?: string;
+    status?: string;
+    customerPersonName?: string;
+    customerCnpjCpf?: string;
+    customerEmail?: string;
+    customerPhoneNumber?: string;
+    description?: string;
+    meta?: Record<string, unknown>;
+    qrCode?: string;
+    qrCodeUrl?: string;
+    copyPaste?: string;
+    txid?: string;
+    paidAt?: string;
+    paidAmount?: number;
+}
+interface PixChargeCreateParams {
+    amount: number;
+    expireAt?: string;
+    customerPersonName?: string;
+    customerCnpjCpf?: string;
+    customerEmail?: string;
+    customerPhoneNumber?: string;
+    description?: string;
+    meta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface PixChargeListParams {
+    page?: number;
+    perPage?: number;
+    status?: string;
+    createdFrom?: string;
+    createdTo?: string;
+    [key: string]: unknown;
+}
+
+declare class BaseResource {
+    static resourceEndpoint: string;
+    static primaryKeyField: string;
+    static _connection: Connection | undefined;
+    protected _connection: Connection | undefined;
+    protected _attributes: ResourceAttributes;
+    protected _errors: string[];
+    protected _created: boolean;
+    protected _updated: boolean;
+    constructor(attributes?: ResourceAttributes, connection?: Connection);
+    static withConnection(connection: Connection): typeof BaseResource;
+    protected static getConnection(): Connection;
+    static getUri(attributes?: ResourceAttributes): string;
+    static create(attributes: ResourceAttributes, options?: RequestOptions): Promise<BaseResource>;
+    static find(id: string | number, params?: ResourceAttributes): Promise<BaseResource | null>;
+    static all(params?: ResourceAttributes): Promise<BaseResource[]>;
+    static findBy(params: ResourceAttributes): Promise<BaseResource | null>;
+    static findOrCreateBy(params: ResourceAttributes, attributes?: ResourceAttributes, options?: RequestOptions): Promise<BaseResource>;
+    get attributes(): ResourceAttributes;
+    get errors(): string[];
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    get id(): string | number | undefined;
+    isNewRecord(): boolean;
+    isCreated(): boolean;
+    isUpdated(): boolean;
+    isValid(): boolean;
+    getUri(): string;
+    protected getConnection(): Connection;
+    save(options?: RequestOptions): Promise<this>;
+    update(newAttributes: ResourceAttributes, options?: RequestOptions): Promise<this>;
+    delete(): Promise<boolean>;
+    toJSON(): ResourceAttributes;
+}
+
+declare class Pix extends BaseResource {
+    static resourceEndpoint: string;
+    get amount(): number | undefined;
+    get expireAt(): string | undefined;
+    get status(): string | undefined;
+    get customerPersonName(): string | undefined;
+    get customerCnpjCpf(): string | undefined;
+    get customerEmail(): string | undefined;
+    get customerPhoneNumber(): string | undefined;
+    get description(): string | undefined;
+    get meta(): Record<string, unknown> | undefined;
+    get qrCode(): string | undefined;
+    get qrCodeUrl(): string | undefined;
+    get copyPaste(): string | undefined;
+    get txid(): string | undefined;
+    get paidAt(): string | undefined;
+    get paidAmount(): number | undefined;
+    get createdAt(): string | undefined;
+    get updatedAt(): string | undefined;
+    static create(attributes: PixChargeCreateParams, options?: RequestOptions): Promise<Pix>;
+    static find(id: string | number, params?: PixChargeListParams): Promise<Pix | null>;
+    static all(params?: PixChargeListParams): Promise<Pix[]>;
+    static findBy(params: PixChargeListParams): Promise<Pix | null>;
+    isPending(): boolean;
+    isPaid(): boolean;
+    isCanceled(): boolean;
+    isExpired(): boolean;
+}
+
+declare class BankBillet extends BaseResource {
+    static resourceEndpoint: string;
+    get amount(): number | undefined;
+    get expireAt(): string | undefined;
+    get customerPersonName(): string | undefined;
+    get customerCnpjCpf(): string | undefined;
+    get customerState(): string | undefined;
+    get customerCityName(): string | undefined;
+    get customerZipcode(): string | undefined;
+    get customerAddress(): string | undefined;
+    get customerNeighborhood(): string | undefined;
+    get customerAddressNumber(): string | undefined;
+    get customerAddressComplement(): string | undefined;
+    get customerPhoneNumber(): string | undefined;
+    get customerEmail(): string | undefined;
+    get bankBilletAccountId(): number | undefined;
+    get ourNumber(): string | undefined;
+    get status(): string | undefined;
+    get shippingStatus(): string | undefined;
+    get meta(): Record<string, unknown> | undefined;
+    get notes(): string | undefined;
+    get instructions(): string | undefined;
+    get pixEnabled(): boolean | undefined;
+    get createdAt(): string | undefined;
+    get updatedAt(): string | undefined;
+    static create(attributes: BankBilletCreateParams, options?: RequestOptions): Promise<BankBillet>;
+    static find(id: string | number, params?: BankBilletListParams): Promise<BankBillet | null>;
+    static all(params?: BankBilletListParams): Promise<BankBillet[]>;
+    static findBy(params: BankBilletListParams): Promise<BankBillet | null>;
+    isPending(): boolean;
+    isOpened(): boolean;
+    isPaid(): boolean;
+    isCanceled(): boolean;
+    isExpired(): boolean;
+}
+
+declare class BankBilletAccount extends BaseResource {
+    static resourceEndpoint: string;
+    get bankContractSlug(): string | undefined;
+    get nextOurNumber(): string | undefined;
+    get agencyNumber(): string | undefined;
+    get agencyDigit(): string | undefined;
+    get accountNumber(): string | undefined;
+    get accountDigit(): string | undefined;
+    get extra1(): string | undefined;
+    get extra1Digit(): string | undefined;
+    get extra2(): string | undefined;
+    get extra2Digit(): string | undefined;
+    get beneficiaryName(): string | undefined;
+    get beneficiaryCnpjCpf(): string | undefined;
+    get beneficiaryAddress(): string | undefined;
+    get name(): string | undefined;
+    get status(): string | undefined;
+    get homologatedAt(): string | undefined;
+    get nextRemittanceNumber(): number | undefined;
+    get configuration(): Record<string, unknown> | undefined;
+    get createdAt(): string | undefined;
+    get updatedAt(): string | undefined;
+    static create(attributes: BankBilletAccountCreateParams, options?: RequestOptions): Promise<BankBilletAccount>;
+    static find(id: string | number, params?: BankBilletAccountListParams): Promise<BankBilletAccount | null>;
+    static all(params?: BankBilletAccountListParams): Promise<BankBilletAccount[]>;
+    static findBy(params: BankBilletAccountListParams): Promise<BankBilletAccount | null>;
+    askHomologation(): Promise<this>;
+    validate(): Promise<this>;
+    setDefault(): Promise<this>;
+    isPending(): boolean;
+    isHomologating(): boolean;
+    isActive(): boolean;
+    isHomologated(): boolean;
+}
+
+interface ChargeProxy {
+    readonly pix: typeof Pix;
+    readonly bankBillet: typeof BankBillet;
+}
+interface FinancialProxy {
+    readonly bankBilletAccount: typeof BankBilletAccount;
+}
+declare class KobanaClient {
+    private _configuration;
+    private _connection;
+    private _chargeProxy;
+    private _financialProxy;
+    constructor(options: ConfigurationOptions);
+    get configuration(): Configuration;
+    configure(options: Partial<ConfigurationOptions>): void;
+    get charge(): ChargeProxy;
+    get financial(): FinancialProxy;
+}
+declare const Kobana: {
+    configure(options: ConfigurationOptions): void;
+    readonly configuration: Configuration | null;
+    readonly charge: ChargeProxy;
+    readonly financial: FinancialProxy;
+    Client: typeof KobanaClient;
+};
+
+declare class KobanaError extends Error {
+    constructor(message: string);
+}
+declare class ConfigurationError extends KobanaError {
+    constructor(message: string);
+}
+declare class ConnectionError extends KobanaError {
+    constructor(message: string);
+}
+declare class ResourceNotFoundError extends KobanaError {
+    constructor(message?: string);
+}
+declare class UnauthorizedError extends KobanaError {
+    constructor(message?: string);
+}
+declare class ValidationError extends KobanaError {
+    readonly errors: string[];
+    constructor(message: string, errors?: string[]);
+}
+declare class APIError extends KobanaError {
+    readonly status: number;
+    readonly responseBody: unknown;
+    readonly errors: string[];
+    constructor(options: {
+        message?: string;
+        status: number;
+        responseBody?: unknown;
+        errors?: string[];
+    });
+}
+
+export { APIError, type ApiErrorResponse, type ApiResponse, type ApiVersion, BankBillet, BankBilletAccount, type BankBilletAccountAttributes, type BankBilletAccountCreateParams, type BankBilletAccountListParams, type BankBilletAttributes, type BankBilletCreateParams, type BankBilletListParams, BaseResource, Configuration, ConfigurationError, type ConfigurationInterface, type ConfigurationOptions, Connection, ConnectionError, type Environment, Kobana, KobanaClient, KobanaError, type PaginationParams, Pix, type PixChargeAttributes, type PixChargeCreateParams, type PixChargeListParams, type RequestOptions, type ResourceAttributes, type ResourceMeta, ResourceNotFoundError, UnauthorizedError, ValidationError };