@pelygo/janus 0.2.0 → 0.4.0

package/README.md

@@ -1,263 +1,718 @@
 # @pelygo/janus
 
-TypeScript API client for JANUS (VCOMSUITE backend) endpoints with full type safety.
+TypeScript API client for JANUS (VCOMSUITE warehouse management backend). Provides typed access to orders, returns, products, stock, invoices, ASNs, dispatches, and more.
 
-## Installation
+## Setup
+
+### Install
 
 ```bash
 npm install @pelygo/janus @pelygo/auth
 ```
 
-## Quick Start
+`@pelygo/auth` is a required peer dependency. It handles token storage and refresh automatically.
+
+### Configure
+
+The JANUS API server and the auth server are **different hosts**. You must provide both URLs.
 
 ```typescript
 import { createJanusApi } from '@pelygo/janus';
 
-// Create API instance
 const janus = createJanusApi({
-  baseUrl: 'https://api.janus.pelygo.com',
+  baseUrl: 'https://api.janus.pelygo.com',       // JANUS API server
+  authUrl: 'https://auth.pelygo.com',             // Auth server (different host)
   onUnauthorized: () => {
-    // Handle session expiry (redirect to login, etc.)
+    // IMPORTANT: use setTimeout in Base44/iframe environments
+    setTimeout(() => window.location.href = '/login', 0);
   },
 });
-
-// Authenticate
-await janus.auth.login('username', 'password');
-
-// Use typed resources
-const clients = await janus.clients.getAll();
-const returns = await janus.returns.query({ clientId: 5, pageSize: 50 });
 ```
 
-## API Reference
-
-### Creating the Client
+**Dev environment:**
 
 ```typescript
 const janus = createJanusApi({
-  baseUrl: string;           // JANUS API base URL
-  onUnauthorized?: () => void;  // Called on 401 responses
+  baseUrl: 'https://api.janus.dev.pelygo.com',
+  authUrl: 'https://auth.dev.pelygo.com',
 });
 ```
 
-### Authentication
+### Read-only mode (default)
 
-The client wraps `@pelygo/auth` for authentication:
+By default the client is **read-only** — any attempt to create, update, or delete data will throw an error. This prevents accidental writes from AI-generated code or dashboard apps that should only display data.
 
 ```typescript
-// Login
-await janus.auth.login(username, password);
+// Read-only (default) — getAll, query, getById work; create, update, delete throw
+const janus = createJanusApi({ baseUrl: '...' });
 
-// Get current user
-const user = await janus.auth.getUser();
+// Full access — all operations allowed
+const janus = createJanusApi({ baseUrl: '...', allowWrites: true });
+```
 
-// Logout
-await janus.auth.logout();
+Read-only mode allows:
+- All `GET` requests (list, getById, stats, reports, filter options)
+- Query-style `POST` requests (`returns.queryPost`, `legacy.queryProducts`)
+- Authentication (`janus.auth.login`, `janus.auth.verify`)
 
-// Check if authenticated
-const isLoggedIn = janus.auth.isAuthenticated();
+Read-only mode blocks:
+- `POST` create operations (e.g. `products.create`, `orders.create`)
+- `PUT` / `PATCH` update operations (e.g. `clients.update`, `returns.update`)
+- `DELETE` operations (e.g. `products.delete`, `users.delete`)
+
+When a blocked operation is attempted, it throws:
+```
+@pelygo/janus: Write operation blocked (POST /products).
+The client is in read-only mode. To enable writes, set allowWrites: true in createJanusApi options.
 ```
 
-### Clients Resource
+### Authenticate
 
 ```typescript
-// Get all clients
-const clients = await janus.clients.getAll();
+await janus.auth.login('username', 'password');
+const user = await janus.auth.getUser();
+const isLoggedIn = janus.auth.isAuthenticated();
+await janus.auth.logout();
+```
 
