aves-sdk 1.2.3 → 1.2.4

package/README.md

@@ -1,15 +1,14 @@
-# Aves SDK
+# AVES SDK
 
-TypeScript SDK for integrating with the Aves
+A type-safe TypeScript SDK for the AVES XML REST API. Automatically handles XML parsing, validation, case transformation, and provides full TypeScript support.
 
 ## Features
 
-- **100% Aves XML 1.8.0 Compliant** - Exact implementation of official spec
-- **Full Type Safety** - Discriminated unions, type narrowing, zero `any` types
-- **Smart Interfaces** - Type-safe search with discriminated unions
-- **Zod Validation** - Runtime validation for all requests/responses
-- **NestJS Native** - Proper module with DI support
-- **Production Ready** - Tested, validated, optimized bundle
+- **Type-safe** - Full TypeScript support with inferred types
+- **Runtime validation** - Input/output validation using Valibot
+- **XML handling** - Automatic XML ↔ JSON conversion
+- **Case transformation** - Automatic camelCase ↔ PascalCase conversion
+- **Error handling** - Custom error types with detailed error information
 
 ## Installation
 
@@ -25,384 +24,231 @@ bun add aves-sdk
 
 ## Quick Start
 
-### 1. Configure Environment
+```typescript
+import { AvesClient } from 'aves-sdk';
+
+const client = new AvesClient(
+  'https://api.example.com', // Base URL
+  '025706', // 6-digit HostID
+  'TOKEN002756', // Xtoken
+  '02' // Optional: 2-digit language code (01=Italian, 02=English)
+);
+
+// Search for records (camelCase input)
+const results = await client.search({
+  searchType: 'CODE',
+  recordCode: '508558',
+});
 
-```env
-AVES_BASE_URL=https://your-aves-instance.com
-AVES_HOST_ID=123456
-AVES_XTOKEN=your_token_here
-AVES_LANGUAGE_CODE=01
+// Insert or update a record (camelCase input)
+const response = await client.upsertRecord({
+  name: 'John Doe',
+  email: 'john@example.com',
+  address: '123 Main St',
+  zipCode: '12345',
+  cityName: 'New York',
+  stateCode: 'USA',
+  // ... other fields
+});
 ```
 
-### 2. Import Module
+## API Reference
 
-```typescript
-import { Module } from '@nestjs/common';
-import { ConfigModule, ConfigService } from '@nestjs/config';
-import { AvesModule } from 'aves-sdk';
-
-@Module({
-  imports: [
-    ConfigModule.forRoot({ isGlobal: true }),
-    AvesModule.forRootAsync({
-      imports: [ConfigModule],
-      useFactory: (config: ConfigService) => ({
-        baseUrl: config.get('AVES_BASE_URL')!,
-        hostId: config.get('AVES_HOST_ID')!,
-        xtoken: config.get('AVES_XTOKEN')!,
-        languageCode: config.get('AVES_LANGUAGE_CODE'),
-      }),
-      inject: [ConfigService],
-    }),
-  ],
-})
-export class AppModule {}
-```
+### `AvesClient`
 
-### 3. Use the Service
+#### Constructor
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { AvesService, SearchCustomerRequest } from 'aves-sdk';
-
-@Injectable()
-export class BookingService {
-  constructor(private readonly aves: AvesService) {}
-
-  async findCustomer(code: string) {
-    // Type-safe discriminated union
-    const request: SearchCustomerRequest = {
-      type: 'code',
-      code: code,
-      pagination: { pages: 50, page: 1 },
-    };
-
-    const result = await this.aves.searchCustomers(request);
-    return result.customers; // Fully typed Customer[]
-  }
-}
+new AvesClient(baseURL: string, hostID: string, xtoken: string, languageCode?: string)
 ```
 
-## Type-Safe Search (Discriminated Union)
+- `baseURL` - Base URL of the AVES API
+- `hostID` - 6-digit identification code
+- `xtoken` - Unique validation string
+- `languageCode` - Optional: 2-digit language code (01=Italian, 02=English, etc.)
 
-The search interface uses **discriminated unions** for perfect type safety:
+#### Methods
 
