aves-sdk 4.0.1 → 5.0.0

package/CHANGELOG.md

@@ -5,12 +5,118 @@ 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).
 
+<a id="v5.0.0"></a>
+## [5.0.0] - 2026-08-24
+
+Effect-native core: **Effect Schema** + **`@effect/platform` HttpClient**, Promise `Result` facade at the edge, optional Layers / `ManagedRuntime` for Effect apps.
+
+### Added
+
+- `makeAvesRuntime(options, deps?)` — `ManagedRuntime` over `avesClientLayer` for `yield* AvesBooking` / `AvesMaster` / `AvesPackages` / `AvesTransport`
+- `avesClientLayer` / `AvesClientLive` — composable Effect Layers (`config → http → transport → domains`)
+- Domain Tags: `AvesBooking`, `AvesMaster`, `AvesPackages`, `AvesTransport`, `AvesHttp`, `AvesConfig`
+- `createAvesClient` — plain-object Promise facade (same shape as `AvesClient`)
+- Public `Result` / `ok` / `err`; `isAvesError`; tagged errors `AvesValidationError` / `AvesApiError` / `AvesUnknownError` (+ factories)
+- Test DI: `deps.httpClient` (`HttpClient.make`) and/or `deps.http` / domain service overrides
+
+### Changed
+
+- **Breaking:** Validation stack is **Effect Schema** (`effect`). Valibot is removed.
+- **Breaking:** HTTP is **`@effect/platform`** (`FetchHttpClient` by default). Undici is no longer a dependency; do not use `MockAgent` / `setGlobalDispatcher` for SDK tests — inject `HttpClient.make` via `deps.httpClient`.
+- **Breaking:** Domains are Effect-native (`Effect.Effect<…, AvesError>`). The Promise API is a thin `toPromiseFacade` edge on `createAvesClient` / `AvesClient`.
+- **Breaking:** `client.transport` is **removed** from the Promise facade. Effect programs use `yield* AvesTransport` (or domain Tags) with `makeAvesRuntime` / `avesClientLayer`.
+- **Breaking:** `AvesError` is a **tagged union**, not a single constructible class. Prefer `isAvesError(e)`, `e instanceof AvesApiError`, or `Effect.catchTag("AvesApiError", …)`. Promise `error.kind` (`validation` | `api` | `unknown`) is unchanged.
+- **Breaking:** DI no longer uses `new AvesTransport(options)` / `new BookingClient(transport)`. Use `AvesClientDeps`: `{ httpClient?, http?, transport?, master?, booking?, packages? }`.
+- Internal layout: `src/client/{booking,master,packages,http,transport,config}/` (types / tag / service / layer).
+- Published types shrank from 1.21 MB to 404 kB (npm tarball 115 kB → 72 kB): op params/results and the domain service types are now written against named types instead of inferred, so the declaration bundle references `BookingInput` & co. instead of inlining every schema structure. The public API is unchanged — `src/client/{ops,services}.test-d.ts` pin each op and domain method against the schema the transport actually uses.
+
+### Migration (4.x → 5.x)
+
+1. **Install** — `aves-sdk@5` pulls `effect` and `@effect/platform`. No Valibot/undici required.
+2. **Promise apps** — keep `new AvesClient(options)` / `createAvesClient(options)`. Import `Result` from `aves-sdk` if you typed it locally. Stop reading `client.transport`.
+3. **Errors** — replace `instanceof AvesError` with `isAvesError(error)` (or the concrete tagged class). `error.kind` / `message` / `status` / `code` still work on the Promise path.
+4. **Tests / DI** — replace undici `MockAgent` with platform mocks:
+
+```ts
+import { HttpClient, HttpClientResponse } from "@effect/platform";
+import { Effect } from "effect";
+import { AvesClient } from "aves-sdk";
+
+const httpClient = HttpClient.make((request, url) =>
+  Effect.succeed(
+    HttpClientResponse.fromWeb(
+      request,
+      new Response(`<SearchMasterRecordRS><RsStatus Status="OK"/></SearchMasterRecordRS>`, {
+        status: 200,
+      }),
+    ),
+  ),
+);
+
+const client = new AvesClient(options, { httpClient });
+```
+
+5. **Effect apps** — use Layers instead of the Promise facade:
+
+```ts
+import { Effect } from "effect";
+import { AvesMaster, makeAvesRuntime } from "aves-sdk";
+
+const runtime = makeAvesRuntime(options);
+const records = await runtime.runPromise(
+  Effect.gen(function* () {
+    const master = yield* AvesMaster;
+    return yield* master.search({ searchType: "CODE", recordCode: "508558" });
+  }),
+);
+await runtime.dispose();
+```
+
+Or `Effect.provide(avesClientLayer(options, deps))` without a ManagedRuntime. Recover with `Effect.catchTag("AvesApiError", …)` / `"AvesValidationError"` / `"AvesUnknownError"`.
+
+XML wire shapes, facade aliases, and domain method names from 4.x are unchanged.
+
+<a id="v4.1.0"></a>
+## [4.1.0] - 2026-08-07
+
+### Added
+
+- `client.booking.exportData(params)` — **ExportBookingData** (`BookingDataExportRQ` / `BookingDataExportRS`). The only AVES operation that reads a booking file back whole: header, passengers, booked services with per-line `amountsDetail`, file-level `bookedFileAmounts`, and **registered payments**. `addPayments` finally has a read counterpart.
+- `ExtraInfo` lookup tables on the response: `currencyList`, `vatList`, `nationList`, `travelAgentList`, `programList`, `statisticList`, `priceOffertList`, `userList`, `passengerCategoryList`, `masterDataSet`, `masterDataSetExtraInfo`. `nationList[].territoriality` (`IN_UE` / `OUT_UE` / `MIXED_UE`) is the VAT-regime input.
+- Object enums (+ schemas) for every closed picklist the export returns: `ExportType`, `Territoriality`, `StatisticType`, `ToSubServiceType`, `SellingType`, `Printable`, `PrintType`, `DeadlineStatus`, `CommissionIncomeType`, `CommissionOwedType`.
+- `RecordTypeWire` — `RecordType` plus `NOT_SET`, for read responses. Mirrors the existing `BookingFileStatus` / `BookingFileStatusWire` split.
+- Remaining documented export structures are now typed: `customerProcessedPrintList`, `instalmentPlanList`, `supplierInstalmentPlanList`, file- and service-level `deadlineList`, `commissionIncomeDetails`, `commissionOwedDetails`.
+- Types `ExportBookingDataRQ` / `ExportBookingDataRS`, `ExportedBookingFile`, `ExportExtraInfo`, and facade aliases `BookingExportInput` / `BookingExportResult`.
+- Facade output aliases: `bookingFileList` → `bookings`, `bookedServices` → `services`, `amountsDetail` → `amounts`, `bookedFileAmounts` → `totals`.
+
+### Fixed
+
+- `master.search` / `master.upsert` responses no longer reject a record whose `RecordType` is `NOT_SET`. The response validation schema was reusing the request picklist, which omits it. Server-only fields AVES returns on read (`AreaCode`, `LastDateContact`, `UseSupplierDataOnTravelDoc`, `BookingEnabled`, `PrivacyPolicyAccepted`, and the misspelled `ModifitedDate`) are no longer dropped.
+
+  Note for TypeScript consumers: `MasterRecordDetailResponse["recordType"]` widens from `RecordType` to `RecordTypeWire`, so an exhaustive `switch` over it now needs a `NOT_SET` branch. Input types are unchanged.
+- Facade arrays now expose public aliases when **iterated**, not only when indexed. `withPublicAliases` bound array methods to the raw target, so `for…of`, destructuring, spread, `Array.from`, `map`, `filter`, `find`, `forEach` and `at` all handed back rows without their alias keys — `const [p] = result.data.payments` yielded a row with `paymentDate` but no aliases, while `result.data.payments[0]` worked. Methods now run with `this` bound to the proxy. This also makes `indexOf` / `includes` consistent: `arr.indexOf(arr[0])` returned `-1` before, since it compared wrapped items against raw ones.
+
+### Changed
+
+- `BoolishSchema` moved from `schemas/booking-shared.ts` to `schemas/common.ts`, next to `StringishSchema` — it is a cross-domain wire primitive, and `master-record` / `package-catalog` were already importing it out of the booking module. Internal only; it is not part of the published entry point.
+
+### Notes
+
+- Request roots are `BookingDataExport*`, not `ExportBookingData*`: the spec's section tables name the endpoint, while its index and both worked XML examples name the elements.
+- `limitRange` enforces the documented bounds (`skip` ≥ 0, `take` ≤ 1000) before the request leaves the SDK.
+- Wire misspellings are normalized on the way in: `PaumentNote` → `paymentNote`, `FirstConfemationDate` → `firstConfirmationDate`, `UsersList` → `userList`, `TOSubServiceType` → `toSubServiceType`.
+- `extraInfo.masterDataSet` rows validate as full master records, reusing the schema behind `master.search`.
+- `regimeType` and `customerPayAt` are the only response fields left as plain strings: Booking.txt:11312 documents no value list for the first, and the second appears nowhere in the response table — only in the example, as `OUR_AGENCY`. There is nothing to validate against; an enum built from one sample would reject every other value.
+- `Printable` values are rejoined from a spec table that hard-wraps identifiers mid-token. If a live response is ever rejected on that field, check the reconstruction against Booking.txt:11261-11289 first.
+
+<a id="v4.0.1"></a>
 ## [4.0.1] - 2026-08-06
 
 ### Added
 
 - Copy `CHANGELOG.md` into `dist/` on build (`tsdown` `copy`) and include `dist/CHANGELOG.md` in published `files`.
 
