npm package: @internal-labs/hoodpay
Description: Lightweight TypeScript SDK for the HoodPay API (customers, payments).
Author: Internal Labs
Latest version: 0.1.6

# @internal-labs/hoodpay

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

## Installation

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

or

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

## Setup

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

1. Log in to your [HoodPay account](https://dash.hoodpay.io)
2. Navigate to [Settings > Developer](https://dash.hoodpay.io/settings/developer)
3. Copy your Business ID and generate a new API key, then copy it securely

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

## Usage

```typescript
import { HoodPayClient } from '@internal-labs/hoodpay';

const client = new HoodPayClient({
  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',
});

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);

// Search for customers and payments
const searchResults = await client.search('alice');
console.log(searchResults);

// Select payment method (public endpoint, no auth required)
const selectResult = await client.livePayments.selectPaymentMethod('payment-id', 'ETHEREUM');
console.log(selectResult);

// Fill customer email (public endpoint)
const emailResult = await client.livePayments.fillCustomerEmail(
  'payment-id',
  'customer@example.com',
);
console.log(emailResult);

// Cancel payment (public endpoint)
const cancelResult = await client.livePayments.cancelPayment('payment-id');
console.log(cancelResult);
```

## API Reference

### HoodPayClient

Main client class for interacting with the HoodPay API.

#### Constructor Options

- `apiKey` (string): Your HoodPay API key
- `baseUrl` (string, optional): API base URL (defaults to production)
- `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

### search(query: string): Promise<SearchResponse>

Searches for customers and payments matching the provided query string.

Parameters:

- `query`: Search query string

Returns a `SearchResponse` containing matching customers and payments.

### Live Payments

#### selectPaymentMethod(paymentId: string, crypto: CryptoCode): Promise<SelectPaymentMethodResponse>

Selects a payment method for a hosted payment page. Automatically detects whether to use XPUB (for LITECOIN/BITCOIN) or direct crypto submission.

Parameters:

- `paymentId`: Payment ID from the hosted page
- `crypto`: Crypto code (automatically handled for XPUB vs direct)

Returns a `SelectPaymentMethodResponse` with charge details.

#### fillCustomerEmail(paymentId: string, email: string): Promise<{ message: string }>

Fills the customer email for a hosted payment page.

Parameters:

- `paymentId`: Payment ID from the hosted page
- `email`: Customer email address

Returns a response with a success message.

#### cancelPayment(paymentId: string): Promise<{ message: string }>

Cancels a payment on the hosted page.

Parameters:

- `paymentId`: Payment ID from the hosted page

Returns a response with a success message.

## Types

### CreatePaymentRequest

- `description?: string` - Optional description of the payment
- `amount: number` - The amount of the payment
- `currency: string` - The currency code for the payment (ISO 4217 format, e.g. USD)
- `name: string` - The name associated with the payment
- `redirectUrl?: string` - Optional URL to redirect after payment
- `notifyUrl?: string` - Optional URL for payment notifications
- `customerEmail?: string` - Optional email of the customer
- `customerIp?: string | null` - Optional IP address of the customer
- `customerUserAgent?: string | null` - Optional user agent of the customer

### Payment

- `id: string` - Payment ID
- `name?: string` - Optional name
- `description?: string` - Optional description
- `endAmount: number` - Payment amount
- `prePaymentAmount?: number` - Pre-payment amount
- `currency: string` - Currency code
- `status: string` - Payment status
- `createdAt: string` - Creation timestamp
- `expiresAt?: string` - Optional expiration timestamp
- `timeline?: TimelineEntry[]` - Optional status timeline
- `customer?: Customer` - Optional customer info
- `paymentMethod?: string` - Optional payment method
- `selectedPaymentMethod?: string` - Optional selected payment method
- `directCryptoCharge?: HoodPayCryptoCharge` - Optional crypto charge details
- `hoodPayFee?: number` - Optional fee
- `onBehalfOfBusinessId?: number` - Optional business ID
- `netAmountUsd?: number` - Optional net amount in USD
- `customerEmail?: string` - Optional customer email

### CustomerStat

- `id: number` - Customer ID
- `email: string` - Customer email
- `totalPayments: number` - Total payments
- `totalSpend: number` - Total spend
- `firstSeen: string` - First seen timestamp
- `lastPayment?: string` - Optional last payment timestamp

### SearchResult

- `customers: SearchCustomer[]` - Matching customers
- `payments: Payment[]` - Matching payments

### SelectPaymentMethodResponse

- `data.chargeId: string` - Charge ID
- `data.chargeCryptoAmount: string` - Crypto amount to pay
- `data.chargeCryptoName: string` - Crypto name
- `data.chargeCryptoAddress: string` - Crypto address to send to
- `message: string` - Response message

## Supported Crypto Codes

The following crypto codes are supported in `paymentMethods.hoodPayCrypto`:

- BITCOIN
- ETHEREUM
- LITECOIN
- BITCOIN_CASH
- ETH_USD_COIN
- ETH_TETHER
- MONERO
- ETH_BNB
- ETH_BUSD
- ETH_MATIC
- ETH_SHIBA_INU
- ETH_APE_COIN
- ETH_CRONOS
- ETH_DAI
- ETH_UNISWAP

## Development

```bash
# Install dependencies
pnpm install

# Build
pnpm run build

# Run example
pnpm run example

# Lint
pnpm run lint

# Format
pnpm run format
```

## Contributing

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

## License

MIT