aves-sdk 1.5.1 → 1.6.0

package/README.md

@@ -1,14 +1,6 @@
 # AVES SDK
 
-A type-safe TypeScript SDK for the AVES XML REST API. Automatically handles XML parsing, validation, case transformation, and provides full TypeScript support.
-
-## Features
-
-- **Type-safe** - Full TypeScript support with inferred types
-- **Runtime validation** - Input/output validation using Valibot
-- **XML handling** - Automatic XML ↔ JSON conversion
-- **Case transformation** - Automatic camelCase ↔ PascalCase conversion
-- **Functional error handling** - Result pattern for type-safe error handling
+Type-safe TypeScript SDK for the AVES XML REST API. Handles XML parsing, Valibot validation, camelCase ↔ PascalCase, and returns `Result` instead of throwing.
 
 ## Installation
 
@@ -27,43 +19,26 @@ bun add aves-sdk
 ```typescript
 import { AvesClient } from 'aves-sdk';
 
-const client = new AvesClient(
-  'https://api.example.com', // Base URL
-  'hostid', // 6-digit HostID
-  'TOKEN', // Xtoken
-  '02' // Optional: 2-digit language code (01=Italian, 02=English)
-);
+const client = new AvesClient({
+  baseURL: 'https://api.example.com',
+  hostID: '000000', // 6 digits
+  xtoken: 'TOKEN',
+  languageCode: '02', // optional: 01=Italian, 02=English
+  timeoutMs: 30_000, // optional
+});
 
-// Search for records
 const searchResult = await client.search({
   searchType: 'CODE',
   recordCode: '508558',
 });
 
 if (searchResult.success) {
-  console.log(searchResult.data); // SearchMasterRecordRS
-} else {
-  console.error(searchResult.error); // AvesError
-}
-
-// Insert or update a record
-const upsertResult = await client.upsertRecord({
-  name: 'John Doe',
-  email: 'john@example.com',
-  address: '123 Main St',
-  zipCode: '12345',
-  cityName: 'New York',
-  stateCode: 'USA',
-  languageCode: '02',
-  // ... other fields
-});
-
-if (upsertResult.success) {
-  console.log(upsertResult.data.customerRecordRS?.customerRecordCode);
+  console.log(searchResult.data.masterRecordList);
 } else {
   console.error(
-    upsertResult.error.errorCode,
-    upsertResult.error.errorDescription
+    searchResult.error.kind,
+    searchResult.error.message,
+    searchResult.error.code,
   );
 }
 ```