+<a id="v4.0.0"></a>
 ## [4.0.0] - 2026-08-06
 
 ### Added
@@ -56,6 +162,7 @@ await client.packages.search(params);
 await client.master.upsert(record);
 ```
 
+<a id="v3.1.1"></a>
 ## [3.1.1] - 2026-08-06
 
 ### Added
@@ -76,9 +183,10 @@ await client.master.upsert(record);
 - 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).
+- `createResponseSchema` camelizes Valibot output **in place** (`pascalToCamelKeysInPlace`) — no second deep-copy.
 - Performance harness: `yarn test:bench` (Vitest bench) and `AVES_PERF=1 yarn test:perf` (relative hot-path asserts).
 
+<a id="v3.0.0"></a>
 ## [3.0.0] - 2026-08-06
 
 ### Changed
@@ -125,6 +233,7 @@ if (result.success) {
 
 3.1.x on top of 3.0 is additive (facade aliases / internal transport). No further breaking migration from 3.0 → 3.1.1.
 
+<a id="v2.0.1"></a>
 ## [2.0.1] - 2026-08-05
 
 ### Changed
@@ -132,6 +241,7 @@ if (result.success) {
 - Omit source maps from the published package; `files` now ships only
   `dist/index.mjs` and `dist/index.d.mts`.
 
+<a id="v2.0.0"></a>
 ## [2.0.0] - 2026-08-05
 
 ### Changed
@@ -155,6 +265,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.9.0"></a>
 ## [1.9.0] - 2026-08-03
 
 ### Changed
@@ -175,6 +286,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.8.0"></a>
 ## [1.8.0] - 2026-08-03
 
 ### Added
@@ -190,6 +302,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.7.0"></a>
 ## [1.7.0] - 2026-08-03
 
 ### Added
@@ -218,6 +331,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.6.0"></a>
 ## [1.6.0] - 2026-07-29
 
 ### Changed
@@ -229,6 +343,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.5.1"></a>
 ## [1.5.1] - 2026-07-29
 
 ### Changed
@@ -238,6 +353,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.5.0"></a>
 ## [1.5.0] - 2026-07-29
 
 ### Added
@@ -248,6 +364,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.4.0"></a>
 ## [1.4.0] - 2026-07-29
 
 ### Added
@@ -262,6 +379,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.3.4"></a>
 ## [1.3.4] - 2026-03-09
 
 ### Added
@@ -279,6 +397,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.3.3"></a>
 ## [1.3.3] - 2026-02-26
 
 ### Fixed
@@ -287,6 +406,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.3.2"></a>
 ## [1.3.2] - 2026-02-10
 
 ### Added
@@ -300,6 +420,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.3.1"></a>
 ## [1.3.1] - 2026-02-01
 
 ### Changed
@@ -309,6 +430,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.3.0"></a>
 ## [1.3.0] - 2026-02-01
 
 ### Added
@@ -324,6 +446,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.2.16"></a>
 ## [1.2.16] - 2026-01-27
 
 ### Changed
@@ -332,6 +455,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.2.15"></a>
 ## [1.2.15] - 2026-01-27
 
 ### Fixed
@@ -340,6 +464,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.2.14"></a>
 ## [1.2.14] - 2026-01-27
 
 ### Changed
@@ -348,6 +473,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.2.13"></a>
 ## [1.2.13] - 2026-01-27
 
 ### Added
@@ -364,6 +490,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.2.12"></a>
 ## [1.2.12] - 2026-01-26
 
 ### Added
@@ -382,6 +509,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.2.11"></a>
 ## [1.2.11] - 2026-01-21
 
 ### Fixed
@@ -390,6 +518,7 @@ if (result.success) {
 
 ---
 
+<a id="v1.0.3"></a>
 ## [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.

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 / `@` attrs, and returns `Result` instead of throwing.
+Type-safe TypeScript SDK for the AVES XML REST API. Handles XML parsing, **Effect Schema** validation, camelCase ↔ PascalCase / `@` attrs, and `@effect/platform` HTTP. Public domain methods return `Result` (they do not throw). Effect apps can also `yield*` domain Tags via Layers / `makeAvesRuntime`.
 
 ## Installation
 
@@ -14,61 +14,102 @@ pnpm add aves-sdk
 bun add aves-sdk
 ```
 
