@haven-team/helix-sdk 1.0.12

package/README.md

@@ -0,0 +1,27 @@
+# @haven-team/helix-sdk
+
+Client-side SDK for Helix Apps embedded via iframe. Vanilla JS, zero
+dependencies, UMD (script tag or `require`).
+
+- Auth context from the Helix shell (`onReady`, `getContext`, `getToken`)
+- Authenticated API helpers (`apiGet` / `apiPost` / `apiPatch` / `apiDelete`)
+- Automatic URL + title sync with the shell (deep links, refresh restore)
+- Opt-in LogRocket session replay with automatic Helix-user identify
+
+Most apps load it from the shell and never install anything:
+
+```html
+<script src="https://app.havenhelix.com/helix-sdk.js"></script>
+<script>
+  const helix = new HelixSDK();
+  helix.onReady(async (ctx) => {
+    const stores = await helix.apiGet('/stores');
+  });
+</script>
+```
+
+The npm package exists so hosts (the Helix shell itself, apps that bundle)
+can consume the SDK as a dependency instead of copying the file.
+
+Canonical source and docs: [haven-team/helix-toolkit](https://github.com/haven-team/helix-toolkit)
+(`sdk/helix-sdk.js`, `docs/`). Versioning follows the toolkit `VERSION` file.

package/helix-sdk.js

@@ -0,0 +1,422 @@
+/**
+ * Helix SDK — Client-side SDK for Helix Apps embedded via iframe.
+ *
+ * Usage:
+ *   <script src="https://your-helix-toolkit/sdk/helix-sdk.js"></script>
+ *   <script>
+ *     const helix = new HelixSDK();
+ *     helix.onReady((ctx) => {
+ *       console.log('Authenticated as:', ctx.user);
+ *       console.log('Token:', ctx.token);
+ *       // Use ctx.token for API calls to Helix
+ *     });
+ *   </script>
+ *
+ * Or as ES module:
+ *   import { HelixSDK } from '@haven-team/helix-sdk';
+ *
+ * URL + title sync (auto):
+ *   Once the SDK is loaded inside a Helix iframe, it automatically mirrors the
+ *   inner app's URL and document.title up to the Helix shell. The shell uses
+ *   that to keep the browser address bar fragment and tab title in sync with
+ *   what the user is actually looking at, so deep-linking, sharing, and
+ *   refresh-restore all work. No per-app code needed — any framework router
+ *   (React, Angular, Vue) that uses the History API is captured automatically.
+ *   Pass `{ autoBroadcast: false }` to disable.
+ *
+ * LogRocket session replay (opt-in):
+ *   const helix = new HelixSDK({ logrocket: true });
+ *   // or with options:
+ *   const helix = new HelixSDK({ logrocket: { appId: 'lto7os/my-app' } });
+ *   // or enable later:
+ *   const lr = await helix.enableLogRocket({ excludeEmails: ['ai@myhavenbot.com'] });
+ *
+ *   The SDK injects the LogRocket script, initializes it, and identifies the
+ *   session with the Helix user (email) once auth is ready — recordings show
+ *   up tied to the acting user with no per-app code. Recording is skipped on
+ *   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.
+ */
+(function (root, factory) {
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.HelixSDK = factory().HelixSDK;
+  }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  'use strict';
+
+  // Haven's existing LogRocket project (the Helix shell records here too).
+  // Apps with their own LogRocket project pass { logrocket: { appId } }.
+  const DEFAULT_LOGROCKET_APP_ID = 'lto7os/helix-frontend';
+  const LOGROCKET_CDN = 'https://cdn.lr-ingest.com/LogRocket.min.js';
+
+  class HelixSDK {
+    constructor(options = {}) {
+      this._ready = false;
+      this._readyCallbacks = [];
+      this._urlCallbacks = [];
+      this._context = null;
+      this._apiBase = options.apiBase || null;
+      this._instrumented = false;
+      this._suspendBroadcast = false;
+      this._lastBroadcast = null;
+      this._autoBroadcast = options.autoBroadcast !== false;
+      this._logrocket = null;
+      this._lrShouldRecord = true;
+      this._lrPromise = null;
+
+      if (options.logrocket) {
+        this.enableLogRocket(options.logrocket === true ? {} : options.logrocket);
+      }
+
+      // Parse auth + restore-path from URL params (injected by Helix iframe loader)
+      const params = new URLSearchParams(window.location.search);
+      const token = params.get('helix_token');
+      const user = params.get('helix_user');
+      const appSecret = params.get('helix_app_secret');
+      const apiBase = params.get('helix_api_base');
+      const initPath = params.get('helix_init_path');
+
+      if (apiBase) this._apiBase = apiBase;
+
+      const stripAuthParams = () => {
+        for (const k of [
+          'helix_token', 'helix_user', 'helix_app_secret',
+          'helix_api_base', 'helix_init_path'
+        ]) params.delete(k);
+        const clean = params.toString();
+        const path = window.location.pathname + (clean ? '?' + clean : '');
+        window.history.replaceState({}, '', path);
+      };
+
+      if (token && user) {
+        this._context = { token, user, appSecret };
+        this._ready = true;
+        stripAuthParams();
+        // If the shell told us where to land (deep link / refresh), apply it
+        // before the app's own router has a chance to read location.
+        if (initPath) this._applyRestoredPath(initPath);
+        this._instrumentNavigation();
+        this._instrumentTitle();
+        this._fireReady();
+      }
+
+      // Also listen for postMessage auth + shell-driven URL restore
+      window.addEventListener('message', (event) => {
+        const data = event.data;
+        if (!data || typeof data !== 'object') return;
+
+        if (data.type === 'helix-auth') {
+          this._context = {
+            token: data.token,
+            user: data.user,
+            appSecret: data.appSecret
+          };
+          this._ready = true;
+          this._instrumentNavigation();
+          this._instrumentTitle();
+          this._fireReady();
+          return;
+        }
+
+        if (data.type === 'helix-restore-url' && typeof data.path === 'string') {
+          this._applyRestoredPath(data.path);
+        }
+      });
+    }
+
+    /** Apply a path (path + search + hash) from the shell without re-broadcasting it back. */
+    _applyRestoredPath(target) {
+      try {
+        this._suspendBroadcast = true;
+        const url = new URL(target, window.location.origin);
+        const next = url.pathname + url.search + url.hash;
+        if (next !== window.location.pathname + window.location.search + window.location.hash) {
+          window.history.replaceState({}, '', next);
+          // Nudge framework routers (React/Vue/Angular) to pick up the change.
+          window.dispatchEvent(new PopStateEvent('popstate'));
+        }
+      } catch (e) {
+        // Bad input from shell — ignore rather than break the app.
+      } finally {
+        this._suspendBroadcast = false;
+      }
+      this._fireUrlCallbacks();
+    }
+
+    /** Monkey-patch History API + listen for popstate/hashchange so any router we sit
+     *  on top of (React, Angular, Vue, plain anchors) is auto-mirrored to the shell. */
+    _instrumentNavigation() {
+      if (this._instrumented || window.parent === window || !this._autoBroadcast) return;
+      this._instrumented = true;
+
+      const sdk = this;
+      const origPush = window.history.pushState;
+      const origReplace = window.history.replaceState;
+      window.history.pushState = function patchedPush() {
+        const result = origPush.apply(this, arguments);
+        sdk._postUrl();
+        return result;
+      };
+      window.history.replaceState = function patchedReplace() {
+        const result = origReplace.apply(this, arguments);
+        sdk._postUrl();
+        return result;
+      };
+      window.addEventListener('popstate', () => this._postUrl());
+      window.addEventListener('hashchange', () => this._postUrl());
+
+      // Broadcast once on boot so the shell can mirror the current URL even if
+      // the app never navigates.
+      setTimeout(() => this._postUrl(), 0);
+    }
+
+    /** Observe <title> and broadcast changes so the browser tab reflects the inner view. */
+    _instrumentTitle() {
+      if (this._titleInstrumented || window.parent === window || !this._autoBroadcast) return;
+      this._titleInstrumented = true;
+      const post = () => this._postTitle();
+      post();
+      const titleEl = document.head && document.head.querySelector('title');
+      if (titleEl && typeof MutationObserver !== 'undefined') {
+        const obs = new MutationObserver(post);
+        obs.observe(titleEl, { childList: true, characterData: true, subtree: true });
+      }
+      // Some apps swap the <title> element entirely; watch <head> for that.
+      if (document.head && typeof MutationObserver !== 'undefined') {
+        const headObs = new MutationObserver(post);
+        headObs.observe(document.head, { childList: true });
+      }
+    }
+
+    _postUrl() {
+      if (this._suspendBroadcast) return;
+      if (window.parent === window) return;
+      const payload = {
+        type: 'helix-url',
+        path: window.location.pathname,
+        search: window.location.search,
+        hash: window.location.hash
+      };
+      const key = payload.path + payload.search + payload.hash;
+      if (key === this._lastBroadcast) return;
+      this._lastBroadcast = key;
+      try { window.parent.postMessage(payload, '*'); } catch (e) { /* ignore */ }
+      this._fireUrlCallbacks();
+    }
+
+    _postTitle() {
+      if (window.parent === window) return;
+      const title = document.title;
+      if (!title) return;
+      if (title === this._lastTitle) return;
+      this._lastTitle = title;
+      try { window.parent.postMessage({ type: 'helix-title', title }, '*'); } catch (e) { /* ignore */ }
+    }
+
+    /** Push an explicit URL state (path + optional search/hash). Useful for apps
+     *  that don't use the History API (e.g. server-rendered or query-only state). */
+    setUrlState(target) {
+      if (typeof target !== 'string' || !target) return;
+      try {
+        const url = new URL(target, window.location.origin);
+        const next = url.pathname + url.search + url.hash;
+        window.history.replaceState({}, '', next);
+        this._postUrl();
+      } catch (e) { /* ignore */ }
+    }
+
+    /** Subscribe to URL changes (inner or shell-driven). */
+    onUrlState(callback) {
+      if (typeof callback === 'function') this._urlCallbacks.push(callback);
+    }
+
+    _fireUrlCallbacks() {
+      const state = {
+        path: window.location.pathname,
+        search: window.location.search,
+        hash: window.location.hash
+      };
+      for (const cb of this._urlCallbacks) {
+        try { cb(state); } catch (e) { console.error('HelixSDK: onUrlState callback error', e); }
+      }
+    }
+
+    /** Register a callback for when auth is ready. Fires immediately if already authenticated. */
+    onReady(callback) {
+      if (this._ready && this._context) {
+        callback(this._context);
+      } else {
+        this._readyCallbacks.push(callback);
+      }
+    }
+
+    /** Get the current auth context, or null if not authenticated. */
+    getContext() {
+      return this._context;
+    }
+
+    /** Check if the SDK has authenticated. */
+    isReady() {
+      return this._ready;
+    }
+
+    /** Get the Helix auth token for API calls. */
+    getToken() {
+      return this._context?.token || null;
+    }
+
+    /** Make an authenticated GET request to the Helix API. */
+    async apiGet(path) {
+      return this._apiFetch('GET', path);
+    }
+
+    /** Make an authenticated POST request to the Helix API. */
+    async apiPost(path, body) {
+      return this._apiFetch('POST', path, body);
+    }
+
+    /** Make an authenticated PATCH request to the Helix API. */
+    async apiPatch(path, body) {
+      return this._apiFetch('PATCH', path, body);
+    }
+
+    /** Make an authenticated DELETE request to the Helix API. */
+    async apiDelete(path) {
+      return this._apiFetch('DELETE', path);
+    }
+
+    /** Internal: make an authenticated fetch to the Helix API. */
+    async _apiFetch(method, path, body) {
+      if (!this._context) throw new Error('HelixSDK: not authenticated');
+      const base = this._apiBase || this._guessApiBase();
+      const url = base + (path.startsWith('/') ? path : '/' + path);
+      const opts = {
+        method,
+        headers: {
+          'Authorization': 'Bearer ' + this._context.token,
+          'Content-Type': 'application/json',
+          'Accept': 'application/json'
+        }
+      };
+      if (body && method !== 'GET') {
+        opts.body = JSON.stringify(body);
+      }
+      const res = await fetch(url, opts);
+      if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+        throw new Error(err.error || 'API request failed: ' + res.status);
+      }
+      return res.json();
+    }
+
+    /** Guess the Helix API base URL from the parent window origin. */
+    _guessApiBase() {
+      // If we're in an iframe, the parent origin is the Helix app
+      if (window.parent !== window) {
+        try {
+          // Can't access parent.location in cross-origin, use document.referrer
+          const referrer = document.referrer;
+          if (referrer) {
+            const url = new URL(referrer);
+            return url.origin + '/api';
+          }
+        } catch (e) { /* ignore */ }
+      }
+      return '/api';
+    }
+
+    _fireReady() {
+      for (const cb of this._readyCallbacks) {
+        try { cb(this._context); } catch (e) { console.error('HelixSDK: onReady callback error', e); }
+      }
+      this._readyCallbacks = [];
+    }
+
+    /**
+     * Enable LogRocket session replay. Loads the LogRocket script (unless one
+     * is already on the page), initializes it, and identifies the session with
+     * the Helix user email once auth is ready.
+     *
+     * Options:
+     *   appId         — LogRocket project id (default: Haven's lto7os/helix-frontend)
+     *   excludeEmails — array of emails whose sessions should not be recorded
+     *   identify      — false to skip the automatic LogRocket.identify call
+     *   force         — true to record even on localhost
+     *
+     * Resolves to the LogRocket object, or null if disabled/failed. Never
+     * rejects and never throws — session replay must not break the app.
+     */
+    enableLogRocket(options = {}) {
+      if (this._lrPromise) return this._lrPromise;
+      this._lrPromise = this._initLogRocket(options).catch((e) => {
+        console.warn('HelixSDK: LogRocket setup failed', e);
+        return null;
+      });
+      return this._lrPromise;
+    }
+
+    /** The LogRocket object once enableLogRocket has resolved, else null. */
+    getLogRocket() {
+      return this._logrocket;
+    }
+
+    async _initLogRocket(options) {
+      if (typeof document === 'undefined') return null;
+      const host = window.location && window.location.hostname;
+      const isLocal = host === 'localhost' || host === '127.0.0.1' || host === '0.0.0.0';
+      if (isLocal && !options.force) {
+        console.info('HelixSDK: LogRocket disabled on localhost (pass force: true to override)');
+        return null;
+      }
+
+      const excludeEmails = options.excludeEmails || [];
+      const lr = await this._loadLogRocketScript();
+      if (!lr) return null;
+
+      lr.init(options.appId || DEFAULT_LOGROCKET_APP_ID, {
+        shouldSendData: () => this._lrShouldRecord
+      });
+      this._logrocket = lr;
+
+      // Identify with the Helix user as soon as auth context exists. If the
+      // user is excluded, flip the shouldSendData gate instead of identifying.
+      if (options.identify !== false) {
+        this.onReady((ctx) => {
+          try {
+            const email = ctx && ctx.user;
+            if (email && excludeEmails.indexOf(email) !== -1) {
+              this._lrShouldRecord = false;
+              return;
+            }
+            if (email) lr.identify(email, { email, via: 'helix-sdk' });
+          } catch (e) {
+            console.warn('HelixSDK: LogRocket identify failed', e);
+          }
+        });
+      }
+      return lr;
+    }
+
+    _loadLogRocketScript() {
+      // Reuse an instance the page already loaded (e.g. app vendored its own).
+      if (window.LogRocket) return Promise.resolve(window.LogRocket);
+      return new Promise((resolve) => {
+        const script = document.createElement('script');
+        script.src = LOGROCKET_CDN;
+        script.async = true;
+        script.crossOrigin = 'anonymous';
+        script.onload = () => resolve(window.LogRocket || null);
+        script.onerror = () => {
+          console.warn('HelixSDK: failed to load LogRocket from ' + LOGROCKET_CDN);
+          resolve(null);
+        };
+        (document.head || document.body || document.documentElement).appendChild(script);
+      });
+    }
+  }
+
+  return { HelixSDK };
+}));

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@haven-team/helix-sdk",
+  "version": "1.0.12",
+  "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",
+  "exports": {
+    ".": "./helix-sdk.js"
+  },
+  "files": [
+    "helix-sdk.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test --test-concurrency=1 test/*.test.js"
+  },
+  "keywords": [
+    "helix",
+    "iframe",
+    "sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haven-team/helix-toolkit.git",
+    "directory": "sdk"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}