aves-sdk 1.5.1 → 1.7.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 / `@` attrs, and returns `Result` instead of throwing.
 
 ## Installation
 
@@ -22,292 +14,459 @@ pnpm add aves-sdk
 bun add aves-sdk
 ```
 
-## Quick Start
+## Quick start
 
 ```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({
+const result = await client.search({
   searchType: 'CODE',
   recordCode: '508558',
 });
 
-if (searchResult.success) {
-  console.log(searchResult.data); // SearchMasterRecordRS
+if (result.success) {
+  console.log(result.data.masterRecordList);
 } else {
-  console.error(searchResult.error); // AvesError
+  console.error(result.error.kind, result.error.message, result.error.code);
 }
+```
 
-// 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
-});
+## Client shape
 
-if (upsertResult.success) {
-  console.log(upsertResult.data.customerRecordRS?.customerRecordCode);
-} else {
-  console.error(
-    upsertResult.error.errorCode,
-    upsertResult.error.errorDescription
-  );
-}
-```
+`AvesClient` is a facade over domain clients. **Prefer namespaces.** Flat methods are auto-bound from domain prototypes (no hand-maintained forwarders).
 
-## API Reference
+```typescript
+// canonical
+await client.booking.createBooking(params);
+await client.packages.searchPackages(params);
+await client.master.search({ searchType: 'CODE', recordCode: '508558' });
+
+// flat compat (same implementations)
+await client.createBooking(params);
+await client.searchPackages(params);
+await client.search({ searchType: 'CODE', recordCode: '508558' });
+```
 
-### `AvesClient`
+| Namespace | Methods |
+| --------- | ------- |
+| `master` | `search`, `upsertRecord` |
+| `booking` | `createBooking`, `modBookingServices`, `modBookingHeader`, `cancelBooking`, `setBookingStatus`, `setBookingServiceStatus`, `insertFilePaymentList`, `searchBookingFiles` |
+| `packages` | `searchPackages`, `searchTopServices`, `getPackageDetail`, `commitPackage` |
 
-#### Constructor
+### Constructor
 
 ```typescript
-new AvesClient(baseURL: string, hostID: string, xtoken: string, languageCode?: string)
+new AvesClient(options: AvesClientOptions, deps?: AvesClientDeps)
 ```
 
-- `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 (default 30000) |
+
+Optional DI (tests / custom transport):
+
+```typescript
+import {
+  AvesClient,
+  AvesTransport,
+  BookingClient,
+} from 'aves-sdk';
+
+const transport = new AvesTransport(options);
+new AvesClient(options, {
+  transport,
+  booking: new BookingClient(transport),
+});
+```
 
-#### Methods
+### Result type
 
-##### `search(params)`
+All methods return `Result<T, AvesError>` — they do **not** throw.
 
-Search for master records by various criteria. The required fields depend on the `searchType` - TypeScript will enforce the correct fields for each search type.
+```typescript
+type Result<T, E> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+```
 
-**Search Types and Required Fields:**
+---
 
-- **`'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`
+## Master records
 
-All search types accept an optional `languageCode` (2-digit code).
+### `search(params)` / `client.master.search`
 
-**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({
+const byCode = await client.master.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)` / `client.master.upsertRecord`
 
-// Search by name (with optional city)
-const byName = await client.search({
-  searchType: 'NAME',
-  name: 'John Doe',
-  city: 'New York', // Optional
+`insertCriteria`: `'S'` always insert · `'N'` skip if exists · `'T'` update all (default) · `'M'` secondary fields only.
+
+```typescript
+const result = await client.upsertRecord({
+  name: 'Jane Smith',
+  email: 'jane@example.com',
+  languageCode: '02',
+  insertCriteria: 'T',
 });
 
-// Search by zone (requires zipCode and countyCode)
-const byZone = await client.search({
-  searchType: 'ZONE',
-  zipCode: '47841',
-  countyCode: 'RN',
-  city: 'Cattolica', // Optional
+if (result.success) {
+  console.log(result.data.masterRecordDetail?.recordCode);
+}
+```
+
+---
+
+## Booking
+
+`*List` request fields are **flat arrays of Detail objects**. The SDK wraps them to AVES List/Detail XML.
+
+| 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 |
+| `searchBookingFiles` | Search practices (`FILE_CODE`, `PAX_NAME`, `PACKAGE_CODE`, `OTHER`) |
+
+### Create
+
+```typescript
+const created = await client.booking.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',
+    },
+  ],
 });
 
-// Search by last modification date
-const byDate = await client.search({
-  searchType: 'LASTMODDATE',
-  lastModificationDate: {
-    minDate: '2024-01-01',
-    maxDate: '2024-12-31',
+if (created.success) {
+  console.log(created.data.bookingFileDetail?.bookingFileCode);
+}
+```
+
+### Modify services / package / overwrite lines
+
+```typescript
+await client.booking.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' },
+    },
+  ],
 });
 ```
 
-##### `upsertRecord(record)`
+### Payments
 
-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.
+Requires `bookingFileCode` **or** `bookingFileRefCode`.
+
+`paymentUser` is serialized as an XML **attribute** on `FilePaymentListRQ` (`PaymentUser="…"`), not as a child element.
 
 ```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
+await client.booking.insertFilePaymentList({
+  bookingFileCode: '18/000172',
+  paymentUser: 'MLDN',
+  enableMultiplePayments: true,
+  operationType: 'AbsoluteAmountsInsertion',
+  filePaymentList: [
+    {
+      paymentDate: '2018-09-08',
+      paymentNote: 'INCASSO',
+      amount: '100.00',
+      paymentType: 'B', // C cash | B bank | R card | …
+    },
+  ],
 });
+```
 
-// Result is Result<ManageMasterRecordRS, AvesError>
-if (result.success) {
-  // Access result.data
-} else {
-  // Handle result.error
-}
+### Header, status, cancel, search practices
+
+```typescript
+await client.booking.modBookingHeader({
+  bookingFileCode: '14/000043',
+  bookingFileStartDate: '2014-04-28',
+  customerRecordCode: '103737',
+  passengerList: [{ rph: '001', name: 'ADULTI 001', sex: 'M' }],
+});
+
+await client.booking.setBookingStatus({
+  customerRecordCode: '000170',
+  bookingFileCode: '14/000081',
+  fileStatus: { value: 'CANCELED' },
+});
+
+await client.booking.setBookingServiceStatus({
+  customerRecordCode: '000001',
+  bookingFileCode: '18/000252',
+  bookingServiceRef: '002',
+  bookingFileServiceStatus: 'NULLIFIED',
+});
+
+await client.booking.cancelBooking({
+  bookingFileCode: '14/000081',
+  customerRecordCode: '000170',
+});
+
+await client.booking.searchBookingFiles({
+  searchType: 'PACKAGE_CODE',
+  customerRecordCode: '138311',
+  packageCode: '2014MDE0000010',
+});
 ```
 
-**Insert Criteria:**
+---
+
+## Package / Program catalog
 
-- `'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
+There is **no** Create Package API in AVES XML 1.8.0. Search, detail, and commit (publish) are supported.
 
-**Example:**
+| Method | Purpose |
+| ------ | ------- |
+| `searchPackages` | Search programs (`avesSearchType`: `PACKAGE` / `PROGRAM`) |
+| `searchTopServices` | Search TOP services (`avesSearchType`: `SERVICE`) |
+| `getPackageDetail` | Package base info + service list |
+| `commitPackage` | Publish existing package (`packageCode` only) |
 
 ```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 packages = await client.packages.searchPackages({
+  baseSearch: {
+    customerRecordCode: '138311',
+    languageCode: '01',
+    currencyCode: 'EUR',
+    startDate: '2014-12-27T00:00:00',
+    endDate: '2015-01-03T00:00:00',
+    passengerList: [
+      {
+        rph: '001',
+        roomRph: '001',
+        name: 'ADULTI 001',
+        categoryCode: 'AD',
+        sex: 'M',
+      },
+    ],
+  },
+  avesSearchType: 'PACKAGE',
+  paxQty: '1',
+  paxQtyCriteria: 'GREATER_OR_EQUAL',
+  servOrPackCode: '2014MDE0000010',
 });
 
-if (response.success) {
-  console.log(response.data.customerRecordRS?.customerRecordCode);
-} else {
-  console.error('Failed:', response.error.message);
-}
-
-// Override insertCriteria
-const newRecord = await client.upsertRecord({
-  name: 'John Doe',
-  insertCriteria: 'S', // Always insert new
-  email: 'john@example.com',
-  languageCode: '02',
-  // ... other fields
+const detail = await client.packages.getPackageDetail({
+  customerRecordCode: '001692',
+  packageCode: '2015F042',
+  startDate: '2015-05-02T00:00:00',
+  endDate: '2015-05-05T00:00:00',
+  selectedServiceList: [
+    { serviceCode: 'PFRM04    PAR', packageRow: '01' },
+  ],
 });
 
-if (newRecord.success) {
-  console.log('Created:', newRecord.data.customerRecordRS?.customerRecordCode);
-}
+await client.packages.commitPackage({ packageCode: '14/PACKAGE001' });
 ```
 
-## Error Handling
+---
 
-The SDK uses a functional `Result` pattern for type-safe error handling. All methods return `Result<Success, AvesError>` instead of throwing exceptions:
+## Errors
 
 ```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) {
+  // kind: 'validation' | 'api' | 'unknown'
+  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 };
-```
+## Case transformation & wire shapes
+
+- **Input**: camelCase (`recordCode`, `selectedServiceList`, `paymentUser`)
+- **Wire**: PascalCase keys; `@`-prefixed keys become XML attributes
+- **Output**: camelCase again
+
+You do not handle XML attribute prefixes yourself. Attr vs element is decided by a **per-request `WireShape`** (`src/utils/wire-shapes.ts`), not a global field set.
+
+### Pipeline
+
+One outbound path for all ops:
+
+1. Valibot validates camelCase input  
+2. `createApiSchema(schema, shape, wrap?)` → `toWireBody` (optional list wrap + empty `paxAssociated` normalize + `camelToPascalKeys`)  
+3. `AvesTransport.invokeOp` adds `RqHeader`, optional `bodyKey` nest, POSTs XML  
 
-This pattern ensures:
+Element-only roots use `elementOnlyWire` (`{}`). Master upsert nests under `bodyKey: "MasterRecordDetail"`; master search and booking spread fields at the RQ root.
 
-- **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
+### Request shapes (one family per op)
 
-## Case Transformation
+| Shape | Used by |
+| ----- | ------- |
+| `masterRecordWire` / `searchMasterWire` | Upsert / Search master |
+| `bookingFileWire` | CreateBooking, ModFileServices, ModFileHeader |
+| `filePaymentListRequestWire` | InsertFilePaymentList (`paymentUser` root attr) |
+| `searchFileWire` | SearchBookingFiles (date ranges / insurance attrs) |
+| `setFileStatusWire` | SetBookingFileStatus |
+| `packageDetailRequestWire` | GetPackageDetail |
+| `baseSearchWire` + `avesSearchWire` | SearchAvesPackages / SearchTopServices |
+| `elementOnlyWire` | CancelFile, SetFileServiceStatus, CommitPackage |
 
-The SDK automatically handles case transformation between your code and the API:
+Editing CreateBooking shapes does not affect SearchFile or AvesSearch.
 
-- **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 never need to worry about case conversion or XML attribute prefixes - the SDK handles it all.
+## Architecture
 
-## Type Safety
+`AvesClient` (`src/client.ts`) is a thin facade over DI-friendly domain clients:
 
-All types are exported and inferred from the validation schemas:
+| Module | Role |
+| ------ | ---- |
+| `AvesTransport` | HTTP + XML encode/decode + `invokeOp` (optional `bodyKey`) |
+| `MasterRecordsClient` | search / upsert |
+| `BookingClient` | booking file ops + search practices |
+| `PackageCatalogClient` | package/program catalog |
+| `client/types.ts` | `AvesClientDeps` / `AvesClientFlat` |
+| `client/flat-aliases.ts` | bind flat compat methods from domain prototypes |
+| `src/xml/` | XML root helpers + JSON ↔ XML |
+
+Flat aliases (`client.createBooking`, …) are attached in the constructor — add a domain method once and both surfaces work.
+
+Outbound path: validate → `createApiSchema` / `toWireBody` → `invokeOp` → XML POST.
+
+---
+
+## Types
 
 ```typescript
 import type {
+  AvesClientOptions,
+  AvesClientDeps,
+  SearchMasterRecord,
   SearchMasterRecordRS,
-  ManageMasterRecordRS,
   MasterRecordDetail,
+  ManageMasterRecordRS,
+  BookingFileRQ,
+  BookingFileRS,
+  ModFileServicesRQ,
+  ModFileHeaderRQ,
+  CancelFileRQ,
+  SetFileStatusRQ,
+  SetFileServiceStatusRQ,
+  FilePaymentListRQ,
+  BookingStatusOnlyRS,
+  SearchBookingFileRQ,
+  SearchBookingFileRS,
+  AvesSearchRQ,
+  SearchPackageRS,
+  SearchServicesRS,
+  PackageDetailRQ,
+  PackageDetailRS,
+  CommitPackageRQ,
+  CommitPackageRS,
 } from 'aves-sdk';
 
-// Use types for your functions
-function processRecord(record: MasterRecordDetail) {
-  // TypeScript knows all available fields in camelCase
-}
+import {
+  AvesClient,
+  AvesTransport,
+  MasterRecordsClient,
+  BookingClient,
+  PackageCatalogClient,
+  AvesError,
+} from 'aves-sdk';
 ```
 
-## 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
 
 ## Links
 
+- [Changelog](./CHANGELOG.md)
 - [GitHub Repository](https://github.com/simoneguglielmi/aves-sdk)
 - [NPM Package](https://npmjs.com/package/aves-sdk)
 - [Issue Tracker](https://github.com/simoneguglielmi/aves-sdk/issues)