-// Get single client
-const client = await janus.clients.getById(5);
+---
+
+## All Available Resources
+
+| Resource | Accessor | Auth | Description |
+|----------|----------|------|-------------|
+| Clients | `janus.clients` | Yes | Client account CRUD, courier services per client |
+| Returns | `janus.returns` | Yes | Full returns management: CRUD, items, comments, statuses, reasons, categories, sources |
+| Orders | `janus.orders` | Yes | Query orders, stats, filter options, create/update |
+| Products | `janus.products` | Yes | Product CRUD (preferred over `legacy.queryProducts`) |
+| Product Categories | `janus.productCategories` | Yes | Product category CRUD |
+| Stocks | `janus.stocks` | Yes | Stock record CRUD |
+| Stock Transactions | `janus.stockTransactions` | Yes | Stock transaction history |
+| Stock Allocations | `janus.stockAllocations` | Yes | Stock allocation records |
+| Locations | `janus.locations` | Yes | Warehouse location CRUD |
+| Dispatches | `janus.dispatches` | Yes | Dispatch CRUD |
+| Consignments | `janus.consignments` | Yes | Consignment records |
+| Invoices | `janus.invoices` | Yes | Invoice CRUD with line items |
+| ASNs | `janus.asns` | Yes | Advance Shipping Notices with lines and receipts |
+| Couriers | `janus.couriers` | Yes | Courier and service management |
+| Reports | `janus.reports` | Yes | Returns summary, reasons, overview reports (JSON + CSV) |
+| Integrations | `janus.integrations` | Yes | Integration management |
+| Users | `janus.users` | Yes | User management |
+| Logs | `janus.logs` | Yes | Activity and order issue logs |
+| Tasks | `janus.tasks` | Yes | Task history |
+| Audits | `janus.audits` | Yes | Audit trail (read-only) |
+| Legacy | `janus.legacy` | Yes | Legacy couriers, post services, products |
+| Helpers | `janus.helpers` | No | Public endpoints: return portal form submission, notification settings |
+| Customer | `janus.customer` | No | Public customer tracking (order lookup) |
+| Auth | `janus.auth` | -- | Underlying AuthApi instance for raw requests |
+
+---
+
+## Entity Field Reference
+
+### Return
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Unique ID |
+| `return_reference` | `string?` | Human-readable return reference |
+| `wms_order_ref` | `string?` | Original order reference |
+| `client_id` | `number?` | Client ID |
+| `status_id` | `number?` | Current status ID |
+| `reason_id` | `number?` | Return reason ID |
+| `customername` | `string?` | Full customer name |
+| `forename` | `string?` | First name |
+| `surname` | `string?` | Last name |
+| `email` | `string?` | Customer email |
+| `tracking_number` | `string?` | Courier tracking number |
+| `tracking_url` | `string?` | Tracking page URL |
+| `approval_status` | `'pending' \| 'approved' \| 'rejected'?` | Approval state |
+| `approved` | `boolean?` | Whether approved |
+| `approved_ts` | `string?` | Approval timestamp |
+| `line_1` | `string?` | Address line 1 |
+| `line_2` | `string?` | Address line 2 |
+| `line_3` | `string?` | Address line 3 |
+| `city` | `string?` | City |
+| `county` | `string?` | County/state |
+| `country` | `string?` | Country name |
+| `country_code` | `string?` | ISO country code (e.g. `"GB"`) |
+| `postcode` | `string?` | Postal code |
+| `company` | `string?` | Company name |
+| `wms_service_cost` | `number?` | WMS service cost |
+| `courier_service_cost` | `number?` | Courier service cost |
+| `courier_service_id` | `number?` | Assigned courier service ID |
+| `items` | `ReturnItem[]?` | Line items (when included) |
+| `statuses` | `ReturnStatusHistory[]?` | Status history (when included) |
+| `comments` | `ReturnComment[]?` | Comments (when included) |
+| `latestStatus` | `ReturnStatusHistory?` | Most recent status |
+| `created_ts` | `string?` | ISO timestamp |
+| `updated_ts` | `string?` | ISO timestamp |
+
+### LegacyOrder
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Primary key |
+| `customerId` | `number?` | FK to customer |
+| `reference` | `string?` | Order reference string |
+| `source` | `number?` | Source ID |
+| `orderDate` | `string?` | ISO date the order was placed |
+| `dispatchCompletedDate` | `string?` | ISO date all dispatches completed |
+| `orderStatus` | `number?` | Numeric status code |
+| `postServiceId` | `number?` | FK to shipping service |
+| `courierId` | `number?` | FK to courier |
+| `actualWeight` | `number?` | Measured weight |
+| `notes` | `string?` | Internal notes |
+| `hold` | `unknown?` | Whether order is on hold |
+| `releaseDate` | `string?` | ISO date when hold was released |
+| `draft` | `unknown?` | Whether order is a draft |
+| `giftMessage` | `string?` | Gift message text |
+| `deliveryInstructions` | `string?` | Delivery instructions |
+| `orderIssue` | `number?` | Issue flag |
+| `deliveryTerms` | `string?` | Incoterms code (e.g. `"DAP"`) |
+| `transaction_type` | `'b2c' \| 'b2b' \| 'internal_transfer' \| 'damage' \| 'expiry'` | **Required.** Transaction classification |
+| `external_order_id` | `string?` | External system order ID |
+| `channel_order_id` | `string?` | Sales channel order ID |
+| `channel` | `string?` | Sales channel name |
+| `created` | `string?` | ISO created timestamp |
+| `modified` | `string?` | ISO modified timestamp |
+| `status` | `number?` | Record status (0 = inactive, 1 = active) |
+| `orderItems` | `LegacyOrderItem[]` | Line items |
+| `orderMeta` | `LegacyOrderMeta[]` | Metadata key-value pairs |
+| `shopperDeliveryAddress` | `LegacyShopperAddress` | Delivery address |
+| `shopperBillingAddress` | `LegacyShopperAddress` | Billing address |
+| `dispatches` | `LegacyDispatch[]` | All dispatches for this order |
+| `dispatch` | `LegacyDispatch` | Primary dispatch |
+| `orderSource` | `Source` | Source reference data |
+
+### LegacyDispatch
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Primary key |
+| `orderId` | `number?` | FK to parent order |
+| `reference` | `string?` | Client-facing reference code |
+| `dispatchDate` | `string?` | ISO date shipped |
+| `dispatchStatus` | `number?` | 0 = pending, 1 = dispatched, 2 = cancelled |
+| `trackingNumber` | `string?` | Carrier tracking number |
+| `actualWeight` | `number?` | Measured weight |
+| `courierId` | `number?` | FK to courier |
+| `postServiceId` | `number?` | FK to shipping service |
+| `notes` | `string?` | Internal notes |
+| `hold` | `unknown?` | 0 = not held, 1 = on hold |
+| `draft` | `unknown?` | 0 = finalised, 1 = draft |
+| `deliveryInstructions` | `string?` | Special delivery instructions |
+| `dispatchActionId` | `number?` | Current action (pick, pack, ship) |
+| `dispatchActionStatus` | `number?` | 0 = not started, 1 = in progress, 2 = completed |
+| `stockStatus` | `number?` | 0 = unallocated, 1 = partial, 2 = fully allocated |
+| `dispatchIssue` | `number?` | 0 = no issue, 1 = issue flagged |
+| `priority` | `number?` | Higher = higher priority |
+| `complete` | `number?` | 0 = incomplete, 1 = complete |
+| `complete_date` | `string?` | ISO date marked complete |
+| `deliveryTerms` | `string?` | Incoterms code |
+| `created` | `string?` | ISO created timestamp |
+| `modified` | `string?` | ISO modified timestamp |
+| `status` | `number?` | 0 = inactive/deleted, 1 = active |
+| `dispatchItems` | `LegacyDispatchItem[]` | Line items in this dispatch |
+| `shopperDeliveryAddress` | `LegacyShopperAddress` | Delivery address |
+| `consignment` | `Consignment` | Consignment record |
+| `postService` | `LegacyPostService` | Shipping service details |
+
+### FormattedProduct
+
+Returned by `janus.products.getAll()`. Field names are snake_case (different from the raw `LegacyProduct` entity).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `product_id` | `number` | Primary key |
+| `client_id` | `number` | FK to owning client |
+| `sku_code` | `string?` | SKU -- unique product identifier within the client |
+| `product_name` | `string?` | Human-readable name |
+| `description` | `string?` | Extended description |
+| `additional_skus` | `string?` | Comma-separated alternative SKUs |
+| `asins` | `string?` | Amazon Standard Identification Numbers |
+| `custom_fields` | `Record<string, unknown>?` | Client-defined key-value pairs |
+| `hs_code` | `string?` | Harmonized System code for customs |
+| `unit_of_measure` | `string?` | e.g. `"each"`, `"kg"`, `"litre"` |
+| `eaches_per_pack` | `number?` | Units per case pack |
+| `case_pack_sku_code` | `string?` | SKU of the case pack |
+| `weight_grams` | `number?` | Unit weight in grams |
+| `barcode` | `string?` | Primary EAN/UPC barcode |
+| `case_pack_barcode` | `string?` | Case pack barcode |
+| `product_category_id` | `number?` | FK to product category |
+| `product_type` | `string?` | e.g. `"physical"`, `"digital"`, `"service"` |
+| `sellable_format` | `string?` | e.g. `"single"`, `"pack"`, `"case"` |
+| `commodity_description` | `string?` | Customs commodity description |
+| `price` | `number?` | Unit sale price |
+| `currency` | `string?` | ISO 4217 code (e.g. `"GBP"`) |
+| `country_of_origin` | `string?` | ISO 3166-1 alpha-2 (e.g. `"CN"`) |
+| `primary_material` | `string?` | Primary material |
+| `secondary_material` | `string?` | Secondary material |
+| `dangerous_goods` | `string?` | DG classification / UN number |
+| `image_url` | `string?` | Product image URL |
+| `low_stock_threshold` | `number?` | Low-stock alert threshold |
+| `requires_batch_tracking` | `number?` | 0 = no, 1 = yes |
+| `requires_serial_tracking` | `number?` | 0 = no, 1 = yes |
+| `requires_bbe_tracking` | `number?` | 0 = no, 1 = yes (best-before/expiry) |
+| `is_bundle` | `number?` | 0 = standalone, 1 = bundle |
+| `bundle_components` | `string?` | Component SKUs and quantities |
+| `default_stock_status` | `string?` | Status assigned on receipt |
+| `product_status` | `string?` | e.g. `"active"`, `"discontinued"` |
+| `status` | `number?` | 0 = inactive/deleted, 1 = active |
+| `created_date` | `string?` | ISO created timestamp |
+| `updated_date` | `string?` | ISO updated timestamp |
+
+### Stock
+
+Extends `BaseEntity` (adds `id`, `created_by`, `updated_by`, `created_ts`, `updated_ts`, `partition_id`).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Primary key (from BaseEntity) |
+| `clientId` | `number?` | FK to owning client |
+| `sku_code` | `string?` | SKU identifying the product |
+| `location` | `string?` | Location code (e.g. `"A-01-03-B"`) |
+| `quantity` | `number?` | Units at this location |
+| `batch_number` | `string?` | Batch/lot number |
+| `serial_number` | `string?` | Serial number |
+| `best_before_date` | `string?` | ISO expiry date (FEFO rotation) |
+| `received_date` | `string?` | ISO date received into warehouse |
+| `stock_status` | `'available' \| 'quarantined' \| 'expired' \| 'damaged' \| 'reserved'` | **Required.** Current status |
+| `fulfilment_location_id` | `number?` | FK to fulfilment centre |
+| `fulfilment_location_name` | `string?` | Fulfilment centre name |
+| `fulfilment_location_country` | `string?` | ISO country code |
+| `notes` | `string?` | Free-text notes |
+| `created_ts` | `string?` | ISO created timestamp (from BaseEntity) |
+| `updated_ts` | `string?` | ISO updated timestamp (from BaseEntity) |
+
+### Location
+
+Extends `BaseEntity`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Primary key |
+| `clientId` | `number?` | FK to owning client |
+| `location_code` | `string?` | Unique code (e.g. `"A-01-03-B"`) |
+| `location_type` | `'pick' \| 'bulk' \| 'staging' \| 'receiving' \| 'shipping' \| 'quarantine' \| 'returns'` | **Required.** Location role |
+| `zone` | `string?` | Warehouse zone (e.g. `"A"`) |
+| `aisle` | `string?` | Aisle identifier |
+| `bay` | `string?` | Bay/rack identifier |
+| `level` | `string?` | Vertical level/shelf |
+| `position` | `string?` | Horizontal position |
+| `fulfilment_location_id` | `number?` | FK to fulfilment centre |
+| `fulfilment_location_name` | `string?` | Fulfilment centre name |
+| `current_units` | `number?` | Stock units currently held |
+| `max_capacity_units` | `number?` | Maximum unit capacity |
+| `max_capacity_weight_kg` | `number?` | Maximum weight (kg) |
+| `is_mixed_sku_allowed` | `number?` | 0 = single SKU only, 1 = mixed |
+| `is_active` | `number?` | 0 = decommissioned, 1 = in use |
+| `is_pickable` | `number?` | 0 = no, 1 = yes |
+| `is_receivable` | `number?` | 0 = no, 1 = yes |
+| `temperature_zone` | `'ambient' \| 'chilled' \| 'frozen'` | **Required.** Temperature classification |
+| `notes` | `string?` | Free-text notes |
+
+### Invoice
+
+Extends `BaseEntity`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Primary key |
+| `clientId` | `number?` | FK to client |
+| `invoice_date` | `string` | **Required.** ISO invoice date |
+| `xero_reference` | `string?` | Xero accounting reference |
+| `total` | `number?` | Total invoice amount |
+| `emailed` | `number?` | 0 = not emailed, 1 = emailed |
+| `paid` | `number?` | 0 = unpaid, 1 = paid |
+| `fuel_mode` | `number?` | 0 = flat rate, 1 = percentage |
+| `status` | `number?` | 0 = inactive/deleted, 1 = active |
+| `invoiceLines` | `InvoiceLine[]?` | Line items |
+
+### InvoiceLine
+
+Extends `BaseEntity`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Primary key |
+| `invoice_id` | `number?` | FK to parent invoice |
+| `class_id` | `number?` | Charge classification (storage, fulfilment, shipping) |
+| `object_id` | `number?` | FK to billable object (dispatch ID, etc.) |
+| `reference` | `string` | **Required.** Client-facing reference |
+| `description` | `string?` | Charge description |
+| `dispatch_date` | `string?` | ISO dispatch date |
+| `service_name` | `string?` | Shipping service name |
+| `price` | `number?` | Unit price |
+| `discount_rate` | `number?` | Discount percentage |
+| `postcode` | `string?` | Destination postcode |
+| `country_code` | `string?` | ISO destination country |
+| `tax_class` | `number?` | 0 = zero-rated, 1 = standard, 2 = exempt |
+| `consignment_price` | `number?` | Carrier cost before margin |
+| `fuel` | `number?` | Fuel surcharge |
+| `packaging_price` | `number?` | Packaging material cost |
+| `discount` | `number?` | Calculated discount amount |
+| `lines` | `number?` | Number of order lines |
+| `picks` | `number?` | Number of picks |
+| `weight` | `number?` | Total weight (kg) |
+| `margin_charged` | `number?` | Margin on carrier cost |
+| `total_override` | `number?` | Manual total override |
+| `status` | `number?` | 0 = inactive/deleted, 1 = active |
+
+### ASN (Advance Shipping Notice)
+
+Extends `BaseEntity`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Primary key |
+| `clientId` | `number` | **Required.** FK to client |
+| `asn_status` | `string` | **Required.** One of: `draft`, `awaiting_arrival`, `arrived`, `processing`, `receipted`, `receipted_with_discrepancies`, `temporarily_receipted`, `quarantined`, `cancelled` |
+| `expected_arrival_date` | `string?` | ISO expected arrival date |
+| `total_expected_units` | `number?` | Total expected units |
+| `asnLines` | `AsnLine[]` | Line items |
+
+### AsnLine
+
+Extends `BaseEntity`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Primary key |
+| `asn_id` | `number` | **Required.** FK to parent ASN |
+| `product_id` | `number?` | FK to product |
+| `sku_code` | `string` | **Required.** SKU code |
+| `expected_quantity` | `number` | **Required.** Expected unit count |
+| `received_quantity` | `number?` | Actual received count |
+| `asnReceipts` | `AsnReceipt[]` | Receipt records |
+
+### AsnReceipt
+
+Extends `BaseEntity`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Primary key |
+| `asn_id` | `number` | **Required.** FK to ASN |
+| `asn_line_id` | `number` | **Required.** FK to ASN line |
+| `received_quantity` | `number` | **Required.** Quantity received |
+| `stock_status` | `'available' \| 'quarantined' \| 'expired' \| 'damaged' \| 'reserved'` | **Required.** Status of received stock |
+
+---
+
+## Query Filter Reference
+
+### PaginatedQueryFilters (v2 endpoints: products, stocks, locations, invoices, ASNs, dispatches)
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `clientId` | `number` | **Yes** | Client ID from `useClient()` |
+| `pageSize` | `number` | No | Results per page (default: 25) |
+| `pageNumber` | `number` | No | Page number, 1-based (default: 1) |
+| `orderColumn` | `string` | No | Column to sort by (e.g. `'id'`, `'created'`) |
+| `orderDirection` | `'ASC' \| 'DESC'` | No | Sort direction (default: DESC) |
+| `query` | `string` | No | Free-text search across key fields |
+
+### ReturnsQueryFilters (janus.returns.query)
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `clientId` | `number` | **Yes** | Client ID |
+| `page` | `number` | No | Page number |
+| `pageSize` | `number` | No | Results per page |
+| `created_at` | `string` | No | Start date (ISO, e.g. `'2025-01-01'`) |
+| `created_to` | `string` | No | End date (ISO) |
+| `last_status_ids` | `string` | No | Comma-separated status IDs to match current status |
+| `include_status_ids` | `string` | No | Include returns with any of these status IDs |
+| `exclude_status_ids` | `string` | No | Exclude returns with these status IDs |
+| `processed_at` | `string` | No | Processed start date (ISO) |
+| `processed_to` | `string` | No | Processed end date (ISO) |
+| `include_associations` | `string` | No | Nested data: `'return_items'`, `'return_comments'`, or comma-separated |
+| `csv` | `boolean` | No | Export as CSV instead of JSON |
+| `group_by` | `string` | No | Group results by field |
+
+### OrdersQueryFilters (janus.orders.getAll)
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `clientId` | `number` | **Yes** | Client ID |
+| `page` | `number` | No | Page number |
+| `pageSize` | `number` | No | Results per page |
+| `order_column` | `string` | No | Sort column |
+| `order_direction` | `'ASC' \| 'DESC'` | No | Sort direction |
+| `created_at` | `string` | No | Start date (ISO) |
+| `created_to` | `string` | No | End date (ISO) |
+| `channel` | `string` | No | Filter by sales channel |
+| `destination` | `string` | No | Filter by destination |
+| `courier` | `string` | No | Filter by courier name |
+| `service` | `string` | No | Filter by courier service |
+| `status` | `string` | No | Filter by order status |
+| `query` | `string` | No | Free-text search |
+| `include_all_stages` | `boolean` | No | Include all order stages |
+
+### ReturnsSummaryFilters (janus.reports.returnsSummary / returnsSummaryCsv)
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `clientId` | `number` | **Yes** | Client ID |
+| `createdFrom` | `string` | No | Start date (ISO) |
+| `createdTo` | `string` | No | End date (ISO) |
+| `approvedFrom` | `string` | No | Approval start date |
+| `approvedTo` | `string` | No | Approval end date |
+| `courierServiceId` | `number` | No | Filter by courier service |
+| `approved` | `boolean` | No | Only approved returns |
+| `isClientsReport` | `boolean` | No | Format as client-level report |
+| `page` | `number` | No | Page number |
+| `pageSize` | `number` | No | Results per page |
+
+### ReturnsReasonsFilters (janus.reports.returnsReasons / returnsReasonsCsv)
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `clientId` | `number` | **Yes** | Client ID |
+| `createdFrom` | `string` | No | Start date (ISO) |
+| `createdTo` | `string` | No | End date (ISO) |
+
+### OrdersStatsFilters (janus.orders.getStats)
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `clientId` | `number` | **Yes** | Client ID |
+| `created_at` | `string` | No | Start date (ISO) |
+| `created_to` | `string` | No | End date (ISO) |
+| `dashboard` | `boolean` | No | Return dashboard-formatted stats (recommended: `true`) |
+
+### Resource-specific extra filters
+
+| Resource method | Extra param | Type | Description |
+|----------------|-----------|------|-------------|
+| `janus.stockTransactions.getAll` | `stockId` | `number` | Filter by stock record |
+| `janus.stockAllocations.getAll` | `orderId` | `number` | Filter by order |
+| `janus.dispatches.getAll` | `orderId` | `number` | Filter by order |
+| `janus.audits.getAll` | `filter` | `string` | Additional filter |
+| `janus.users.getAll` | `filterRole` | `string` | Filter by user role |
+| `janus.users.getAll` | `filterType` | `string` | Filter by user type |
+| `janus.users.getAll` | `filterClientId` | `number` | Filter by assigned client |
+
+---
+
+## Common Patterns
+
+### Querying with Filters and Pagination
+
+**v2 endpoints** (products, stocks, locations, invoices, ASNs, dispatches) use `ClientScopedPaginatedQueryFilters`:
 
