aves-sdk 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -5,12 +5,120 @@ 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).
 
+## [4.0.0] - 2026-08-06
+
+### Added
+
+- `OpBodyKey` object enum (`MasterRecordDetail`) for RQ payload nest keys; typed on `AVES_OPS` / envelope.
+- `AvesOp` object enum (+ `AvesOpSchema`) for `invokeOp` keys; domains use `AvesOp.create` instead of string literals.
+
+### Changed
+
+- **Breaking:** Domain method names no longer repeat the namespace / AVES verb soup. `AVES_OPS` keys follow the same short names (with `searchBookings` / `searchPackages` where `search` would collide).
+
+| Namespace | 3.x | 4.x |
+| --------- | --- | --- |
+| `master` | `upsertRecord` | `upsert` |
+| `booking` | `createBooking` | `create` |
+| `booking` | `modBookingServices` | `updateServices` |
+| `booking` | `modBookingHeader` | `updateHeader` |
+| `booking` | `cancelBooking` | `cancel` |
+| `booking` | `setBookingStatus` | `setStatus` |
+| `booking` | `setBookingServiceStatus` | `setServiceStatus` |
+| `booking` | `insertFilePaymentList` | `addPayments` |
+| `booking` | `searchBookingFiles` | `search` |
+| `packages` | `searchPackages` | `search` |
+| `packages` | `searchTopServices` | `searchServices` |
+| `packages` | `getPackageDetail` | `get` |
+| `packages` | `commitPackage` | `commit` |
+
+`master.search` is unchanged. Endpoint URLs and XML roots are unchanged.
+
+### Migration (1.x / 3.x → 4.x)
+
+Jump straight to 4.x for September apps: apply the 3.x facade + `master.search` flat-array notes, then rename methods per the table above (no compatibility aliases).
+
+```ts
+// 3.x
+await client.booking.createBooking(params);
+await client.packages.searchPackages(params);
+await client.master.upsertRecord(record);
+
+// 4.x
+await client.booking.create(params);
+await client.packages.search(params);
+await client.master.upsert(record);
+```
+
+## [3.1.1] - 2026-08-06
+
+### Added
+
+- Concise facade aliases for common I/O properties: `customerCode`, `bookingCode`, `services`, `passengers`, `packageCode`, `serviceCode`, `quantity`, `session`, and related fields.
+- Schema-owned dual keys via `facadeObject` / `coalesceAliases` (same pattern as `coalesceCustomerRecordCode`).
+- Simplified public type aliases including `BookingInput`, `Booking`, `MasterRecord`, `PackageInput`, and `Package`.
+- `AVES_OPS` registry + `invokeOp(op, params)` with external `OpParams` / `OpResult` typings.
+- Full facade alias property map in README (outbound `publicKeyAliases` + inbound scoped maps).
+- 2.x → 3.x migration notes for `master.search` (flat array success payload).
+
+### Changed
+
+- Facade names are accepted on Valibot input schemas and coalesced to AVES camelCase before wire encoding. Success payloads also expose concise compatibility aliases.
+- Internal transport split: `HttpClient`, `buildOpEnvelope`, `readAvesResponse`, `createRqHeader`; `toAvesError` lives in `error.ts`. Public `invokeOp` API unchanged.
+- Hot-path micro-opts: cached endpoint URLs, shared XML POST headers, frozen cached `RqHeader`, single `AVES_OPS` lookup per `invokeOp`.
+- Cap HTTP error body reads via `readTextCapped` (drain stream, keep ≤ `MAX_ERROR_BODY`).
+- WeakMap cache for `itemShape` / `encodeShapeFor` on static WireShape refs.
+- `toWireBody` single shape-driven walk (list wrap + pax normalize + wire keys).
+- Zero-copy `withPublicAliases` via hardened lazy Proxy (WeakMap identity, proto-pollution blocked).
+- ADR 0001 Phase 2a: `createResponseSchema` camelizes Valibot output **in place** (`pascalToCamelKeysInPlace`) — no second deep-copy. See [`docs/adr/0001-validate-during-camelize.md`](docs/adr/0001-validate-during-camelize.md).
+- Performance harness: `yarn test:bench` (Vitest bench) and `AVES_PERF=1 yarn test:perf` (relative hot-path asserts).
+
 ## [3.0.0] - 2026-08-06
 
 ### Changed
 
 - **Breaking:** `master.search` success payload is now `MasterRecordDetailResponse[]` — always a flat array (`[]`, one element, or many). No `rsStatus` wrapper on success (non-OK AVES status remains `result.error`). Replaces the prior `{ rsStatus, masterRecordList }` shape.
 