-## Quick start
+`aves-sdk` depends on `effect` and `@effect/platform`.
+
+## Quick start (Promise facade)
 
 ```typescript
-import { AvesClient } from 'aves-sdk';
+import { AvesClient, isAvesError, type Result } from "aves-sdk";
 
 const client = new AvesClient({
-  baseURL: 'https://api.example.com',
-  hostID: '000000', // 6 digits
-  xtoken: 'TOKEN',
-  languageCode: '02', // optional: 01=Italian, 02=English
+  baseURL: "https://api.example.com",
+  hostID: "000000", // 6 digits
+  xtoken: "TOKEN",
+  languageCode: "02", // optional: 01=Italian, 02=English
   timeoutMs: 30_000, // optional
 });
 
-const result = await client.master.search({
-  searchType: 'CODE',
-  recordCode: '508558',
+const result: Result<unknown> = await client.master.search({
+  searchType: "CODE",
+  recordCode: "508558",
 });
 
 if (result.success) {
   const [record] = result.data;
   console.log(record?.recordCode);
-} else {
+} else if (isAvesError(result.error)) {
   console.error(result.error.kind, result.error.message, result.error.code);
 }
 ```
 
+`createAvesClient(options, deps?)` returns the same Promise API as a plain object.
+
+## Quick start (Effect)
+
+```typescript
+import { Effect } from "effect";
+import { AvesMaster, makeAvesRuntime } from "aves-sdk";
+
+const runtime = makeAvesRuntime({
+  baseURL: "https://api.example.com",
+  hostID: "000000",
+  xtoken: "TOKEN",
+});
+
+const records = await runtime.runPromise(
+  Effect.gen(function* () {
+    const master = yield* AvesMaster;
+    return yield* master.search({
+      searchType: "CODE",
+      recordCode: "508558",
+    });
+  }).pipe(
+    Effect.catchTag("AvesApiError", (e) =>
+      Effect.succeed({ failed: true as const, code: e.code }),
+    ),
+  ),
+);
+
+await runtime.dispose();
+```
+
+Also: `Effect.provide(avesClientLayer(options, deps))` or `AvesClientLive(options)` for the full stack including `AvesConfig` / `AvesHttp`.
+
 ## Client shape
 