@@ -75,233 +50,265 @@ if (upsertResult.success) {
 #### Constructor
 
 ```typescript
-new AvesClient(baseURL: string, hostID: string, xtoken: string, languageCode?: string)
+new AvesClient(options: AvesClientOptions)
 ```
 
-- `baseURL` - Base URL of the AVES API
-- `hostID` - 6-digit identification code
-- `xtoken` - Unique validation string
-- `languageCode` - Optional: 2-digit language code (01=Italian, 02=English, etc.)
+| Option         | Description                    |
+| -------------- | ------------------------------ |
+| `baseURL`      | AVES API base URL              |
+| `hostID`       | 6-digit host id                |
+| `xtoken`       | Auth token                     |
+| `languageCode` | Optional 2-digit language code |
+| `timeoutMs`    | Optional request timeout       |
 
-#### Methods
+All methods return `Result<T, AvesError>`:
 
-##### `search(params)`
+```typescript
+type Result<T, E> = { success: true; data: T } | { success: false; error: E };
+```
 
-Search for master records by various criteria. The required fields depend on the `searchType` - TypeScript will enforce the correct fields for each search type.
+---
 
-**Search Types and Required Fields:**
+### Master records
 
-- **`'CODE'`** - Requires `recordCode` (6 digits)
-- **`'NAME'`** - Requires `name`, optionally `city`
-- **`'VATCODE'`** - Requires `vatCode`, optionally `phoneNumber`
-- **`'ZONE'`** - Requires `zipCode` and `countyCode`, optionally `city`
-- **`'CATEGORY'`** - Requires `categoryCode`
-- **`'EMAIL'`** - Requires `email`
-- **`'LASTMODDATE'`** - Requires `lastModificationDate` with `minDate` and `maxDate`
-- **`'SEARCH_FIELD'`** - Requires `searchFieldValue`
-- **`'EXTERNAL_REF_CODE'`** - Requires `searchFieldValue`
+#### `search(params)`
 
-All search types accept an optional `languageCode` (2-digit code).
+Search by `searchType`. TypeScript enforces the required fields per variant.
 
-**Examples:**
+| `searchType`                             | Required fields                              |
+| ---------------------------------------- | -------------------------------------------- |
+| `'CODE'`                                 | `recordCode`                                 |
+| `'NAME'`                                 | `name` (+ optional `city`)                   |
+| `'VATCODE'`                              | `vatCode` (+ optional `phoneNumber`)         |
+| `'ZONE'`                                 | `zipCode`, `countyCode` (+ optional `city`)  |
+| `'CATEGORY'`                             | `categoryCode`                               |
+| `'EMAIL'`                                | `email`                                      |
+| `'LASTMODDATE'`                          | `lastModificationDate: { minDate, maxDate }` |
+| `'SEARCH_FIELD'` / `'EXTERNAL_REF_CODE'` | `searchFieldValue`                           |
 
 ```typescript
-// Search by code
 const byCode = await client.search({
   searchType: 'CODE',
   recordCode: '508558',
 });
 
-if (byCode.success) {
-  console.log('Found records:', byCode.data.masterRecordList);
-}
-
-// Search by email
 const byEmail = await client.search({
   searchType: 'EMAIL',
   email: 'user@example.com',
 });
+```
 
-if (byEmail.success) {
-  console.log('Found:', byEmail.data.masterRecordList);
-} else {
-  console.error('Error:', byEmail.error.message);
-}
+#### `upsertRecord(record)`
 
-// Search by name (with optional city)
-const byName = await client.search({
-  searchType: 'NAME',
-  name: 'John Doe',
-  city: 'New York', // Optional
-});
+Insert or update a master record. `insertCriteria` defaults to `'T'`.
 
-// Search by zone (requires zipCode and countyCode)
-const byZone = await client.search({
-  searchType: 'ZONE',
-  zipCode: '47841',
-  countyCode: 'RN',
-  city: 'Cattolica', // Optional
-});
+- `'S'` — always insert
+- `'N'` — do not update if exists
+- `'T'` — update all fields if exists (default)
+- `'M'` — update secondary fields only
 
-// Search by last modification date
-const byDate = await client.search({
-  searchType: 'LASTMODDATE',
-  lastModificationDate: {
-    minDate: '2024-01-01',
-    maxDate: '2024-12-31',
-  },
+```typescript
+const result = await client.upsertRecord({
+  name: 'Jane Smith',
+  email: 'jane@example.com',
+  address: '456 Oak Ave',
+  zipCode: '67890',
+  cityName: 'Los Angeles',
+  stateCode: 'USA',
+  languageCode: '02',
+  insertCriteria: 'T',
 });
+
+if (result.success) {
+  console.log(result.data.masterRecordDetail?.recordCode);
+}
 ```
 
-##### `upsertRecord(record)`
+---
+
+### Booking
+
+`*List` request fields are **flat arrays of Detail objects**. The SDK wraps them to AVES List/Detail XML automatically.
 
-Insert or update a master record. The `insertCriteria` defaults to `'T'` (update all fields if exists) but can be overridden by including it in the record.
+| Method                    | Purpose                                                    |
+| ------------------------- | ---------------------------------------------------------- |
+| `createBooking`           | Create booking file                                        |
+| `modBookingServices`      | Add/replace services, assign package, delete/nullify lines |
+| `modBookingHeader`        | Header only (pax, notes, billing) — no costs               |
+| `cancelBooking`           | Delete booking file                                        |
+| `setBookingStatus`        | Change file status (`CANCELED` / `NULLIFIED` / …)          |
+| `setBookingServiceStatus` | Nullify a single service line                              |
+| `insertFilePaymentList`   | Register payments on a booking                             |
+
+#### `createBooking(params)`
 
 ```typescript
-const result = await client.upsertRecord({
-  name: string,
-  email: string,
-  address: string,
-  zipCode: string,
-  cityName: string,
-  countyCode: string,
-  stateCode: string,
-  firstPhoneNumber: string,
-  mobilePhoneNumber: string,
-  fiscalCode: string,
-  birthDate: string,
-  gender: string,
-  languageCode: string, // Required
-  categoryCode: string,
-  recordCode: string, // Optional: 6-digit code
-  insertCriteria: 'S' | 'N' | 'T' | 'M', // Optional: defaults to 'T'
-  // ... see types for full list
+const created = await client.createBooking({
+  customerDetail: { recordCode: '138311' },
+  bookingFileStatus: { value: 'QUOTATION' },
+  startDate: '2015-01-22T00:00:00',
+  endDate: '2015-01-25T00:00:00',
+  selectedServiceList: [
+    {
+      sCode: 'HT00110840',
+      ssCode: 'DL',
+      avesServiceType: 'TOP',
+      toServiceType: 'RESIDENCE',
+      startDate: '2015-01-22T00:00:00',
+      endDate: '2015-01-25T00:00:00',
+      qty: '1',
+      pax: '2',
+      paxAssociated: [],
+      avesSession: '1',
+    },
+  ],
+  passengerList: [
+    {
+      rph: '001',
+      roomRph: '001',
+      name: 'ADULTI 001',
+      categoryCode: 'AD', // required on create
+      sex: 'M',
+    },
+  ],
 });
 
-// Result is Result<ManageMasterRecordRS, AvesError>
-if (result.success) {
-  // Access result.data
-} else {
-  // Handle result.error
+if (created.success) {
+  console.log(created.data.bookingFileDetail?.bookingFileCode);
 }
 ```
 
-**Insert Criteria:**
+#### `modBookingServices(params)`
 
-- `'S'` - Insert always new record
-- `'N'` - If record exists, do not update
-- `'T'` - If record exists, update all fields (default)
-- `'M'` - If record exists, update only secondary fields
+```typescript
+const result = await client.modBookingServices({
+  customerRecordCode: '138311',
+  bookingFileCode: '14/036654',
+  selectedPackageDetail: {
+    pCode: '2014MDE0000010',
+    startDate: '2015-01-22T00:00:00',
+    endDate: '2015-01-25T00:00:00',
+  },
+  cancellableBookedServiceList: [
+    {
+      cancelOperationType: 'DELETE', // or 'NULLIFY'
+      serviceRefType: 'RPH',
+      serviceRefValue: '001',
+    },
+  ],
+  selectedServiceList: [
+    {
+      sCode: 'HT00110840',
+      avesServiceType: 'TOP',
+      toServiceType: 'RESIDENCE',
+      startDate: '2015-01-22T00:00:00',
+      endDate: '2015-01-25T00:00:00',
+      qty: '1',
+      pax: '2',
+      avesSession: '1',
+      bookedServiceRef: '001',
+      serviceFare: { currencyCode: 'EUR', cost: '100.00', price: '120.00' },
+    },
+  ],
+});
+```
+
+#### `insertFilePaymentList(params)`
 
-**Example:**
+Requires `bookingFileCode` **or** `bookingFileRefCode`.
 
 ```typescript
-// Default behavior (update all fields if exists)
-const response = await client.upsertRecord({
-  name: 'Jane Smith',
-  email: 'jane@example.com',
-  address: '456 Oak Ave',
-  zipCode: '67890',
-  cityName: 'Los Angeles',
-  stateCode: 'USA',
-  firstPhoneNumber: '+1234567890',
-  languageCode: '02',
+const paid = await client.insertFilePaymentList({
+  bookingFileCode: '18/000172',
+  enableMultiplePayments: true,
+  operationType: 'AbsoluteAmountsInsertion',
+  filePaymentList: [
+    {
+      paymentDate: '2018-09-08',
+      paymentNote: 'INCASSO',
+      amount: '100.00',
+      paymentType: 'B', // C cash | B bank | R card | …
+    },
+  ],
 });
+```
 
-if (response.success) {
-  console.log(response.data.customerRecordRS?.customerRecordCode);
-} else {
-  console.error('Failed:', response.error.message);
-}
+#### Other booking ops
 
-// Override insertCriteria
-const newRecord = await client.upsertRecord({
-  name: 'John Doe',
-  insertCriteria: 'S', // Always insert new
-  email: 'john@example.com',
-  languageCode: '02',
-  // ... other fields
+```typescript
+await client.modBookingHeader({
+  bookingFileCode: '14/000043',
+  bookingFileStartDate: '2014-04-28',
+  customerRecordCode: '103737',
+  passengerList: [{ rph: '001', name: 'ADULTI 001', sex: 'M' }],
 });
 
-if (newRecord.success) {
-  console.log('Created:', newRecord.data.customerRecordRS?.customerRecordCode);
-}
+await client.setBookingStatus({
+  customerRecordCode: '000170',
+  bookingFileCode: '14/000081',
+  fileStatus: { value: 'CANCELED' },
+});
+
+await client.setBookingServiceStatus({
+  customerRecordCode: '000001',
+  bookingFileCode: '18/000252',
+  bookingServiceRef: '002',
+  bookingFileServiceStatus: 'NULLIFIED',
+});
+
+await client.cancelBooking({
+  bookingFileCode: '14/000081',
+  customerRecordCode: '000170',
+});
 ```
 
-## Error Handling
+---
 
-The SDK uses a functional `Result` pattern for type-safe error handling. All methods return `Result<Success, AvesError>` instead of throwing exceptions:
+## Error Handling
 
 ```typescript
-import { AvesClient, AvesError, type Result } from 'aves-sdk';
+import { AvesClient, AvesError } from 'aves-sdk';
 
 const result = await client.search({
   searchType: 'CODE',
   recordCode: '508558',
 });
 
-if (result.success) {
-  // TypeScript knows result.data is SearchMasterRecordRS
-  console.log(result.data.masterRecordList);
-} else {
-  // TypeScript knows result.error is AvesError
-  console.error('Status:', result.error.status); // 'ERROR' | 'TIMEOUT' | 'WARNING'
-  console.error('Error Code:', result.error.errorCode);
-  console.error('Description:', result.error.errorDescription);
+if (!result.success) {
+  // AvesError: kind ('validation' | 'api' | 'unknown'), message, status?, code?
+  console.error(result.error.kind, result.error.message, result.error.code);
 }
 ```
 
-**Result Type:**
-
-```typescript
-type Result<T, E> = { success: true; data: T } | { success: false; error: E };
-```
-
-This pattern ensures:
-
-- **Type safety**: TypeScript narrows the type based on `success`
-- **No exceptions**: All errors are explicit in the return type
-- **Functional style**: Easier to compose and chain operations
-
 ## Case Transformation
 
-The SDK automatically handles case transformation between your code and the API:
+- **Input**: camelCase (`recordCode`, `selectedServiceList`)
+- **Wire**: PascalCase / `@` attributes for XML
+- **Output**: camelCase again
 
-- **Input**: Use camelCase (e.g., `recordCode`, `zipCode`)
-- **API**: Automatically converted to PascalCase with XML attributes (e.g., `@RecordCode`, `ZipCode`)
-- **Output**: Automatically converted back to camelCase
+You do not handle XML attribute prefixes yourself.
 
-You never need to worry about case conversion or XML attribute prefixes - the SDK handles it all.
-
-## Type Safety
-
-All types are exported and inferred from the validation schemas:
+## Types
 
 ```typescript
 import type {
+  AvesClientOptions,
+  SearchMasterRecord,
   SearchMasterRecordRS,
-  ManageMasterRecordRS,
   MasterRecordDetail,
+  ManageMasterRecordRS,
+  BookingFileRQ,
+  BookingFileRS,
+  ModFileServicesRQ,
+  ModFileHeaderRQ,
+  CancelFileRQ,
+  SetFileStatusRQ,
+  SetFileServiceStatusRQ,
+  FilePaymentListRQ,
+  BookingStatusOnlyRS,
 } from 'aves-sdk';
-
-// Use types for your functions
-function processRecord(record: MasterRecordDetail) {
-  // TypeScript knows all available fields in camelCase
-}
 ```
 
-## Validation
-
-The SDK validates all inputs and outputs using Valibot schemas:
-
-- **HostID**: Must be exactly 6 digits
-- **RecordCode**: Must be exactly 6 characters
-- **LanguageCode**: Must be exactly 2 digits (01=Italian, 02=English, etc.)
-- **Search parameters**: Required fields are enforced based on `searchType` using discriminated unions
-- All other fields follow the AVES API specification
-
-Invalid data will return an error `Result` before making the API request. All validation happens on camelCase input, making it easy to use. TypeScript will also provide type checking and autocomplete based on the selected `searchType`.
-
 ## License
 
 MIT