-// Update client
-const updated = await janus.clients.update(5, { name: 'New Name' });
+```typescript
+const { data, meta } = await janus.products.getAll({
+  clientId: 5,           // REQUIRED
+  pageSize: 50,
+  pageNumber: 1,
+  orderColumn: 'sku_code',
+  orderDirection: 'ASC',
+  query: 'widget',       // free-text search
+});
 
-// Get courier services for client
-const services = await janus.clients.getCourierServices(5);
-const service = await janus.clients.getCourierServiceById(5, serviceId);
-await janus.clients.updateCourierService(5, serviceId, { active: true });
+// meta = { total_items, total_pages, current_page, page_size }
 ```
 
-### Returns Resource
+**Legacy endpoints** (orders, returns) use their own filter shapes:
 
 ```typescript
-// Query returns with filters
 const returns = await janus.returns.query({
   clientId: 5,
   last_status_ids: '1,2,3',
   created_at: '2024-01-01',
   created_to: '2024-12-31',
   pageSize: 100,
+  csv: false,
 });
 
-// Get single return with items
-const ret = await janus.returns.getById(123, { includeAssociations: true });
-
-// Create a return
-const newReturn = await janus.returns.create({
-  client_id: 5,
-  customer_name: 'John Doe',
-  // ...
+const orders = await janus.orders.getAll({
+  clientId: 5,
+  created_at: '2024-01-01',
+  created_to: '2024-12-31',
+  status: 'dispatched',
+  order_column: 'created',
+  order_direction: 'DESC',
 });
+```
 