-`AvesClient` is a facade over domain clients. Operations are namespaced by domain.
+`AvesClient` / `createAvesClient` expose **Promise** domain namespaces only (`master`, `booking`, `packages`). There is no `client.transport` on the Promise facade — use `AvesTransport` with Layers for Effect programs.
 
 ```typescript
 await client.booking.create(params);
+await client.booking.exportData(params);
 await client.packages.search(params);
-await client.master.search({ searchType: 'CODE', recordCode: '508558' });
+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#200---2026-08-05).
+`client.search` → `client.master.search`). See the [2.0.0 migration notes](https://github.com/simoneguglielmi/aves-sdk/blob/main/CHANGELOG.md#v2.0.0).
 
 Migration from 2.x: `master.search` success is a flat array — see the
-[3.0.0 migration notes](./CHANGELOG.md#300---2026-08-06).
+[3.0.0 migration notes](https://github.com/simoneguglielmi/aves-sdk/blob/main/CHANGELOG.md#v3.0.0).
 
 Migration from 3.x: domain method names were shortened — see the
-[4.0.0 migration notes](./CHANGELOG.md#400---2026-08-06).
+[4.0.0 migration notes](https://github.com/simoneguglielmi/aves-sdk/blob/main/CHANGELOG.md#v4.0.0).
+
+Migration from 4.x: Effect Schema + platform HTTP + tagged errors — see the
+[5.0.0 migration notes](https://github.com/simoneguglielmi/aves-sdk/blob/main/CHANGELOG.md#v5.0.0).
 
 | Namespace | Methods |
 | --------- | ------- |
 | `master` | `search`, `upsert` |
-| `booking` | `create`, `updateServices`, `updateHeader`, `cancel`, `setStatus`, `setServiceStatus`, `addPayments`, `search` |
+| `booking` | `create`, `updateServices`, `updateHeader`, `cancel`, `setStatus`, `setServiceStatus`, `addPayments`, `search`, `exportData` |
 | `packages` | `search`, `searchServices`, `get`, `commit` |
 
 ### Constructor
 
 ```typescript
 new AvesClient(options: AvesClientOptions, deps?: AvesClientDeps)
