@pelygo/janus 0.6.0 → 0.6.2

package/README.md

@@ -83,7 +83,8 @@ await janus.auth.logout();
 |----------|----------|------|-------------|
 | 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 |
+| Orders | `janus.orders` | Yes | General-purpose orders (`/legacy/orders`): paginated list, getById, query. Returns `LegacyOrder` with ISO dates |
+| Orders (Microtrack) | `janus.ordersMt` | Yes | Microtrack orders (`/orders`): stats, returns, filter options, create/update. Returns formatted objects with DD/MM/YYYY dates |
 | 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 |
@@ -148,33 +149,26 @@ await janus.auth.logout();
 | `created_ts` | `string?` | ISO timestamp |
 | `updated_ts` | `string?` | ISO timestamp |
 
-### Order (formatted response from `getAll` / `getByRef`)
+### LegacyOrder (from `janus.orders.getAll` / `getById`)
 
-The orders API returns **formatted** objects — field names differ from the raw database entity. Use these exact names:
+`janus.orders` is the **general-purpose orders resource**. It hits `/legacy/orders` and returns `LegacyOrder` entities with ISO dates.
 
 | Field | Type | Format | Description |
 |-------|------|--------|-------------|
-| `orderId` | `number` | — | Order ID |
-| `orderRef` | `string` | — | Order reference number |
-| `dispatchId` | `number` | — | Dispatch ID |
-| `dispatchRef` | `string` | — | Dispatch reference |
-| `orderCreated` | `string` | `DD/MM/YYYY HH:mm` | Date order was received. **Not ISO** |
-| `releaseDate` | `string` | `DD/MM/YYYY HH:mm` | Scheduled release date |
-| `dispatchCompletedDate` | `string` | `DD/MM/YYYY HH:mm` | Date dispatch completed |
+| `id` | `number` | — | Order ID |
+| `reference` | `string` | — | Order reference number |
 | `channel` | `string` | — | Sales channel name |
-| `itemCount` | `number` | — | Number of line items |
-| `products` | `array` | — | Line items (when included) |
-| `address` | `object` | — | Shipping address: `{ fullName, company, addrLine1, addrLine2, city, postcode, country, destination, email, phoneNumber }` |
-
-**Date fields use `DD/MM/YYYY HH:mm` format** (e.g. `"25/03/2026 14:30"`), NOT ISO 8601. To parse:
-```js
-function parseOrderDate(dateStr) {
-  if (!dateStr) return null;
-  const [datePart, timePart] = dateStr.split(' ');
-  const [day, month, year] = datePart.split('/');
-  return new Date(`${year}-${month}-${day}T${timePart || '00:00'}`);
-}
-```
+| `transaction_type` | `string` | — | Transaction type |
+| `orderDate` | `string` | ISO 8601 | Date order was received |
+| `orderStatus` | `string` | — | Current order status |
+| `created` | `string` | ISO 8601 | Record creation timestamp |
+| `modified` | `string` | ISO 8601 | Record last modified timestamp |
+| `orderItems` | `array` | — | Order line items |
+| `dispatches` | `array` | — | Associated dispatches |
+
+**Date fields are ISO 8601** — no custom parsing required. Use `new Date(order.orderDate)` directly.
+
+> **Microtrack orders (`janus.ordersMt`):** If you are building a Microtrack integration, use `janus.ordersMt` instead. It hits `/orders` and returns formatted objects with `DD/MM/YYYY HH:mm` dates and different field names (`orderRef`, `dispatchRef`, `orderCreated`, etc.). See the [Orders Endpoint Guide](docs/AI-usage/endpoints/orders/README.md) for details.
 
 ### LegacyDispatch
 
@@ -422,24 +416,18 @@ Extends `BaseEntity`.
 | `csv` | `boolean` | No | Export as CSV instead of JSON |
 | `group_by` | `string` | No | Group results by field |
 
-### OrdersQueryFilters (janus.orders.getAll)
+### ClientScopedPaginatedQueryFilters (janus.orders.getAll)
+
+`janus.orders.getAll` now uses the same `ClientScopedPaginatedQueryFilters` as other v2 endpoints:
 
 | 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 |
