@herazgo/sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @herazgo/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typings and install helpers for the Herazgo embeddable script. The widget
+runtime always loads from the Herazgo CDN (`static.herazgo.com/hg.js`) — this
+package ships no widget code, so the snippet stays the canonical install.
+
+## What's in it
+
+- `HGGlobal` / `HGModuleApi` — the typed `window.HG` contract; a global
+  `Window.HG` declaration ships with the types.
+- `loadHG({ key })` — injects the same snippet and resolves when the loader
+  marker (`HG.__herazgo`) or a requested module sub-API exists.
+- `seedHG({ feedback: { hidden: true } })` — typed pre-seed for first-render
+  suppression; call before the snippet / `loadHG()`.
+
+## Usage
+
+Snippet-and-types only (no code import):
+
+```sh
+pnpm add @herazgo/sdk
+```
+
+```jsonc
+// tsconfig.json
+"compilerOptions": { "types": ["@herazgo/sdk"] }
+```
+
+Managed loading:
+
+```ts
+import { loadHG } from "@herazgo/sdk";
+await loadHG({ key: "hz-XXXXXXXXXX", module: "feedback" });
+HG.feedback?.open(); // typed
+```
+
+Suppressed launcher (before loading):
+
+```ts
+import { seedHG, loadHG } from "@herazgo/sdk";
+seedHG({ feedback: { hidden: true } });
+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
+  (`window.__herazgoLoaded`). If a plain snippet is already present, tagging
+  it `data-hg-key` is optional — a race injects a second script that no-ops.
+- `module: "feedback"` resolves when `HG.feedback` exists — enabled modules
+  only; a wrong or disabled module name times out (default 10s).
+- The published contract is compiled against the loader's own sub-API
+  (`satisfies HGModuleApi` in the sdk repo's `src/host-api.ts`), so loader
+  drift fails the sdk repo's typecheck before release.

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/host-api-types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `window.HG` — the host-facing contract (`platform/tech-spec.md` § Embeddable
+ * Script). Canonical source for the typings customers install via
+ * `@herazgo/sdk` (this package); the loader compiles its own sub-API against
+ * `HGModuleApi` (`satisfies` in `src/host-api.ts` of the sdk repo), so a
+ * loader change that drifts from the published contract fails typecheck.
+ *
+ * One key per enabled module; a disabled module has no key at all. Hosts
+ * pre-seed `window.HG = { <module>: { hidden: true } }` before the snippet
+ * loads — through `seedHG()` rather than this type (the seed grammar is
+ * wider than the upgraded API).
+ */
+/** One module's sub-API on `HG.<module>`, exposed after the loader upgrade. */
+export interface HGModuleApi {
+    /** Host-led hidden state (seed / `hide()`); presentation rules own the launcher display only. */
+    readonly hidden: boolean;
+    /** Live panel state; false while the module is unmounted. */
+    readonly opened: boolean;
+    /** Kill switch: unmounts instantly, mid-flight mounts included. */
+    hide(): void;
+    /** Re-mount (booting first when the module was seed-hidden). */
+    show(): void;
+    /** Open the panel: mounts if needed, ignoring rules and the hidden state. */
+    open(): void;
+    /** Close the panel; visibility returns to the rules/host state. */
+    close(): void;
+    /** Panel open/close events; returns the unsubscribe. */
+    on(type: "open" | "close", cb: () => void): () => void;
+}
+/** The upgraded host namespace (set once the snippet claims `window.HG`). */
+export interface HGGlobal {
+    /** Marker the loader sets when it owns the name. */
+    __herazgo: true;
+    /** One entry per enabled product module (feedback today; extended as modules ship). */
+    feedback?: HGModuleApi;
+}

package/lib/host-api-types.js

@@ -0,0 +1,13 @@
+/**
+ * `window.HG` — the host-facing contract (`platform/tech-spec.md` § Embeddable
+ * Script). Canonical source for the typings customers install via
+ * `@herazgo/sdk` (this package); the loader compiles its own sub-API against
+ * `HGModuleApi` (`satisfies` in `src/host-api.ts` of the sdk repo), so a
+ * loader change that drifts from the published contract fails typecheck.
+ *
+ * One key per enabled module; a disabled module has no key at all. Hosts
+ * pre-seed `window.HG = { <module>: { hidden: true } }` before the snippet
+ * loads — through `seedHG()` rather than this type (the seed grammar is
+ * wider than the upgraded API).
+ */
+export {};

package/lib/index.d.ts

@@ -0,0 +1,14 @@
+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). */
+        HG?: HGGlobal | undefined;
+    }
+}

package/lib/index.js

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

package/lib/load-hg.d.ts

@@ -0,0 +1,18 @@
+/** Pre-seed entry: first-render suppression before the snippet loads. */
+export interface HGSeedEntry {
+    hidden?: boolean;
+}
+export interface LoadHGOptions {
+    /** Product public key from the studio snippet (`hz-…`). */
+    key: string;
+    /** Wait for this module's sub-API (e.g. "feedback"); default: the loader marker. */
+    module?: string;
+    /** Snippet URL override (dev/self-host); default: the prod CDN. */
+    scriptUrl?: string;
+    /** Ready-wait budget in ms; default 10000. Non-positive: check once, no wait. */
+    timeoutMs?: number;
+}
+/** Typed pre-seed for `window.HG` — call before the snippet / loadHG(). */
+export declare function seedHG(modules: Record<string, HGSeedEntry>): void;
+/** Injects the snippet for `key` and resolves when the widget is usable. */
+export declare function loadHG(options: LoadHGOptions): Promise<void>;

package/lib/load-hg.js

@@ -0,0 +1,84 @@
+const DEFAULT_SCRIPT_URL = "https://static.herazgo.com/hg.js";
+/** Mirrors the loader's key check (loader.ts main()). */
+const KEY_PATTERN = /^[\w-]{3,64}$/;
+/** Typed pre-seed for `window.HG` — call before the snippet / loadHG(). */
+export function seedHG(modules) {
+    if (typeof window === "undefined") {
+        throw new Error("seedHG: browser-only; there is no window here");
+    }
+    const seed = {};
+    for (const [name, entry] of Object.entries(modules)) {
+        seed[name] = { hidden: entry.hidden === true };
+    }
+    window.HG = seed;
+}
+/** Injects the snippet for `key` and resolves when the widget is usable. */
+export function loadHG(options) {
+    if (typeof window === "undefined") {
+        return Promise.reject(new Error("loadHG: browser-only; there is no window here"));
+    }
+    if (!KEY_PATTERN.test(options.key)) {
+        return Promise.reject(new Error(`loadHG: key "${options.key}" is not a usable product key (3-64 word chars)`));
+    }
+    const w = window;
+    const scriptUrl = options.scriptUrl ?? DEFAULT_SCRIPT_URL;
+    const timeoutMs = options.timeoutMs ?? 10000;
+    const module = options.module;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let poll;
+        let deadline;
+        const finish = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (poll != null)
+                clearInterval(poll);
+            if (deadline != null)
+                clearTimeout(deadline);
+            if (err != null)
+                reject(err);
+            else
+                resolve();
+        };
+        const ready = () => {
+            if (module != null) {
+                // Sub-APIs exist only for enabled modules after boot; a wrong or
+                // disabled module name times out (the error says which).
+                return w.HG != null && w.HG[module] != null;
+            }
+            return w.HG?.__herazgo === true;
+        };
+        if (ready())
+            return finish();
+        const src = `${scriptUrl}?key=${encodeURIComponent(options.key)}`;
+        // Idempotent per key: a snippet (with or without our marker attr) or an
+        // earlier loadHG() may already be loading; the loader dedupes via
+        // window.__herazgoLoaded regardless. A pre-existing tagged snippet shares
+        // its load error with this caller too.
+        const existing = document.querySelector(`script[data-hg-key="${options.key}"]`);
+        if (existing == null) {
+            const snippet = document.createElement("script");
+            snippet.src = src;
+            snippet.async = true;
+            snippet.dataset.hgKey = options.key;
+            snippet.addEventListener("error", () => {
+                finish(new Error(`loadHG: failed to load ${src} (blocked or unreachable)`));
+            });
+            document.head.appendChild(snippet);
+        }
+        else {
+            existing.addEventListener("error", () => {
+                finish(new Error(`loadHG: failed to load ${src} (blocked or unreachable)`));
+            });
+        }
+        poll = setInterval(() => {
+            if (ready())
+                finish();
+        }, 50);
+        deadline = setTimeout(() => {
+            finish(new Error(`loadHG: timed out after ${timeoutMs}ms waiting for ${module ?? "the loader"} — ` +
+                `check the key${module != null ? `, that "${module}" is enabled` : ", network reachability"}`));
+        }, Math.max(0, timeoutMs));
+    });
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@herazgo/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/herazgo/sdk.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "herazgo",
+    "feedback",
+    "widget",
+    "embeddable",
+    "sdk"
+  ],
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
 }