@pelygo/janus 0.3.0 → 0.5.0

package/README.md

@@ -38,6 +38,34 @@ const janus = createJanusApi({
 });
 ```
 
+### 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.
+
+```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 });
+```
+
+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
 
 ```typescript

package/USAGE.md

@@ -19,9 +19,26 @@ export const janus = createJanusApi({
   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()`:

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

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createAuthApi as L } from "@pelygo/auth/core";
-function T(t) {
+function P(t) {
   return {
     async getAll() {
       return t.get("/clients");
@@ -95,29 +95,31 @@ function u(t, e) {
   const n = t.includes("?") ? "&" : "?";
   return `${t}${n}${r}`;
 }
-function P(t) {
+function b(t) {
   return t.replace(/[A-Z]/g, (e) => `_${e.toLowerCase()}`);
 }
-function F(t) {
+function D(t) {
   const e = {};
   for (const [r, n] of Object.entries(t))
-    e[P(r)] = n;
+    e[b(r)] = n;
   return e;
 }
 function l(t, e) {
-  return e ? u(t, F(e)) : t;
+  if (!e) return t;
+  const r = { pageNumber: 1, ...e };
+  return u(t, D(r));
 }
 function o(t, e) {
   if (e.clientId == null)
     throw new Error("clientId is required for this endpoint");
   return l(t, e);
 }
-function b(t) {
+function F(t) {
   return {
     // ── Core returns ─────────────────────────────────────────────
     async query(e) {
-      const r = u("/returns/", e);
-      return t.get(r);
+      const r = e && { page: 1, ...e }, n = u("/returns/", r);
+      return t.get(n);
     },
     async queryPost(e) {
       return t.post("/returns/query", e);
@@ -264,30 +266,30 @@ function b(t) {
     }
   };
 }
-function x(t) {
+function N(t) {
   return {
     async returnsSummary(e) {
-      const r = u("/reports/returns/summary/", e);
-      return t.get(r);
+      const r = e && { page: 1, ...e }, n = u("/reports/returns/summary/", r);
+      return t.get(n);
     },
     async returnsSummaryCsv(e) {
-      const r = { ...e, csv: !0, pageSize: 1e5 }, n = u("/reports/returns/summary/", r);
+      const r = { ...e, csv: !0, pageSize: 1e5, page: 1 }, n = u("/reports/returns/summary/", r);
       return t.get(n);
     },
     async returnsReasons(e) {
-      const r = u("/reports/returns/reasons/", e);
-      return t.get(r);
+      const r = e && { page: 1, ...e }, n = u("/reports/returns/reasons/", r);
+      return t.get(n);
     },
     async returnsReasonsCsv(e) {
-      const r = { ...e, csv: !0, pageSize: 1e5 }, n = u("/reports/returns/reasons/", r);
+      const r = { ...e, csv: !0, pageSize: 1e5, page: 1 }, n = u("/reports/returns/reasons/", r);
       return t.get(n);
     },
     async returnsOverview(e) {
-      const r = u("/reports/returns/overview/", e);
-      return t.get(r);
+      const r = e && { page: 1, ...e }, n = u("/reports/returns/overview/", r);
+      return t.get(n);
     },
     async returnsOverviewCsv(e) {
-      const r = { ...e, csv: !0, pageSize: 1e5 }, n = u("/reports/returns/overview/", r);
+      const r = { ...e, csv: !0, pageSize: 1e5, page: 1 }, n = u("/reports/returns/overview/", r);
       return t.get(n);
     },
     async returnsStats(e) {
@@ -295,7 +297,7 @@ function x(t) {
     }
   };
 }
-function N(t) {
+function x(t) {
   const { baseUrl: e } = t;
   async function r(n, s) {
     const c = await fetch(n, {
@@ -333,7 +335,7 @@ function N(t) {
     }
   };
 }
-function z(t) {
+function q(t) {
   return {
     async getAll() {
       return t.get("/couriers");
@@ -361,19 +363,19 @@ function z(t) {
     }
   };
 }
-function j(t) {
+function J(t) {
   return {
     async getAll(e) {
-      const r = u("/orders", e);
-      return t.get(r);
+      const r = e && { pageNumber: 1, ...e }, n = u("/orders", r);
+      return t.get(n);
     },
     async getStats(e) {
       const r = u("/orders/stats", e);
       return t.get(r);
     },
     async getReturns(e) {
-      const r = u("/orders/returns", e);
-      return t.get(r);
+      const r = e && { pageNumber: 1, ...e }, n = u("/orders/returns", r);
+      return t.get(n);
     },
     async getByRef(e, r) {
       const n = u(`/orders/${encodeURIComponent(e)}`, r != null ? { clientId: r } : void 0);
@@ -394,7 +396,7 @@ function j(t) {
     }
   };
 }
-function q(t) {
+function j(t) {
   return {
     async getAll() {
       return t.get("/integrations");
@@ -419,7 +421,7 @@ function q(t) {
     }
   };
 }
-function J(t) {
+function z(t) {
   return {
     async getAll(e) {
       const r = l("/users", e);
@@ -448,7 +450,7 @@ function J(t) {
     }
   };
 }
-function D(t) {
+function W(t) {
   return {
     async createActivity(e) {
       return t.post("/logs/activity", e);
@@ -516,7 +518,7 @@ function V(t) {
     }
   };
 }
-function W(t) {
+function G(t) {
   return {
     async getCouriers() {
       return t.get("/legacy-couriers");
@@ -536,7 +538,7 @@ function W(t) {
     }
   };
 }
-function G(t) {
+function K(t) {
   return {
     async getAll(e) {
       const r = o("/products", e);
@@ -556,7 +558,7 @@ function G(t) {
     }
   };
 }
-function K(t) {
+function M(t) {
   return {
     async getAll(e) {
       const r = o("/product-categories", e);
@@ -576,7 +578,7 @@ function K(t) {
     }
   };
 }
-function M(t) {
+function Q(t) {
   return {
     async getAll(e) {
       const r = o("/stocks", e);
@@ -596,7 +598,7 @@ function M(t) {
     }
   };
 }
-function Q(t) {
+function Z(t) {
   return {
     async getAll(e) {
       const r = o("/transactions", e);
@@ -616,7 +618,7 @@ function Q(t) {
     }
   };
 }
-function Z(t) {
+function X(t) {
   return {
     async getAll(e) {
       const r = o("/allocations", e);
@@ -633,7 +635,7 @@ function Z(t) {
     }
   };
 }
-function X(t) {
+function Y(t) {
   return {
     async getAll(e) {
       const r = o("/locations", e);
@@ -653,7 +655,7 @@ function X(t) {
     }
   };
 }
-function Y(t) {
+function ee(t) {
   return {
     async getAll(e) {
       const r = o("/audits", e);
@@ -664,7 +666,7 @@ function Y(t) {
     }
   };
 }
-function ee(t) {
+function te(t) {
   return {
     // ── ASN CRUD ─────────────────────────────────
     async getAll(e) {
@@ -731,7 +733,7 @@ function ee(t) {
     }
   };
 }
-function te(t) {
+function re(t) {
   return {
     async getAll(e) {
       const r = o("/dispatches", e);
@@ -751,7 +753,7 @@ function te(t) {
     }
   };
 }
-function re(t) {
+function ne(t) {
   return {
     async getByDispatchId(e) {
       return t.get(`/consignments/${e}`);
@@ -767,7 +769,7 @@ function re(t) {
     }
   };
 }
-function ne(t) {
+function se(t) {
   return {
     // ── Invoice CRUD ────────────────────────────────────────────
     async getAll(e) {
@@ -813,39 +815,63 @@ function ne(t) {
     }
   };
 }
-const se = "https://api.janus.pelygo.com";
-function oe(t = {}) {
-  const e = t.baseUrl || se, r = {
+const ce = "https://api.janus.pelygo.com", ue = [
+  "/auth/",
+  "/returns/query",
+  "/legacy/products/query",
+  "/legacy/"
+];
+function oe(t) {
+  return ue.some((e) => t.includes(e));
+}
+function ae(t) {
+  const e = (r, n) => {
+    throw new Error(
+      `@pelygo/janus: Write operation blocked (${r.toUpperCase()}${n ? " " + n : ""}). The client is in read-only mode. To enable writes, set allowWrites: true in createJanusApi options:
+
+  createJanusApi({ baseUrl: '...', allowWrites: true })`
+    );
+  };
+  return {
+    ...t,
+    post: (r, n, s) => oe(r) ? t.post(r, n, s) : e("POST", r),
+    put: (r, n, s) => e("PUT", r),
+    patch: (r, n, s) => e("PATCH", r),
+    delete: (r, n) => e("DELETE", r)
+  };
+}
+function le(t = {}) {
+  const e = t.baseUrl || ce, r = {
     baseUrl: e,
     authUrl: t.authUrl,
     onUnauthorized: t.onUnauthorized,
     onLoginSuccess: t.onLoginSuccess,
     onLoginError: t.onLoginError
-  }, n = L(r), s = T(n), c = b(n), a = x(n), y = N({ baseUrl: e }), g = z(n), d = j(n), $ = q(n), m = J(n), f = D(n), v = H(n), h = V({ baseUrl: e }), R = W(n), p = G(n), S = K(n), I = M(n), C = Q(n), A = Z(n), B = X(n), U = Y(n), w = ee(n), k = te(n), _ = re(n), E = ne(n);
+  }, n = L(r), s = t.allowWrites ? n : ae(n), c = P(s), a = F(s), y = N(s), g = x({ baseUrl: e }), d = q(s), $ = J(s), m = j(s), p = z(s), h = W(s), v = H(s), f = V({ baseUrl: e }), R = G(s), S = K(s), I = M(s), C = Q(s), w = Z(s), A = X(s), U = Y(s), B = ee(s), k = te(s), _ = re(s), E = ne(s), T = se(s);
   return {
-    clients: s,
-    returns: c,
-    reports: a,
-    helpers: y,
-    couriers: g,
-    orders: d,
-    integrations: $,
-    users: m,
-    logs: f,
+    clients: c,
+    returns: a,
+    reports: y,
+    helpers: g,
+    couriers: d,
+    orders: $,
+    integrations: m,
+    users: p,
+    logs: h,
     tasks: v,
-    customer: h,
+    customer: f,
     legacy: R,
-    products: p,
-    productCategories: S,
-    stocks: I,
-    stockTransactions: C,
+    products: S,
+    productCategories: I,
+    stocks: C,
+    stockTransactions: w,
     stockAllocations: A,
-    locations: B,
-    audits: U,
-    asns: w,
-    dispatches: k,
-    consignments: _,
-    invoices: E,
+    locations: U,
+    audits: B,
+    asns: k,
+    dispatches: _,
+    consignments: E,
+    invoices: T,
     auth: n
   };
 }
@@ -856,44 +882,44 @@ class i extends Error {
     s.captureStackTrace && s.captureStackTrace(this, i);
   }
 }
-class ce extends i {
+class ie extends i {
   constructor(e = "Unauthorized", r) {
     super(e, 401, r), this.name = "UnauthorizedError";
   }
 }
-class ae extends i {
+class ge extends i {
   constructor(e = "Forbidden", r) {
     super(e, 403, r), this.name = "ForbiddenError";
   }
 }
-class ie extends i {
+class de extends i {
   constructor(e = "Not Found", r) {
     super(e, 404, r), this.name = "NotFoundError";
   }
 }
-class ye extends i {
+class $e extends i {
   constructor(e = "Validation Error", r, n) {
     super(e, 400, n), this.name = "ValidationError", this.errors = r;
   }
 }
-function le(t) {
+function me(t) {
   return t instanceof i;
 }
-function ge(t) {
-  return t instanceof ce;
+function pe(t) {
+  return t instanceof ie;
 }
 export {
-  se as DEFAULT_JANUS_URL,
-  ae as ForbiddenError,
+  ce as DEFAULT_JANUS_URL,
+  ge as ForbiddenError,
   i as JanusApiError,
-  ie as NotFoundError,
-  ce as UnauthorizedError,
-  ye as ValidationError,
+  de as NotFoundError,
+  ie as UnauthorizedError,
+  $e as ValidationError,
   o as buildClientScopedPaginatedUrl,
   l as buildPaginatedUrl,
   O as buildQueryString,
   u as buildUrl,
-  oe as createJanusApi,
-  le as isJanusApiError,
-  ge as isUnauthorizedError
+  le as createJanusApi,
+  me as isJanusApiError,
+  pe as isUnauthorizedError
 };

package/package.json

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