@vulog/aima-billing 1.1.89 → 1.1.92

package/README.md

@@ -1 +1,182 @@
 # @vulog/aima-billing
+
+Billing and credit management module for the AIMA platform. This module provides functionality to manage user credits, invoices, and billing operations.
+
+## Installation
+
+```bash
+npm install @vulog/aima-client @vulog/aima-core @vulog/aima-billing
+```
+
+## Usage
+
+### Initialize Client
+
+```javascript
+import { getClient } from '@vulog/aima-client';
+import { addCredits, getUserCreditsByEntityId, getInvoiceById, chargeProduct } from '@vulog/aima-billing';
+
+const client = getClient({
+    apiKey: 'your-api-key',
+    baseUrl: 'https://your-api-base-url',
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    fleetId: 'your-fleet-id',
+});
+```
+
+## API Reference
+
+### addCredits
+
+Add credits to a user's account.
+
+```javascript
+const credits = await addCredits(client, {
+    initialAmount: 100,
+    validityStartDate: '2024-01-01T00:00:00Z',
+    validityEndDate: '2024-12-31T23:59:59Z',
+    notes: 'Welcome bonus',
+    discountCategory: 'CREDITS',
+    oneTimeUsage: false,
+    entityId: 'user-uuid-here',
+    type: 'LOCAL',
+    usage: 'ALL'
+});
+```
+
+**Parameters:**
+- `client`: AIMA client instance
+- `payload`: Credit configuration object
+  - `initialAmount`: Number of credits to add
+  - `validityStartDate`: Start date in ISO format
+  - `validityEndDate`: End date in ISO format
+  - `notes`: Optional notes
+  - `discountCategory`: 'CREDITS' or 'PERCENTAGE'
+  - `oneTimeUsage`: Boolean for one-time usage
+  - `entityId`: User UUID
+  - `type`: 'LOCAL', 'GLOBAL', or 'PERIODIC'
+  - `usage`: 'TRIP', 'REGISTRATION', 'PRODUCTS', or 'ALL'
+
+### getUserCreditsByEntityId
+
+Retrieve user credits by entity ID.
+
+```javascript
+const userCredits = await getUserCreditsByEntityId(client, 'user-uuid-here');
+```
+
+**Parameters:**
+- `client`: AIMA client instance
+- `entityId`: User UUID
+
+### getInvoiceById
+
+Get invoice details by ID.
+
+```javascript
+const invoice = await getInvoiceById(client, 'invoice-id-here');
+```
+
+**Parameters:**
+- `client`: AIMA client instance
+- `invoiceId`: Invoice identifier
+
+### chargeProduct
+
+Charge a product to a user.
+
+```javascript
+const charge = await chargeProduct(client, {
+    entityId: 'user-uuid-here',
+    productId: 'product-id-here',
+    amount: 50
+});
+```
+
+**Parameters:**
+- `client`: AIMA client instance
+- `payload`: Charge configuration object
+  - `entityId`: User UUID
+  - `productId`: Product identifier
+  - `amount`: Amount to charge
+
+## Types
+
+### Credit
+
+```typescript
+interface Credit {
+    id: string;
+    initialAmount: number;
+    availableAmount: number;
+    usedAmount: number;
+    originId: string;
+    creditAlreadyUsed: boolean;
+    validityStartDate: string;
+    validityEndDate: string;
+    notes: string | null;
+    discountCategory: 'CREDITS' | 'PERCENTAGE';
+    oneTimeUsage: boolean;
+    entityId: string;
+    type: 'LOCAL' | 'GLOBAL' | 'PERIODIC';
+    usage: 'TRIP' | 'REGISTRATION' | 'PRODUCTS' | 'ALL';
+    updateDate: string;
+}
+```
+
+## Error Handling
+
+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.
+
+## Examples
+
+### Complete Billing Workflow
+
+```javascript
+import { getClient } from '@vulog/aima-client';
+import { addCredits, getUserCreditsByEntityId, chargeProduct } from '@vulog/aima-billing';
+
+const client = getClient({
+    apiKey: 'your-api-key',
+    baseUrl: 'https://your-api-base-url',
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    fleetId: 'your-fleet-id',
+});
+
+async function billingWorkflow() {
+    try {
+        // Add credits to user
+        const credits = await addCredits(client, {
+            initialAmount: 100,
+            validityStartDate: '2024-01-01T00:00:00Z',
+            validityEndDate: '2024-12-31T23:59:59Z',
+            notes: 'Welcome bonus',
+            discountCategory: 'CREDITS',
+            oneTimeUsage: false,
+            entityId: 'user-uuid-here',
+            type: 'LOCAL',
+            usage: 'ALL'
+        });
+        
+        console.log('Credits added:', credits);
+        
+        // Check user credits
+        const userCredits = await getUserCreditsByEntityId(client, 'user-uuid-here');
+        console.log('User credits:', userCredits);
+        
+        // Charge a product
+        const charge = await chargeProduct(client, {
+            entityId: 'user-uuid-here',
+            productId: 'product-id-here',
+            amount: 25
+        });
+        
+        console.log('Product charged:', charge);
+        
+    } catch (error) {
+        console.error('Billing error:', error);
+    }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vulog/aima-billing",
-    "version": "1.1.89",
+    "version": "1.1.92",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
     "types": "dist/index.d.ts",
@@ -19,8 +19,8 @@
     "author": "Vulog",
     "license": "MIT",
     "dependencies": {
-        "@vulog/aima-client": "1.1.89",
-        "@vulog/aima-core": "1.1.89"
+        "@vulog/aima-client": "1.1.92",
+        "@vulog/aima-core": "1.1.92"
     },
     "peerDependencies": {
         "zod": "^3.25.76"