aves-sdk 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -0,0 +1,224 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.7.0] - 2026-08-03
+
+### Added
+
+- Package / Program catalog APIs: `searchPackages`, `searchTopServices`, `getPackageDetail`, `commitPackage`
+- `searchBookingFiles` (`FILE_CODE` | `PAX_NAME` | `PACKAGE_CODE` | `OTHER`)
+- Domain clients with DI: `AvesTransport`, `MasterRecordsClient`, `BookingClient`, `PackageCatalogClient`, `AvesClientDeps`
+- Per-request `WireShape` model (`src/utils/wire-shapes.ts`)
+- Flat method aliases auto-bound from domain prototypes (`client/flat-aliases.ts`)
+
+### Changed
+
+- `AvesClient` is a thin facade; prefer `client.booking.*` / `client.packages.*` / `client.master.*`
+- Single outbound wire path: `createApiSchema` / `toWireBody` / `invokeOp` (optional `bodyKey`)
+- XML helpers moved to `src/xml/`
+- Master search/upsert routed through `invokeOp`
+
+### Fixed
+
+- InsertFilePaymentList root `paymentUser` emitted as `@PaymentUser` (not a child element)
+
+### Removed
+
+- Global `ATTRIBUTE_FIELDS` registry
+- Versioned docs under `docs/` from git (`docs/` gitignored)
+
+---
+
+## [1.6.0] - 2026-07-29
+
+### Changed
+
+- **Breaking:** booking `*List` SDK inputs are flat `Detail[]`; SDK wraps to AVES List/Detail XML
+- Shared `PaymentTypeSchema` across booking ops
+- README refreshed for constructor, `Result` / `AvesError`, and flat list examples
+- Documented additional package managers in README
+
+---
+
+## [1.5.1] - 2026-07-29
+
+### Changed
+
+- Added `fast-xml-builder` dependency
+- Dependency / `tsdown` config maintenance
+
+---
+
+## [1.5.0] - 2026-07-29
+
+### Added
+
+- `insertFilePaymentList` (InsertFilePaymentList) for payment registration
+- Tighter `invokeOp` schema inference
+- Booking ops documentation updates
+
+---
+
+## [1.4.0] - 2026-07-29
+
+### Added
+
+- Booking ops: ModBookingFileServices, ModBookingFileHeader, CancelBookingFile, SetStatus / SetStatusService
+- Shared transforms and typed BOOKEDFILE responses
+- Unit coverage for booking ops
+
+### Changed
+
+- Dependency updates
+
+---
+
+## [1.3.4] - 2026-03-09
+
+### Added
+
+- Create-booking related input schemas: financial deadlines, payments, selected packages/services, notes, passengers
+
+### Fixed
+
+- Union formatting in `SelectedServiceListInputSchema`
+
+### Changed
+
+- Error handling via `isOk`
+- Schema / quote standardization across client and types
+
+---
+
+## [1.3.3] - 2026-02-26
+
+### Fixed
+
+- `package.json` packaging fix
+
+---
+
+## [1.3.2] - 2026-02-10
+
+### Added
+
+- `createBooking` (CreateBookingFile) with tests
+- Migrated bundler from `tsup` to `tsdown`
+
+### Changed
+
+- Package configuration updates
+
+---
+
+## [1.3.1] - 2026-02-01
+
+### Changed
+
+- Error-handling path formatting simplified
+- String-quote standardization
+
+---
+
+## [1.3.0] - 2026-02-01
+
+### Added
+
+- Biome linting
+- Undici-based mock improvements in tests
+- Additional master-record properties and attribute-schema refactor
+- Broader test coverage
+
+### Changed
+
+- Consolidated XML root element definitions and utilities
+
+---
+
+## [1.2.16] - 2026-01-27
+
+### Changed
+
+- Removed unnecessary `as any` casts
+
+---
+
+## [1.2.15] - 2026-01-27
+
+### Fixed
+
+- XML / validation follow-up fixes
+
+---
+
+## [1.2.14] - 2026-01-27
+
+### Changed
+
+- XML ↔ JSON conversion and validation schema improvements
+
+---
+
+## [1.2.13] - 2026-01-27
+
+### Added
+
+- Request timeout handling with clear timeout vs other errors
+- `isAbortError` utility
+
+### Changed
+
+- `AvesClientOptions` moved to `types.ts`
+- Request method uses Valibot `BaseSchema` more consistently
+- Upsert response schema and error detail improvements
+- `recordCode` length validation tests
+
+---
+
+## [1.2.12] - 2026-01-26
+
+### Added
+
+- Export `AvesClientOptions` for external usage
+- Mapped profiling record support
+
+### Changed
+
+- Restructured `AvesError` handling and client initialization
+- Optional `insertCriteria` on upsert flow
+
+### Fixed
+
+- Misc client fixes
+
+---
+
+## [1.2.11] - 2026-01-21
+
+### Fixed
+
+- Error code handling uses numeric values instead of strings
+
+---
+
+## [1.0.3] - 2025-10-04
+
+Early tagged releases (`v1.0.0` … `v1.0.3`) from the initial NestJS-oriented AVES SDK work. Detailed commit notes for those tags are limited in the current branch history.
+
+### Added
+
+- Initial AVES SDK implementation with XML/REST interfaces (2025-10-03)
+
+---
+
+## Links
+
+- [npm](https://www.npmjs.com/package/aves-sdk)
+- [GitHub](https://github.com/simoneguglielmi/aves-sdk)
+- Tags: [v1.0.0](https://github.com/simoneguglielmi/aves-sdk/releases/tag/v1.0.0) … [v1.0.3](https://github.com/simoneguglielmi/aves-sdk/releases/tag/v1.0.3)
+
+> Git tags after `v1.0.3` were not present when this file was generated; version sections follow `package.json` bumps and commit messages.

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` is a facade over domain clients. **Prefer namespaces.** Flat methods are auto-bound from domain prototypes (no hand-maintained forwarders).
+
+```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(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)`
+### `upsertRecord(record)` / `client.master.upsertRecord`
 
-Insert or update a master record. `insertCriteria` defaults to `'T'`.
-
-- `'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,94 @@ 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 (`avesSearchType`: `PACKAGE` / `PROGRAM`) |
+| `searchTopServices` | Search TOP services (`avesSearchType`: `SERVICE`) |
+| `getPackageDetail` | Package base info + service list |
+| `commitPackage` | Publish existing package (`packageCode` only) |
+
+```typescript
+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',
+});
+
+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,24 +358,74 @@ 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,
+  AvesClientDeps,
   SearchMasterRecord,
   SearchMasterRecordRS,
   MasterRecordDetail,
@@ -306,6 +439,24 @@ import type {
   SetFileServiceStatusRQ,
   FilePaymentListRQ,
   BookingStatusOnlyRS,
+  SearchBookingFileRQ,
+  SearchBookingFileRS,
+  AvesSearchRQ,
+  SearchPackageRS,
+  SearchServicesRS,
+  PackageDetailRQ,
+  PackageDetailRS,
+  CommitPackageRQ,
+  CommitPackageRS,
+} from 'aves-sdk';
+
+import {
+  AvesClient,
+  AvesTransport,
+  MasterRecordsClient,
+  BookingClient,
+  PackageCatalogClient,
+  AvesError,
 } from 'aves-sdk';
 ```
 
@@ -315,6 +466,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)