# Akua SDK

[![npm version](https://img.shields.io/npm/v/akua-sdk.svg)](https://www.npmjs.com/package/akua-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

A modern TypeScript SDK for integrating with the Akua Payment Gateway. This SDK provides a type-safe and developer-friendly way to interact with Akua's payment processing services.

⚠️ **This SDK is in BETA stage and it can sometimes have differences from the official Akua API.**
Access and usage are strictly limited to teams authorized by Akua.

## 📋 Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Reference](#api-reference)
  - [Authentication](#authentication)
  - [Creating an AkuaClient instance](#creating-an-akuaclient-instance)
  - [Organizations](#organizations)
  - [Merchants](#merchants)
  - [Payment Instruments](#payment-instruments)
  - [Payments](#payments)
  - [Webhooks](#webhooks)
- [TypeScript Types](#typescript-types)
  - [Available Types](#available-types)
  - [Type Categories](#type-categories)
  - [Type Safety Example](#type-safety-example)
- [Error Handling](#error-handling)
- [License](#license)

<a id="features"></a>

## ✨ Features

- 🔒 Full TypeScript support with comprehensive type definitions
- 🚀 SDK functionalities:
  - Automatic token management (generation and refresh)
  - Organization Management
    - Create and manage organizations
    - Group related business entities
  - Merchant Management
    - Create, update, and delete merchants
    - Configure payment rails (VISA, Mastercard)
    - Set up merchant profiles and settings
  - Payment Instruments
    - Tokenize and store payment methods
    - Manage card information securely
    - Support for multiple payment methods
  - Payment Processing
    - Authorization with PAN or token
    - Automatic and manual capture modes
    - Payment cancellation
    - Refund processing
    - Payment verification
    - Installment support
  - Webhook Management
    - Configure webhook endpoints
    - Set up event notifications
    - Manage webhook secrets
- ⚡ Modern async/await API
- 🛡️ Built-in error handling
- 📚 Comprehensive documentation
- 🔐 Secure token management
- 🌐 Multi-currency support
- 🏢 Multi-tenant architecture

<a id="installation"></a>

## 📦 Installation

```bash
# Using npm
npm install akua-sdk

# Using yarn
yarn add akua-sdk

# Using pnpm
pnpm add akua-sdk
```

<a id="quick-start"></a>

## 🚀 Quick Start

```typescript
import { AkuaClient, AkuaTypes } from 'akua-sdk';

// Create the AkuaClient instance with your credentials
// The client will automatically handle token management
const akuaClientConfig: AkuaTypes.ClientConfig = {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  environment: AkuaTypes.Enums.Environment.SANDBOX, // or PRODUCTION
};

const akuaClient = new AkuaClient(akuaClientConfig);

// Now you can use the AkuaClient instance
const createOrganizationRequest: AkuaTypes.RequestTypes.CreateOrganizationRequest = {
  name: 'My Organization',
};

const createOrganizationResponse: AkuaTypes.ApiResponse<AkuaTypes.ResponseTypes.OrganizationDTO> =
  await akuaClient.organizations.create(createOrganizationRequest);

if (!createOrganizationResponse.success || !createOrganizationResponse.data) {
  throw new Error('Create organization failed');
}

const organization: AkuaTypes.ResponseTypes.OrganizationDTO = createOrganizationResponse.data;

const createMerchantRequest: AkuaTypes.RequestTypes.CreateMerchantRequest = {
  name: 'My Store',
  organization_id: organization.id,
  country: 'US',
  city: 'New York',
  state: 'NY',
  billing_address: {
    street: '123 Main St',
    city: 'New York',
    state: 'NY',
    country: 'US',
    postal_code: '10001',
  },
  location_address: {
    street: '123 Main St',
    city: 'New York',
    state: 'NY',
    country: 'US',
    postal_code: '10001',
  },
  classification_mode: 'retail',
  default_currency: 'USD',
  supported_currencies: ['USD', 'EUR'],
  activity: 'retail',
  alias: 'my-store-ny',
  email: 'store@example.com',
  external_id: 'ext_123',
  phone: '+1234567890',
  tax_id: '123456789',
  rails: {
    VISA: {
      category_code: '5411',
      payfac_id: 'payfac_123',
    },
    MASTERCARD: {
      category_code: '5411',
      payfac_id: 'payfac_123',
    },
  },
};

const createMerchantResponse: AkuaTypes.ApiResponse<AkuaTypes.ResponseTypes.MerchantDTO> =
  await akuaClient.merchants.create(createMerchantRequest);

if (!createMerchantResponse.success || !createMerchantResponse.data) {
  throw new Error('Create merchant failed');
}

const merchant: AkuaTypes.ResponseTypes.MerchantDTO = createMerchantResponse.data;

const createInstrumentRequest: AkuaTypes.RequestTypes.CreateInstrumentRequest = {
  type: 'CARD',
  card: {
    number: '4242424242424242',
    expiration_month: '12',
    expiration_year: '2030',
    first_name: 'John',
    last_name: 'Doe',
    cvv: '123',
  },
  user_data: {
    billing_address: {
      street: '123 Main St',
      number: 'Apt 4B',
      city: 'New York',
      state: 'NY',
      zip_code: '10001',
      country: 'US',
    },
  },
};

const createInstrumentResponse: AkuaTypes.ApiResponse<AkuaTypes.ResponseTypes.InstrumentDTO> =
  await akuaClient.instruments.create(createInstrumentRequest);

if (!createInstrumentResponse.success || !createInstrumentResponse.data) {
  throw new Error('Create instrument failed');
}

const instrument: AkuaTypes.ResponseTypes.InstrumentDTO = createInstrumentResponse.data;
```

<a id="api-reference"></a>

## 📋 API Reference

### Authentication

The SDK handles authentication automatically. When you create an `AkuaClient` instance with your client credentials, it will:

1. Generate an initial token using your credentials
2. Automatically refresh the token before it expires (with a 5-minute buffer)
3. Handle token reuse across all requests
4. Manage concurrent token refresh requests
5. Handle authentication errors gracefully

### Creating an AkuaClient instance

The `AkuaClient` is the main entry point for interacting with the Akua API. It requires your client credentials and an environment configuration.

```typescript
import { AkuaClient, AkuaTypes } from 'akua-sdk';

const clientConfig: AkuaTypes.ClientConfig = {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  environment: AkuaTypes.Enums.Environment.SANDBOX, // or PRODUCTION
};

const akuaClient = new AkuaClient(clientConfig);
```

### Organizations

#### `organizations.create(data: CreateOrganizationRequest): Promise<ApiResponse<OrganizationDTO>>`

Creates a new organization in the Akua system. Organizations can have multiple merchants and are used to group related business entities.

```typescript
const organization = await akuaClient.organizations.create({
  name: 'Acme Corp',
});
```

#### `organizations.get(): Promise<ApiResponse<OrganizationDTO[]>>`

Retrieves all organizations from the Akua system.

```typescript
const organizations = await akuaClient.organizations.get();
```

### Merchants

#### `merchants.create(data: CreateMerchantRequest): Promise<ApiResponse<MerchantDTO>>`

Creates a new merchant in the Akua system. This is the first step in setting up a new merchant account. The merchant will be associated with the specified organization and will be configured with the provided payment rails and settings.

```typescript
const merchant = await akuaClient.merchants.create({
  name: 'My Store',
  organization_id: 'org_123',
  country: AkuaTypes.Enums.Country.UNITED_STATES,
  city: 'New York',
  state: 'NY',
  billing_address: {
    street: '123 Main St',
    city: 'New York',
    state: 'NY',
    country: AkuaTypes.Enums.Country.UNITED_STATES,
    postal_code: '10001',
  },
  location_address: {
    street: '123 Main St',
    city: 'New York',
    state: 'NY',
    country: AkuaTypes.Enums.Country.UNITED_STATES,
    postal_code: '10001',
  },
  classification_mode: 'retail',
  default_currency: AkuaTypes.Enums.Currency.USD,
  supported_currencies: [AkuaTypes.Enums.Currency.USD, AkuaTypes.Enums.Currency.EUR],
  activity: 'retail',
  alias: 'my-store-ny',
  email: 'store@example.com',
  external_id: 'ext_123',
  phone: '+1234567890',
  tax_id: '123456789',
  rails: {
    [AkuaTypes.Enums.Rail.VISA]: {
      category_code: '5411',
      payfac_id: 'payfac_123',
    },
    [AkuaTypes.Enums.Rail.MASTERCARD]: {
      category_code: '5411',
      payfac_id: 'payfac_123',
    },
  },
});
```

#### `merchants.getById(merchantId: string): Promise<ApiResponse<MerchantDTO>>`

Retrieves a merchant's information by its unique identifier.

```typescript
const merchant = await akuaClient.merchants.getById('merch_123456789');
```

#### `merchants.get(request: GetMerchantsRequest): Promise<ApiResponse<MerchantDTO[]>>`

Lists all merchants for an organization with pagination support.

```typescript
const merchants = await akuaClient.merchants.get({
  organization_id: 'org-d0j35vc4t5u70r4eso70',
  page: 1,
  page_size: 20,
  sort: 'created_at:desc',
});
```

#### `merchants.update(merchantId: string, data: UpdateMerchantRequest): Promise<ApiResponse<MerchantDTO>>`

Updates an existing merchant's information.

```typescript
const updatedMerchant = await akuaClient.merchants.update('merch_123456789', {
  name: 'Updated Store Name',
  email: 'updated@example.com',
  phone: '+1987654321',
  billing_address: {
    street: '456 New St',
    city: 'Los Angeles',
    state: 'CA',
    country: AkuaTypes.Enums.Country.UNITED_STATES,
    postal_code: '90001',
  },
});
```

#### `merchants.updateRails(merchantId: string, data: UpdateMerchantRailsRequest): Promise<ApiResponse<MerchantDTO>>`

Updates the rails configuration for a merchant.

```typescript
const updatedMerchant = await akuaClient.merchants.updateRails('merch_123456789', {
  [AkuaTypes.Enums.Rail.VISA]: {
    category_code: '1234',
    payfac_id: 'pfc-123',
    external_id: 'mer-ext-123',
    classification: 'micro-merchant',
    annual_volume: [
      {
        currency: AkuaTypes.Enums.Currency.COP,
        value: 10000000,
      },
    ],
    products: {
      [AkuaTypes.Enums.Product.DEBIT]: {
        network_merchant_id: 'VISA-123',
        enabled: true,
      },
      [AkuaTypes.Enums.Product.CREDIT]: {
        network_merchant_id: 'VISA-123',
        enabled: true,
      },
    },
  },
});
```

#### `merchants.delete(merchantId: string): Promise<ApiResponse<void>>`

Deletes a merchant from the Akua system.

```typescript
await akuaClient.merchants.delete('merch_123456789');
```

### Payment Instruments

#### `instruments.create(data: CreateInstrumentRequest): Promise<ApiResponse<InstrumentDTO>>`

Creates a new payment instrument. The instrument is tokenized and stored securely in the Akua system.

```typescript
const card = await akuaClient.instruments.create({
  type: 'CARD',
  card: {
    number: '4242424242424242',
    expiration_month: '12',
    expiration_year: '2025',
    first_name: 'John',
    last_name: 'Doe',
    cvv: '123',
  },
  user_data: {
    billing_address: {
      street: '123 Main St',
      number: 'Apt 4B',
      city: 'New York',
      state: 'NY',
      zip_code: '10001',
      country: AkuaTypes.Enums.Country.UNITED_STATES,
    },
  },
});
```

#### `instruments.get(): Promise<ApiResponse<InstrumentDTO[]>>`

Retrieves all payment instruments associated with the merchant. This includes both active and inactive instruments, with their current status and details.

```typescript
const instruments = await akuaClient.instruments.get();
```

#### `instruments.getById(id: string): Promise<ApiResponse<InstrumentDTO>>`

Retrieves detailed information about a specific payment instrument, including its type and status.

```typescript
const instrument = await akuaClient.instruments.getById('instr_123');
```

#### `instruments.update(id: string, data: UpdateInstrumentRequest): Promise<ApiResponse<InstrumentDTO>>`

Updates an existing payment instrument's information. This can be used to update expiration dates, cardholder information, or other instrument details.

```typescript
const updatedInstrument = await akuaClient.instruments.update('instr_123', {
  card: {
    expiration_month: '12',
    expiration_year: '2026',
    first_name: 'John',
    last_name: 'Smith',
  },
});
```

#### `instruments.delete(id: string): Promise<ApiResponse<void>>`

Permanently deletes a payment instrument from the system. This operation cannot be undone and will invalidate the instrument for future use.

```typescript
await client.instruments.delete('instr_123');
```

### Payments

#### `payments.authorizeWithPan(data: AuthorizeWithPanRequest): Promise<ApiResponse<AuthorizePaymentDTO>>`

Authorizes a payment transaction using PAN (Primary Account Number). This is used for direct card payments.

```typescript
const payment = await akuaClient.payments.authorizeWithPan({
  amount: {
    value: 25.25,
    currency: AkuaTypes.Enums.Currency.USD,
  },
  intent: AkuaTypes.Enums.PaymentIntent.AUTHORIZATION,
  trace_id: 'any-format-34324366',
  entry_mode: AkuaTypes.Enums.PaymentEntryMode.MANUAL,
  capture: {
    mode: AkuaTypes.Enums.CaptureMode.AUTOMATIC,
  },
  merchant_id: 'mer-d0r0b17npsai542l2400',
  installments: {
    quantity: 2,
    type: '03',
  },
  instrument: {
    type: 'CARD',
    card: {
      number: '4024007108904086',
      expiration_month: '12',
      expiration_year: '25',
      holder_name: 'John Doe',
      cvv: '123',
    },
    user_data: {
      billing_address: {
        street: '123 Main St',
        number: 'Apt 4B',
        city: 'New York',
        state: 'NY',
        zip_code: '10001',
        country: AkuaTypes.Enums.Country.UNITED_STATES,
        phone_number: '+1234567890',
      },
    },
  },
});
```

#### `payments.authorizeWithToken(data: AuthorizeWithTokenRequest): Promise<ApiResponse<AuthorizePaymentDTO>>`

Authorizes a payment transaction using a previously tokenized instrument.

```typescript
const payment = await akuaClient.payments.authorizeWithToken({
  amount: {
    value: 25.25,
    currency: AkuaTypes.Enums.Currency.USD,
  },
  intent: AkuaTypes.Enums.PaymentIntent.AUTHORIZATION,
  trace_id: 'any-format-34324366',
  entry_mode: AkuaTypes.Enums.PaymentEntryMode.MANUAL,
  capture: {
    mode: AkuaTypes.Enums.CaptureMode.AUTOMATIC,
  },
  merchant_id: 'mer-d0r0b17npsai542l2400',
  installments: {
    quantity: 2,
    type: '03',
  },
  instrument: {
    id: 'instr_123456789',
  },
});
```

#### `payments.capture(paymentId: string, data: CapturePaymentRequest): Promise<ApiResponse<CapturePaymentDTO>>`

Captures a previously authorized payment. Only payments created with capture_manual mode can be captured.

```typescript
const capture = await akuaClient.payments.capture('pay_123', {
  amount: {
    value: 25.25,
    currency: AkuaTypes.Enums.Currency.USD,
  },
});
```

#### `payments.cancel(paymentId: string): Promise<ApiResponse<CancelPaymentDTO>>`

Cancels a payment transaction.

```typescript
const cancel = await akuaClient.payments.cancel('pay-d0v32ak2mts03heh7amg');
```

#### `payments.refund(paymentId: string, data: RefundPaymentRequest): Promise<ApiResponse<RefundPaymentDTO>>`

Refunds a payment transaction.

```typescript
const refund = await akuaClient.payments.refund('pay-d0v32ak2mts03heh7amg', {
  amount: {
    value: 25.25,
    currency: AkuaTypes.Enums.Currency.USD,
  },
});
```

#### `payments.verify(data: VerifyPaymentRequest): Promise<ApiResponse<AuthorizePaymentDTO>>`

Verifies a payment instrument (card) status.

```typescript
const verify = await akuaClient.payments.verify({
  intent: AkuaTypes.Enums.PaymentIntent.AUTHORIZATION,
  merchant_id: 'mer-d0r0b17npsai542l2400',
  trace_id: 'any-format-34324366',
  instrument: {
    type: 'CARD',
    card: {
      number: '4024007108904086',
      expiration_month: '12',
      expiration_year: '25',
      holder_name: 'John Doe',
      cvv: '123',
    },
    user_data: {
      billing_address: {
        street: '123 Main St',
        number: 'Apt 4B',
        city: 'New York',
        state: 'NY',
        zip_code: '10001',
        country: AkuaTypes.Enums.Country.UNITED_STATES,
        phone_number: '+1234567890',
      },
    },
  },
});
```

### Webhooks

#### `webhooks.create(data: CreateWebhookRequest): Promise<ApiResponse<WebhookDTO>>`

Creates a new webhook configuration.

```typescript
const webhook = await akuaClient.webhooks.create({
  url: 'https://example.com/webhook',
  events: [AkuaTypes.Enums.EventType.PAYMENT_AUTHORIZATION_PROCESSED],
  description: 'Webhook for payment events',
  rate_limit: 1,
});
```

#### `webhooks.get(): Promise<ApiResponse<WebhookDTO[]>>`

Retrieves all webhook configurations.

```typescript
const webhooks = await akuaClient.webhooks.get();
```

#### `webhooks.getSecret(webhookId: string): Promise<ApiResponse<WebhookSecretDTO>>`

Retrieves a webhook configuration's secret key by its ID.

```typescript
const webhookSecret = await akuaClient.webhooks.getSecret('webhook_123');
```

<a id="typescript-types"></a>

## 📘 TypeScript Types

The SDK provides comprehensive TypeScript types that can be imported from the `AkuaTypes` namespace. This allows you to have full type safety and autocompletion when working with the SDK.

### Available Types

```typescript
import { AkuaTypes } from 'akua-sdk';

// Enums
const environment = AkuaTypes.Enums.Environment.SANDBOX;
const country = AkuaTypes.Enums.Country.USA;
const rail = AkuaTypes.Enums.Rail.VISA;

// Request Types
const createMerchantRequest: AkuaTypes.RequestTypes.CreateMerchantRequest = {
  name: 'My Store',
  organization_id: 'org_123',
  // ... other merchant fields
};

const createInstrumentRequest: AkuaTypes.RequestTypes.CreateInstrumentRequest = {
  type: 'CARD',
  card: {
    number: '4242424242424242',
    expiration_month: '12',
    expiration_year: '2025',
    first_name: 'John',
    last_name: 'Doe',
    cvv: '123',
  },
};

// Response Types
const merchantResponse: AkuaTypes.ResponseTypes.MerchantDTO = {
  id: 'merch_123',
  name: 'My Store',
  // ... other merchant fields
};

const instrumentResponse: AkuaTypes.ResponseTypes.InstrumentDTO = {
  id: 'instr_123',
  type: 'CARD',
  // ... other instrument fields
};
```

### Type Categories

The SDK's types are organized into several categories:

1. **Enums**: Constants and enumerations used throughout the SDK

2. **Request Types**: Types for API request payloads

3. **Response Types**: Types for API response data

4. **API Response**: Generic wrapper type for all API responses
   ```typescript
   interface ApiResponse<T> {
     data: T | null;
     success: boolean;
     error?: {
       code: string;
       message: string;
       details?: Record<string, unknown>;
     };
   }
   ```

### Type Safety Example

Here's an example of how the types help catch errors at compile time:

```typescript
import { AkuaClient, AkuaTypes } from 'akua-sdk';

const client = new AkuaClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  environment: AkuaTypes.Enums.Environment.SANDBOX,
});

// TypeScript will show an error if required fields are missing
const merchant = await client.merchants.create({
  name: 'My Store',
  // Error: missing required field 'organization_id'
});

// TypeScript will show an error if field types don't match
const instrument = await client.instruments.create({
  type: 'CARD',
  card: {
    number: 4242424242424242, // Error: number should be a string
    expiration_month: 12, // Error: should be a string
    expiration_year: 2025, // Error: should be a string
    first_name: 'John',
    last_name: 'Doe',
  },
});

// TypeScript will provide autocompletion for response fields
const response = await client.instruments.getById('ins_123');
if (response.success && response.data) {
  console.log(response.data.status); // Autocomplete available
  console.log(response.data.type); // Autocomplete available
  console.log(response.data.invalid_field); // Error: field doesn't exist
}
```

<a id="error-handling"></a>

## 🛡️ Error Handling

The SDK provides built-in error handling with detailed error messages. All API responses are wrapped in an `ApiResponse` type:

```typescript
interface ApiResponse<T> {
  data: T | null;
  success: boolean;
  error?: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
}
```

Example error handling:

```typescript
try {
  const result = await akuaClient.organizations.create({
    name: 'Acme Corp',
  });

  if (!result.success) {
    console.error(`Error ${result.error?.code}: ${result.error?.message}`);
    if (result.error?.details) {
      console.error('Details:', result.error.details);
    }
    return;
  }

  // Use result.data safely here
  console.log('Organization created:', result.data);
} catch (error) {
  // Handle unexpected errors
  console.error('Unexpected error:', error);
}
```

<a id="license"></a>

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.