-// Update a return
-await janus.returns.update(123, { customer_name: 'Jane Doe' });
-
-// Delete a return
-await janus.returns.delete(123);
-
-// Manage statuses
-await janus.returns.addStatus(123, statusId);
-await janus.returns.removeStatus(123, statusId);
-const statuses = await janus.returns.getStatuses(123);
-
-// Manage comments
-await janus.returns.addComment(123, 'Comment text');
-await janus.returns.removeComment(123, commentId);
-const comments = await janus.returns.getComments(123);
-
-// Manage items
-const items = await janus.returns.getItems(123);
-await janus.returns.addItem(123, { wms_product_sku: 'SKU123', qty: 2 });
-await janus.returns.updateItem(123, itemId, { qty: 3 });
+### CSV Export
 
-// Approval workflow
-await janus.returns.setApproval(123, true);  // Approve
-await janus.returns.setApproval(123, false); // Reject
+Reports have dedicated CSV methods:
 
-// Reference data
-const reasons = await janus.returns.getReasons();
-const allStatuses = await janus.returns.getAllStatuses();
-const filterOptions = await janus.returns.getFilterOptions(5);
+```typescript
+const csvString = await janus.reports.returnsSummaryCsv({ clientId: 5 });
+const reasonsCsv = await janus.reports.returnsReasonsCsv({ clientId: 5 });
+const overviewCsv = await janus.reports.returnsOverviewCsv({ clientId: 5 });
 ```
 
