@vulog/aima-billing 1.2.45 → 1.2.47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +100 -164
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,182 +1,118 @@
1
1
  # @vulog/aima-billing
2
2
 
3
- Billing and credit management module for the AIMA platform. This module provides functionality to manage user credits, invoices, and billing operations.
3
+ Invoice management, credits, wallets, and refunds.
4
4
 
5
5
  ## Installation
6
6
 
7
- ```bash
8
- npm install @vulog/aima-client @vulog/aima-core @vulog/aima-billing
7
+ ```sh
8
+ npm install @vulog/aima-billing @vulog/aima-client @vulog/aima-core
9
9
  ```
10
10
 
11
11
  ## Usage
12
12
 
13
- ### Initialize Client
14
-
15
- ```javascript
13
+ ```ts
16
14
  import { getClient } from '@vulog/aima-client';
17
- import { addCredits, getUserCreditsByEntityId, getInvoiceById, chargeProduct } from '@vulog/aima-billing';
18
-
19
- const client = getClient({
20
- apiKey: 'your-api-key',
21
- baseUrl: 'https://your-api-base-url',
22
- clientId: 'your-client-id',
23
- clientSecret: 'your-client-secret',
24
- fleetId: 'your-fleet-id',
25
- });
26
- ```
27
-
28
- ## API Reference
15
+ import { getInvoiceById, getWalletsByEntity } from '@vulog/aima-billing';
29
16
 
30
- ### addCredits
31
-
32
- Add credits to a user's account.
33
-
34
- ```javascript
35
- const credits = await addCredits(client, {
36
- initialAmount: 100,
37
- validityStartDate: '2024-01-01T00:00:00Z',
38
- validityEndDate: '2024-12-31T23:59:59Z',
39
- notes: 'Welcome bonus',
40
- discountCategory: 'CREDITS',
41
- oneTimeUsage: false,
42
- entityId: 'user-uuid-here',
43
- type: 'LOCAL',
44
- usage: 'ALL'
45
- });
46
- ```
17
+ const client = getClient({ /* ClientOptions */ });
47
18
 
48
- **Parameters:**
49
- - `client`: AIMA client instance
50
- - `payload`: Credit configuration object
51
- - `initialAmount`: Number of credits to add
52
- - `validityStartDate`: Start date in ISO format
53
- - `validityEndDate`: End date in ISO format
54
- - `notes`: Optional notes
55
- - `discountCategory`: 'CREDITS' or 'PERCENTAGE'
56
- - `oneTimeUsage`: Boolean for one-time usage
57
- - `entityId`: User UUID
58
- - `type`: 'LOCAL', 'GLOBAL', or 'PERIODIC'
59
- - `usage`: 'TRIP', 'REGISTRATION', 'PRODUCTS', or 'ALL'
60
-
61
- ### getUserCreditsByEntityId
62
-
63
- Retrieve user credits by entity ID.
64
-
65
- ```javascript
66
- const userCredits = await getUserCreditsByEntityId(client, 'user-uuid-here');
19
+ const invoice = await getInvoiceById(client, 'invoice-uuid');
20
+ const wallets = await getWalletsByEntity(client, 'entity-uuid');
67
21
  ```
68
22
 
69
- **Parameters:**
70
- - `client`: AIMA client instance
71
- - `entityId`: User UUID
72
-
73
- ### getInvoiceById
74
-
75
- Get invoice details by ID.
76
-
77
- ```javascript
78
- const invoice = await getInvoiceById(client, 'invoice-id-here');
79
- ```
80
-
81
- **Parameters:**
82
- - `client`: AIMA client instance
83
- - `invoiceId`: Invoice identifier
84
-
85
- ### chargeProduct
86
-
87
- Charge a product to a user.
88
-
89
- ```javascript
90
- const charge = await chargeProduct(client, {
91
- entityId: 'user-uuid-here',
92
- productId: 'product-id-here',
93
- amount: 50
94
- });
95
- ```
23
+ ## API Reference
96
24
 