+### Migration (2.x → 3.x)
+
+Only `master.search` success shape changed. Other domain methods and error/`Result` contracts are unchanged from 2.x.
+
+| Change | Symptom on upgrade | Fix |
+| ------ | ------------------ | --- |
+| `master.search` success is a flat array | `result.data.masterRecordList` / `result.data.rsStatus` are `undefined`; types fail | Use `result.data` as `MasterRecordDetailResponse[]` (e.g. `const [record] = result.data` or `result.data.map(...)`) |
+| Looking for `rsStatus` on success | Always missing when `result.success` | Keep using `result.error` for non-OK AVES / HTTP failures (`error.kind`, `error.status`, `error.code`) |
+| Empty search | May have expected a missing list or wrapper | Success with no hits is `result.data === []` |
+
+**Before (2.x):**
+
+```ts
+const result = await client.master.search({
+  searchType: "CODE",
+  recordCode: "508558",
+});
+if (result.success) {
+  const records = result.data.masterRecordList ?? [];
+  console.log(result.data.rsStatus.status, records[0]?.recordCode);
+}
+```
+
+**After (3.x):**
+
+```ts
+const result = await client.master.search({
+  searchType: "CODE",
+  recordCode: "508558",
+});
+if (result.success) {
+  const [record] = result.data; // MasterRecordDetailResponse[]
+  console.log(record?.recordCode);
+} else {
+  console.error(result.error.kind, result.error.status, result.error.message);
+}
+```
+
+3.1.x on top of 3.0 is additive (facade aliases / internal transport). No further breaking migration from 3.0 → 3.1.1.
+
 ## [2.0.1] - 2026-08-05
 
 ### Changed

package/README.md