-```typescript
-// Search by customer code - TypeScript knows only 'code' is available
-const searchByCode: SearchCustomerRequest = {
-  type: 'code',
-  code: '123456',
-  // Only 'code' property available - type-safe!
-};
-
-// Search by name - different fields available
-const searchByName: SearchCustomerRequest = {
-  type: 'name',
-  name: 'Smith',
-  city: 'New York', // Optional for 'name' type
-};
-
-// Search by VAT code
-const searchByVat: SearchCustomerRequest = {
-  type: 'vat_code',
-  vatCode: 'IT12345678',
-  phoneNumber: '+39123456', // Optional for 'vat_code' type
-};
+##### `search(params)`
 
-// Search by last modification date
-const searchByDate: SearchCustomerRequest = {
-  type: 'last_mod_date',
-  from: '2025-01-01',
-  to: '2025-12-31',
-  // 'from' and 'to' are required for this type
-};
-```
+Search for master records by various criteria. The required fields depend on the `searchType` - TypeScript will enforce the correct fields for each search type.
 
-### Available Search Types
+**Search Types and Required Fields:**
 
-| Type                | Required Fields   | Optional Fields                    |
-| ------------------- | ----------------- | ---------------------------------- |
-| `code`              | `code`            | `pagination`                       |
-| `name`              | `name`            | `city`, `pagination`               |
-| `vat_code`          | `vatCode`         | `phoneNumber`, `pagination`        |
-| `zone`              | `zipCode`         | `city`, `countyCode`, `pagination` |
-| `category`          | `categoryCode`    | `pagination`                       |
-| `email`             | `email`           | `pagination`                       |
-| `last_mod_date`     | `from`, `to`      | `pagination`                       |
-| `search_field`      | `searchField`     | `pagination`                       |
-| `external_ref_code` | `externalRefCode` | `pagination`                       |
+- **`'CODE'`** - Requires `recordCode` (6 digits)
+- **`'NAME'`** - Requires `name`, optionally `city`
+- **`'VATCODE'`** - Requires `vatCode`, optionally `phoneNumber`
+- **`'ZONE'`** - Requires `zipCode` and `countyCode`, optionally `city`
+- **`'CATEGORY'`** - Requires `categoryCode`
+- **`'EMAIL'`** - Requires `email`
+- **`'LASTMODDATE'`** - Requires `lastModificationDate` with `minDate` and `maxDate`
+- **`'SEARCH_FIELD'`** - Requires `searchFieldValue`
+- **`'EXTERNAL_REF_CODE'`** - Requires `searchFieldValue`
 
-## API Methods
+All search types accept an optional `languageCode` (2-digit code).
 
-### Customer Management
+**Examples:**
 
 ```typescript
-// Search customers
-const result = await aves.searchCustomers({
-  type: 'name',
-  name: 'Rossi',
-  pagination: { pages: 25, page: 1 },
+// Search by code
+const byCode = await client.search({
+  searchType: 'CODE',
+  recordCode: '508558',
 });
 
-// Create customer
-const customer = await aves.createCustomer({
-  id: '123456',
-  type: 'customer',
-  status: 'enabled',
-  personalInfo: {
-    firstName: 'Mario',
-    lastName: 'Rossi',
-    dateOfBirth: '1990-01-01',
-    gender: 'male',
-  },
-  contact: {
-    email: { address: 'mario.rossi@example.com' },
-    phone: { number: '+39123456789' },
-  },
+// Search by email
+const byEmail = await client.search({
+  searchType: 'EMAIL',
+  email: 'user@example.com',
 });
 
-// Update customer
-await aves.updateCustomer(customer);
-
-// Upsert customer (insert or update secondary fields)
-await aves.upsertCustomer(customer);
-```
-
-### Booking Management
-
-```typescript
-// Create booking
-const booking = await aves.createBooking({
-  customerId: '123456',
-  description: 'Summer vacation package',
-  startDate: '2025-07-01',
-  endDate: '2025-07-14',
-  currency: 'EUR',
-  passengers: [
-    {
-      id: '001',
-      type: 'adult',
-      firstName: 'Mario',
-      lastName: 'Rossi',
-      dateOfBirth: '1990-01-01',
-      gender: 'male',
-    },
-  ],
-  services: [
-    {
-      id: 'HTL001',
-      type: 'hotel',
-      status: 'pending',
-      name: 'Hotel Paradise',
-      startDate: '2025-07-01',
-      endDate: '2025-07-14',
-    },
-  ],
-  statisticCodes: {
-    code2: 'USA',
-    code3: 'GEN',
-  },
-  printDocument: false,
-  sendDocumentViaEmail: false,
+// Search by name (with optional city)
+const byName = await client.search({
+  searchType: 'NAME',
+  name: 'John Doe',
+  city: 'New York', // Optional
 });
 
-// Update booking header
-await aves.updateBookingHeader('123456', 'BK/2025/001', '2025-07-01', {
-  notes: 'Updated booking notes',
-  passengers: [
-    /* updated passengers */
-  ],
+// Search by zone (requires zipCode and countyCode)
+const byZone = await client.search({
+  searchType: 'ZONE',
+  zipCode: '47841',
+  countyCode: 'RN',
+  city: 'Cattolica', // Optional
 });
 
-// Set booking status
-await aves.setBookingStatus('123456', 'BK/2025/001', 'confirmed');
-
-// Cancel booking
-await aves.cancelBooking({
-  bookingId: 'BK/2025/001',
-  customerId: '123456',
+// Search by last modification date
+const byDate = await client.search({
+  searchType: 'LASTMODDATE',
+  lastModificationDate: {
+    minDate: '2024-01-01',
+    maxDate: '2024-12-31',
+  },
 });
 ```
 
