@vulog/aima-billing

Invoice management, credits, wallets, and refunds.

Installation

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

Usage

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 |