@herazgo/sdk 0.1.0 → 0.2.0

package/README.md

@@ -43,6 +43,26 @@ await loadHG({ key: "hz-XXXXXXXXXX", module: "feedback" });
 HG.feedback?.show();
 ```
 
+## Always-safe facade (default export)
+
+```ts
+import HG from "@herazgo/sdk";
+HG.feedback.open(); // safe anytime
+```
+
+The facade is a view of the live `window.HG` API, resolved per call. Before
+the snippet runs it never throws: `open()` is deferred (drains when the
+widget lands), `on()` subscriptions are buffered (the returned unsubscribe
+cancels in either phase), `hide()`/`show()` are vacuous, `opened`/`hidden`
+read `false`. Each pre-load call path warns once (subsequent calls stay
+quiet); `HG.module("name")` builds the same safe stub for any other module.
+Server-side (no window) everything is silently inert, so SSR code can call
+freely — nothing is logged and intents are dropped.
+
+The facade never becomes `window.HG` and never touches the loader's
+claim/lock semantics; snippet apps can keep using typed-optional
+`window.HG`. Multi-instance hosts that need isolated state use `createHG()`.
+
 ## Notes
 
 - `loadHG` is idempotent; the loader itself dedupes double loads

package/lib/facade.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The npm-path facade (`HG.feedback.open()` is safe pre-load by contract):
+ * every member resolves the live `window.HG` API per call — delegates when
+ * the snippet has run, no-ops + one-time warn when it hasn't. Never throws,
+ * never touches the loader's claim/lock semantics (this is not `window.HG`;
+ * it's a view of it). `open()` and `on()` intents buffer and drain once the
+ * live API appears; `hide()`/`show()` pre-live are vacuous (nothing mounted).
+ * Server-side (no window) everything is silently inert — SSR calls log
+ * nothing.
+ */
+import type { HGModuleApi } from "./host-api-types.js";
+export interface HGFacade {
+    /** Feedback module sub-API — safe stub until the live API exists. */
+    readonly feedback: HGModuleApi;
+    /** Safe sub-API for any other module name (cached per name). */
+    module(name: string): HGModuleApi;
+}
+/**
+ * Builds a facade. The default export is one long-lived instance; npm tests
+ * and multi-instance hosts use the factory to get isolated state.
+ */
+export declare function createHG(): HGFacade;
+/** The shared facade instance behind the package's default export. */
+declare const HG: HGFacade;
+export default HG;

package/lib/facade.js

@@ -0,0 +1,137 @@
+/** Live module API off window.HG, or undefined while absent. */
+function liveModule(name) {
+    if (typeof window === "undefined")
+        return undefined;
+    const live = window.HG?.[name];
+    return liveObject(live) ? live : undefined;
+}
+function liveObject(value) {
+    return typeof value === "object" && value != null;
+}
+function warnOnce(slot, name, method) {
+    if (typeof window === "undefined")
+        return; // SSR: silent everywhere
+    if (slot.warned.has(method))
+        return;
+    slot.warned.add(method);
+    console.warn(`[herazgo] ${name}.${method}() before the Herazgo snippet loaded — ` +
+        (method === "open" || method === "on" ? "deferred until it loads" : "ignored"));
+}
+/**
+ * Builds a facade. The default export is one long-lived instance; npm tests
+ * and multi-instance hosts use the factory to get isolated state.
+ */
+export function createHG() {
+    const slots = new Map();
+    let poller;
+    const slotFor = (name) => {
+        const existing = slots.get(name);
+        if (existing)
+            return existing;
+        const slot = { openRequested: false, buffered: [], warned: new Set() };
+        slots.set(name, slot);
+        return slot;
+    };
+    /** Drains buffered intents once the live API exists; stops itself when no
+     * slot has pending state left. */
+    const ensurePoller = () => {
+        poller ?? (poller = setInterval(() => {
+            let pending = false;
+            for (const [name, slot] of slots) {
+                const live = liveModule(name);
+                if (live == null) {
+                    pending = pending || slot.openRequested || slot.buffered.length > 0;
+                    continue;
+                }
+                if (slot.openRequested) {
+                    slot.openRequested = false;
+                    live.open();
+                }
+                for (const entry of slot.buffered.splice(0)) {
+                    entry.unsub = live.on(entry.type, entry.cb);
+                }
+            }
+            if (!pending) {
+                clearInterval(poller);
+                poller = undefined;
+            }
+        }, 200));
+    };
+    /** The safe sub-API for one module name: per-call delegation. */
+    const apiFor = (name) => ({
+        get hidden() {
+            return liveModule(name)?.hidden ?? false;
+        },
+        get opened() {
+            return liveModule(name)?.opened ?? false;
+        },
+        hide() {
+            const live = liveModule(name);
+            if (live != null)
+                return live.hide();
+            warnOnce(slotFor(name), name, "hide");
+        },
+        show() {
+            const live = liveModule(name);
+            if (live != null)
+                return live.show();
+            // pre-live there is nothing suppressed that hide() would have set
+        },
+        open() {
+            if (typeof window === "undefined")
+                return; // SSR: intents are lost
+            const live = liveModule(name);
+            const slot = slotFor(name);
+            if (live != null)
+                return live.open();
+            warnOnce(slot, name, "open");
+            slot.openRequested = true;
+            ensurePoller();
+        },
+        close() {
+            // last call wins: a close pre-live also cancels a buffered open
+            slotFor(name).openRequested = false;
+            liveModule(name)?.close();
+        },
+        on(type, cb) {
+            if (typeof window === "undefined")
+                return () => { }; // SSR: silent no-op
+            const slot = slotFor(name);
+            const live = liveModule(name);
+            if (live != null)
+                return live.on(type, cb);
+            const entry = { type, cb };
+            slot.buffered.push(entry);
+            warnOnce(slot, name, "on");
+            ensurePoller();
+            return () => {
+                // cancel pre-drain or live subscription, whichever phase we're in
+                if (entry.unsub != null) {
+                    entry.unsub();
+                    entry.unsub = undefined;
+                }
+                const at = slot.buffered.indexOf(entry);
+                if (at >= 0)
+                    slot.buffered.splice(at, 1);
+            };
+        },
+    });
+    const feedbackCache = apiFor("feedback");
+    const otherCache = new Map();
+    return {
+        get feedback() {
+            return feedbackCache;
+        },
+        module(name) {
+            const cached = otherCache.get(name);
+            if (cached)
+                return cached;
+            const api = apiFor(name);
+            otherCache.set(name, api);
+            return api;
+        },
+    };
+}
+/** The shared facade instance behind the package's default export. */
+const HG = createHG();
+export default HG;

package/lib/index.d.ts

@@ -2,6 +2,10 @@ export { loadHG, seedHG } from "./load-hg.js";
 export type { HGSeedEntry, LoadHGOptions } from "./load-hg.js";
 import type { HGGlobal } from "./host-api-types.js";
 export type { HGGlobal, HGModuleApi } from "./host-api-types.js";
+import HG from "./facade.js";
+export type { HGFacade } from "./facade.js";
+export { createHG } from "./facade.js";
+export default HG;
 declare global {
     interface Window {
         /** Herazgo host API, set by the embeddable script (hg.js). */

package/lib/index.js

@@ -1 +1,4 @@
 export { loadHG, seedHG } from "./load-hg.js";
+import HG from "./facade.js";
+export { createHG } from "./facade.js";
+export default HG;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herazgo/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Typings and install helpers for the Herazgo embeddable script (hg.js). The widget runtime always loads from the Herazgo CDN.",
   "license": "MIT",