-### Reports Resource
+Returns can also export as CSV via the query filter:
 
 ```typescript
-// Returns summary report
-const summary = await janus.reports.returnsSummary({
-  clientId: 5,
-  created_at: '2024-01-01',
-  created_to: '2024-12-31',
-  groupBy: 'month',
-});
-
-// CSV export
-const csvData = await janus.reports.returnsSummaryCsv({ clientId: 5 });
+const csv = await janus.returns.query({ clientId: 5, csv: true });
+```
 
-// Returns by reason
-const reasonReport = await janus.reports.returnsReasons({ clientId: 5 });
-const reasonCsv = await janus.reports.returnsReasonsCsv({ clientId: 5 });
+### CRUD on Sub-Resources
 
-// Returns overview
-const overview = await janus.reports.returnsOverview({ clientId: 5 });
-const overviewCsv = await janus.reports.returnsOverviewCsv({ clientId: 5 });
+Invoices, ASNs, and returns have nested sub-resources:
 
-// Statistics
-const stats = await janus.reports.returnsStats(5);
+```typescript
+// Invoice lines
+const { data: lines } = await janus.invoices.getLines(invoiceId, { clientId: 5 });
+await janus.invoices.createLine(invoiceId, lineData);
+await janus.invoices.updateLine(invoiceId, lineId, updatedData);
+
+// ASN lines and receipts
+const { data: asnLines } = await janus.asns.getLines(asnId, { clientId: 5 });
+await janus.asns.createReceipt(asnId, lineId, receiptData);
+
+// Return items, comments, statuses
+const items = await janus.returns.getItems(returnId);
+await janus.returns.addComment(returnId, 'Inspected, item damaged');
+await janus.returns.addStatus(returnId, statusId);
 ```
 
