aves-sdk 4.0.1 → 5.0.1

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 |
@@ -77,30 +118,38 @@ new AvesClient(options: AvesClientOptions, deps?: AvesClientDeps)
 | `hostID` | 6-digit host id |
 | `xtoken` | Auth token |
 | `languageCode` | Optional 2-digit language code |
-| `timeoutMs` | Optional request timeout (default 30000) |
+| `timeoutMs` | Optional request timeout in milliseconds (default 30000). A numeric string (e.g. from an env var) is accepted; any other non-positive value throws `AvesValidationError` when the client is created |
 
-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)