97
- **Parameters:**
98
- - `client`: AIMA client instance
99
- - `payload`: Charge configuration object
100
- - `entityId`: User UUID
101
- - `productId`: Product identifier
102
- - `amount`: Amount to charge
25
+ ### Invoices
26
+
27
+ | Function | Signature | Description |
28
+ |----------|-----------|-------------|
29
+ | `getInvoiceById` | `(client, id: string) => Promise<Invoice>` | Retrieve an invoice by UUID |
30
+ | `getInvoicePdf` | `(client, invoiceId: string) => Promise<ArrayBuffer \| null>` | Download an invoice as PDF — returns `null` when empty |
31
+ | `getInvoicesByTripId` | `(client, tripId: string) => Promise<InvoicesByTripIdResponse>` | Retrieve all invoices associated with a trip |
32
+ | `payInvoice` | `(client, invoiceId: string, manualPayment: ManualPayment) => Promise<Invoice>` | Pay an invoice manually |
33
+
34
+ #### payInvoice — manualPayment fields
35
+
36
+ | Field | Type | Required |
37
+ |-------|------|----------|
38
+ | `requiresActionReturnUrl` | `string` | Yes |
39
+ | `scope` | `'RENTAL' \| 'DEPOSIT'` | Yes |
40
+ | `online` | `boolean` | No |
41
+
42
+ ### Refunds
43
+
44
+ | Function | Signature | Description |
45
+ |----------|-----------|-------------|
46
+ | `getRefundableAmount` | `(client, invoiceId: string) => Promise<RefundableAmount>` | Retrieve the refundable amount for an invoice |
47
+ | `refund` | `(client, payload: RefundPayload) => Promise<void>` | Issue a refund for an invoice |
48
+
49
+ #### refund — payload fields
50
+
51
+ | Field | Type | Required |
52
+ |-------|------|----------|
53
+ | `invoiceId` | `string` | Yes |
54
+ | `amount` | `number` | No |
55
+ | `note` | `string \| null` | No |
56
+ | `paymentIntentPspReference` | `string` | No |
57
+
58
+ ### Credits
59
+
60
+ | Function | Signature | Description |
61
+ |----------|-----------|-------------|
62
+ | `getUserCreditsByEntityId` | `(client, id: string) => Promise<Credit>` | Retrieve credits for an entity by UUID |
63
+ | `addCredits` | `(client, payload: AddCreditsPayload) => Promise<Credit>` | Add credits to an entity |
64
+
65
+ #### addCredits — payload fields
66
+
67
+ | Field | Type | Required |
68
+ |-------|------|----------|
69
+ | `initialAmount` | `number` | Yes |
70
+ | `validityStartDate` | `string` | Yes |
71
+ | `validityEndDate` | `string` | Yes |
72
+ | `discountCategory` | `'CREDITS' \| 'PERCENTAGE'` | Yes |
73
+ | `entityId` | `string` (UUID) | Yes |
74
+ | `type` | `'LOCAL' \| 'GLOBAL' \| 'PERIODIC'` | Yes |
75
+ | `usage` | `'TRIP' \| 'REGISTRATION' \| 'PRODUCTS' \| 'ALL'` | Yes |
76
+ | `notes` | `string` | No |
77
+ | `oneTimeUsage` | `boolean` | No |
78
+
79
+ ### Products
80
+
81
+ | Function | Signature | Description |
82
+ |----------|-----------|-------------|
83
+ | `chargeProduct` | `(client, info: ChargeProductInfo) => Promise<Invoice>` | Charge a product to a user |
84
+
85
+ #### chargeProduct — ChargeProductInfo fields
86
+
87
+ | Field | Type | Required |
88
+ |-------|------|----------|
89
+ | `productId` | `string` (UUID) | Yes |
90
+ | `amount` | `number` | Yes |
91
+ | `userId` | `string` (UUID) | Yes |
92
+ | `entityId` | `string` (UUID) | Yes |
93
+ | `serviceId` | `string \| null` (UUID) | No |
94
+ | `subscriptionId` | `string \| null` (UUID) | No |
95
+ | `productNotes` | `string \| null` | No |
96
+ | `originId` | `string \| null` | No |
97
+ | `chargeProductRequestId` | `string \| null` (UUID) | No |
98
+ | `additionalInfo` | `{ manualPayment?: boolean }` | No |
99
+
100
+ ### Wallets
101
+
102
+ | Function | Signature | Description |
103
+ |----------|-----------|-------------|
104
+ | `getWalletsByEntity` | `(client, entityId: string) => Promise<Wallet[]>` | Retrieve all wallets for an entity (UUID validated) |
105
+ | `updateWallet` | `(client, walletId: string, actions: PatchAction<'/availableAmount' \| '/percentage'>[]) => Promise<void>` | Update wallet fields via PATCH actions (walletId must be UUID) |
103
106
 