-### Helpers Resource (Public Endpoints)
+### Paginated Response Shape
 
-```typescript
-// Submit return portal form (no auth required)
-const result = await janus.helpers.submitReturnPortalForm(formData);
+v2 endpoints return:
 
-// Get notification settings
-const settings = await janus.helpers.getNotificationSettings(clientId);
+```typescript
+{
+  data: T[],
+  meta: {
+    total_items: number,
+    total_pages: number,
+    current_page: number,
+    page_size: number,
+  }
+}
 ```
 
-## Types
+### Raw API Access
 
-All entity types are exported and can be imported:
+For endpoints not yet wrapped:
 
 ```typescript
-import type {
-  Client,
-  Return,
-  ReturnItem,
-  ReturnStatus,
-  ReturnReason,
-  User,
-  // ... more types
-} from '@pelygo/janus';
+const result = await janus.auth.get('/some/endpoint?clientId=5');
+const result = await janus.auth.post('/some/endpoint', { body: 'data' });
 ```
 
-### Filter Types
+---
 
-```typescript
-import type { ReturnsQueryParams, ReportFilters } from '@pelygo/janus';
+## Important Rules
 
-const filters: ReturnsQueryParams = {
-  clientId: 5,
-  last_status_ids: '1,2',
-  pageSize: 50,
-};
-```
+1. **Always pass `clientId`.**
+   Get it from `useClient()` or equivalent. Never omit it.
+   - New v2 endpoints (`products`, `stocks`, `locations`, `invoices`, `asns`, `dispatches`) **reject with 400** if `clientId` is missing.
+   - Older endpoints (`orders`, `returns`) silently return **all clients' data** if omitted -- this is a data leak, not a feature.
 
-## Development
+2. **Use the exact field names from this README.**
+   Field names differ between entities (e.g. `sku_code` not `sku`, `product_name` not `name`, `price` not `value`). Do not guess -- refer to the tables above.
 
-```bash
-# Install dependencies
-npm install
+3. **Navigation in Base44/iframe environments must use `setTimeout`.**
+   Direct `window.location` or router calls inside callbacks (like `onUnauthorized`) will fail silently in iframed environments:
+   ```typescript
+   onUnauthorized: () => {
+     setTimeout(() => window.location.href = '/login', 0);
+   },
+   ```
 
