@herazgo/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,55 @@
-# 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();
+```
+
+## 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/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,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";
+declare global {
+    interface Window {
+        /** Herazgo host API, set by the embeddable script (hg.js). */
+        HG?: HGGlobal | undefined;
+    }
+}

package/lib/index.js

@@ -0,0 +1 @@
+export { loadHG, seedHG } from "./load-hg.js";

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.1.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"
+  }
 }