aves-sdk 1.6.0 → 1.8.0

package/README.md

@@ -1,6 +1,6 @@
 # AVES SDK
 
-Type-safe TypeScript SDK for the AVES XML REST API. Handles XML parsing, Valibot validation, camelCase ↔ PascalCase, and returns `Result` instead of throwing.
+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
 
@@ -14,7 +14,7 @@ pnpm add aves-sdk
 bun add aves-sdk
 ```
 
-## Quick Start
+## Quick start
 
 ```typescript
 import { AvesClient } from 'aves-sdk';
@@ -27,67 +27,99 @@ const client = new AvesClient({
   timeoutMs: 30_000, // optional
 });
 
-const searchResult = await client.search({
+const result = await client.search({
   searchType: 'CODE',
   recordCode: '508558',
 });
 
-if (searchResult.success) {
-  console.log(searchResult.data.masterRecordList);
+if (result.success) {
+  console.log(result.data.masterRecordList);
 } else {
-  console.error(
-    searchResult.error.kind,
-    searchResult.error.message,
-    searchResult.error.code,
-  );
+  console.error(result.error.kind, result.error.message, result.error.code);
 }
 ```
 
-## API Reference
+## Client shape
 
-### `AvesClient`
+`AvesClient` is a facade over domain clients. **Prefer namespaces.** Flat methods are auto-bound from domain prototypes (no hand-maintained forwarders).
 
-#### Constructor
+```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' });
+```
+
+| Namespace | Methods |
+| --------- | ------- |
+| `master` | `search`, `upsertRecord` |
+| `booking` | `createBooking`, `modBookingServices`, `modBookingHeader`, `cancelBooking`, `setBookingStatus`, `setBookingServiceStatus`, `insertFilePaymentList`, `searchBookingFiles` |
+| `packages` | `searchPackages`, `searchTopServices`, `getPackageDetail`, `commitPackage` |
+
+### Constructor
 
 ```typescript
-new AvesClient(options: AvesClientOptions)
+new AvesClient(options: AvesClientOptions, deps?: AvesClientDeps)
 ```
 
-| Option         | Description                    |
-| -------------- | ------------------------------ |
-| `baseURL`      | AVES API base URL              |
-| `hostID`       | 6-digit host id                |
-| `xtoken`       | Auth token                     |
+| 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       |
+| `timeoutMs` | Optional request timeout (default 30000) |
 
-All methods return `Result<T, AvesError>`:
+Optional DI (tests / custom transport):
 
 ```typescript
-type Result<T, E> = { success: true; data: T } | { success: false; error: E };
+import {
+  AvesClient,
+  AvesTransport,
+  BookingClient,
+} from 'aves-sdk';
+
+const transport = new AvesTransport(options);
+new AvesClient(options, {
+  transport,
+  booking: new BookingClient(transport),
+});
 ```
 
----
+### Result type
+
+All methods return `Result<T, AvesError>` — they do **not** throw.
+
+```typescript
+type Result<T, E> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+```
 
-### Master records
+---
 
-#### `search(params)`
+## Master records
 
-Search by `searchType`. TypeScript enforces the required fields per variant.
+### `search(params)` / `client.master.search`
 
-| `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`                           |
+| `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
-const byCode = await client.search({
+const byCode = await client.master.search({
   searchType: 'CODE',
   recordCode: '508558',
 });
@@ -98,23 +130,14 @@ const byEmail = await client.search({
 });
 ```
 
-#### `upsertRecord(record)`
-
-Insert or update a master record. `insertCriteria` defaults to `'T'`.
+### `upsertRecord(record)` / `client.master.upsertRecord`
 
-- `'S'` — always insert
-- `'N'` — do not update if exists
-- `'T'` — update all fields if exists (default)
-- `'M'` — update secondary fields only
+`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',
-  address: '456 Oak Ave',
-  zipCode: '67890',
-  cityName: 'Los Angeles',
-  stateCode: 'USA',
   languageCode: '02',
   insertCriteria: 'T',
 });
@@ -126,24 +149,25 @@ if (result.success) {
 
 ---
 
-### Booking
+## Booking
 
-`*List` request fields are **flat arrays of Detail objects**. The SDK wraps them to AVES List/Detail XML automatically.
+`*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 on a booking                             |
+| 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`) |
 
-#### `createBooking(params)`
+### Create
 
 ```typescript
-const created = await client.createBooking({
+const created = await client.booking.createBooking({
   customerDetail: { recordCode: '138311' },
   bookingFileStatus: { value: 'QUOTATION' },
   startDate: '2015-01-22T00:00:00',
@@ -178,10 +202,10 @@ if (created.success) {
 }
 ```
 
-#### `modBookingServices(params)`
+### Modify services / package / overwrite lines
 
 ```typescript
-const result = await client.modBookingServices({
+await client.booking.modBookingServices({
   customerRecordCode: '138311',
   bookingFileCode: '14/036654',
   selectedPackageDetail: {
@@ -213,13 +237,16 @@ const result = await client.modBookingServices({
 });
 ```
 
-#### `insertFilePaymentList(params)`
+### Payments
 
 Requires `bookingFileCode` **or** `bookingFileRefCode`.
 
+`paymentUser` is serialized as an XML **attribute** on `FilePaymentListRQ` (`PaymentUser="…"`), not as a child element.
+
 ```typescript
-const paid = await client.insertFilePaymentList({
+await client.booking.insertFilePaymentList({
   bookingFileCode: '18/000172',
+  paymentUser: 'MLDN',
   enableMultiplePayments: true,
   operationType: 'AbsoluteAmountsInsertion',
   filePaymentList: [
@@ -233,38 +260,91 @@ const paid = await client.insertFilePaymentList({
 });
 ```
 
-#### Other booking ops
+### Header, status, cancel, search practices
 
 ```typescript
-await client.modBookingHeader({
+await client.booking.modBookingHeader({
   bookingFileCode: '14/000043',
   bookingFileStartDate: '2014-04-28',
   customerRecordCode: '103737',
   passengerList: [{ rph: '001', name: 'ADULTI 001', sex: 'M' }],
 });
 
-await client.setBookingStatus({
+await client.booking.setBookingStatus({
   customerRecordCode: '000170',
   bookingFileCode: '14/000081',
   fileStatus: { value: 'CANCELED' },
 });
 
-await client.setBookingServiceStatus({
+await client.booking.setBookingServiceStatus({
   customerRecordCode: '000001',
   bookingFileCode: '18/000252',
   bookingServiceRef: '002',
   bookingFileServiceStatus: 'NULLIFIED',
 });
 
-await client.cancelBooking({
+await client.booking.cancelBooking({
   bookingFileCode: '14/000081',
   customerRecordCode: '000170',
 });
+
+await client.booking.searchBookingFiles({
+  searchType: 'PACKAGE_CODE',
+  customerRecordCode: '138311',
+  packageCode: '2014MDE0000010',
+});
+```
+
+---
+
+## Package / Program catalog
+
+There is **no** Create Package API in AVES XML 1.8.0. Search, detail, and commit (publish) are supported.
+
+| Method | Purpose |
+| ------ | ------- |
+| `searchPackages` | Search programs (defaults `avesSearchType: 'PACKAGE'`) |
+| `searchTopServices` | Search TOP services (defaults `avesSearchType: 'SERVICE'`) |
+| `getPackageDetail` | Package base info + service list |
+| `commitPackage` | Publish existing package (`packageCode` only) |
+
+`paxQty` defaults to `passengerList.length`; `paxQtyCriteria` defaults to `GREATER_OR_EQUAL`. `languageCode` can be omitted when set on `AvesClient` options.
+
+```typescript
+const packages = await client.packages.searchPackages({
+  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',
+    },
+  ],
+  servOrPackCode: '2014MDE0000010',
+});
+
+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' },
+  ],
+});
+
+await client.packages.commitPackage({ packageCode: '14/PACKAGE001' });
 ```
 
 ---
 
-## Error Handling
+## Errors
 
 ```typescript
 import { AvesClient, AvesError } from 'aves-sdk';
@@ -275,38 +355,100 @@ const result = await client.search({
 });
 
 if (!result.success) {
-  // AvesError: kind ('validation' | 'api' | 'unknown'), message, status?, code?
+  // kind: 'validation' | 'api' | 'unknown'
   console.error(result.error.kind, result.error.message, result.error.code);
 }
 ```
 
-## Case Transformation
+---
+
+## Case transformation & wire shapes
 
-- **Input**: camelCase (`recordCode`, `selectedServiceList`)
-- **Wire**: PascalCase / `@` attributes for XML
+- **Input**: camelCase (`recordCode`, `selectedServiceList`, `paymentUser`)
+- **Wire**: PascalCase keys; `@`-prefixed keys become XML attributes
 - **Output**: camelCase again
 
-You do not handle XML attribute prefixes yourself.
+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  
+
+Element-only roots use `elementOnlyWire` (`{}`). Master upsert nests under `bodyKey: "MasterRecordDetail"`; master search and booking spread fields at the RQ root.
+
+### Request shapes (one family per op)
+
+| 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 |
+
+Editing CreateBooking shapes does not affect SearchFile or AvesSearch.
+
+---
+
+## Architecture
+
+`AvesClient` (`src/client.ts`) is a thin facade over DI-friendly domain clients:
+
+| 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,
-  SearchMasterRecord,
-  SearchMasterRecordRS,
-  MasterRecordDetail,
-  ManageMasterRecordRS,
+  AvesClientDeps,
+  AvesSearchRQ,
   BookingFileRQ,
-  BookingFileRS,
-  ModFileServicesRQ,
-  ModFileHeaderRQ,
-  CancelFileRQ,
-  SetFileStatusRQ,
-  SetFileServiceStatusRQ,
-  FilePaymentListRQ,
-  BookingStatusOnlyRS,
+  SearchMasterRecord,
+} from 'aves-sdk';
+
+import {
+  AvesClient,
+  AvesTransport,
+  MasterRecordsClient,
+  BookingClient,
+  PackageCatalogClient,
+  AvesError,
+  // object enums
+  AvesSearchType,
+  BookingFileStatus,
+  InsertCriteria,
+  PassengerCategory,
+  PaxQtyCriteria,
+  PaymentType,
+  SearchMasterType,
 } from 'aves-sdk';
+
+PaxQtyCriteria.GREATER_OR_EQUAL
+AvesSearchType.PACKAGE
+PaymentType.B
+InsertCriteria.T
 ```
 
 ## License
@@ -315,6 +457,7 @@ 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)