-### Document Management
-
-```typescript
-// Print booking documents
-const result = await aves.printDocument({
-  bookingId: 'BK/2025/001',
-  customerId: '123456',
-  documentType: 'voucher',
-  format: 'pdf',
-  language: '01',
-});
+##### `upsertRecord(record)`
 
-// Access generated documents
-result.data.documents.forEach((doc) => {
-  console.log(doc.fileName);
-  console.log(doc.content); // Base64 content
-  console.log(doc.contentSize);
-});
-```
-
-### Payment Management
+Insert or update a master record. The `insertCriteria` defaults to `'T'` (update all fields if exists) but can be overridden by including it in the record.
 
 ```typescript
-// Add payment
-await aves.addPayment({
-  bookingId: 'BK/2025/001',
-  payments: [
-    {
-      id: 'PAY001',
-      type: 'cash',
-      status: 'confirmed',
-      amount: {
-        currency: 'EUR',
-        amount: 500.0,
-      },
-    },
-  ],
-  enableMultiple: true,
-  operationType: 'absolute',
+const response = await client.upsertRecord({
+  name: string,
+  email: string,
+  address: string,
+  zipCode: string,
+  cityName: string,
+  countyCode: string,
+  stateCode: string,
+  firstPhoneNumber: string,
+  mobilePhoneNumber: string,
+  fiscalCode: string,
+  birthDate: string,
+  gender: string,
+  languageCode: string,
+  categoryCode: string,
+  recordCode: string, // Optional: 6-digit code
+  insertCriteria: 'S' | 'N' | 'T' | 'M', // Optional: defaults to 'T'
+  // ... see types for full list
 });
 ```
 
-## Type Definitions
+**Insert Criteria:**
 
-### Customer Types
+- `'S'` - Insert always new record
+- `'N'` - If record exists, do not update
+- `'T'` - If record exists, update all fields (default)
+- `'M'` - If record exists, update only secondary fields
 
-```typescript
-type CustomerType = 'customer' | 'supplier' | 'voucher' | 'supplier_voucher';
-type CustomerStatusType = 'enabled' | 'warning' | 'blacklisted' | 'disabled';
-type PassengerType = 'adult' | 'child' | 'infant' | 'senior';
-type GenderType = 'male' | 'female';
-```
-
-### Booking Types
+**Example:**
 
 ```typescript
-type BookingStatusType =
-  | 'quotation'
-  | 'work_in_progress'
-  | 'confirmed'
-  | 'optioned'
-  | 'nullified'
-  | 'canceled';
-```
+// Default behavior (update all fields if exists)
+const response = await client.upsertRecord({
+  name: 'Jane Smith',
+  email: 'jane@example.com',
+  address: '456 Oak Ave',
+  zipCode: '67890',
+  cityName: 'Los Angeles',
+  stateCode: 'USA',
+  firstPhoneNumber: '+1234567890',
+  languageCode: '02',
+});
 
-### Document Types
+// Override insertCriteria
+const newRecord = await client.upsertRecord({
+  name: 'John Doe',
+  insertCriteria: 'S', // Always insert new
+  email: 'john@example.com',
+  // ... other fields
+});
 
-```typescript
-type DocumentType =
-  | 'visa_request'
-  | 'travel_information'
-  | 'voucher'
-  | 'booking_contract'
-  | 'booking_confirmation'
-  | 'supplier_service_list'
-  | 'invoice'
-  | 'proforma_invoice'
-  | 'adeguamento'
-  | 'reservation_form'
-  | 'open_xml'
-  | 'sales_invoice'
-  | 'ticketing_tmaster'
-  | 'summary_form';
+console.log(response.customerRecordRS?.customerRecordCode);
 ```
 