+| `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 |
 
 ### ReturnsSummaryFilters (janus.reports.returnsSummary / returnsSummaryCsv)
 
@@ -464,7 +452,7 @@ Extends `BaseEntity`.
 | `createdFrom` | `string` | No | Start date (ISO) |
 | `createdTo` | `string` | No | End date (ISO) |
 
-### OrdersStatsFilters (janus.orders.getStats)
+### OrdersStatsFilters (janus.ordersMt.getStats — Microtrack only)
 
 | Param | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -506,7 +494,22 @@ const { data, meta } = await janus.products.getAll({
 // meta = { total_items, total_pages, current_page, page_size }
 ```
 
-**Legacy endpoints** (orders, returns) use their own filter shapes:
+**Orders** use `ClientScopedPaginatedQueryFilters` (same as v2 endpoints):
+
+```typescript
+const { data: orders, meta } = await janus.orders.getAll({
+  clientId: 5,
+  pageSize: 25,
+  pageNumber: 1,
+  orderColumn: 'created',
+  orderDirection: 'DESC',
+  query: 'ORD-123',
+});
+// orders = LegacyOrder[] with ISO dates
+// meta = { total_items, total_pages, current_page, page_size }
+```
+
+**Returns** use their own filter shape:
 
 ```typescript
 const returns = await janus.returns.query({
@@ -517,15 +520,6 @@ const returns = await janus.returns.query({
   pageSize: 100,
   csv: false,
 });
-
-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',
-});
 ```
 
 ### CSV Export
@@ -628,7 +622,8 @@ Common codes: 400 (bad request/validation), 401 (unauthorized), 404 (not found).
 ### Date formats
 - **Query params:** ISO 8601 format (`'2025-01-01'` or `'2025-01-01 12:00:00'`)
 - **v2 response fields** (returns, stocks, etc.): ISO 8601 timestamps (`created_ts`, `updated_ts`)
-- **Orders response fields**: `DD/MM/YYYY HH:mm` format (e.g. `"25/03/2026 14:30"`) — **NOT ISO**. Fields: `orderCreated`, `releaseDate`, `dispatchCompletedDate`. Must be parsed before use.
+- **Orders response fields** (`janus.orders`): ISO 8601 timestamps (`orderDate`, `created`, `modified`) — no parsing needed
+- **Microtrack orders response fields** (`janus.ordersMt`): `DD/MM/YYYY HH:mm` format — **NOT ISO**. Fields: `orderCreated`, `releaseDate`, `dispatchCompletedDate`. Must be parsed before use.
 - **CSV exports:** formatted as `DD-MM-YYYY HH:mm`
 
 ### Pagination defaults

package/USAGE.md

@@ -100,27 +100,25 @@ const returns = await janus.returns.query({
 });
 ```
 
-### OrdersQueryFilters (janus.orders.getAll)
+### ClientScopedPaginatedQueryFilters (janus.orders.getAll)
+
+`janus.orders.getAll` now uses `ClientScopedPaginatedQueryFilters` (same as other v2 endpoints):
 
 | 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 |
+| `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 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',
+const { data: orders, meta } = await janus.orders.getAll({
+  clientId, pageSize: 25, pageNumber: 1, orderDirection: 'DESC', query: 'ORD-123',
 });
+// orders = LegacyOrder[] with ISO dates
+// meta = { total_items, total_pages, current_page, page_size }
 ```
 
 ### ReturnsSummaryFilters (janus.reports.returnsSummary)
@@ -162,7 +160,8 @@ const summary = await janus.reports.returnsSummary({
 |----------|--------|-------------|
 | `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.orders` | Auth | General-purpose orders (`/legacy/orders`): paginated list, getById, query. Returns `LegacyOrder` with ISO dates |
+| `janus.ordersMt` | Auth | Microtrack orders (`/orders`): stats, returns, filter options, create/update (Microtrack only) |
 | `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 |