-# Run tests
-npm run test
+4. **`baseUrl` and `authUrl` are different servers.**
+   Do not pass the same URL for both. The JANUS API server handles data; the auth server handles tokens.
 
-# Run tests once
-npm run test:run
+5. **Use `janus.products` instead of `janus.legacy.queryProducts`.**
+   The `products` resource uses the newer v2 endpoint with proper pagination and typed responses.
 
-# Type check
-npm run typecheck
+---
 
-# Build
-npm run build
+## API Behaviour Notes
 
-# Generate entity types from v2 TypeORM entities
-npm run generate-types
+### Error responses
+```json
+{ "statusCode": 400, "message": "Error description" }
 ```
+Common codes: 400 (bad request/validation), 401 (unauthorized), 404 (not found).
 
-### Integration Tests
+### Date formats
+- **Query params:** ISO 8601 format (`'2025-01-01'` or `'2025-01-01 12:00:00'`)
+- **Response fields:** ISO 8601 timestamps (e.g. `created_ts`, `orderDate`, `created`)
+- **CSV exports:** formatted as `DD-MM-YYYY HH:mm`
 
-To run integration tests against a real JANUS API, set environment variables:
+### Pagination defaults
+- Default `pageSize`: 50 (v2 endpoints)
+- Default `pageNumber`: 1 (1-based indexing)
+- Default sort: DESC (newest first)
+- Max sensible page size: 1,000
 