+// or
+createAvesClient(options, deps?)
 ```
 
 | Option | Description |
@@ -79,28 +120,36 @@ new AvesClient(options: AvesClientOptions, deps?: AvesClientDeps)
 | `languageCode` | Optional 2-digit language code |
 | `timeoutMs` | Optional request timeout (default 30000) |
 
-Optional DI (tests / custom transport):
+Optional DI (tests / custom HTTP):
 
 ```typescript
-import {
-  AvesClient,
-  AvesTransport,
-  BookingClient,
-} from 'aves-sdk';
+import { HttpClient, HttpClientResponse } from "@effect/platform";
+import { Effect } from "effect";
+import { AvesClient } from "aves-sdk";
+
+const httpClient = HttpClient.make((request, url) =>
+  Effect.succeed(
+    HttpClientResponse.fromWeb(
+      request,
+      new Response(xmlBody, { status: 200 }),
+    ),
+  ),
+);
 
-const transport = new AvesTransport(options);
 new AvesClient(options, {
-  transport,
-  booking: new BookingClient(transport),
+  httpClient,
+  // or: http, transport, master, booking, packages service overrides
 });
 ```
 
 ### Result type
 
-All methods return `Result<T, AvesError>` — they do **not** throw.
+Promise domain methods return `Result<T, AvesError>` — they do **not** throw. `Result` is exported from `aves-sdk`.
 
 ```typescript
-type Result<T, E> =
+import type { Result } from "aves-sdk";
+
+type Result<T, E = Error> =
   | { success: true; data: T }
   | { success: false; error: E };
 ```
@@ -108,7 +157,7 @@ type Result<T, 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`)
+dual keys are owned by Effect Schema 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.
 