-## Response Interfaces
-
-### Search Response with Pagination
-
-```typescript
-interface CustomerSearchResult {
-  customers: Customer[];
-  pagination: {
-    page: number; // Current page
-    pages: number; // Minimum known pages
-    totalItems: number; // Items in this response
-    hasMore: boolean; // More results available
-  };
-}
-```
+## Error Handling
 
-### Document Print Result
+The SDK throws `AvesError` for API errors and validation failures:
 
 ```typescript
-interface DocumentPrintResult {
-  emailRecipient?: string;
-  documents: PrintedDocument[];
-  additionalDocuments?: {
-    emailRecipient: string;
-    documents: PrintedDocument[];
-  }[];
-}
+import { AvesError } from 'aves-sdk';
 
-interface PrintedDocument {
-  fileName: string;
-  content?: string; // Base64 content
-  contentSize: number;
+try {
+  await client.search({ searchType: 'CODE', recordCode: '123' });
+} catch (error) {
+  if (error instanceof AvesError) {
+    console.error('Status:', error.status); // 'ERROR' | 'TIMEOUT' | 'WARNING'
+    console.error('Error Code:', error.errorCode);
+    console.error('Description:', error.errorDescription);
+  }
 }
 ```
 
-## Validation
+## Case Transformation
 
-All requests are validated using Zod schemas:
+The SDK automatically handles case transformation between your code and the API:
 
-```typescript
-import { searchCustomerRequestSchema } from 'aves-sdk';
+- **Input**: Use camelCase (e.g., `recordCode`, `zipCode`)
+- **API**: Automatically converted to PascalCase with XML attributes (e.g., `@RecordCode`, `ZipCode`)
+- **Output**: Automatically converted back to camelCase
 
-const result = searchCustomerRequestSchema.safeParse(request);
-if (!result.success) {
-  console.error(result.error.issues);
-}
-```
+You never need to worry about case conversion or XML attribute prefixes - the SDK handles it all.
 
-## Error Handling
+## Type Safety
 
-```typescript
-import { AvesErrorHandler, AvesErrorCodes } from 'aves-sdk';
+All types are exported and inferred from the validation schemas:
 
-try {
-  const booking = await aves.createBooking(request);
-} catch (error) {
-  const avesError = errorHandler.handleHttpError(error);
-  console.error(avesError.code, avesError.message);
+```typescript
+import type {
+  SearchMasterRecordRS,
+  ManageMasterRecordRS,
+  MasterRecordDetail,
+} from 'aves-sdk';
+
+// Use types for your functions
+function processRecord(record: MasterRecordDetail) {
+  // TypeScript knows all available fields in camelCase
 }
 ```
 
-## Bundle Size
-
-Optimized for production:
+## Validation
 
-- **ESM**: 51.75 KB (gzipped)
-- **CJS**: 55.13 KB (gzipped)
-- **DTS**: 137.03 KB
+The SDK validates all inputs and outputs using Valibot schemas:
 
-## Architecture
+- **HostID**: Must be exactly 6 digits
+- **RecordCode**: Must be exactly 6 characters
+- **LanguageCode**: Must be exactly 2 digits (01=Italian, 02=English, etc.)
+- **Search parameters**: Required fields are enforced based on `searchType` using discriminated unions
+- All other fields follow the AVES API specification
 
-```
-aves-sdk/
-├── validation/
-│   └── api-schemas.ts         # Zod schemas + inferred types (single source of truth)
-├── types/
-│   ├── interfaces.ts           # XML layer (Aves API)
-│   └── common.ts              # Shared types
-├── mappers/
-│   ├── request-mappers.ts     # API → XML
-│   ├── response-mappers.ts    # XML → API
-│   └── type-mappers.ts        # Enum conversions
-├── nest/
-│   ├── aves.module.ts         # NestJS module
-│   └── aves.service.ts        # Main service
-└── config/
-    ├── endpoints.ts           # API endpoints
-    └── root-elements.ts       # XML root elements
-```
+Invalid data will throw a validation error before making the API request. All validation happens on camelCase input, making it easy to use. TypeScript will also provide type checking and autocomplete based on the selected `searchType`.
 
 ## License
 
 MIT
 
-## Credits
+## Links
 
-Built for the Aves XML 1.8.0 Booking CPX API specification.
+- [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)