Merge pull request #5 from FiscalAPI/feat/AddLadingSupport

Added lading support

Author: mendozagit

CLAUDE.md

@@ -9,59 +9,66 @@ FiscalAPI SDK for Node.js - Official TypeScript SDK for Mexican electronic invoi
 ## Build Commands
 
 ```bash
-npm run build          # Full build: clean + esm + cjs + types
-npm run build:esm      # TypeScript to ES Modules (dist/esm)
-npm run build:cjs      # TypeScript to CommonJS (dist/cjs)
-npm run build:types    # TypeScript declaration files (dist/types)
+npm run build          # Full build: clean + cjs + esm + package-json markers
+npm run build:esm      # TypeScript → ES Modules (dist/esm), then fix-esm-imports.js adds .js extensions
+npm run build:cjs      # TypeScript → CommonJS (dist/cjs)
 npm run clean          # Remove dist directory
-npm test               # Run Jest tests
-npm run lint           # ESLint on src/**/*.ts
+npm test               # Run Jest (note: jest not in devDependencies yet)
+npm run lint           # ESLint on src/**/*.ts (note: eslint not in devDependencies yet)
 npm run main           # Run examples/main.ts with ts-node
 ```
 
+There is no `build:types` script — the full `build` script handles CJS + ESM + dual-package markers via `build:package-json` (creates `dist/cjs/package.json` with `"type":"commonjs"` and `dist/esm/package.json` with `"type":"module"`).
+
 ## Architecture
 
-**Facade Pattern**: `FiscalapiClient` is the main entry point exposing all services:
-- `invoices` - CFDI invoice creation, cancellation, PDF generation
-- `products` - Product/service catalog management
-- `persons` - Issuer/recipient (emisor/receptor) management
-- `taxFiles` - CSD certificate upload
-- `catalogs` - SAT catalog queries
-- `downloadCatalogs`, `downloadRules`, `downloadRequests` - Bulk XML download
-
-**Directory Structure**:
-- `src/abstractions/` - Service interfaces (I*Service)
-- `src/services/` - Service implementations extending `BaseFiscalapiService`
-- `src/models/` - Data models (Invoice, Person, Product, etc.)
-- `src/common/` - Shared DTOs (ApiResponse, PagedList, FiscalapiSettings)
-- `src/utils/` - Date formatting (Luxon), Base64 encoding, validation helpers
+**Facade Pattern**: `FiscalapiClient` (`src/services/fiscalapi-client.ts`) is the single entry point.
+- Static factory: `FiscalapiClient.create(settings)` — validates settings, sets defaults, creates one shared HTTP client
+- Private constructor enforces factory usage
+- Services exposed as readonly properties: `invoices`, `products`, `persons`, `taxFiles`, `catalogs`, `apiKeys`, `stamps`, `downloadCatalogs`, `downloadRules`, `downloadRequests`
+
+**Service Layer**:
+- `BaseFiscalapiService` provides CRUD: `list()`, `getById()`, `create()`, `update()`, `remove()`, `upload()`
+- Specialized services add domain methods (e.g., `InvoiceService.cancel()`, `.getPdf()`, `.getXml()`, `.send()`, `.getStatus()`)
+- `PersonService` contains nested `EmployeeService` and `EmployerService`
+
+**HTTP Client** (`src/http/`):
+- Axios-based with 30s timeout
+- Factory caches clients by key `apiKey:tenant:apiUrl`
+- Headers: `X-API-KEY`, `X-TENANT-KEY`, `X-TIMEZONE`
+- Debug mode enables request/response logging via Axios interceptors and disables SSL certificate verification (`rejectUnauthorized: false`)
 
 **Key Patterns**:
-- All services implement interfaces from `abstractions/`
-- HTTP client injected via factory pattern
-- Dual-package output: ESM + CommonJS + TypeScript declarations
-- Date handling uses Luxon with `America/Mexico_City` timezone
-- SAT date format: `yyyy-MM-ddTHH:mm:ss`
+- All services implement interfaces from `src/abstractions/`
+- `ApiResponse<T>` wraps all responses: `{ succeeded, data, message, details, httpStatusCode }`
+- Dual-package output: ESM + CJS. Post-build script `scripts/fix-esm-imports.js` adds `.js` extensions to ESM imports for Node.js native module support
+- Date handling uses Luxon with `America/Mexico_City` timezone; SAT format: `yyyy-MM-dd'T'HH:mm:ss`
+- `src/index.ts` re-exports 100+ types — all public API surface
 
 ## Configuration
 
 ```typescript
-const settings: FiscalapiSettings = {
+const client = FiscalapiClient.create({
   apiUrl: "https://test.fiscalapi.com",  // or https://live.fiscalapi.com
   apiKey: "<api_key>",
   tenant: "<tenant>",
-  apiVersion?: "v4",                      // default
-  timeZone?: "America/Mexico_City",       // default
-  debug?: false
-};
-const client = FiscalapiClient.create(settings);
+  apiVersion: "v4",                      // default
+  timeZone: "America/Mexico_City",       // default
+  debug: false                           // enables logging + disables SSL verification
+});
 ```
 
 ## Two Operation Modes
 
 1. **By References**: Send only IDs of pre-configured entities in FiscalAPI dashboard
 2. **By Values**: Send complete data in each request (no prior setup needed)
 
+Examples for both modes are in `examples/` (7 files covering invoices, payroll, local taxes, stamps, employee/employer data).
+
 ## TypeScript Configuration
 
-Strict mode enabled with all checks: `noImplicitAny`, `strictNullChecks`, `noImplicitReturns`, `noUnusedParameters`. Target ES2018.
+Strict mode enabled. Target: **ES2019**. Key flags: `noImplicitAny`, `strictNullChecks`, `noImplicitReturns`, `noUnusedParameters`, `noFallthroughCasesInSwitch`. `noUnusedLocals` is **false**. Three tsconfig files: `tsconfig.base.json` (shared), `tsconfig.esm.json` (ESNext modules → dist/esm), `tsconfig.cjs.json` (CommonJS → dist/cjs).
+
+## CI/CD
+
+GitHub Actions (`.github/workflows/main.yml`): manual trigger only, builds on Node 18, publishes to npm. No tests run before publish.