@pelygo/janus 0.2.0 → 0.4.0

package/USAGE.md

@@ -0,0 +1,393 @@
+# @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);
+  },
+  // allowWrites: true,  // uncomment to enable create/update/delete operations
+});
+```
+
+## Read-only mode (default)
+
+The client is **read-only by default**. All GET requests and query-style POSTs work. Create, update, and delete operations throw an error unless `allowWrites: true` is set.
+
+```js
+// Read-only (default) — safe for dashboards and analytics
+const janus = createJanusApi({ baseUrl: '...' });
+
+// Full access — required for apps that create/update/delete data
+const janus = createJanusApi({ baseUrl: '...', allowWrites: true });
+```
+
+**Always allowed** (even in read-only mode): `getAll`, `getById`, `query`, `queryPost`, `getStats`, `getFilterOptions`, `auth.login`, `auth.verify`, all report methods, all CSV exports.
+
+**Blocked in read-only mode**: `create`, `update`, `replace`, `delete`, `addItem`, `addComment`, `addStatus`, and all other write operations.
+
+## 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

@@ -1897,6 +1897,29 @@ export declare interface JanusApiOptions {
     onLoginSuccess?: (token: string) => void;
     /** Called on login failure */
     onLoginError?: (error: Error) => void;
+    /**
+     * Allow write operations (POST, PUT, PATCH, DELETE).
+     *
+     * By default the client is **read-only** — any attempt to create, update,
+     * or delete data will throw an error. Set this to `true` to enable write
+     * operations.
+     *
+     * Query-style POST endpoints (e.g. `/returns/query`, `/legacy/products/query`)
+     * and authentication endpoints (e.g. `/auth/login`) are always allowed
+     * regardless of this setting.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // Read-only (default) — getAll, query, getById work; create, update, delete throw
+     * const janus = createJanusApi({ baseUrl: '...' });
+     *
+     * // Full access — all operations allowed
+     * const janus = createJanusApi({ baseUrl: '...', allowWrites: true });
+     * ```
+     */
+    allowWrites?: boolean;
 }
 
 /**
@@ -2461,9 +2484,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 +2644,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 +2681,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 +2927,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 +3238,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>;