@vulog/aima-business

Business account management — CRUD operations, users, cost centers, invoices, trips, and Stripe integration.

Installation

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

Usage

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 |