npm package: @internal-labs/forebit
Description: Lightweight TypeScript SDK for the Forebit API (customers, payments, portfolio management).
Author: Internal Labs
Latest version: 0.2.8

# @internal-labs/forebit

Lightweight TypeScript SDK for the Forebit API (customers, payments, wallets).

## Installation

```bash
npm install @internal-labs/forebit
```

or

```bash
pnpm add @internal-labs/forebit
```

## Setup

Before using the SDK, you'll need to obtain your Business ID and generate an API key from your Forebit account.

### Getting Your Business ID

1. Log in to your [Forebit account](https://app.forebit.io)
2. Navigate to [Business Settings > Developer](https://app.forebit.io/payments/settings/developer)
3. Copy your Business ID from the developer settings

### Generating an API Key

1. Log in to your [Forebit account](https://app.forebit.io)
2. Navigate to [Account Settings > Developer](https://app.forebit.io/account/settings/developer)
3. Generate a new API key and copy it securely

**⚠️ Important:** Keep your API key secure and never commit it to version control.

## Usage

```typescript
import { ForebitClient } from '@internal-labs/forebit';

const client = new ForebitClient({
  apiKey: 'your-api-key-here',
  businessId: 'your-business-id-here',
});

// Create a payment
const payment = await client.payments.create({
  amount: 5,
  currency: 'USD',
  name: 'Subscription Test',
  paymentMethods: {
    FOREBIT_CRYPTO: ['BITCOIN', 'ETHEREUM'],
  },
});

console.log(payment);

// List payments with pagination
const payments = await client.payments.list({
  searchString: 'test',
  pageSize: 10,
  pageNumber: 1,
});

console.log(payments);

// Get a single payment
const singlePayment = await client.payments.get('payment-id');
console.log(singlePayment);

// List customers
const customers = await client.customers.list({
  searchString: 'email@example.com',
  pageSize: 10,
  pageNumber: 1,
});

console.log(customers);

// Get a single customer
const customer = await client.customers.get(123);
console.log(customer);

// List all wallets
const wallets = await client.wallets.list({
  includeDeleted: false,
});

console.log(wallets);

// List wallet accounts
const accounts = await client.wallets.listAccounts('wallet-id', {
  pageSize: 10,
  pageNumber: 1,
});

console.log(accounts);

// Get current deposit address
const depositAddress = await client.wallets.getDepositAddress('wallet-id', 'account-id');
console.log(depositAddress);

// Create new deposit address
const newDepositAddress = await client.wallets.createDepositAddress('wallet-id', 'account-id');
console.log(newDepositAddress);

// List deposit addresses
const depositAddresses = await client.wallets.listDepositAddresses('wallet-id', 'account-id', {
  hasBalance: false,
  isUsed: false,
});
console.log(depositAddresses);
```

## API Reference

### ForebitClient

Main client class for interacting with the Forebit API.

#### Constructor Options

- `apiKey` (string): Your Forebit API key
- `businessId` (string): Your business ID

### Payments

#### create(data: CreatePaymentRequest): Promise<CreatePaymentResponse>

Creates a new payment.

Parameters:

- `data`: Payment creation data
  - `paymentMethods` (optional): Object specifying allowed payment methods. If not provided, all available payment methods will be used.

#### list(options?: { searchString?: string; pageSize?: number; pageNumber?: number }): Promise<PaymentListResponse>

Lists payments with optional search and pagination.

Parameters:

- `options.searchString`: Search string for filtering
- `options.pageSize`: Number of payments per page
- `options.pageNumber`: Page number

#### get(paymentId: string): Promise<PaymentResponse>

Gets a single payment by ID.

Parameters:

- `paymentId`: Payment ID

### Customers

#### list(options?: { searchString?: string; pageSize?: number; pageNumber?: number }): Promise<CustomerListResponse>

Lists customers with optional search and pagination.

Parameters:

- `options.searchString`: Search string for filtering
- `options.pageSize`: Number of customers per page
- `options.pageNumber`: Page number

#### get(customerId: number): Promise<CustomerResponse>

Gets a single customer by ID.

Parameters:

- `customerId`: Customer ID

### Wallets

#### list(options?: { includeDeleted?: boolean }): Promise<Wallet[]>

Lists all wallets.

Parameters:

- `options.includeDeleted`: Whether to include deleted wallets (default: false)

#### listAccounts(walletId: string, options?: { pageSize?: number; pageNumber?: number }): Promise<WalletAccountListResponse>

Lists wallet accounts for a specific wallet.

Parameters:

- `walletId`: Wallet ID
- `options.pageSize`: Number of accounts per page
- `options.pageNumber`: Page number

#### getDepositAddress(walletId: string, accountId: string): Promise<DepositAddress>

Gets the current deposit address for a wallet account.

Parameters:

- `walletId`: Wallet ID
- `accountId`: Account ID

#### createDepositAddress(walletId: string, accountId: string): Promise<DepositAddress>

Creates a new deposit address for a wallet account.

Parameters:

- `walletId`: Wallet ID
- `accountId`: Account ID

#### listDepositAddresses(walletId: string, accountId: string, options?: { hasBalance?: boolean; isUsed?: boolean }): Promise<DepositAddress[]>

Lists deposit addresses for a wallet account with optional filters.

Parameters:

- `walletId`: Wallet ID
- `accountId`: Account ID
- `options.hasBalance`: Filter addresses by balance status (optional)
- `options.isUsed`: Filter addresses by usage status (optional)

## Supported Crypto Codes

The following crypto codes are supported in `paymentMethods`:

- BITCOIN
- LITECOIN
- ETH_TETHER
- ETH_USD_COIN
- ETHEREUM
- TRON
- TRX_TETHER
- TRX_USD_C
- SOL_TETHER
- SOL_USD_COIN
- SOLANA

## Development

```bash
# Install dependencies
pnpm install

# Build
pnpm run build

# Run examples
pnpm run example              # General usage example
pnpm run example:wallets      # Wallet-specific example

# Lint
pnpm run lint

# Format
pnpm run format
```

## Contributing

Contributions are welcome. Please open an issue or submit a pull request.

## License

MIT