@vulog/aima-billing/README.md

Invoice management, credits, wallets, and refunds.

# @vulog/aima-billing

Invoice management, credits, wallets, and refunds.

## Installation

```sh
npm install @vulog/aima-billing @vulog/aima-client @vulog/aima-core
```

## Usage

```ts
import { getClient } from '@vulog/aima-client';
import { getInvoiceById, getWalletsByEntity } from '@vulog/aima-billing';

const client = getClient({ /* ClientOptions */ });

const invoice = await getInvoiceById(client, 'invoice-uuid');
const wallets = await getWalletsByEntity(client, 'entity-uuid');
```

## API Reference

### Invoices

| Function | Signature | Description |
|----------|-----------|-------------|
| `getInvoiceById` | `(client, id: string) => Promise<Invoice>` | Retrieve an invoice by UUID |
| `getInvoicePdf` | `(client, invoiceId: string) => Promise<ArrayBuffer \| null>` | Download an invoice as PDF — returns `null` when empty |
| `getInvoicesByTripId` | `(client, tripId: string) => Promise<InvoicesByTripIdResponse>` | Retrieve all invoices associated with a trip |
| `payInvoice` | `(client, invoiceId: string, manualPayment: ManualPayment) => Promise<Invoice>` | Pay an invoice manually |

#### payInvoice — manualPayment fields

| Field | Type | Required |
|-------|------|----------|
| `requiresActionReturnUrl` | `string` | Yes |
| `scope` | `'RENTAL' \| 'DEPOSIT'` | Yes |
| `online` | `boolean` | No |

### Refunds

| Function | Signature | Description |
|----------|-----------|-------------|
| `getRefundableAmount` | `(client, invoiceId: string) => Promise<RefundableAmount>` | Retrieve the refundable amount for an invoice |
| `refund` | `(client, payload: RefundPayload) => Promise<void>` | Issue a refund for an invoice |

#### refund — payload fields

| Field | Type | Required |
|-------|------|----------|
| `invoiceId` | `string` | Yes |
| `amount` | `number` | No |
| `note` | `string \| null` | No |
| `paymentIntentPspReference` | `string` | No |

### Credits

| Function | Signature | Description |
|----------|-----------|-------------|
| `getUserCreditsByEntityId` | `(client, id: string) => Promise<Credit>` | Retrieve credits for an entity by UUID |
| `addCredits` | `(client, payload: AddCreditsPayload) => Promise<Credit>` | Add credits to an entity |

#### addCredits — payload fields

| Field | Type | Required |
|-------|------|----------|
| `initialAmount` | `number` | Yes |
| `validityStartDate` | `string` | Yes |
| `validityEndDate` | `string` | Yes |
| `discountCategory` | `'CREDITS' \| 'PERCENTAGE'` | Yes |
| `entityId` | `string` (UUID) | Yes |
| `type` | `'LOCAL' \| 'GLOBAL' \| 'PERIODIC'` | Yes |
| `usage` | `'TRIP' \| 'REGISTRATION' \| 'PRODUCTS' \| 'ALL'` | Yes |
| `notes` | `string` | No |
| `oneTimeUsage` | `boolean` | No |

### Products

| Function | Signature | Description |
|----------|-----------|-------------|
| `chargeProduct` | `(client, info: ChargeProductInfo) => Promise<Invoice>` | Charge a product to a user |

#### chargeProduct — ChargeProductInfo fields

| Field | Type | Required |
|-------|------|----------|
| `productId` | `string` (UUID) | Yes |
| `amount` | `number` | Yes |
| `userId` | `string` (UUID) | Yes |
| `entityId` | `string` (UUID) | Yes |
| `serviceId` | `string \| null` (UUID) | No |
| `subscriptionId` | `string \| null` (UUID) | No |
| `productNotes` | `string \| null` | No |
| `originId` | `string \| null` | No |
| `chargeProductRequestId` | `string \| null` (UUID) | No |
| `additionalInfo` | `{ manualPayment?: boolean }` | No |

### Wallets

| Function | Signature | Description |
|----------|-----------|-------------|
| `getWalletsByEntity` | `(client, entityId: string) => Promise<Wallet[]>` | Retrieve all wallets for an entity (UUID validated) |
| `updateWallet` | `(client, walletId: string, actions: PatchAction<'/availableAmount' \| '/percentage'>[]) => Promise<void>` | Update wallet fields via PATCH actions (walletId must be UUID) |

## Types

| Type | Description |
|------|-------------|
| `Invoice` | Invoice record |
| `Credit` | Credit record |
| `Receipt` | Payment receipt |
| `RefundableAmount` | Refundable amount details |
| `InvoicesByTripIdResponse` | Collection of invoices for a trip |
| `Wallet` | Wallet record |
| `ChargeProductInfo` | Input for charging a product |
| `ManualPayment` | Manual payment input |