@@ -202,33 +201,26 @@ const summary = await janus.reports.returnsSummary({
 | `created_ts` | `string` | ISO timestamp |
 | `updated_ts` | `string` | ISO timestamp |
 
-## Order Fields (formatted response from getAll / getByRef)
+## LegacyOrder Fields (from `janus.orders.getAll` / `getById`)
 
-The orders API returns **formatted** objects — use these exact field names:
+`janus.orders` is the **general-purpose orders resource**. It hits `/legacy/orders` and returns `LegacyOrder` entities with ISO dates:
 
 | Field | Type | Format | Description |
 |-------|------|--------|-------------|
-| `orderId` | `number` | — | Order ID |
-| `orderRef` | `string` | — | Order reference number |
-| `dispatchId` | `number` | — | Dispatch ID |
-| `dispatchRef` | `string` | — | Dispatch reference |
-| `orderCreated` | `string` | `DD/MM/YYYY HH:mm` | Date received (**not ISO**) |
-| `releaseDate` | `string` | `DD/MM/YYYY HH:mm` | Release date |
-| `dispatchCompletedDate` | `string` | `DD/MM/YYYY HH:mm` | Dispatch completed |
-| `channel` | `string` | — | Sales channel |
-| `itemCount` | `number` | — | Number of line items |
-| `products` | `array` | — | Line items (when included) |
-| `address` | `object` | — | `{ fullName, company, addrLine1, city, postcode, country, email }` |
-
-**Date parsing:** Dates are `DD/MM/YYYY HH:mm`, not ISO. Parse with:
-```js
-function parseOrderDate(dateStr) {
-  if (!dateStr) return null;
-  const [datePart, timePart] = dateStr.split(' ');
-  const [day, month, year] = datePart.split('/');
-  return new Date(`${year}-${month}-${day}T${timePart || '00:00'}`);
-}
-```
+| `id` | `number` | — | Order ID |
+| `reference` | `string` | — | Order reference number |
+| `channel` | `string` | — | Sales channel name |
+| `transaction_type` | `string` | — | Transaction type |
+| `orderDate` | `string` | ISO 8601 | Date order was received |
+| `orderStatus` | `string` | — | Current order status |
+| `created` | `string` | ISO 8601 | Record creation timestamp |
+| `modified` | `string` | ISO 8601 | Record last modified timestamp |
+| `orderItems` | `array` | — | Order line items |
+| `dispatches` | `array` | — | Associated dispatches |
+
+**Dates are ISO 8601** — no custom parsing needed. Use `new Date(order.orderDate)` directly.
+
+> **Microtrack orders (`janus.ordersMt`):** For Microtrack integrations only. Hits `/orders`, returns formatted objects with `DD/MM/YYYY HH:mm` dates and different field names (`orderRef`, `dispatchRef`, `orderCreated`, etc.). Methods: `getAll`, `getStats`, `getReturns`, `getByRef`, `getReturnFilterOptions`, `getFilterTypes`, `create`, `updateOrder`.
 
 ## Product Entity Fields (from /products endpoint)
 
@@ -297,10 +289,11 @@ const stats = await janus.reports.returnsStats(clientId);
 // }
 ```
 
-## OrdersStatsResponse Fields
+## OrdersStatsResponse Fields (Microtrack only)
 
 ```js
-const stats = await janus.orders.getStats({ clientId, dashboard: true });
+// Microtrack only — use janus.ordersMt for stats
+const stats = await janus.ordersMt.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, ... }
@@ -318,7 +311,8 @@ 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'`)
 - **v2 response fields** (returns, stocks, etc.): ISO 8601 timestamps (`created_ts`, `updated_ts`)
-- **Orders response fields**: `DD/MM/YYYY HH:mm` format — **NOT ISO**. Fields: `orderCreated`, `releaseDate`, `dispatchCompletedDate`. Parse with date splitter (see Order Fields section below).
+- **Orders response fields** (`janus.orders`): ISO 8601 timestamps (`orderDate`, `created`, `modified`) — no parsing needed
+- **Microtrack orders response fields** (`janus.ordersMt`): `DD/MM/YYYY HH:mm` format — **NOT ISO**. Fields: `orderCreated`, `releaseDate`, `dispatchCompletedDate`. Must be parsed.
 - **CSV exports:** formatted as `DD-MM-YYYY HH:mm`
 
 ### Pagination defaults

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pelygo/janus",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "TypeScript API client for JANUS endpoints with full type safety",
   "type": "module",
   "main": "./dist/index.js",