npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@pelygo/janus

v0.6.3

Published

TypeScript API client for JANUS endpoints with full type safety

Readme

@pelygo/janus

TypeScript API client for JANUS (VCOMSUITE warehouse management backend). Provides typed access to orders, returns, products, stock, invoices, ASNs, dispatches, and more.

Setup

Install

npm install @pelygo/janus @pelygo/auth

@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.

import { createJanusApi } from '@pelygo/janus';

const janus = createJanusApi({
  baseUrl: 'https://api.janus.pelygo.com',       // JANUS API server
  authUrl: 'https://auth.pelygo.com',             // Auth server (different host)
  onUnauthorized: () => {
    // IMPORTANT: use setTimeout in Base44/iframe environments
    setTimeout(() => window.location.href = '/login', 0);
  },
});

Dev environment:

const janus = createJanusApi({
  baseUrl: 'https://api.janus.dev.pelygo.com',
  authUrl: 'https://auth.dev.pelygo.com',
});

Read-only mode (default)

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.

// 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 });

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)

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.

Authenticate

await janus.auth.login('username', 'password');
const user = await janus.auth.getUser();
const isLoggedIn = janus.auth.isAuthenticated();
await janus.auth.logout();

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 | 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 | | 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 (from janus.orders.getAll / getById)

janus.orders is the general-purpose orders resource. It hits /legacy/orders and returns LegacyOrder entities with ISO dates.

| Field | Type | Format | Description | |-------|------|--------|-------------| | 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 |

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 for details.

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 |

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 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)

| 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.ordersMt.getStats — Microtrack only)

| 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:

const { data, meta } = await janus.products.getAll({
  clientId: 5,           // REQUIRED
  pageSize: 50,
  pageNumber: 1,
  orderColumn: 'sku_code',
  orderDirection: 'ASC',
  query: 'widget',       // free-text search
});

// meta = { total_items, total_pages, current_page, page_size }

Orders use ClientScopedPaginatedQueryFilters (same as v2 endpoints):

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:

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,
});

CSV Export

Reports have dedicated CSV methods:

const csvString = await janus.reports.returnsSummaryCsv({ clientId: 5 });
const reasonsCsv = await janus.reports.returnsReasonsCsv({ clientId: 5 });
const overviewCsv = await janus.reports.returnsOverviewCsv({ clientId: 5 });

Returns can also export as CSV via the query filter:

const csv = await janus.returns.query({ clientId: 5, csv: true });

CRUD on Sub-Resources

Invoices, ASNs, and returns have nested sub-resources:

// 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);

Paginated Response Shape

v2 endpoints return:

{
  data: T[],
  meta: {
    total_items: number,
    total_pages: number,
    current_page: number,
    page_size: number,
  }
}

Raw API Access

For endpoints not yet wrapped:

const result = await janus.auth.get('/some/endpoint?clientId=5');
const result = await janus.auth.post('/some/endpoint', { body: 'data' });

Important Rules

  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.
  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.

  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:

    onUnauthorized: () => {
      setTimeout(() => window.location.href = '/login', 0);
    },
  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.

  5. Use janus.products instead of janus.legacy.queryProducts. The products resource uses the newer v2 endpoint with proper pagination and typed responses.


API Behaviour Notes

Error responses

{ "statusCode": 400, "message": "Error description" }

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 (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

  • Default pageSize: 50 (v2 endpoints)
  • Default pageNumber: 1 (1-based indexing)
  • Default sort: DESC (newest first)
  • Max sensible page size: 1,000

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

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'

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.


Type Imports

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';

Development

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

License

See LICENSE file.