@@ -410,6 +459,7 @@ if (result.success) {
 | `setServiceStatus` | Nullify a single service line |
 | `addPayments` | Register payments |
 | `search` | Search practices (`FILE_CODE`, `PAX_NAME`, `PACKAGE_CODE`, `OTHER`) |
+| `exportData` | Read practices back whole, **incl. registered payments and amounts** |
 
 ### Create
 
@@ -543,6 +593,54 @@ await client.booking.search({
 });
 ```
 
+### Read a practice back (`exportData`)
+
+`search` returns the header and booked services. `exportData` is the only AVES
+operation that also returns **registered payments**, per-line amounts and file
+totals — use it to reconcile what was written with `addPayments` / `create`.
+
+Every field is an optional filter. With none set AVES exports everything the
+credentials can reach, so pass `limitRange` for anything broader than one
+`bookingFileCode` (`skip` ≥ 0, `take` ≤ 1000 — enforced before sending).
+
+```typescript
+const result = await client.booking.exportData({
+  bookingFileCode: '14/036654',
+  // or filter a window:
+  // lastModificationDate: { minDate: '2026-08-01', maxDate: '2026-08-07' },
+  // statusLists: ['CONFIRMED'],
+  // limitRange: { skip: 0, take: 500 },
+});
+
+if (result.success) {
+  const file = result.data.bookingFileList?.[0];
+
+  for (const payment of file?.paymentList ?? []) {
+    console.log(payment.paymentDate, payment.amount, payment.paymentType);
+  }
+
+  for (const service of file?.bookedServices ?? []) {
+    console.log(service.serviceCode, service.amountsDetail?.costWithTax);
+  }
+
+  console.log(file?.bookedFileAmounts?.customerDueAmount);
+
+  // Lookup tables the exported codes resolve against.
+  // `territoriality` (IN_UE | OUT_UE | MIXED_UE) drives the VAT regime.
+  console.log(result.data.extraInfo?.nationList);
+  console.log(result.data.extraInfo?.vatList);
+}
+```
+
+`extraInfo.masterDataSet` rows are validated as full master records — the same
+shape `client.master.search` returns. Read responses accept `RecordType:
+'NOT_SET'` via `RecordTypeWire`; the request-side `RecordType` stays strict.
+
+Every picklist the spec closes is validated, so an undocumented value fails the
+whole response rather than reaching your code. Two fields are deliberately
+plain strings because AVES documents no values for them: `regimeType` (no list
+given) and `customerPayAt` (absent from the response table entirely).
+
 ---
 
 ## Package / Program catalog
@@ -597,20 +695,29 @@ if (detail.success) console.log(detail.data.pCode, detail.data.serviceList?.[0])
 
 ## Errors
 
+`AvesError` is a tagged union: `AvesValidationError` | `AvesApiError` | `AvesUnknownError`.
+Each has `_tag` (for `Effect.catchTag`) and Promise-friendly `kind` (`validation` | `api` | `unknown`).
+
 ```typescript
-import { AvesClient, AvesError } from 'aves-sdk';
+import { AvesClient, AvesApiError, isAvesError } from "aves-sdk";
 
 const result = await client.master.search({
-  searchType: 'CODE',
-  recordCode: '508558',
+  searchType: "CODE",
+  recordCode: "508558",
 });
 
 if (!result.success) {
-  // kind: 'validation' | 'api' | 'unknown'
-  console.error(result.error.kind, result.error.message, result.error.code);
+  if (isAvesError(result.error)) {
+    console.error(result.error.kind, result.error.message, result.error.code);
+  }
+  if (result.error instanceof AvesApiError) {
+    console.error(result.error._tag, result.error.status);
+  }
 }
 ```
 
+Effect programs recover with `Effect.catchTag("AvesApiError", …)` (also `"AvesValidationError"`, `"AvesUnknownError"`).
+
 ---
 
 ## Case transformation & wire shapes
@@ -626,9 +733,9 @@ You do not handle XML attribute prefixes yourself. Attr vs element is decided by
 
 One outbound path for all ops:
 
-1. Valibot validates camelCase input  
+1. Effect Schema validates camelCase input  
 2. `createApiSchema(schema, shape, wrap?)` → `toWireBody` (optional list wrap + `paxAssociated` string[]/empty normalize + `camelToPascalKeys`)  
-3. `AvesTransport.invokeOp` adds `RqHeader`, optional `bodyKey` nest, POSTs XML  
+3. Transport `invoke` / `ops.*` adds `RqHeader`, optional `bodyKey` nest, POSTs XML  
 
 Inbound: `createResponseSchema` / `createFlattenedResponseSchema` / `createListResponseSchema` → camelCase + optional detail spread or typed list RS; `listDetailApiSchema` unwraps wire `*List`/`*Detail` to flat arrays; `coalesceWireAliases` normalizes dialect attrs. Input aliases: `valueFieldSchema`, `coalesceCustomerRecordCode`, `coalesceListHead`. Shared primitives: `LanguageCodeSchema`, `StringishSchema`, `DateRangeSchema`, `StatusOnlyResponseSchema`.
 
@@ -653,18 +760,23 @@ Editing CreateBooking shapes does not affect SearchFile or AvesSearch.
 
 ## Architecture
 
-`AvesClient` (`src/client.ts`) is a thin facade over DI-friendly domain clients:
+Promise edge: `createAvesClient` / `AvesClient` → `toPromiseFacade` on domain services.
+Effect edge: `makeAvesRuntime` / `avesClientLayer` / `AvesClientLive` → `yield*` Tags.
 
 | 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` |
+| `src/client.ts` | Promise facade + `makeAvesRuntime` |
+| `src/client/layer.ts` | `avesClientLayer` / `AvesClientLive` composition |
+| `src/client/booking/` | Booking Tag / service / layer |
+| `src/client/master/` | Master-records Tag / service / layer |
+| `src/client/packages/` | Package catalog Tag / service / layer |
+| `src/client/transport/` | `invoke` / `ops` / response reader |
+| `src/client/http/` | XML POST via `@effect/platform` HttpClient |
+| `src/client/config/` | `AvesConfig` |
+| `src/schemas/` | Effect Schema RQ/RS |
 | `src/xml/` | XML root helpers + JSON ↔ XML |
 
-Outbound path: validate → `createApiSchema` / `toWireBody` → `invokeOp` → XML POST.
+Outbound path: Schema decode → `createApiSchema` / `toWireBody` → transport → HTTP POST.
 
 ---
 
@@ -673,24 +785,30 @@ Outbound path: validate → `createApiSchema` / `toWireBody` → `invokeOp` →
 Operations are available only through `client.master`, `client.booking`, and
 `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).
+See the [CHANGELOG migration notes](https://github.com/simoneguglielmi/aves-sdk/blob/main/CHANGELOG.md).
 
 ```typescript
 import type {
   AvesClientOptions,
   AvesClientDeps,
+  AvesError,
   AvesSearchRQ,
   BookingFileRQ,
+  Result,
   SearchMasterRecord,
-} from 'aves-sdk';
+} from "aves-sdk";
 
 import {
   AvesClient,
+  createAvesClient,
+  makeAvesRuntime,
+  AvesMaster,
+  AvesBooking,
+  AvesPackages,
   AvesTransport,
-  MasterRecordsClient,
-  BookingClient,
-  PackageCatalogClient,
-  AvesError,
+  avesClientLayer,
+  isAvesError,
+  AvesApiError,
   // object enums
   AvesSearchType,
   BookingFileStatus,
@@ -699,7 +817,7 @@ import {
   PaxQtyCriteria,
   PaymentType,
   SearchMasterType,
-} from 'aves-sdk';
+} from "aves-sdk";
 
 PaxQtyCriteria.GREATER_OR_EQUAL
 AvesSearchType.PACKAGE
@@ -713,7 +831,7 @@ MIT
 
 ## Links
 
-- [Changelog](./CHANGELOG.md)
+- [Changelog](https://github.com/simoneguglielmi/aves-sdk/blob/main/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)