104
107
  ## Types
105
108
 
106
- ### Credit
107
-
108
- ```typescript
109
- interface Credit {
110
- id: string;
111
- initialAmount: number;
112
- availableAmount: number;
113
- usedAmount: number;
114
- originId: string;
115
- creditAlreadyUsed: boolean;
116
- validityStartDate: string;
117
- validityEndDate: string;
118
- notes: string | null;
119
- discountCategory: 'CREDITS' | 'PERCENTAGE';
120
- oneTimeUsage: boolean;
121
- entityId: string;
122
- type: 'LOCAL' | 'GLOBAL' | 'PERIODIC';
123
- usage: 'TRIP' | 'REGISTRATION' | 'PRODUCTS' | 'ALL';
124
- updateDate: string;
125
- }
126
- ```
127
-
128
- ## Error Handling
129
-
130
- All functions include validation using Zod schemas and will throw `TypeError` with detailed error information if validation fails. Network errors are handled by the underlying client.
131
-
132
- ## Examples
133
-
134
- ### Complete Billing Workflow
135
-
136
- ```javascript
137
- import { getClient } from '@vulog/aima-client';
138
- import { addCredits, getUserCreditsByEntityId, chargeProduct } from '@vulog/aima-billing';
139
-
140
- const client = getClient({
141
- apiKey: 'your-api-key',
142
- baseUrl: 'https://your-api-base-url',
143
- clientId: 'your-client-id',
144
- clientSecret: 'your-client-secret',
145
- fleetId: 'your-fleet-id',
146
- });
147
-
148
- async function billingWorkflow() {
149
- try {
150
- // Add credits to user
151
- const credits = await addCredits(client, {
152
- initialAmount: 100,
153
- validityStartDate: '2024-01-01T00:00:00Z',
154
- validityEndDate: '2024-12-31T23:59:59Z',
155
- notes: 'Welcome bonus',
156
- discountCategory: 'CREDITS',
157
- oneTimeUsage: false,
158
- entityId: 'user-uuid-here',
159
- type: 'LOCAL',
160
- usage: 'ALL'
161
- });
162
-
163
- console.log('Credits added:', credits);
164
-
165
- // Check user credits
166
- const userCredits = await getUserCreditsByEntityId(client, 'user-uuid-here');
167
- console.log('User credits:', userCredits);
168
-
169
- // Charge a product
170
- const charge = await chargeProduct(client, {
171
- entityId: 'user-uuid-here',
172
- productId: 'product-id-here',
173
- amount: 25
174
- });
175
-
176
- console.log('Product charged:', charge);
177
-
178
- } catch (error) {
179
- console.error('Billing error:', error);
180
- }
181
- }
182
- ```
109
+ | Type | Description |
110
+ |------|-------------|
111
+ | `Invoice` | Invoice record |
112
+ | `Credit` | Credit record |
113
+ | `Receipt` | Payment receipt |
114
+ | `RefundableAmount` | Refundable amount details |
115
+ | `InvoicesByTripIdResponse` | Collection of invoices for a trip |
116
+ | `Wallet` | Wallet record |
117
+ | `ChargeProductInfo` | Input for charging a product |
118
+ | `ManualPayment` | Manual payment input |
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@vulog/aima-billing",
3
3
  "type": "module",
4
- "version": "1.2.45",
4
+ "version": "1.2.47",
5
5
  "main": "dist/index.cjs",
6
6
  "module": "dist/index.mjs",
7
7
  "types": "dist/index.d.cts",
@@ -32,8 +32,8 @@
32
32
  "author": "Vulog",
33
33
  "license": "MIT",
34
34
  "dependencies": {
35
- "@vulog/aima-client": "1.2.45",
36
- "@vulog/aima-core": "1.2.45"
35
+ "@vulog/aima-client": "1.2.47",
36
+ "@vulog/aima-core": "1.2.47"
37
37
  },
38
38
  "peerDependencies": {
39
39
  "zod": "^4.3.6"