-```bash
-export JANUS_API_URL="https://api.janus.dev.pelygo.com"
-export JANUS_TEST_USERNAME="testuser"
-export JANUS_TEST_PASSWORD="testpass"
-export JANUS_TEST_CLIENT_ID="5"
+### Search behaviour (`query` param)
+Free-text search is case-insensitive LIKE matching across key text columns:
+- **Products:** `sku`, `name`, `description`
+- **Returns:** order references, tracking numbers
+- **Clients:** client names
+- **Orders:** order references, channel IDs
 
-npm run test:integration
-```
+### Returns-specific behaviour
+- **Archived returns** (status ID 10) are excluded by default — pass `include_archived: true` to include
+- **Return types:** `0` = regular return, `1` = exchange — filter with `return_types: '0'` or `'1'`
+- **Associations:** `include_associations: 'return_items'` loads line items; `'return_items,return_comments'` loads both
+- **Approval statuses:** `'pending'`, `'approved'`, `'rejected'`
 
-## Architecture
+### Stats responses
+`getStats()` endpoints return flat objects with numeric values. **Keys vary by client data.** Always use `Object.entries(stats)` to iterate — never hardcode expected keys.
 
-```
-src/
-├── index.ts           # Main exports
-├── client.ts          # createJanusApi() factory
-├── types/
-│   ├── entities/      # Generated entity interfaces
-│   ├── filters.ts     # Query filter types
-│   └── responses.ts   # API response types
-├── resources/
-│   ├── clients.ts     # Clients API
-│   ├── returns.ts     # Returns API
-│   ├── reports.ts     # Reports API
-│   └── helpers.ts     # Public endpoints
-└── utils/
-    └── query-builder.ts  # URL query string builder
+---
+
+## Type Imports
+
+```typescript
+import type {
+  // Entities
+  Return, ReturnItem, ReturnStatus, ReturnReason, ReturnComment,
+  LegacyOrder, LegacyDispatch, LegacyOrderItem, LegacyDispatchItem,
+  LegacyShopperAddress,
+  FormattedProduct,
+  Stock,
+  Location,
+  Invoice, InvoiceLine,
+  Asn, AsnLine, AsnReceipt,
+  Client,
+
+  // Filters
+  ReturnsQueryFilters,
+  OrdersQueryFilters,
+  ClientScopedPaginatedQueryFilters,
+  PaginatedQueryFilters,
+  ReturnsSummaryFilters,
+
+  // Responses
+  PaginatedListResponse,
+  PaginatedResponse,
+  PaginationMeta,
+  ReturnsStatsResponse,
+  FilterOptionsResponse,
+
+  // API types
+  JanusApi,
+  JanusApiOptions,
+} from '@pelygo/janus';
 ```
 
-## Base44 Integration
+---
 
-For Base44 applications, see the **[Base44 Integration Guide](docs/BASE44_GUIDE.md)** which includes:
+## Development
 
-- Installation and setup for Base44
-- AI prompt examples for generating pages
-- Common patterns and code snippets
+```bash
+npm run build          # Build with Vite
+npm run typecheck      # TypeScript check
+npm run test           # Run tests with Vitest
+npm run test:run       # Run tests once
+npm run generate-types # Generate entity types from v2 TypeORM entities
+```
 
 ## Related Packages
 
-- [@pelygo/auth](https://www.npmjs.com/package/@pelygo/auth) - Authentication client (peer dependency)
+- [@pelygo/auth](https://www.npmjs.com/package/@pelygo/auth) -- Authentication client (peer dependency)
 
 ## License