@@ -45,19 +45,25 @@ if (result.success) {
 `AvesClient` is a facade over domain clients. Operations are namespaced by domain.
 
 ```typescript
-await client.booking.createBooking(params);
-await client.packages.searchPackages(params);
+await client.booking.create(params);
+await client.packages.search(params);
 await client.master.search({ searchType: 'CODE', recordCode: '508558' });
 ```
 
 Migration from 1.x: insert the appropriate domain namespace (for example,
-`client.search` → `client.master.search`). See the [2.0.0 migration notes](./CHANGELOG.md).
+`client.search` → `client.master.search`). See the [2.0.0 migration notes](./CHANGELOG.md#200---2026-08-05).
+
+Migration from 2.x: `master.search` success is a flat array — see the
+[3.0.0 migration notes](./CHANGELOG.md#300---2026-08-06).
+
+Migration from 3.x: domain method names were shortened — see the
+[4.0.0 migration notes](./CHANGELOG.md#400---2026-08-06).
 
 | Namespace | Methods |
 | --------- | ------- |
-| `master` | `search`, `upsertRecord` |
-| `booking` | `createBooking`, `modBookingServices`, `modBookingHeader`, `cancelBooking`, `setBookingStatus`, `setBookingServiceStatus`, `insertFilePaymentList`, `searchBookingFiles` |
-| `packages` | `searchPackages`, `searchTopServices`, `getPackageDetail`, `commitPackage` |
+| `master` | `search`, `upsert` |
+| `booking` | `create`, `updateServices`, `updateHeader`, `cancel`, `setStatus`, `setServiceStatus`, `addPayments`, `search` |
+| `packages` | `search`, `searchServices`, `get`, `commit` |
 
 ### Constructor
 
@@ -99,6 +105,244 @@ type Result<T, E> =
   | { success: false; error: E };
 ```
 
+## Simple facade names
+
+The facade exposes concise aliases for the AVES payload vocabulary. Inbound
+dual keys are owned by Valibot input schemas (`facadeObject` / `coalesceAliases`)
+and coalesced to AVES camelCase before wire encoding. Outbound success payloads
+keep AVES names and add concise compatibility aliases. XML shapes are unchanged.
+
+Source of truth in code:
+
+- Outbound (AVES → facade): `publicKeyAliases` in `src/utils/facade-transform.ts`
+- Inbound (facade → AVES): scoped maps in `src/utils/facade-aliases.ts`
+
+Some facade names are reused (`services`, `status`, `passengerCount`, `financial`,
+`payments`, `packages`, `identityDocument`). Resolution is **schema-scoped** on
+input and **target-key presence** on Proxy output — not a single global rename.
+
+### Outbound map (AVES → facade)
+
+Applied on success payloads via `withPublicAliases` (both names remain readable).
+
+| AVES-shaped name | Facade name |
+| ---------------- | ----------- |
+| `rsStatus` | `response` |
+| `customerRecordCode` | `customerCode` |
+| `bookingFileCode` | `bookingCode` |
+| `bookingFileRefCode` | `bookingReference` |
+| `bookingFileStatus` | `status` |
+| `fileStatus` | `status` |
+| `bookingFileDescription` | `description` |
+| `bookingFileStartDate` | `startDate` |
+| `bookingFileReferenceName` | `referenceName` |
+| `bookingFileServiceStatus` | `serviceStatus` |
+| `bookingFileServiceStatusDate` | `serviceStatusDate` |
+| `bookingServiceRef` | `serviceReference` |
+| `newCustomerRecordCode` | `newCustomerCode` |
+| `customerDetail` | `customer` |
+| `bookingFileDocument` | `documents` |
+| `bookingFinancialInfo` | `financial` |
+| `financialDetail` | `financial` |
+| `idDocumentDetail` | `identityDocument` |
+| `idDocInfo` | `identityDocument` |
+| `accountPolicies` | `policies` |
+| `dynamicFields` | `customFields` |
+| `supplierRefMasterRecords` | `supplierReference` |
+| `selectedPackageDetail` | `package` |
+| `selectedPackageList` | `packages` |
+| `packageList` | `packages` |
+| `selectedServiceList` | `services` |
+| `bookedServiceList` | `services` |
+| `serviceList` | `services` |
+| `extraQuoteServiceList` | `extraServices` |
+| `passengerList` | `passengers` |
+| `noteList` | `notes` |
+| `deadlineList` | `deadlines` |
+| `financialDeadlineList` | `financialDeadlines` |
+| `paymentList` | `payments` |
+| `filePaymentList` | `payments` |
+| `cancellableBookedServiceList` | `cancellableServices` |
+| `subServiceList` | `subServices` |
+| `featureList` | `features` |
+| `pCode` | `packageCode` |
+| `sCode` | `serviceCode` |
+| `ssCode` | `subServiceCode` |
+| `rph` | `passengerRef` |
+| `roomRph` | `roomRef` |
+| `avesSession` | `session` |
+| `paxAssociated` | `passengerRefs` |
+| `paxQty` | `passengerCount` |
+| `pax` | `passengerCount` |
+| `paxQtyCriteria` | `passengerCountRule` |
+| `qty` | `quantity` |
+| `eMail` | `email` |
+| `sex` | `gender` |
+| `nType` | `noteType` |
+| `avesServiceType` | `serviceType` |
+| `toServiceType` | `targetType` |
+| `packageParams` | `packageOptions` |
+| `topServiceParams` | `serviceOptions` |
+| `servOrPackCode` | `serviceOrPackageCode` |
+| `servOrPackDesc` | `serviceOrPackageDescription` |
+| `getDocumentation` | `includeDocumentation` |
+| `getServicesFromPackage` | `includeServices` |
+| `mergeBoardAndAccomodation` | `mergeBoardAndAccommodation` |
+| `discartNotAvailables` | `discardUnavailable` |
+| `discartNotAvailablesMinSales` | `discardUnavailableMinSales` |
+| `discartNotAvailablesDaysInOut` | `discardUnavailableDaysInOut` |
+| `getAllDeptDate` | `allDepartureDates` |
+| `getAllAccomodation` | `allAccommodation` |
+| `compatibleAccomodation` | `compatibleAccommodation` |
+| `alternativeAccomodation` | `alternativeAccommodation` |
+
+### Inbound map (facade → AVES)
+
+Applied only on the schema that owns each fragment (`facadeObject` / `coalesceAliases`).
+
+#### Shared refs
+
+| Facade | AVES |
+| ------ | ---- |
+| `customerCode` | `customerRecordCode` |
+| `bookingCode` | `bookingFileCode` |
+| `bookingReference` | `bookingFileRefCode` |
+
+#### Passenger / note / service line
+
+| Facade | AVES |
+| ------ | ---- |
+| `passengerRef` | `rph` |
+| `roomRef` | `roomRph` |
+| `gender` | `sex` |
+| `email` | `eMail` |
+| `identityDocument` | `idDocInfo` |
+| `noteType` | `nType` |
+| `serviceCode` | `sCode` |
+| `subServiceCode` | `ssCode` |
+| `quantity` | `qty` |
+| `passengerCount` | `pax` |
+| `session` | `avesSession` |
+| `passengerRefs` | `paxAssociated` |
+| `serviceType` | `avesServiceType` |
+| `targetType` | `toServiceType` |
+| `notes` | `noteList` |
+| `packageCode` | `pCode` |
+| `includeServices` | `getServicesFromPackage` |
+
+#### Booking root (`create`)
+
+| Facade | AVES |
+| ------ | ---- |
+| `customer` | `customerDetail` |
+| `status` | `bookingFileStatus` |
+| `description` | `bookingFileDescription` |
+| `referenceName` | `bookingFileReferenceName` |
+| `financial` | `bookingFinancialInfo` |
+| `package` | `selectedPackageDetail` |
+| `packages` | `selectedPackageList` |
+| `services` | `selectedServiceList` |
+| `extraServices` | `extraQuoteServiceList` |
+| `passengers` | `passengerList` |
+| `payments` | `paymentList` |
+| `documents` | `bookingFileDocument` |
+| `deadlines` | `deadlineList` |
+| `financialDeadlines` | `financialDeadlineList` |
+| `notes` | `noteList` |
+
+(+ shared refs above)
+
+#### Mod services / mod header / status / payments / search booking
+
+| Scope | Facade | AVES |
+| ----- | ------ | ---- |
+| Mod services | `package` / `packages` | `selectedPackageDetail` / `selectedPackageList` |
+| Mod services | `services` / `passengers` / `deadlines` | `selectedServiceList` / `passengerList` / `deadlineList` |
+| Mod services | `cancellableServices` | `cancellableBookedServiceList` |
+| Mod header | `startDate` | `bookingFileStartDate` |
+| Mod header | `newCustomerCode` | `newCustomerRecordCode` |
+| Mod header | `referenceName` / `passengers` / `financial` / `financialDeadlines` | `bookingFileReferenceName` / `passengerList` / `bookingFinancialInfo` / `financialDeadlineList` |
+| Set file status | `status` / `documents` | `fileStatus` / `bookingFileDocument` |
+| Set service status | `serviceReference` / `serviceStatus` / `serviceStatusDate` | `bookingServiceRef` / `bookingFileServiceStatus` / `bookingFileServiceStatusDate` |
+| Insert payments | `payments` | `filePaymentList` |
+| Search booking files | `status` | `fileStatus` |
+
+(+ shared refs where listed in each map)
+
+#### Master record
+
+| Facade | AVES |
+| ------ | ---- |
+| `financial` | `financialDetail` |
+| `identityDocument` | `idDocumentDetail` |
+| `policies` | `accountPolicies` |
+| `customFields` | `dynamicFields` |
+| `supplierReference` | `supplierRefMasterRecords` |
+
+#### Package / top-service search + package params + get package detail
+
+| Facade | AVES |
+| ------ | ---- |
+| `searchType` | `avesSearchType` |
+| `passengers` | `passengerList` |
+| `packageOptions` | `packageParams` |
+| `serviceOptions` | `topServiceParams` |
+| `serviceOrPackageCode` | `servOrPackCode` |
+| `serviceOrPackageDescription` | `servOrPackDesc` |
+| `passengerCount` | `paxQty` |
+| `passengerCountRule` | `paxQtyCriteria` |
+| `features` | `featureList` |
+| `includeDocumentation` | `getDocumentation` |
+| `mergeBoardAndAccommodation` | `mergeBoardAndAccomodation` |
+| `discardUnavailable` | `discartNotAvailables` |
+| `discardUnavailableMinSales` | `discartNotAvailablesMinSales` |
+| `discardUnavailableDaysInOut` | `discartNotAvailablesDaysInOut` |
+| `allDepartureDates` | `getAllDeptDate` |
+| `allAccommodation` | `getAllAccomodation` |
+| `compatibleAccommodation` | `compatibleAccomodation` |
+| `alternativeAccommodation` | `alternativeAccomodation` |
+| `services` (package detail RQ) | `selectedServiceList` |
+
+(+ shared refs on search / package detail)
+
+New code can use the simplified vocabulary directly:
+
+```typescript
+const created = await client.booking.create({
+  customerCode: '138311',
+  status: 'CONFIRMED',
+  startDate: '2026-08-06',
+  endDate: '2026-08-07',
+  services: [
+    {
+      serviceCode: 'HT00110840',
+      serviceType: 'TOP',
+      targetType: 'RESIDENCE',
+      quantity: '1',
+      passengerCount: '2',
+      session: '1',
+    },
+  ],
+  passengers: [
+    {
+      passengerRef: '001',
+      name: 'ADULT 001',
+      categoryCode: 'AD',
+      gender: 'M',
+    },
+  ],
+});
+
+if (created.success) {
+  console.log(created.data.bookingCode);
+  console.log(created.data.services?.[0]?.serviceStatus);
+}
+```
+
+The previous AVES-shaped names remain accepted and returned as compatibility
+aliases. New type aliases such as `BookingInput`, `Booking`, `MasterRecord`,
+`PackageInput`, and `Package` are exported for new integrations.
+
 ---
 
 ## Master records
@@ -133,12 +377,12 @@ const byEmail = await client.master.search({
 });
 ```
 
-### `client.master.upsertRecord(record)`
+### `client.master.upsert(record)`
 
 `insertCriteria`: `'S'` always insert · `'N'` skip if exists · `'T'` update all (default) · `'M'` secondary fields only.
 
 ```typescript
-const result = await client.master.upsertRecord({
+const result = await client.master.upsert({
   name: 'Jane Smith',
   email: 'jane@example.com',
   languageCode: '02',
@@ -158,19 +402,19 @@ if (result.success) {
 
 | 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` | Create booking file |
+| `updateServices` | Add/replace services, assign package, delete/nullify lines |
+| `updateHeader` | Header only (pax, notes, billing) — no costs |
+| `cancel` | Delete booking file |
+| `setStatus` | Change file status (`CANCELED` / `NULLIFIED` / …) |
+| `setServiceStatus` | Nullify a single service line |
+| `addPayments` | Register payments |
+| `search` | Search practices (`FILE_CODE`, `PAX_NAME`, `PACKAGE_CODE`, `OTHER`) |
 
 ### Create
 
 ```typescript
-const created = await client.booking.createBooking({
+const created = await client.booking.create({
   customerRecordCode: '138311', // or customerDetail: { recordCode: '138311' }
   bookingFileStatus: 'QUOTATION', // or { value: 'QUOTATION', expiredDate? }
   startDate: '2015-01-22T00:00:00',
@@ -209,7 +453,7 @@ if (created.success) {
 ### Modify services / package / overwrite lines
 
 ```typescript
-await client.booking.modBookingServices({
+await client.booking.updateServices({
   customerRecordCode: '138311',
   bookingFileCode: '14/036654',
   selectedPackageDetail: {
@@ -248,7 +492,7 @@ Requires `bookingFileCode` **or** `bookingFileRefCode`.
 `paymentUser` is serialized as an XML **attribute** on `FilePaymentListRQ` (`PaymentUser="…"`), not as a child element.
 
 ```typescript
-await client.booking.insertFilePaymentList({
+await client.booking.addPayments({
   bookingFileCode: '18/000172',
   paymentUser: 'MLDN',
   enableMultiplePayments: true,
@@ -267,32 +511,32 @@ await client.booking.insertFilePaymentList({
 ### Header, status, cancel, search practices
 
 ```typescript
-await client.booking.modBookingHeader({
+await client.booking.updateHeader({
   bookingFileCode: '14/000043',
   bookingFileStartDate: '2014-04-28',
   customerRecordCode: '103737',
   passengerList: [{ rph: '001', name: 'ADULTI 001', sex: 'M' }],
 });
 
-await client.booking.setBookingStatus({
+await client.booking.setStatus({
   customerRecordCode: '000170',
   bookingFileCode: '14/000081',
   fileStatus: 'CANCELED', // or { value: 'CANCELED' }
 });
 
-await client.booking.setBookingServiceStatus({
+await client.booking.setServiceStatus({
   customerRecordCode: '000001',
   bookingFileCode: '18/000252',
   bookingServiceRef: '002',
   bookingFileServiceStatus: 'NULLIFIED',
 });
 
-await client.booking.cancelBooking({
+await client.booking.cancel({
   bookingFileCode: '14/000081',
   customerRecordCode: '000170',
 });
 
-await client.booking.searchBookingFiles({
+await client.booking.search({
   searchType: 'PACKAGE_CODE',
   customerRecordCode: '138311',
   packageCode: '2014MDE0000010',
@@ -307,15 +551,15 @@ There is **no** Create Package API in AVES XML 1.8.0. Search, detail, and commit
 
 | 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) |
+| `search` | Search programs (defaults `avesSearchType: 'PACKAGE'`) |
+| `searchServices` | Search TOP services (defaults `avesSearchType: 'SERVICE'`) |
+| `get` | Package base info + service list |
+| `commit` | 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({
+const packages = await client.packages.search({
   customerRecordCode: '138311',
   languageCode: '01',
   currencyCode: 'EUR',
@@ -333,7 +577,7 @@ const packages = await client.packages.searchPackages({
   servOrPackCode: '2014MDE0000010',
 });
 
-const detail = await client.packages.getPackageDetail({
+const detail = await client.packages.get({
   customerRecordCode: '001692',
   packageCode: '2015F042',
   startDate: '2015-05-02T00:00:00',
@@ -343,7 +587,7 @@ const detail = await client.packages.getPackageDetail({
   ],
 });
 
-await client.packages.commitPackage({ packageCode: '14/PACKAGE001' });
+await client.packages.commit({ packageCode: '14/PACKAGE001' });
 
 if (packages.success) console.log(packages.data.packageList?.[0]?.pCode);
 if (detail.success) console.log(detail.data.pCode, detail.data.serviceList?.[0]);
@@ -371,9 +615,10 @@ if (!result.success) {
 
 ## Case transformation & wire shapes
 
-- **Input**: camelCase (`recordCode`, `selectedServiceList`, `paymentUser`)
+- **Facade input**: concise camelCase (`customerCode`, `services`, `passengers`)
+- **Wire input**: AVES-shaped camelCase before XML (`recordCode`, `selectedServiceList`, `paymentUser`)
 - **Wire**: PascalCase keys; `@`-prefixed keys become XML attributes
-- **Output**: camelCase again
+- **Output**: concise facade aliases plus compatibility aliases
 
 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.
 
@@ -426,8 +671,9 @@ Outbound path: validate → `createApiSchema` / `toWireBody` → `invokeOp` →
 ## Types
 
 Operations are available only through `client.master`, `client.booking`, and
-`client.packages`; flat aliases were removed in 2.0.0. See the
-[migration notes](./CHANGELOG.md) when upgrading.
+`client.packages`; flat aliases were removed in 2.0.0. When upgrading from 2.x,
+also update `master.search` consumers for the flat array success payload (3.0.0).
+See the [CHANGELOG migration notes](./CHANGELOG.md).
 
 ```typescript
 import type {