@vulog/aima-business 1.2.44 → 1.2.46

package/README.md

@@ -0,0 +1,208 @@
+# @vulog/aima-business
+
+Business account management — CRUD operations, users, cost centers, invoices, trips, and Stripe integration.
+
+## Installation
+
+```sh
+npm install @vulog/aima-business @vulog/aima-client @vulog/aima-core
+```
+
+## Usage
+
+```ts
+import { getClient } from '@vulog/aima-client';
+import { getBusinessById, getBusinessUsers } from '@vulog/aima-business';
+
+const client = getClient({ /* ClientOptions */ });
+
+const business = await getBusinessById(client, 'business-uuid');
+const users = await getBusinessUsers(client, 'business-uuid', { page: 0, pageSize: 50 });
+```
+
+## API Reference
+
+### Business CRUD
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getBusinesses` | `(client, options?: PaginableOptions<{ name?; status?; updateSince? }>) => Promise<PaginableResponse<Business>>` | Retrieve a paginated list of businesses |
+| `getBusinessById` | `(client, businessId: string) => Promise<Business>` | Retrieve a business by UUID |
+| `createBusiness` | `(client, body: CreateBusinessBody) => Promise<Business>` | Create a new business — `name` required |
+| `updateBusiness` | `(client, businessId: string, body: UpdateBusinessBody) => Promise<Business>` | Update a business — all fields optional |
+| `getBusinessContacts` | `(client, businessId: string) => Promise<BusinessContact[]>` | Retrieve contacts for a business |
+| `getBusinessPaymentDetails` | `(client, businessId: string) => Promise<BusinessPaymentDetails>` | Retrieve payment details for a business |
+| `updateBusinessProfileStatus` | `(client, businessId: string, status: string) => Promise<void>` | Update the profile status of a business |
+| `archiveBusinessProfile` | `(client, businessId: string, userId: string, profileId: string) => Promise<void>` | Archive a business profile |
+| `deactivateBusinessProfile` | `(client, businessId: string, profileId: string) => Promise<void>` | Deactivate a business profile |
+| `addBusinessCredit` | `(client, businessId: string, body: { amount: number; expirationDate: string }) => Promise<void>` | Add credit to a business |
+| `chargeBusinessProduct` | `(client, businessId: string, body: ChargeBusinessProductBody) => Promise<void>` | Charge a product to a business |
+| `redeemBusinessPromoCode` | `(client, businessId: string, reference: string) => Promise<void>` | Redeem a promo code for a business |
+| `sendBusinessIban` | `(client, businessId: string, body: { iban: string; entityId?: string }) => Promise<void>` | Submit an IBAN for a business |
+| `getBusinessProducts` | `(client) => Promise<BusinessProduct[]>` | Retrieve all available business products |
+| `getBusinessBillingGroups` | `(client) => Promise<BusinessBillingGroup[]>` | Retrieve all billing groups |
+
+#### createBusiness / updateBusiness — optional fields
+
+`legalName`, `phoneNumber`, `faxNumber`, `email`, `vat`, `ein`, `registrationUrl`, `comment`, `paymentType`, `locale`, `invoiceFrequency`, `status`, `nationality`, `pec`, `legalForm`, `fiscalCode`, `taxNumberCountry`, `communityTaxNumber`, `sdicemCode`, `mandatoryTripNotes`, `billingAddress`, `address`, `billingGroup`
+
+#### chargeBusinessProduct — body fields
+
+| Field | Type | Required |
+|-------|------|----------|
+| `productId` | `string` | Yes |
+| `amount` | `number` | Yes |
+| `userId` | `string` | No |
+| `productNotes` | `string` | No |
+| `serviceId` | `string` | No |
+
+### Business Users
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getBusinessUsers` | `(client, businessId: string, options?: PaginableOptions<{ role?; status? }>) => Promise<PaginableResponse<BusinessUser>>` | Retrieve users for a business |
+| `getBusinessUserById` | `(client, businessId: string, userId: string) => Promise<BusinessUser>` | Retrieve a business user by ID |
+| `getBusinessUserGlobalById` | `(client, userId: string) => Promise<BusinessUser>` | Retrieve a business user globally by ID |
+| `listBusinessUsersGlobal` | `(client, body: { userIds: string[] }) => Promise<BusinessUser[]>` | Retrieve multiple business users by ID list (min 1) |
+| `addUserToBusiness` | `(client, businessId: string, userId: string, data?: AddUserToBusinessData) => Promise<BusinessUserProfile>` | Add an existing user to a business |
+| `bulkAddBusinessUsers` | `(client, businessId: string, file: Blob \| Buffer, locale?: string) => Promise<any>` | Bulk add users via multipart file upload |
+| `inviteBusinessUser` | `(client, businessId: string, params: InviteBusinessUserParams) => Promise<void>` | Invite a new user to a business by email |
+| `updateBusinessUserProfile` | `(client, businessId: string, userId: string, profileId: string, body: UpdateBusinessUserProfileBody) => Promise<BusinessUserProfile>` | Update a user's business profile |
+| `searchBusinessUsersByName` | `(client, businessId: string, name: string) => Promise<BusinessUser[]>` | Search business users by name |
+| `searchBusinessUsersGlobal` | `(client, name: string) => Promise<BusinessUser[]>` | Search all business users by name |
+| `setBusinessOwner` | `(client, businessId: string, userId: string) => Promise<void>` | Set a user as the business owner |
+| `removeBusinessOwner` | `(client, businessId: string, userId: string) => Promise<void>` | Remove the owner role from a user |
+| `setDelegatedAdmin` | `(client, businessId: string, userId: string) => Promise<void>` | Grant delegated admin role to a user |
+| `removeDelegatedAdmin` | `(client, businessId: string, userId: string) => Promise<void>` | Remove delegated admin role from a user |
+
+#### inviteBusinessUser — params
+
+| Field | Type | Required |
+|-------|------|----------|
+| `email` | `string` | Yes |
+| `firstName` | `string` | No |
+| `lastName` | `string` | No |
+| `costCenterId` | `string` | No |
+| `locale` | `string` | No |
+
+#### addUserToBusiness / updateBusinessUserProfile — optional fields
+
+`email`, `emailConsent`, `requestId` (add only), `costCenterId`
+
+### Cost Centers
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getBusinessCostCenters` | `(client, businessId: string) => Promise<CostCenter[]>` | Retrieve all cost centers for a business |
+| `getBusinessCostCenterById` | `(client, businessId: string, costCenterId: string) => Promise<CostCenter>` | Retrieve a cost center by ID |
+| `createBusinessCostCenter` | `(client, businessId: string, body: { name: string; value: string }) => Promise<CostCenter>` | Create a cost center |
+| `updateBusinessCostCenter` | `(client, businessId: string, costCenterId: string, body: { name?; value? }) => Promise<CostCenter>` | Update a cost center |
+| `deleteBusinessCostCenter` | `(client, businessId: string, costCenterId: string) => Promise<void>` | Delete a cost center |
+
+### Invitations
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getBusinessInviteLink` | `(client, businessId: string, params: InviteParams) => Promise<BusinessInviteLink>` | Generate an invite link for a business |
+| `getInvitationRequest` | `(client, invitationId: string) => Promise<InvitationRequest>` | Retrieve an invitation request by ID |
+| `deleteInvitationRequest` | `(client, invitationId: string) => Promise<void>` | Delete an invitation request |
+
+#### getBusinessInviteLink — params
+
+| Field | Type | Required |
+|-------|------|----------|
+| `email` | `string` | Yes |
+| `firstName` | `string` | No |
+| `lastName` | `string` | No |
+| `costCenterId` | `string` | No |
+
+### Invoices
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getBusinessInvoices` | `(client, entityId: string, options?: PaginableOptions<{ fromDate?; toDate? }>) => Promise<PaginableResponse<BusinessInvoice>>` | Retrieve invoices for an entity |
+| `getBusinessInvoiceProducts` | `(client, entityId: string, invoiceId: string) => Promise<any[]>` | Retrieve line item products for a business invoice |
+| `getBusinessInvoiceTrips` | `(client, entityId: string, invoiceId: string) => Promise<any[]>` | Retrieve trips associated with a business invoice |
+| `getInvoicePdf` | `(client, invoiceId: string) => Promise<ArrayBuffer \| null>` | Download an invoice as PDF — returns `null` when empty |
+| `getInvoiceRefundableAmount` | `(client, invoiceId: string) => Promise<InvoiceRefundableAmount>` | Retrieve the refundable amount for an invoice |
+| `getInvoiceRefundNote` | `(client, invoiceId: string, paymentRefundPspReference?: string) => Promise<InvoiceRefundNote>` | Retrieve a refund note for an invoice |
+| `refundInvoice` | `(client, invoiceId: string, body?: { amount?: number; note?: string \| null }) => Promise<void>` | Issue a refund for an invoice |
+| `refundInvoiceAmount` | `(client, invoiceId: string, amount: number) => Promise<void>` | **@deprecated** Use `refundInvoice` instead |
+| `setInvoiceExternalPayment` | `(client, invoiceId: string, body: SetExternalPaymentBody) => Promise<void>` | Mark an invoice as paid externally |
+| `updateInvoiceStatus` | `(client, invoiceId: string, status: string) => Promise<void>` | Update the status of an invoice |
+
+#### setInvoiceExternalPayment — body fields
+
+| Field | Type | Required |
+|-------|------|----------|
+| `requesterId` | `string` | Yes |
+| `notes` | `string` | No |
+| `paymentMethod` | `string` | No |
+
+### Trips & Entity Billing
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getOngoingTrips` | `(client, businessId: string, options?: PaginableOptions) => Promise<PaginableResponse<BusinessTrip>>` | Retrieve ongoing trips for a business |
+| `getBusinessTripById` | `(client, tripId: string) => Promise<BusinessTrip>` | Retrieve a business trip by ID |
+| `getOngoingTripNotes` | `(client, tripId: string) => Promise<TripNote[]>` | Retrieve notes for an ongoing trip |
+| `addTripNote` | `(client, tripId: string, body: { content: string }) => Promise<TripNote>` | Add a note to a trip |
+| `getEntityBalance` | `(client, entityId: string) => Promise<EntityBalance>` | Retrieve the balance for an entity |
+| `getEntityProducts` | `(client, entityId: string, options: PaginableOptions<EntityProductsFilters>) => Promise<PaginableResponse<any>>` | Retrieve product usage for an entity |
+| `getEntityTrips` | `(client, entityId: string, options: PaginableOptions<EntityTripsFilters>) => Promise<PaginableResponse<any>>` | Retrieve trips for an entity |
+| `getEntityTripsCost` | `(client, entityId: string, options: PaginableOptions<EntityTripsCostFilters>) => Promise<PaginableResponse<any>>` | Retrieve trip costs for an entity |
+
+#### getEntityProducts — filter fields
+
+| Field | Type | Required |
+|-------|------|----------|
+| `period` | `string` | Yes |
+| `user` | `string` | No |
+| `productDetailsType` | `'UNIT' \| 'ACCUMULATIVE' \| 'DEFAULT'` | No |
+
+#### getEntityTrips — filter fields
+
+| Field | Type | Required |
+|-------|------|----------|
+| `period` | `string` | Yes |
+| `user` | `string` | No |
+| `costCenterIds` | `string[]` | No |
+
+#### getEntityTripsCost — filter fields
+
+| Field | Type | Required |
+|-------|------|----------|
+| `startDate` | `string` | Yes |
+| `endDate` | `string` | Yes |
+| `tripId` | `string` | No |
+
+### Stripe
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getStripePublishableKey` | `(client) => Promise<StripeConfig>` | Retrieve the Stripe publishable key |
+| `getStripeSetup` | `(client, businessId: string) => Promise<StripeSetup>` | Retrieve Stripe setup for a business |
+| `addStripePayment` | `(client, businessId: string) => Promise<StripeSetup>` | **@deprecated** |
+
+## Types
+
+| Type | Description |
+|------|-------------|
+| `Business` | Business record |
+| `BusinessContact` | Contact associated with a business |
+| `CostCenter` | Cost center record |
+| `BusinessPaymentDetails` | Payment configuration for a business |
+| `BusinessUser` | User within a business context |
+| `BusinessUserProfile` | User profile within a business |
+| `BusinessInviteLink` | Generated invite link |
+| `InvitationRequest` | Pending invitation record |
+| `EntityBalance` | Financial balance for an entity |
+| `BusinessBillingGroup` | Billing group configuration |
+| `StripeSetup` | Stripe setup details |
+| `StripeConfig` | Stripe publishable key config |
+| `BusinessInvoice` | Invoice in a business context |
+| `InvoiceRefundNote` | Refund note for a business invoice |
+| `InvoiceRefundableAmount` | Refundable amount details |
+| `BusinessTrip` | Trip in a business context |
+| `TripNote` | Note attached to a trip |
+| `BusinessProduct` | Product available for businesses |

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@vulog/aima-business",
     "type": "module",
-    "version": "1.2.44",
+    "version": "1.2.46",
     "main": "dist/index.cjs",
     "module": "dist/index.mjs",
     "types": "dist/index.d.cts",
@@ -32,8 +32,8 @@
     "author": "Vulog",
     "license": "MIT",
     "dependencies": {
-        "@vulog/aima-client": "1.2.44",
-        "@vulog/aima-core": "1.2.44"
+        "@vulog/aima-client": "1.2.46",
+        "@vulog/aima-core": "1.2.46"
     },
     "peerDependencies": {
         "zod": "^4.3.6"