@pelygo/janus 0.2.0 → 0.3.0

package/README.md

@@ -1,263 +1,690 @@
 # @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
-
-The client wraps `@pelygo/auth` for authentication:
+### Authenticate
 
 ```typescript
-// Login
-await janus.auth.login(username, password);
-
-// Get current user
+await janus.auth.login('username', 'password');
 const user = await janus.auth.getUser();
-
-// Logout
-await janus.auth.logout();
-
-// Check if authenticated
 const isLoggedIn = janus.auth.isAuthenticated();
+await janus.auth.logout();
 ```
 
-### Clients Resource
+---
+
+## 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`:
 
 ```typescript
-// Get all clients
-const clients = await janus.clients.getAll();
-
-// Get single client
-const client = await janus.clients.getById(5);
-
-// Update client
-const updated = await janus.clients.update(5, { name: 'New Name' });
+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
 

package/USAGE.md

@@ -0,0 +1,376 @@
+# @pelygo/janus — Quick Usage Reference
+
+This file ships inside the npm package for AI tools to reference.
+
+## Setup
+
+```js
+import { createJanusApi } from '@pelygo/janus';
+import { configure } from '@pelygo/auth/core';
+
+// Auth and API are separate servers — both URLs required
+configure({
+  apiBaseUrl: 'https://api.janus.dev.pelygo.com',
+  authBaseUrl: 'https://api.auth.dev.pelygo.com',
+});
+
+export const janus = createJanusApi({
+  baseUrl: 'https://api.janus.dev.pelygo.com',
+  onUnauthorized: () => {
+    setTimeout(() => { window.location.href = '/SignIn'; }, 100);
+  },
+});
+```
+
+## Rules
+
+1. **Always pass `clientId`** to every query. Get it from `useClient()`:
+   ```js
+   const { clientId } = useClient();
+   ```
+   New endpoints reject without it (400). Older endpoints return ALL clients' data without it.
+
+2. **Use exact field names** from the tables below. Do not guess field names.
+
+3. **Navigation in callbacks** (onSuccess, onSelect, logout) must use:
+   ```js
+   setTimeout(() => { window.location.href = '/path'; }, 100);
+   ```
+   This is required for Base44 and other iframe-based environments.
+
+4. **Use `Object.entries(data)`** for dynamic response shapes (like `getStats`).
+
+## Query Filter Reference
+
+### PaginatedQueryFilters (v2 endpoints: products, stocks, locations, etc.)
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `clientId` | `number` | **Required.** Client ID from `useClient()` |
+| `pageSize` | `number` | Results per page (default: 25) |
+| `pageNumber` | `number` | Page number, 1-based (default: 1) |
+| `orderColumn` | `string` | Column to sort by (e.g. `'id'`, `'created'`) |
+| `orderDirection` | `'ASC' \| 'DESC'` | Sort direction (default: DESC) |
+| `query` | `string` | Free-text search across key fields |
+
+```js
+const { data, meta } = await janus.products.getAll({
+  clientId, pageSize: 25, pageNumber: 1, orderDirection: 'DESC', query: 'widget',
+});
+```
+
+### ReturnsQueryFilters (janus.returns.query)
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `clientId` | `number` | Client ID |
+| `page` | `number` | Page number |
+| `pageSize` | `number` | Results per page |
+| `created_at` | `string` | Start date (ISO, e.g. `'2025-01-01'`) |
+| `created_to` | `string` | End date (ISO) |
+| `last_status_ids` | `string` | Comma-separated status IDs to match current status |
+| `include_status_ids` | `string` | Include returns with any of these status IDs |
+| `exclude_status_ids` | `string` | Exclude returns with these status IDs |
+| `include_associations` | `string` | Include nested data: `'return_items'`, `'return_comments'`, or both comma-separated |
+| `csv` | `boolean` | Export as CSV instead of JSON |
+| `group_by` | `string` | Group results by field |
+
+```js
+const returns = await janus.returns.query({
+  clientId, page: 1, pageSize: 25,
+  created_at: '2025-01-01', created_to: '2025-12-31',
+  last_status_ids: '1,2', include_associations: 'return_items',
+});
+```
+
+### OrdersQueryFilters (janus.orders.getAll)
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `clientId` | `number` | Client ID |
+| `page` | `number` | Page number |
+| `pageSize` | `number` | Results per page |
+| `order_column` | `string` | Sort column |
+| `order_direction` | `'ASC' \| 'DESC'` | Sort direction |
+| `created_at` | `string` | Start date (ISO) |
+| `created_to` | `string` | End date (ISO) |
+| `channel` | `string` | Filter by sales channel |
+| `courier` | `string` | Filter by courier name |
+| `status` | `string` | Filter by order status |
+| `query` | `string` | Free-text search |
+
+```js
+const orders = await janus.orders.getAll({
+  clientId, page: 1, pageSize: 25, order_direction: 'DESC',
+  created_at: '2025-01-01', created_to: '2025-12-31', query: 'ORD-123',
+});
+```
+
+### ReturnsSummaryFilters (janus.reports.returnsSummary)
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `clientId` | `number` | Client ID |
+| `createdFrom` | `string` | Start date (ISO) |
+| `createdTo` | `string` | End date (ISO) |
+| `approvedFrom` | `string` | Approval start date |
+| `approvedTo` | `string` | Approval end date |
+| `courierServiceId` | `number` | Filter by courier service |
+| `approved` | `boolean` | Only approved returns |
+| `page` | `number` | Page number |
+| `pageSize` | `number` | Results per page |
+| `csv` | `boolean` | Set true for CSV export (use `returnsSummaryCsv` instead) |
+
+```js
+const summary = await janus.reports.returnsSummary({
+  clientId, createdFrom: '2025-01-01', createdTo: '2025-12-31',
+});
+```
+
+### Resource-specific extra filters
+
+| Resource | 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 role |
+| `janus.users.getAll` | `filterType` | `string` | Filter by user type |
+| `janus.users.getAll` | `filterClientId` | `number` | Filter by assigned client |
+
+## All Resources
+
+| Resource | Access | Description |
+|----------|--------|-------------|
+| `janus.clients` | Auth | Client CRUD, courier services, return reasons, integrations, files |
+| `janus.returns` | Auth | Returns CRUD, items, comments, statuses, reasons, categories, sources |
+| `janus.orders` | Auth | Order queries, stats, returns, filter options, CRUD |
+| `janus.reports` | Auth | Returns summary/reasons/overview/stats + CSV exports |
+| `janus.products` | Auth | Product CRUD (preferred over legacy.queryProducts) |
+| `janus.productCategories` | Auth | Product category CRUD |
+| `janus.stocks` | Auth | Stock record CRUD |
+| `janus.stockTransactions` | Auth | Stock movement CRUD |
+| `janus.stockAllocations` | Auth | Stock allocation CRUD (no delete) |
+| `janus.locations` | Auth | Warehouse location CRUD |
+| `janus.audits` | Auth | Audit trail (read-only) |
+| `janus.asns` | Auth | ASNs with nested lines and receipts |
+| `janus.dispatches` | Auth | Dispatch CRUD |
+| `janus.consignments` | Auth | Consignment tracking |
+| `janus.invoices` | Auth | Invoices with nested line items |
+| `janus.users` | Auth | User CRUD, password management |
+| `janus.couriers` | Auth | Courier and service management |
+| `janus.integrations` | Auth | Integration management |
+| `janus.logs` | Auth | Activity and issue logging |
+| `janus.tasks` | Auth | Task history |
+| `janus.legacy` | Auth | Legacy couriers, post services, products (deprecated) |
+| `janus.helpers` | Public | Client settings, notifications |
+| `janus.customer` | Public | Customer tracking and login |
+
+## Return Entity Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Unique ID |
+| `return_reference` | `string` | Return reference number |
+| `wms_order_ref` | `string` | Original order reference |
+| `customername` | `string` | Full customer name |
+| `forename` | `string` | First name |
+| `surname` | `string` | Last name |
+| `email` | `string` | Customer email |
+| `approval_status` | `string` | "pending", "approved", or "rejected" |
+| `tracking_number` | `string` | Courier tracking number |
+| `latestStatus` | `object` | `{ name: string }` — current status |
+| `return_items` | `array` | Line items (when include_associations set) |
+| `created_ts` | `string` | ISO timestamp |
+| `updated_ts` | `string` | ISO timestamp |
+
+## Order Entity Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Order ID |
+| `reference` | `string` | Order reference number |
+| `channel` | `string` | Sales channel ("shopify", "amazon", etc.) |
+| `transaction_type` | `string` | "b2c", "b2b", "internal_transfer", "damage", "expiry" |
+| `orderDate` | `string` | ISO date when order was placed |
+| `orderStatus` | `number` | Numeric status code |
+| `notes` | `string` | Order notes |
+| `hold` | `number` | 0 = not on hold, 1 = on hold |
+| `draft` | `number` | 0 = confirmed, 1 = draft |
+| `created` | `string` | ISO date when created |
+| `modified` | `string` | ISO date when last modified |
+| `orderItems` | `array` | Order line items |
+| `dispatches` | `array` | Dispatch records |
+
+## Product Entity Fields (from /products endpoint)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `product_id` | `number` | Product ID |
+| `client_id` | `number` | Client ID |
+| `sku_code` | `string` | Product SKU |
+| `product_name` | `string` | Product name |
+| `description` | `string` | Product description |
+| `barcode` | `string` | Barcode (EAN/UPC) |
+| `price` | `number` | Unit price |
+| `currency` | `string` | Currency code ("GBP", "USD") |
+| `weight_grams` | `number` | Weight in grams |
+| `product_status` | `string` | "active", "discontinued", "inactive", "archived" |
+| `product_type` | `string` | "sellable_unit", "packaging", "component", "consumables" |
+| `stock` | `number` | Current stock level |
+| `image_url` | `string` | Product image URL |
+| `low_stock_threshold` | `number` | Low stock alert threshold |
+| `created_date` | `string` | ISO date |
+| `updated_date` | `string` | ISO date |
+
+## Stock Entity Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Stock record ID |
+| `clientId` | `number` | Client ID |
+| `sku_code` | `string` | Product SKU |
+| `location` | `string` | Storage location |
+| `quantity` | `number` | Current quantity |
+| `batch_number` | `string` | Batch/lot number |
+| `serial_number` | `string` | Serial number |
+| `best_before_date` | `string` | ISO date |
+| `stock_status` | `string` | "available", "quarantined", "expired", "damaged", "reserved" |
+| `fulfilment_location_name` | `string` | Warehouse name |
+| `notes` | `string` | Notes |
+
+## Invoice Entity Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Invoice ID |
+| `clientId` | `number` | Client ID |
+| `invoice_date` | `string` | ISO date |
+| `xero_reference` | `string` | Xero accounting reference |
+| `total` | `number` | Total amount |
+| `emailed` | `number` | 0 = not emailed, 1 = emailed |
+| `paid` | `number` | 0 = unpaid, 1 = paid |
+| `invoiceLines` | `array` | Line items |
+
+## ReturnsStatsResponse Fields
+
+```js
+const stats = await janus.reports.returnsStats(clientId);
+// stats = {
+//   total: 150,
+//   awaiting_processing: 12,
+//   in_progress: 25,
+//   completed: 100,
+//   awaiting_approval: 5,
+//   approved: 90,
+//   rejected: 8,
+//   by_status: { "Processing": 25, "Complete": 100, ... },
+//   by_reason: { "Faulty": 30, "Wrong item": 20, ... }
+// }
+```
+
+## OrdersStatsResponse Fields
+
+```js
+const stats = await janus.orders.getStats({ clientId, dashboard: true });
+// Returns a flat object with numeric counts — keys vary by data.
+// Use Object.entries(stats) to iterate. Do NOT hardcode field names.
+// Example: { total_orders: 150, dispatched: 120, processing: 15, ... }
+```
+
+## API Behaviour Notes
+
+### Error response format
+All errors follow this shape:
+```json
+{ "statusCode": 400, "message": "Error description" }
+```
+Common codes: 400 (bad request/validation), 401 (unauthorized), 404 (not found).
+
+### Date formats
+- **Query params:** ISO 8601 (`'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`
+
+### Pagination defaults
+- Default `pageSize`: 50 (v2 endpoints), varies for legacy
+- Default `pageNumber`: 1 (1-based indexing)
+- Default sort: DESC (newest first)
+
+### Search behaviour (`query` param)
+Free-text search is case-insensitive LIKE matching across key text columns:
+- Products: searches `sku`, `name`, `description`
+- Returns: searches order references, tracking numbers
+- Clients: searches client names
+
+### Returns default behaviour
+- Archived returns (status 10) are **excluded by default** — pass `include_archived: true` to include them
+- Returns with `return_type: 0` are regular returns, `return_type: 1` are exchanges
+- `include_associations: 'return_items'` eagerly loads line items; `'return_items,return_comments'` loads both
+
+### Stats responses
+`getStats` endpoints return flat objects with numeric values. The keys vary based on the client's data. **Always use `Object.entries(stats)` to iterate — never hardcode expected keys.**
+
+## Common Patterns
+
+### Paginated list query
+```js
+const { data, meta } = await janus.products.getAll({
+  clientId,
+  pageSize: 25,
+  pageNumber: 1,
+  orderDirection: 'DESC',
+  query: searchText,
+});
+// meta = { total_items, total_pages, current_page, page_size }
+```
+
+### CSV export
+```js
+const csv = await janus.reports.returnsSummaryCsv({ clientId, createdFrom, createdTo });
+const blob = new Blob([csv], { type: 'text/csv' });
+const url = URL.createObjectURL(blob);
+const a = document.createElement('a');
+a.href = url;
+a.download = 'export.csv';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+### Login page
+```jsx
+import { LoginForm } from '@pelygo/auth/react';
+
+<LoginForm
+  onSuccess={() => setTimeout(() => { window.location.href = '/clients'; }, 100)}
+  onError={(error) => console.log('Login error:', error)}
+/>
+```
+
+### Client selection
+```jsx
+import { SelectClientForm } from '@pelygo/auth/react';
+
+<SelectClientForm
+  onSelect={() => setTimeout(() => { window.location.href = '/dashboard'; }, 100)}
+/>
+```
+
+### Route guard (must check isLoading)
+```jsx
+const { isAuthenticated, isLoading } = useAuth();
+const { requiresClientSelection, hasSelectedClient } = useClient();
+
+if (isLoading) return <LoadingSpinner />;
+if (!isAuthenticated) return <Navigate to="/SignIn" replace />;
+if (requiresClientSelection && !hasSelectedClient) return <Navigate to="/clients" replace />;
+```
+
+### Logout
+```jsx
+onClick={() => {
+  logout();
+  setTimeout(() => { window.location.href = '/SignIn'; }, 100);
+}}
+```

package/dist/index.d.ts

@@ -2461,9 +2461,24 @@ export declare interface OrdersQueryFilters extends BaseFilters {
  * Orders resource interface
  */
 export declare interface OrdersResource {
-    /** Get all orders with optional query filters (client, date range, status, etc.) */
+    /**
+     * Get all orders with optional query filters (client, date range, status, etc.)
+     *
+     * @example
+     * const orders = await janus.orders.getAll({ clientId, pageSize: 25 });
+     * // Each order has: id, reference, channel, transaction_type, orderDate,
+     * // orderStatus, notes, hold, draft, created, modified,
+     * // orderItems (array), dispatches (array)
+     */
     getAll(filters?: OrdersQueryFilters): Promise<unknown[]>;
-    /** Get aggregated order statistics (counts, totals) with optional filters */
+    /**
+     * Get aggregated order statistics (counts, totals) with optional filters
+     *
+     * @example
+     * const stats = await janus.orders.getStats({ clientId, dashboard: true });
+     * // Returns a flat object with numeric counts — keys vary by data.
+     * // Use Object.entries(stats) to iterate. Do NOT hardcode field names.
+     */
     getStats(filters?: OrdersStatsFilters): Promise<OrdersStatsResponse>;
     /** Get orders that have associated returns, with optional return-specific filters */
     getReturns(filters?: OrderReturnsFilters): Promise<unknown[]>;
@@ -2606,7 +2621,16 @@ export declare interface ProductCategory extends BaseEntity_2 {
  * Products resource interface
  */
 export declare interface ProductsResource {
-    /** Get all products with optional filters */
+    /**
+     * Get all products with optional filters
+     *
+     * @example
+     * const { data, meta } = await janus.products.getAll({ clientId, pageSize: 25 });
+     * // Each product has: product_id, client_id, sku_code, product_name,
+     * // description, barcode, price, currency, product_status, stock,
+     * // weight_grams, image_url, product_category_id, created_date, updated_date
+     * // meta has: total_items, total_pages, current_page, page_size
+     */
     getAll(filters: ClientScopedPaginatedQueryFilters): Promise<PaginatedListResponse<FormattedProduct>>;
     /** Get a product by ID */
     getById(id: number): Promise<FormattedProduct>;
@@ -2634,7 +2658,14 @@ export declare interface ReportsResource {
     returnsOverview(filters?: ReturnsOverviewFilters): Promise<unknown>;
     /** Get returns overview as CSV */
     returnsOverviewCsv(filters?: ReturnsOverviewFilters): Promise<string>;
-    /** Get returns statistics for a client */
+    /**
+     * Get returns statistics for a client
+     *
+     * @example
+     * const stats = await janus.reports.returnsStats(clientId);
+     * // Returns: { total, awaiting_processing, in_progress, completed,
+     * //   awaiting_approval, approved, rejected, by_status, by_reason }
+     */
     returnsStats(clientId: number): Promise<ReturnsStatsResponse>;
 }
 
@@ -2873,7 +2904,16 @@ export declare interface ReturnsReasonsFilters extends BaseFilters {
  * Returns resource interface
  */
 export declare interface ReturnsResource {
-    /** Query returns with filters */
+    /**
+     * Query returns with filters
+     *
+     * @example
+     * const returns = await janus.returns.query({ clientId, page: 1, pageSize: 25 });
+     * // Each return has: id, return_reference, wms_order_ref, customername,
+     * // forename, surname, email, approval_status, tracking_number,
+     * // created_ts, updated_ts, latestStatus (object with .name),
+     * // return_items (array, when include_associations set)
+     */
     query(filters?: ReturnsQueryFilters): Promise<Return[]>;
     /** Query returns with HTTP query body */
     queryPost(query: HttpQueryRequest): Promise<Return[]>;
@@ -3175,7 +3215,15 @@ export declare interface StockAllocationsResource {
  * Stocks resource interface
  */
 export declare interface StocksResource {
-    /** Get all stock records with optional filters */
+    /**
+     * Get all stock records with optional filters
+     *
+     * @example
+     * const { data, meta } = await janus.stocks.getAll({ clientId, pageSize: 25 });
+     * // Each stock record has: id, clientId, sku_code, location, quantity,
+     * // batch_number, serial_number, best_before_date, stock_status,
+     * // fulfilment_location_id, fulfilment_location_name, notes
+     */
     getAll(filters: ClientScopedPaginatedQueryFilters): Promise<PaginatedListResponse<Stock>>;
     /** Get a stock record by ID */
     getById(id: number): Promise<Stock>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pelygo/janus",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript API client for JANUS endpoints with full type safety",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,7 +14,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "USAGE.md"
   ],
   "scripts": {
     "build": "vite build",