@haven-team/helix-sdk 1.0.12 → 1.0.13

package/helix-sdk.js

@@ -37,6 +37,16 @@
  *   localhost unless `force: true`. Failures never break the app; the SDK
  *   logs a warning and `enableLogRocket()` resolves to null. See
  *   docs/logrocket.md for the full manual.
+ *
+ * Store scoping (which stores the user may access):
+ *   const scope = await helix.getStoreScope();
+ *   // { unrestricted: false, store_ids: [3, 7], source: 'grant' }
+ *   if (await helix.canAccessStore(storeId)) { ... }
+ *
+ *   Resolved from GET /api/v1/auth/authenticate (cached). Admins / district
+ *   managers come back `unrestricted: true`; everyone else is limited to
+ *   `store_ids`. Fails CLOSED on error. This shapes the UI; the API still
+ *   enforces scope server-side. See docs/store-scoping.md.
  */
 (function (root, factory) {
   if (typeof module !== 'undefined' && module.exports) {
@@ -52,6 +62,19 @@
   const DEFAULT_LOGROCKET_APP_ID = 'lto7os/helix-frontend';
   const LOGROCKET_CDN = 'https://cdn.lr-ingest.com/LogRocket.min.js';
 
+  // Coerce whatever the identity endpoint returns into a well-formed store
+  // scope. Missing/garbage input fails CLOSED (no access) rather than open.
+  function normalizeStoreScope(s) {
+    if (!s || typeof s !== 'object') return { unrestricted: false, store_ids: [], source: 'error' };
+    return {
+      unrestricted: s.unrestricted === true,
+      store_ids: Array.isArray(s.store_ids)
+        ? s.store_ids.filter((v) => v != null && v !== '' && Number.isFinite(Number(v))).map(Number)
+        : [],
+      source: typeof s.source === 'string' ? s.source : 'unknown'
+    };
+  }
+
   class HelixSDK {
     constructor(options = {}) {
       this._ready = false;
@@ -66,6 +89,8 @@
       this._logrocket = null;
       this._lrShouldRecord = true;
       this._lrPromise = null;
+      this._storeScope = null;
+      this._storeScopePromise = null;
 
       if (options.logrocket) {
         this.enableLogRocket(options.logrocket === true ? {} : options.logrocket);
@@ -268,6 +293,43 @@
       return this._context?.token || null;
     }
 
+    /**
+     * Resolve the acting user's store scope — which stores they may access.
+     * Fetches GET /api/v1/auth/authenticate once and caches the result.
+     *
+     * Returns { unrestricted: boolean, store_ids: number[], source: string }.
+     * On any failure it returns a CLOSED default ({ unrestricted: false,
+     * store_ids: [], source: 'error' }) — fail closed, never accidentally
+     * grant access. Apps should still treat the server as the source of truth;
+     * this is for shaping the UI, not for security.
+     */
+    async getStoreScope() {
+      if (this._storeScope) return this._storeScope;
+      if (this._storeScopePromise) return this._storeScopePromise;
+      this._storeScopePromise = this.apiGet('/api/v1/auth/authenticate')
+        .then((res) => {
+          const s = res && res.user && res.user.store_scope;
+          this._storeScope = normalizeStoreScope(s);
+          return this._storeScope;
+        })
+        .catch((e) => {
+          console.warn('HelixSDK: getStoreScope failed, defaulting to no access', e);
+          this._storeScope = { unrestricted: false, store_ids: [], source: 'error' };
+          return this._storeScope;
+        });
+      return this._storeScopePromise;
+    }
+
+    /**
+     * True if the acting user may access the given store id. Resolves the
+     * store scope (cached) and checks it. Unrestricted users pass for any id.
+     */
+    async canAccessStore(storeId) {
+      const scope = await this.getStoreScope();
+      if (scope.unrestricted) return true;
+      return scope.store_ids.indexOf(Number(storeId)) !== -1;
+    }
+
     /** Make an authenticated GET request to the Helix API. */
     async apiGet(path) {
       return this._apiFetch('GET', path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haven-team/helix-sdk",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Client-side SDK for Helix Apps embedded via iframe — auth context, API helpers, URL/title sync, LogRocket session replay.",
   "license": "MIT",
   "main": "helix-sdk.js",