@guidelytech/electron 0.0.0-stage → 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guidely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @guidelytech/electron
 
-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.
+Guidely guides, analytics, session replay and feature flags in Electron (and other Chromium desktop
+shells). The web SDK runs in your renderer as it does in a browser; this package adds the desktop
+parts:
+
+* **Page paths that make sense.** `file:///…/Acme.app/Contents/Resources/app.asar/index.html#/settings`
+  becomes `file://app/settings`, and `app://bundle/index.html#/inbox` becomes `app://bundle/inbox`, so
+  guide URL patterns (`/settings`), Pages, Heatmaps and Funnels work the same on every machine.
+* **App version and OS.** The main process reports the app version, OS, architecture and Electron
+  version: **App version** targeting rules, feature-flag attributes (`appVersion`), release-matched
+  source maps for errors, and optional desktop traits for your users.
+* **Offline.** Events, guide progress and survey answers wait in `localStorage` while the machine is
+  offline and are delivered later (the web SDK's outbox), and guides run from the cached config.
+
+```bash
+npm install @guidelytech/electron @guidelytech/sdk-core
+```
+
+## 1. Main process
+
+```ts
+import { app, BrowserWindow, ipcMain } from "electron";
+import { setupGuidelyMain } from "@guidelytech/electron/main";
+
+app.whenReady().then(() => {
+  setupGuidelyMain({ app, ipcMain });
+  new BrowserWindow({ webPreferences: { preload: path.join(__dirname, "preload.js"), contextIsolation: true } }).loadFile("index.html");
+});
+```
+
+## 2. Preload
+
+```ts
+import { contextBridge, ipcRenderer } from "electron";
+import { exposeGuidely } from "@guidelytech/electron/preload";
+
+exposeGuidely({ contextBridge, ipcRenderer }); // window.guidelyElectron.getAppInfo()
+```
+
+Sandboxed preloads (the default since Electron 20) can't `require` npm packages: bundle your preload
+(esbuild, Vite, webpack) or inline the equivalent:
+
+```ts
+contextBridge.exposeInMainWorld("guidelyElectron", { getAppInfo: () => ipcRenderer.invoke("guidely:app-info") });
+```
+
+## 3. Renderer
+
+```ts
+import { createGuidelyElectron, desktopTraits } from "@guidelytech/electron";
+
+const guidely = await createGuidelyElectron({
+  projectId: "pk_prod_…",
+  apiUrl: "https://guidelytech.com",
+  user: { id: me.id, traits: { plan: me.plan } }, // desktopOs, desktopArch, appVersion… are added
+});
+```
+
+Or keep your existing setup (React, Svelte, script tag) and spread the options:
+
+```tsx
+import { electronOptions, getElectronAppInfo } from "@guidelytech/electron";
+const info = await getElectronAppInfo();
+<GuidelyProvider projectId="pk_prod_…" {...electronOptions(info)}>…</GuidelyProvider>
+```
+
+| Export | Where | What |
+|---|---|---|
+| `setupGuidelyMain({ app, ipcMain })` | main | Answers `guidely:app-info`; returns a dispose function |
+| `exposeGuidely({ contextBridge, ipcRenderer })` | preload | Exposes `window.guidelyElectron` |
+| `getElectronAppInfo(timeoutMs = 1000)` | renderer | `{ appName, appVersion, platform, arch, osVersion, electronVersion, chromeVersion, locale, packaged }` or `null` |
+| `electronOptions(info)` | renderer | `{ pageUrl: normalizeAppUrl, appVersion, release }` |
+| `desktopTraits(info)` | renderer | `{ appVersion, desktopOs, desktopOsVersion, desktopArch, electronVersion }` |
+| `createGuidelyElectron(options)` | renderer | `createGuidely` with all of the above |
+| `normalizeAppUrl(href)` | anywhere | The URL mapping (also exported by `@guidelytech/sdk-core`) |
+
+## Page URLs
+
+The SDK maps every non-http(s) URL (`file:`, custom protocols) with `normalizeAppUrl`, even without
+this package: `<scheme>://<host or "app"><route>`, where the route is the hash route (`#/x`, `#!/x`)
+when there is one, otherwise the page file (`index.html` → `/`, `settings.html` → `/settings`) or the
+custom protocol's own path (`app://bundle/deals/42` → `/deals/42`). Write guide URL patterns against
+the route: `/settings`, `/deals/*`. Pass your own `pageUrl: (href) => string` option to map URLs
+differently (for example to keep a `?tab=` parameter out).
+
+## Things to know
+
+* **Allowed origins.** Requests from `file://` pages carry `Origin: null` (or `file://`), and custom
+  protocols their own origin (`app://bundle`). Leave the environment's allowed origins empty, or add
+  that origin, in Settings → Environments.
+* **Custom protocols** need `protocol.registerSchemesAsPrivileged([{ scheme: "app", privileges: {
+  standard: true, secure: true, supportFetchAPI: true, corsEnabled: true } }])` before `app` is ready,
+  or `localStorage` (identity, offline queue) and `fetch` won't work on them.
+* **CSP.** If your renderer sets a Content-Security-Policy, allow the Guidely API in `connect-src`
+  (and `img-src` for guide images), and `script-src` for the session-replay recorder chunk if you use
+  replay (or self-host the SDK files, see [docs/sdk-versioning.md](../../docs/sdk-versioning.md)).
+* The **in-app element picker** opens the target URL in a browser window, which a packaged desktop app
+  can't receive: author against your app's web build or a dev server (`http://localhost:…`), or use
+  manual selectors.
+* Guides use the **Web** platform (tick *Web* under Trigger → Platforms). Device type is `desktop`;
+  the browser is reported as `electron` and the OS from the user agent.

package/dist/chunk-AGZOVF3N.js

@@ -0,0 +1,16 @@
+// src/types.ts
+var APP_INFO_CHANNEL = "guidely:app-info";
+var BRIDGE_KEY = "guidelyElectron";
+function osName(platform) {
+  if (platform === "darwin") return "macos";
+  if (platform === "win32") return "windows";
+  if (platform === "linux") return "linux";
+  return platform;
+}
+
+export {
+  APP_INFO_CHANNEL,
+  BRIDGE_KEY,
+  osName
+};
+//# sourceMappingURL=chunk-AGZOVF3N.js.map

package/dist/chunk-AGZOVF3N.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/** What the main process knows about the desktop app, sent to the renderer over IPC. */\nexport interface ElectronAppInfo {\n  /** `app.getName()`. */\n  appName: string;\n  /** `app.getVersion()` (from package.json). */\n  appVersion: string;\n  /** `process.platform`: `darwin`, `win32`, `linux`. */\n  platform: string;\n  /** `process.arch`: `x64`, `arm64`, … */\n  arch: string;\n  /** `os.release()` / `process.getSystemVersion()`, when available. */\n  osVersion?: string;\n  electronVersion?: string;\n  chromeVersion?: string;\n  /** `app.getLocale()`. */\n  locale?: string;\n  /** `app.isPackaged`: false while running from source (`electron .`). */\n  packaged?: boolean;\n}\n\n/** The API the preload script exposes on `window.guidelyElectron`. */\nexport interface GuidelyElectronBridge {\n  getAppInfo(): Promise<ElectronAppInfo>;\n}\n\n/** IPC channel used between the main-process handler and the preload bridge. */\nexport const APP_INFO_CHANNEL = \"guidely:app-info\";\n/** Global the preload bridge is exposed as (`contextBridge.exposeInMainWorld`). */\nexport const BRIDGE_KEY = \"guidelyElectron\";\n\n/** Desktop operating system names used in Guidely device properties. */\nexport function osName(platform: string): string {\n  if (platform === \"darwin\") return \"macos\";\n  if (platform === \"win32\") return \"windows\";\n  if (platform === \"linux\") return \"linux\";\n  return platform;\n}\n"],"mappings":";AA0BO,IAAM,mBAAmB;AAEzB,IAAM,aAAa;AAGnB,SAAS,OAAO,UAA0B;AAC/C,MAAI,aAAa,SAAU,QAAO;AAClC,MAAI,aAAa,QAAS,QAAO;AACjC,MAAI,aAAa,QAAS,QAAO;AACjC,SAAO;AACT;","names":[]}

package/dist/index.cjs

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APP_INFO_CHANNEL: () => APP_INFO_CHANNEL,
+  BRIDGE_KEY: () => BRIDGE_KEY,
+  createGuidelyElectron: () => createGuidelyElectron,
+  desktopTraits: () => desktopTraits,
+  electronOptions: () => electronOptions,
+  getElectronAppInfo: () => getElectronAppInfo,
+  normalizeAppUrl: () => import_sdk_core2.normalizeAppUrl,
+  osName: () => osName
+});
+module.exports = __toCommonJS(index_exports);
+var import_sdk_core = require("@guidelytech/sdk-core");
+
+// src/types.ts
+var APP_INFO_CHANNEL = "guidely:app-info";
+var BRIDGE_KEY = "guidelyElectron";
+function osName(platform) {
+  if (platform === "darwin") return "macos";
+  if (platform === "win32") return "windows";
+  if (platform === "linux") return "linux";
+  return platform;
+}
+
+// src/index.ts
+var import_sdk_core2 = require("@guidelytech/sdk-core");
+var bridge = () => {
+  const g = globalThis;
+  const b = g[BRIDGE_KEY];
+  return b && typeof b.getAppInfo === "function" ? b : null;
+};
+async function getElectronAppInfo(timeoutMs = 1e3) {
+  const b = bridge();
+  if (!b) return null;
+  let timer;
+  try {
+    return await Promise.race([
+      b.getAppInfo().then((info) => info && typeof info === "object" && typeof info.appVersion === "string" ? info : null),
+      new Promise((resolve) => timer = setTimeout(() => resolve(null), timeoutMs))
+    ]);
+  } catch {
+    return null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+function electronOptions(info) {
+  return {
+    pageUrl: import_sdk_core.normalizeAppUrl,
+    ...info?.appVersion ? { appVersion: info.appVersion, release: info.appVersion } : {}
+  };
+}
+function desktopTraits(info) {
+  if (!info) return {};
+  const out = { appVersion: info.appVersion, desktopOs: osName(info.platform), desktopArch: info.arch };
+  if (info.osVersion) out.desktopOsVersion = info.osVersion;
+  if (info.electronVersion) out.electronVersion = info.electronVersion;
+  return out;
+}
+async function createGuidelyElectron(options) {
+  const { bridgeTimeoutMs, ...rest } = options;
+  const info = await getElectronAppInfo(bridgeTimeoutMs);
+  const user = rest.user ? { ...rest.user, traits: { ...desktopTraits(info), ...rest.user.traits ?? {} } } : void 0;
+  return (0, import_sdk_core.createGuidely)({ ...electronOptions(info), ...rest, ...user ? { user } : {} });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APP_INFO_CHANNEL,
+  BRIDGE_KEY,
+  createGuidelyElectron,
+  desktopTraits,
+  electronOptions,
+  getElectronAppInfo,
+  normalizeAppUrl,
+  osName
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/types.ts"],"sourcesContent":["import { createGuidely, normalizeAppUrl, type GuidelyClient, type GuidelyOptions } from \"@guidelytech/sdk-core\";\nimport { BRIDGE_KEY, osName, type ElectronAppInfo, type GuidelyElectronBridge } from \"./types\";\n\nexport { APP_INFO_CHANNEL, BRIDGE_KEY, osName } from \"./types\";\nexport type { ElectronAppInfo, GuidelyElectronBridge } from \"./types\";\nexport { normalizeAppUrl } from \"@guidelytech/sdk-core\";\n\nconst bridge = (): GuidelyElectronBridge | null => {\n  const g = globalThis as unknown as Record<string, unknown>;\n  const b = g[BRIDGE_KEY] as GuidelyElectronBridge | undefined;\n  return b && typeof b.getAppInfo === \"function\" ? b : null;\n};\n\n/**\n * Renderer: the app info exposed by the preload bridge, or null when it is missing (plain browser,\n * preload not installed) or does not answer within `timeoutMs`.\n */\nexport async function getElectronAppInfo(timeoutMs = 1000): Promise<ElectronAppInfo | null> {\n  const b = bridge();\n  if (!b) return null;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  try {\n    return await Promise.race([\n      b.getAppInfo().then((info) => (info && typeof info === \"object\" && typeof info.appVersion === \"string\" ? info : null)),\n      new Promise<null>((resolve) => (timer = setTimeout(() => resolve(null), timeoutMs))),\n    ]);\n  } catch {\n    return null;\n  } finally {\n    if (timer) clearTimeout(timer);\n  }\n}\n\n/**\n * SDK options for a desktop app: app-relative page URLs for `file:` and custom protocols, the app\n * version for **App version** targeting rules and flag attributes, and the release for source-mapped\n * errors. Spread your own options after it to override.\n */\nexport function electronOptions(info: ElectronAppInfo | null): Pick<GuidelyOptions, \"pageUrl\" | \"appVersion\" | \"release\"> {\n  return {\n    pageUrl: normalizeAppUrl,\n    ...(info?.appVersion ? { appVersion: info.appVersion, release: info.appVersion } : {}),\n  };\n}\n\n/**\n * Desktop details as user traits (`desktopOs`, `desktopOsVersion`, `desktopArch`, `electronVersion`,\n * `appVersion`), for `identify(userId, { ...traits, ...desktopTraits(info) })` so targeting rules,\n * audiences and the Users list can use them.\n */\nexport function desktopTraits(info: ElectronAppInfo | null): Record<string, string> {\n  if (!info) return {};\n  const out: Record<string, string> = { appVersion: info.appVersion, desktopOs: osName(info.platform), desktopArch: info.arch };\n  if (info.osVersion) out.desktopOsVersion = info.osVersion;\n  if (info.electronVersion) out.electronVersion = info.electronVersion;\n  return out;\n}\n\n/**\n * Renderer: creates the Guidely client for an Electron window, after reading the app info from the\n * preload bridge (at most `bridgeTimeoutMs`, default 1 s; without the bridge it still works, with\n * app-relative page URLs but no app version). `options.user.traits` get the desktop traits added.\n *\n * ```ts\n * import { createGuidelyElectron } from \"@guidelytech/electron\";\n * const guidely = await createGuidelyElectron({ projectId: \"pk_prod_…\", user: { id: me.id, traits: { plan: me.plan } } });\n * ```\n */\nexport async function createGuidelyElectron(options: GuidelyOptions & { bridgeTimeoutMs?: number }): Promise<GuidelyClient> {\n  const { bridgeTimeoutMs, ...rest } = options;\n  const info = await getElectronAppInfo(bridgeTimeoutMs);\n  const user = rest.user ? { ...rest.user, traits: { ...desktopTraits(info), ...(rest.user.traits ?? {}) } } : undefined;\n  return createGuidely({ ...electronOptions(info), ...rest, ...(user ? { user } : {}) });\n}\n","/** What the main process knows about the desktop app, sent to the renderer over IPC. */\nexport interface ElectronAppInfo {\n  /** `app.getName()`. */\n  appName: string;\n  /** `app.getVersion()` (from package.json). */\n  appVersion: string;\n  /** `process.platform`: `darwin`, `win32`, `linux`. */\n  platform: string;\n  /** `process.arch`: `x64`, `arm64`, … */\n  arch: string;\n  /** `os.release()` / `process.getSystemVersion()`, when available. */\n  osVersion?: string;\n  electronVersion?: string;\n  chromeVersion?: string;\n  /** `app.getLocale()`. */\n  locale?: string;\n  /** `app.isPackaged`: false while running from source (`electron .`). */\n  packaged?: boolean;\n}\n\n/** The API the preload script exposes on `window.guidelyElectron`. */\nexport interface GuidelyElectronBridge {\n  getAppInfo(): Promise<ElectronAppInfo>;\n}\n\n/** IPC channel used between the main-process handler and the preload bridge. */\nexport const APP_INFO_CHANNEL = \"guidely:app-info\";\n/** Global the preload bridge is exposed as (`contextBridge.exposeInMainWorld`). */\nexport const BRIDGE_KEY = \"guidelyElectron\";\n\n/** Desktop operating system names used in Guidely device properties. */\nexport function osName(platform: string): string {\n  if (platform === \"darwin\") return \"macos\";\n  if (platform === \"win32\") return \"windows\";\n  if (platform === \"linux\") return \"linux\";\n  return platform;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,sBAAwF;;;AC0BjF,IAAM,mBAAmB;AAEzB,IAAM,aAAa;AAGnB,SAAS,OAAO,UAA0B;AAC/C,MAAI,aAAa,SAAU,QAAO;AAClC,MAAI,aAAa,QAAS,QAAO;AACjC,MAAI,aAAa,QAAS,QAAO;AACjC,SAAO;AACT;;;AD/BA,IAAAA,mBAAgC;AAEhC,IAAM,SAAS,MAAoC;AACjD,QAAM,IAAI;AACV,QAAM,IAAI,EAAE,UAAU;AACtB,SAAO,KAAK,OAAO,EAAE,eAAe,aAAa,IAAI;AACvD;AAMA,eAAsB,mBAAmB,YAAY,KAAuC;AAC1F,QAAM,IAAI,OAAO;AACjB,MAAI,CAAC,EAAG,QAAO;AACf,MAAI;AACJ,MAAI;AACF,WAAO,MAAM,QAAQ,KAAK;AAAA,MACxB,EAAE,WAAW,EAAE,KAAK,CAAC,SAAU,QAAQ,OAAO,SAAS,YAAY,OAAO,KAAK,eAAe,WAAW,OAAO,IAAK;AAAA,MACrH,IAAI,QAAc,CAAC,YAAa,QAAQ,WAAW,MAAM,QAAQ,IAAI,GAAG,SAAS,CAAE;AAAA,IACrF,CAAC;AAAA,EACH,QAAQ;AACN,WAAO;AAAA,EACT,UAAE;AACA,QAAI,MAAO,cAAa,KAAK;AAAA,EAC/B;AACF;AAOO,SAAS,gBAAgB,MAA0F;AACxH,SAAO;AAAA,IACL,SAAS;AAAA,IACT,GAAI,MAAM,aAAa,EAAE,YAAY,KAAK,YAAY,SAAS,KAAK,WAAW,IAAI,CAAC;AAAA,EACtF;AACF;AAOO,SAAS,cAAc,MAAsD;AAClF,MAAI,CAAC,KAAM,QAAO,CAAC;AACnB,QAAM,MAA8B,EAAE,YAAY,KAAK,YAAY,WAAW,OAAO,KAAK,QAAQ,GAAG,aAAa,KAAK,KAAK;AAC5H,MAAI,KAAK,UAAW,KAAI,mBAAmB,KAAK;AAChD,MAAI,KAAK,gBAAiB,KAAI,kBAAkB,KAAK;AACrD,SAAO;AACT;AAYA,eAAsB,sBAAsB,SAAgF;AAC1H,QAAM,EAAE,iBAAiB,GAAG,KAAK,IAAI;AACrC,QAAM,OAAO,MAAM,mBAAmB,eAAe;AACrD,QAAM,OAAO,KAAK,OAAO,EAAE,GAAG,KAAK,MAAM,QAAQ,EAAE,GAAG,cAAc,IAAI,GAAG,GAAI,KAAK,KAAK,UAAU,CAAC,EAAG,EAAE,IAAI;AAC7G,aAAO,+BAAc,EAAE,GAAG,gBAAgB,IAAI,GAAG,GAAG,MAAM,GAAI,OAAO,EAAE,KAAK,IAAI,CAAC,EAAG,CAAC;AACvF;","names":["import_sdk_core"]}

package/dist/index.d.cts

@@ -0,0 +1,37 @@
+import { GuidelyOptions, GuidelyClient } from '@guidelytech/sdk-core';
+export { normalizeAppUrl } from '@guidelytech/sdk-core';
+import { E as ElectronAppInfo } from './types-BEnWCecg.cjs';
+export { A as APP_INFO_CHANNEL, B as BRIDGE_KEY, G as GuidelyElectronBridge, o as osName } from './types-BEnWCecg.cjs';
+
+/**
+ * Renderer: the app info exposed by the preload bridge, or null when it is missing (plain browser,
+ * preload not installed) or does not answer within `timeoutMs`.
+ */
+declare function getElectronAppInfo(timeoutMs?: number): Promise<ElectronAppInfo | null>;
+/**
+ * SDK options for a desktop app: app-relative page URLs for `file:` and custom protocols, the app
+ * version for **App version** targeting rules and flag attributes, and the release for source-mapped
+ * errors. Spread your own options after it to override.
+ */
+declare function electronOptions(info: ElectronAppInfo | null): Pick<GuidelyOptions, "pageUrl" | "appVersion" | "release">;
+/**
+ * Desktop details as user traits (`desktopOs`, `desktopOsVersion`, `desktopArch`, `electronVersion`,
+ * `appVersion`), for `identify(userId, { ...traits, ...desktopTraits(info) })` so targeting rules,
+ * audiences and the Users list can use them.
+ */
+declare function desktopTraits(info: ElectronAppInfo | null): Record<string, string>;
+/**
+ * Renderer: creates the Guidely client for an Electron window, after reading the app info from the
+ * preload bridge (at most `bridgeTimeoutMs`, default 1 s; without the bridge it still works, with
+ * app-relative page URLs but no app version). `options.user.traits` get the desktop traits added.
+ *
+ * ```ts
+ * import { createGuidelyElectron } from "@guidelytech/electron";
+ * const guidely = await createGuidelyElectron({ projectId: "pk_prod_…", user: { id: me.id, traits: { plan: me.plan } } });
+ * ```
+ */
+declare function createGuidelyElectron(options: GuidelyOptions & {
+    bridgeTimeoutMs?: number;
+}): Promise<GuidelyClient>;
+
+export { ElectronAppInfo, createGuidelyElectron, desktopTraits, electronOptions, getElectronAppInfo };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { GuidelyOptions, GuidelyClient } from '@guidelytech/sdk-core';
+export { normalizeAppUrl } from '@guidelytech/sdk-core';
+import { E as ElectronAppInfo } from './types-BEnWCecg.js';
+export { A as APP_INFO_CHANNEL, B as BRIDGE_KEY, G as GuidelyElectronBridge, o as osName } from './types-BEnWCecg.js';
+
+/**
+ * Renderer: the app info exposed by the preload bridge, or null when it is missing (plain browser,
+ * preload not installed) or does not answer within `timeoutMs`.
+ */
+declare function getElectronAppInfo(timeoutMs?: number): Promise<ElectronAppInfo | null>;
+/**
+ * SDK options for a desktop app: app-relative page URLs for `file:` and custom protocols, the app
+ * version for **App version** targeting rules and flag attributes, and the release for source-mapped
+ * errors. Spread your own options after it to override.
+ */
+declare function electronOptions(info: ElectronAppInfo | null): Pick<GuidelyOptions, "pageUrl" | "appVersion" | "release">;
+/**
+ * Desktop details as user traits (`desktopOs`, `desktopOsVersion`, `desktopArch`, `electronVersion`,
+ * `appVersion`), for `identify(userId, { ...traits, ...desktopTraits(info) })` so targeting rules,
+ * audiences and the Users list can use them.
+ */
+declare function desktopTraits(info: ElectronAppInfo | null): Record<string, string>;
+/**
+ * Renderer: creates the Guidely client for an Electron window, after reading the app info from the
+ * preload bridge (at most `bridgeTimeoutMs`, default 1 s; without the bridge it still works, with
+ * app-relative page URLs but no app version). `options.user.traits` get the desktop traits added.
+ *
+ * ```ts
+ * import { createGuidelyElectron } from "@guidelytech/electron";
+ * const guidely = await createGuidelyElectron({ projectId: "pk_prod_…", user: { id: me.id, traits: { plan: me.plan } } });
+ * ```
+ */
+declare function createGuidelyElectron(options: GuidelyOptions & {
+    bridgeTimeoutMs?: number;
+}): Promise<GuidelyClient>;
+
+export { ElectronAppInfo, createGuidelyElectron, desktopTraits, electronOptions, getElectronAppInfo };

package/dist/index.js

@@ -0,0 +1,59 @@
+import {
+  APP_INFO_CHANNEL,
+  BRIDGE_KEY,
+  osName
+} from "./chunk-AGZOVF3N.js";
+
+// src/index.ts
+import { createGuidely, normalizeAppUrl } from "@guidelytech/sdk-core";
+import { normalizeAppUrl as normalizeAppUrl2 } from "@guidelytech/sdk-core";
+var bridge = () => {
+  const g = globalThis;
+  const b = g[BRIDGE_KEY];
+  return b && typeof b.getAppInfo === "function" ? b : null;
+};
+async function getElectronAppInfo(timeoutMs = 1e3) {
+  const b = bridge();
+  if (!b) return null;
+  let timer;
+  try {
+    return await Promise.race([
+      b.getAppInfo().then((info) => info && typeof info === "object" && typeof info.appVersion === "string" ? info : null),
+      new Promise((resolve) => timer = setTimeout(() => resolve(null), timeoutMs))
+    ]);
+  } catch {
+    return null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+function electronOptions(info) {
+  return {
+    pageUrl: normalizeAppUrl,
+    ...info?.appVersion ? { appVersion: info.appVersion, release: info.appVersion } : {}
+  };
+}
+function desktopTraits(info) {
+  if (!info) return {};
+  const out = { appVersion: info.appVersion, desktopOs: osName(info.platform), desktopArch: info.arch };
+  if (info.osVersion) out.desktopOsVersion = info.osVersion;
+  if (info.electronVersion) out.electronVersion = info.electronVersion;
+  return out;
+}
+async function createGuidelyElectron(options) {
+  const { bridgeTimeoutMs, ...rest } = options;
+  const info = await getElectronAppInfo(bridgeTimeoutMs);
+  const user = rest.user ? { ...rest.user, traits: { ...desktopTraits(info), ...rest.user.traits ?? {} } } : void 0;
+  return createGuidely({ ...electronOptions(info), ...rest, ...user ? { user } : {} });
+}
+export {
+  APP_INFO_CHANNEL,
+  BRIDGE_KEY,
+  createGuidelyElectron,
+  desktopTraits,
+  electronOptions,
+  getElectronAppInfo,
+  normalizeAppUrl2 as normalizeAppUrl,
+  osName
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createGuidely, normalizeAppUrl, type GuidelyClient, type GuidelyOptions } from \"@guidelytech/sdk-core\";\nimport { BRIDGE_KEY, osName, type ElectronAppInfo, type GuidelyElectronBridge } from \"./types\";\n\nexport { APP_INFO_CHANNEL, BRIDGE_KEY, osName } from \"./types\";\nexport type { ElectronAppInfo, GuidelyElectronBridge } from \"./types\";\nexport { normalizeAppUrl } from \"@guidelytech/sdk-core\";\n\nconst bridge = (): GuidelyElectronBridge | null => {\n  const g = globalThis as unknown as Record<string, unknown>;\n  const b = g[BRIDGE_KEY] as GuidelyElectronBridge | undefined;\n  return b && typeof b.getAppInfo === \"function\" ? b : null;\n};\n\n/**\n * Renderer: the app info exposed by the preload bridge, or null when it is missing (plain browser,\n * preload not installed) or does not answer within `timeoutMs`.\n */\nexport async function getElectronAppInfo(timeoutMs = 1000): Promise<ElectronAppInfo | null> {\n  const b = bridge();\n  if (!b) return null;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  try {\n    return await Promise.race([\n      b.getAppInfo().then((info) => (info && typeof info === \"object\" && typeof info.appVersion === \"string\" ? info : null)),\n      new Promise<null>((resolve) => (timer = setTimeout(() => resolve(null), timeoutMs))),\n    ]);\n  } catch {\n    return null;\n  } finally {\n    if (timer) clearTimeout(timer);\n  }\n}\n\n/**\n * SDK options for a desktop app: app-relative page URLs for `file:` and custom protocols, the app\n * version for **App version** targeting rules and flag attributes, and the release for source-mapped\n * errors. Spread your own options after it to override.\n */\nexport function electronOptions(info: ElectronAppInfo | null): Pick<GuidelyOptions, \"pageUrl\" | \"appVersion\" | \"release\"> {\n  return {\n    pageUrl: normalizeAppUrl,\n    ...(info?.appVersion ? { appVersion: info.appVersion, release: info.appVersion } : {}),\n  };\n}\n\n/**\n * Desktop details as user traits (`desktopOs`, `desktopOsVersion`, `desktopArch`, `electronVersion`,\n * `appVersion`), for `identify(userId, { ...traits, ...desktopTraits(info) })` so targeting rules,\n * audiences and the Users list can use them.\n */\nexport function desktopTraits(info: ElectronAppInfo | null): Record<string, string> {\n  if (!info) return {};\n  const out: Record<string, string> = { appVersion: info.appVersion, desktopOs: osName(info.platform), desktopArch: info.arch };\n  if (info.osVersion) out.desktopOsVersion = info.osVersion;\n  if (info.electronVersion) out.electronVersion = info.electronVersion;\n  return out;\n}\n\n/**\n * Renderer: creates the Guidely client for an Electron window, after reading the app info from the\n * preload bridge (at most `bridgeTimeoutMs`, default 1 s; without the bridge it still works, with\n * app-relative page URLs but no app version). `options.user.traits` get the desktop traits added.\n *\n * ```ts\n * import { createGuidelyElectron } from \"@guidelytech/electron\";\n * const guidely = await createGuidelyElectron({ projectId: \"pk_prod_…\", user: { id: me.id, traits: { plan: me.plan } } });\n * ```\n */\nexport async function createGuidelyElectron(options: GuidelyOptions & { bridgeTimeoutMs?: number }): Promise<GuidelyClient> {\n  const { bridgeTimeoutMs, ...rest } = options;\n  const info = await getElectronAppInfo(bridgeTimeoutMs);\n  const user = rest.user ? { ...rest.user, traits: { ...desktopTraits(info), ...(rest.user.traits ?? {}) } } : undefined;\n  return createGuidely({ ...electronOptions(info), ...rest, ...(user ? { user } : {}) });\n}\n"],"mappings":";;;;;;;AAAA,SAAS,eAAe,uBAAgE;AAKxF,SAAS,mBAAAA,wBAAuB;AAEhC,IAAM,SAAS,MAAoC;AACjD,QAAM,IAAI;AACV,QAAM,IAAI,EAAE,UAAU;AACtB,SAAO,KAAK,OAAO,EAAE,eAAe,aAAa,IAAI;AACvD;AAMA,eAAsB,mBAAmB,YAAY,KAAuC;AAC1F,QAAM,IAAI,OAAO;AACjB,MAAI,CAAC,EAAG,QAAO;AACf,MAAI;AACJ,MAAI;AACF,WAAO,MAAM,QAAQ,KAAK;AAAA,MACxB,EAAE,WAAW,EAAE,KAAK,CAAC,SAAU,QAAQ,OAAO,SAAS,YAAY,OAAO,KAAK,eAAe,WAAW,OAAO,IAAK;AAAA,MACrH,IAAI,QAAc,CAAC,YAAa,QAAQ,WAAW,MAAM,QAAQ,IAAI,GAAG,SAAS,CAAE;AAAA,IACrF,CAAC;AAAA,EACH,QAAQ;AACN,WAAO;AAAA,EACT,UAAE;AACA,QAAI,MAAO,cAAa,KAAK;AAAA,EAC/B;AACF;AAOO,SAAS,gBAAgB,MAA0F;AACxH,SAAO;AAAA,IACL,SAAS;AAAA,IACT,GAAI,MAAM,aAAa,EAAE,YAAY,KAAK,YAAY,SAAS,KAAK,WAAW,IAAI,CAAC;AAAA,EACtF;AACF;AAOO,SAAS,cAAc,MAAsD;AAClF,MAAI,CAAC,KAAM,QAAO,CAAC;AACnB,QAAM,MAA8B,EAAE,YAAY,KAAK,YAAY,WAAW,OAAO,KAAK,QAAQ,GAAG,aAAa,KAAK,KAAK;AAC5H,MAAI,KAAK,UAAW,KAAI,mBAAmB,KAAK;AAChD,MAAI,KAAK,gBAAiB,KAAI,kBAAkB,KAAK;AACrD,SAAO;AACT;AAYA,eAAsB,sBAAsB,SAAgF;AAC1H,QAAM,EAAE,iBAAiB,GAAG,KAAK,IAAI;AACrC,QAAM,OAAO,MAAM,mBAAmB,eAAe;AACrD,QAAM,OAAO,KAAK,OAAO,EAAE,GAAG,KAAK,MAAM,QAAQ,EAAE,GAAG,cAAc,IAAI,GAAG,GAAI,KAAK,KAAK,UAAU,CAAC,EAAG,EAAE,IAAI;AAC7G,SAAO,cAAc,EAAE,GAAG,gBAAgB,IAAI,GAAG,GAAG,MAAM,GAAI,OAAO,EAAE,KAAK,IAAI,CAAC,EAAG,CAAC;AACvF;","names":["normalizeAppUrl"]}

package/dist/main.cjs

@@ -0,0 +1,66 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/main.ts
+var main_exports = {};
+__export(main_exports, {
+  APP_INFO_CHANNEL: () => APP_INFO_CHANNEL,
+  appInfo: () => appInfo,
+  setupGuidelyMain: () => setupGuidelyMain
+});
+module.exports = __toCommonJS(main_exports);
+
+// src/types.ts
+var APP_INFO_CHANNEL = "guidely:app-info";
+
+// src/main.ts
+function appInfo(app, proc = process, osRelease) {
+  const safe = (fn) => {
+    try {
+      return fn();
+    } catch {
+      return void 0;
+    }
+  };
+  const osVersion = safe(() => proc.getSystemVersion?.()) || safe(() => osRelease?.());
+  return {
+    appName: safe(() => app.getName()) ?? "app",
+    appVersion: safe(() => app.getVersion()) ?? "0.0.0",
+    platform: proc.platform,
+    arch: proc.arch,
+    ...osVersion ? { osVersion } : {},
+    ...proc.versions.electron ? { electronVersion: proc.versions.electron } : {},
+    ...proc.versions.chrome ? { chromeVersion: proc.versions.chrome } : {},
+    ...app.getLocale ? { locale: safe(() => app.getLocale()) } : {},
+    ...typeof app.isPackaged === "boolean" ? { packaged: app.isPackaged } : {}
+  };
+}
+function setupGuidelyMain(opts) {
+  const info = appInfo(opts.app, opts.process, opts.osRelease);
+  opts.ipcMain.removeHandler?.(APP_INFO_CHANNEL);
+  opts.ipcMain.handle(APP_INFO_CHANNEL, () => info);
+  return () => opts.ipcMain.removeHandler?.(APP_INFO_CHANNEL);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APP_INFO_CHANNEL,
+  appInfo,
+  setupGuidelyMain
+});
+//# sourceMappingURL=main.cjs.map

package/dist/main.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/main.ts","../src/types.ts"],"sourcesContent":["import { APP_INFO_CHANNEL, type ElectronAppInfo } from \"./types\";\n\nexport { APP_INFO_CHANNEL } from \"./types\";\nexport type { ElectronAppInfo } from \"./types\";\n\n/** The parts of Electron's `app` the helper reads (pass `import { app } from \"electron\"`). */\nexport interface ElectronAppLike {\n  getName(): string;\n  getVersion(): string;\n  getLocale?(): string;\n  isPackaged?: boolean;\n}\n\n/** The parts of Electron's `ipcMain` the helper uses. */\nexport interface IpcMainLike {\n  handle(channel: string, listener: (event: unknown, ...args: unknown[]) => unknown): void;\n  removeHandler?(channel: string): void;\n}\n\n/** Node's `process` fields read for the app info (overridable for tests). */\nexport interface ProcessLike {\n  platform: string;\n  arch: string;\n  versions: Record<string, string | undefined>;\n  getSystemVersion?: () => string;\n}\n\n/** Collects the app info Guidely reports: app name and version, OS, architecture and Electron/Chrome versions. */\nexport function appInfo(app: ElectronAppLike, proc: ProcessLike = process as unknown as ProcessLike, osRelease?: () => string): ElectronAppInfo {\n  const safe = <T>(fn: () => T): T | undefined => {\n    try {\n      return fn();\n    } catch {\n      return undefined;\n    }\n  };\n  const osVersion = safe(() => proc.getSystemVersion?.()) || safe(() => osRelease?.());\n  return {\n    appName: safe(() => app.getName()) ?? \"app\",\n    appVersion: safe(() => app.getVersion()) ?? \"0.0.0\",\n    platform: proc.platform,\n    arch: proc.arch,\n    ...(osVersion ? { osVersion } : {}),\n    ...(proc.versions.electron ? { electronVersion: proc.versions.electron } : {}),\n    ...(proc.versions.chrome ? { chromeVersion: proc.versions.chrome } : {}),\n    ...(app.getLocale ? { locale: safe(() => app.getLocale!()) } : {}),\n    ...(typeof app.isPackaged === \"boolean\" ? { packaged: app.isPackaged } : {}),\n  };\n}\n\n/**\n * Main process: answers the preload bridge's app-info request. Call once after `app` is ready:\n *\n * ```ts\n * import { app, ipcMain } from \"electron\";\n * import { setupGuidelyMain } from \"@guidelytech/electron/main\";\n * app.whenReady().then(() => { setupGuidelyMain({ app, ipcMain }); createWindow(); });\n * ```\n *\n * Returns a function that removes the handler.\n */\nexport function setupGuidelyMain(opts: { app: ElectronAppLike; ipcMain: IpcMainLike; process?: ProcessLike; osRelease?: () => string }): () => void {\n  const info = appInfo(opts.app, opts.process, opts.osRelease);\n  opts.ipcMain.removeHandler?.(APP_INFO_CHANNEL);\n  opts.ipcMain.handle(APP_INFO_CHANNEL, () => info);\n  return () => opts.ipcMain.removeHandler?.(APP_INFO_CHANNEL);\n}\n","/** What the main process knows about the desktop app, sent to the renderer over IPC. */\nexport interface ElectronAppInfo {\n  /** `app.getName()`. */\n  appName: string;\n  /** `app.getVersion()` (from package.json). */\n  appVersion: string;\n  /** `process.platform`: `darwin`, `win32`, `linux`. */\n  platform: string;\n  /** `process.arch`: `x64`, `arm64`, … */\n  arch: string;\n  /** `os.release()` / `process.getSystemVersion()`, when available. */\n  osVersion?: string;\n  electronVersion?: string;\n  chromeVersion?: string;\n  /** `app.getLocale()`. */\n  locale?: string;\n  /** `app.isPackaged`: false while running from source (`electron .`). */\n  packaged?: boolean;\n}\n\n/** The API the preload script exposes on `window.guidelyElectron`. */\nexport interface GuidelyElectronBridge {\n  getAppInfo(): Promise<ElectronAppInfo>;\n}\n\n/** IPC channel used between the main-process handler and the preload bridge. */\nexport const APP_INFO_CHANNEL = \"guidely:app-info\";\n/** Global the preload bridge is exposed as (`contextBridge.exposeInMainWorld`). */\nexport const BRIDGE_KEY = \"guidelyElectron\";\n\n/** Desktop operating system names used in Guidely device properties. */\nexport function osName(platform: string): string {\n  if (platform === \"darwin\") return \"macos\";\n  if (platform === \"win32\") return \"windows\";\n  if (platform === \"linux\") return \"linux\";\n  return platform;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC0BO,IAAM,mBAAmB;;;ADEzB,SAAS,QAAQ,KAAsB,OAAoB,SAAmC,WAA2C;AAC9I,QAAM,OAAO,CAAI,OAA+B;AAC9C,QAAI;AACF,aAAO,GAAG;AAAA,IACZ,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AACA,QAAM,YAAY,KAAK,MAAM,KAAK,mBAAmB,CAAC,KAAK,KAAK,MAAM,YAAY,CAAC;AACnF,SAAO;AAAA,IACL,SAAS,KAAK,MAAM,IAAI,QAAQ,CAAC,KAAK;AAAA,IACtC,YAAY,KAAK,MAAM,IAAI,WAAW,CAAC,KAAK;AAAA,IAC5C,UAAU,KAAK;AAAA,IACf,MAAM,KAAK;AAAA,IACX,GAAI,YAAY,EAAE,UAAU,IAAI,CAAC;AAAA,IACjC,GAAI,KAAK,SAAS,WAAW,EAAE,iBAAiB,KAAK,SAAS,SAAS,IAAI,CAAC;AAAA,IAC5E,GAAI,KAAK,SAAS,SAAS,EAAE,eAAe,KAAK,SAAS,OAAO,IAAI,CAAC;AAAA,IACtE,GAAI,IAAI,YAAY,EAAE,QAAQ,KAAK,MAAM,IAAI,UAAW,CAAC,EAAE,IAAI,CAAC;AAAA,IAChE,GAAI,OAAO,IAAI,eAAe,YAAY,EAAE,UAAU,IAAI,WAAW,IAAI,CAAC;AAAA,EAC5E;AACF;AAaO,SAAS,iBAAiB,MAAmH;AAClJ,QAAM,OAAO,QAAQ,KAAK,KAAK,KAAK,SAAS,KAAK,SAAS;AAC3D,OAAK,QAAQ,gBAAgB,gBAAgB;AAC7C,OAAK,QAAQ,OAAO,kBAAkB,MAAM,IAAI;AAChD,SAAO,MAAM,KAAK,QAAQ,gBAAgB,gBAAgB;AAC5D;","names":[]}

package/dist/main.d.cts

@@ -0,0 +1,43 @@
+import { E as ElectronAppInfo } from './types-BEnWCecg.cjs';
+export { A as APP_INFO_CHANNEL } from './types-BEnWCecg.cjs';
+
+/** The parts of Electron's `app` the helper reads (pass `import { app } from "electron"`). */
+interface ElectronAppLike {
+    getName(): string;
+    getVersion(): string;
+    getLocale?(): string;
+    isPackaged?: boolean;
+}
+/** The parts of Electron's `ipcMain` the helper uses. */
+interface IpcMainLike {
+    handle(channel: string, listener: (event: unknown, ...args: unknown[]) => unknown): void;
+    removeHandler?(channel: string): void;
+}
+/** Node's `process` fields read for the app info (overridable for tests). */
+interface ProcessLike {
+    platform: string;
+    arch: string;
+    versions: Record<string, string | undefined>;
+    getSystemVersion?: () => string;
+}
+/** Collects the app info Guidely reports: app name and version, OS, architecture and Electron/Chrome versions. */
+declare function appInfo(app: ElectronAppLike, proc?: ProcessLike, osRelease?: () => string): ElectronAppInfo;
+/**
+ * Main process: answers the preload bridge's app-info request. Call once after `app` is ready:
+ *
+ * ```ts
+ * import { app, ipcMain } from "electron";
+ * import { setupGuidelyMain } from "@guidelytech/electron/main";
+ * app.whenReady().then(() => { setupGuidelyMain({ app, ipcMain }); createWindow(); });
+ * ```
+ *
+ * Returns a function that removes the handler.
+ */
+declare function setupGuidelyMain(opts: {
+    app: ElectronAppLike;
+    ipcMain: IpcMainLike;
+    process?: ProcessLike;
+    osRelease?: () => string;
+}): () => void;
+
+export { ElectronAppInfo, type ElectronAppLike, type IpcMainLike, type ProcessLike, appInfo, setupGuidelyMain };

package/dist/main.d.ts

@@ -0,0 +1,43 @@
+import { E as ElectronAppInfo } from './types-BEnWCecg.js';
+export { A as APP_INFO_CHANNEL } from './types-BEnWCecg.js';
+
+/** The parts of Electron's `app` the helper reads (pass `import { app } from "electron"`). */
+interface ElectronAppLike {
+    getName(): string;
+    getVersion(): string;
+    getLocale?(): string;
+    isPackaged?: boolean;
+}
+/** The parts of Electron's `ipcMain` the helper uses. */
+interface IpcMainLike {
+    handle(channel: string, listener: (event: unknown, ...args: unknown[]) => unknown): void;
+    removeHandler?(channel: string): void;
+}
+/** Node's `process` fields read for the app info (overridable for tests). */
+interface ProcessLike {
+    platform: string;
+    arch: string;
+    versions: Record<string, string | undefined>;
+    getSystemVersion?: () => string;
+}
+/** Collects the app info Guidely reports: app name and version, OS, architecture and Electron/Chrome versions. */
+declare function appInfo(app: ElectronAppLike, proc?: ProcessLike, osRelease?: () => string): ElectronAppInfo;
+/**
+ * Main process: answers the preload bridge's app-info request. Call once after `app` is ready:
+ *
+ * ```ts
+ * import { app, ipcMain } from "electron";
+ * import { setupGuidelyMain } from "@guidelytech/electron/main";
+ * app.whenReady().then(() => { setupGuidelyMain({ app, ipcMain }); createWindow(); });
+ * ```
+ *
+ * Returns a function that removes the handler.
+ */
+declare function setupGuidelyMain(opts: {
+    app: ElectronAppLike;
+    ipcMain: IpcMainLike;
+    process?: ProcessLike;
+    osRelease?: () => string;
+}): () => void;
+
+export { ElectronAppInfo, type ElectronAppLike, type IpcMainLike, type ProcessLike, appInfo, setupGuidelyMain };

package/dist/main.js

@@ -0,0 +1,38 @@
+import {
+  APP_INFO_CHANNEL
+} from "./chunk-AGZOVF3N.js";
+
+// src/main.ts
+function appInfo(app, proc = process, osRelease) {
+  const safe = (fn) => {
+    try {
+      return fn();
+    } catch {
+      return void 0;
+    }
+  };
+  const osVersion = safe(() => proc.getSystemVersion?.()) || safe(() => osRelease?.());
+  return {
+    appName: safe(() => app.getName()) ?? "app",
+    appVersion: safe(() => app.getVersion()) ?? "0.0.0",
+    platform: proc.platform,
+    arch: proc.arch,
+    ...osVersion ? { osVersion } : {},
+    ...proc.versions.electron ? { electronVersion: proc.versions.electron } : {},
+    ...proc.versions.chrome ? { chromeVersion: proc.versions.chrome } : {},
+    ...app.getLocale ? { locale: safe(() => app.getLocale()) } : {},
+    ...typeof app.isPackaged === "boolean" ? { packaged: app.isPackaged } : {}
+  };
+}
+function setupGuidelyMain(opts) {
+  const info = appInfo(opts.app, opts.process, opts.osRelease);
+  opts.ipcMain.removeHandler?.(APP_INFO_CHANNEL);
+  opts.ipcMain.handle(APP_INFO_CHANNEL, () => info);
+  return () => opts.ipcMain.removeHandler?.(APP_INFO_CHANNEL);
+}
+export {
+  APP_INFO_CHANNEL,
+  appInfo,
+  setupGuidelyMain
+};
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/main.ts"],"sourcesContent":["import { APP_INFO_CHANNEL, type ElectronAppInfo } from \"./types\";\n\nexport { APP_INFO_CHANNEL } from \"./types\";\nexport type { ElectronAppInfo } from \"./types\";\n\n/** The parts of Electron's `app` the helper reads (pass `import { app } from \"electron\"`). */\nexport interface ElectronAppLike {\n  getName(): string;\n  getVersion(): string;\n  getLocale?(): string;\n  isPackaged?: boolean;\n}\n\n/** The parts of Electron's `ipcMain` the helper uses. */\nexport interface IpcMainLike {\n  handle(channel: string, listener: (event: unknown, ...args: unknown[]) => unknown): void;\n  removeHandler?(channel: string): void;\n}\n\n/** Node's `process` fields read for the app info (overridable for tests). */\nexport interface ProcessLike {\n  platform: string;\n  arch: string;\n  versions: Record<string, string | undefined>;\n  getSystemVersion?: () => string;\n}\n\n/** Collects the app info Guidely reports: app name and version, OS, architecture and Electron/Chrome versions. */\nexport function appInfo(app: ElectronAppLike, proc: ProcessLike = process as unknown as ProcessLike, osRelease?: () => string): ElectronAppInfo {\n  const safe = <T>(fn: () => T): T | undefined => {\n    try {\n      return fn();\n    } catch {\n      return undefined;\n    }\n  };\n  const osVersion = safe(() => proc.getSystemVersion?.()) || safe(() => osRelease?.());\n  return {\n    appName: safe(() => app.getName()) ?? \"app\",\n    appVersion: safe(() => app.getVersion()) ?? \"0.0.0\",\n    platform: proc.platform,\n    arch: proc.arch,\n    ...(osVersion ? { osVersion } : {}),\n    ...(proc.versions.electron ? { electronVersion: proc.versions.electron } : {}),\n    ...(proc.versions.chrome ? { chromeVersion: proc.versions.chrome } : {}),\n    ...(app.getLocale ? { locale: safe(() => app.getLocale!()) } : {}),\n    ...(typeof app.isPackaged === \"boolean\" ? { packaged: app.isPackaged } : {}),\n  };\n}\n\n/**\n * Main process: answers the preload bridge's app-info request. Call once after `app` is ready:\n *\n * ```ts\n * import { app, ipcMain } from \"electron\";\n * import { setupGuidelyMain } from \"@guidelytech/electron/main\";\n * app.whenReady().then(() => { setupGuidelyMain({ app, ipcMain }); createWindow(); });\n * ```\n *\n * Returns a function that removes the handler.\n */\nexport function setupGuidelyMain(opts: { app: ElectronAppLike; ipcMain: IpcMainLike; process?: ProcessLike; osRelease?: () => string }): () => void {\n  const info = appInfo(opts.app, opts.process, opts.osRelease);\n  opts.ipcMain.removeHandler?.(APP_INFO_CHANNEL);\n  opts.ipcMain.handle(APP_INFO_CHANNEL, () => info);\n  return () => opts.ipcMain.removeHandler?.(APP_INFO_CHANNEL);\n}\n"],"mappings":";;;;;AA4BO,SAAS,QAAQ,KAAsB,OAAoB,SAAmC,WAA2C;AAC9I,QAAM,OAAO,CAAI,OAA+B;AAC9C,QAAI;AACF,aAAO,GAAG;AAAA,IACZ,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AACA,QAAM,YAAY,KAAK,MAAM,KAAK,mBAAmB,CAAC,KAAK,KAAK,MAAM,YAAY,CAAC;AACnF,SAAO;AAAA,IACL,SAAS,KAAK,MAAM,IAAI,QAAQ,CAAC,KAAK;AAAA,IACtC,YAAY,KAAK,MAAM,IAAI,WAAW,CAAC,KAAK;AAAA,IAC5C,UAAU,KAAK;AAAA,IACf,MAAM,KAAK;AAAA,IACX,GAAI,YAAY,EAAE,UAAU,IAAI,CAAC;AAAA,IACjC,GAAI,KAAK,SAAS,WAAW,EAAE,iBAAiB,KAAK,SAAS,SAAS,IAAI,CAAC;AAAA,IAC5E,GAAI,KAAK,SAAS,SAAS,EAAE,eAAe,KAAK,SAAS,OAAO,IAAI,CAAC;AAAA,IACtE,GAAI,IAAI,YAAY,EAAE,QAAQ,KAAK,MAAM,IAAI,UAAW,CAAC,EAAE,IAAI,CAAC;AAAA,IAChE,GAAI,OAAO,IAAI,eAAe,YAAY,EAAE,UAAU,IAAI,WAAW,IAAI,CAAC;AAAA,EAC5E;AACF;AAaO,SAAS,iBAAiB,MAAmH;AAClJ,QAAM,OAAO,QAAQ,KAAK,KAAK,KAAK,SAAS,KAAK,SAAS;AAC3D,OAAK,QAAQ,gBAAgB,gBAAgB;AAC7C,OAAK,QAAQ,OAAO,kBAAkB,MAAM,IAAI;AAChD,SAAO,MAAM,KAAK,QAAQ,gBAAgB,gBAAgB;AAC5D;","names":[]}

package/dist/preload.cjs

@@ -0,0 +1,43 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/preload.ts
+var preload_exports = {};
+__export(preload_exports, {
+  exposeGuidely: () => exposeGuidely
+});
+module.exports = __toCommonJS(preload_exports);
+
+// src/types.ts
+var APP_INFO_CHANNEL = "guidely:app-info";
+var BRIDGE_KEY = "guidelyElectron";
+
+// src/preload.ts
+function exposeGuidely(opts) {
+  let cached = null;
+  const bridge = {
+    getAppInfo: () => cached ?? (cached = opts.ipcRenderer.invoke(APP_INFO_CHANNEL))
+  };
+  opts.contextBridge.exposeInMainWorld(BRIDGE_KEY, bridge);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  exposeGuidely
+});
+//# sourceMappingURL=preload.cjs.map

package/dist/preload.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/preload.ts","../src/types.ts"],"sourcesContent":["import { APP_INFO_CHANNEL, BRIDGE_KEY, type ElectronAppInfo, type GuidelyElectronBridge } from \"./types\";\n\nexport type { ElectronAppInfo, GuidelyElectronBridge } from \"./types\";\n\n/** The parts of Electron's `contextBridge` the helper uses. */\nexport interface ContextBridgeLike {\n  exposeInMainWorld(key: string, api: unknown): void;\n}\n\n/** The parts of Electron's `ipcRenderer` the helper uses. */\nexport interface IpcRendererLike {\n  invoke(channel: string, ...args: unknown[]): Promise<unknown>;\n}\n\n/**\n * Preload script: exposes `window.guidelyElectron.getAppInfo()` to the page (works with\n * `contextIsolation: true`; the page gets a function, never `ipcRenderer` itself).\n *\n * ```ts\n * // preload.ts\n * import { contextBridge, ipcRenderer } from \"electron\";\n * import { exposeGuidely } from \"@guidelytech/electron/preload\";\n * exposeGuidely({ contextBridge, ipcRenderer });\n * ```\n *\n * Sandboxed preloads (Electron's default since 20) can't `require` npm packages: bundle the preload\n * (esbuild, Vite, webpack), or copy these few lines into it.\n */\nexport function exposeGuidely(opts: { contextBridge: ContextBridgeLike; ipcRenderer: IpcRendererLike }): void {\n  let cached: Promise<ElectronAppInfo> | null = null;\n  const bridge: GuidelyElectronBridge = {\n    getAppInfo: () => (cached ??= opts.ipcRenderer.invoke(APP_INFO_CHANNEL) as Promise<ElectronAppInfo>),\n  };\n  opts.contextBridge.exposeInMainWorld(BRIDGE_KEY, bridge);\n}\n","/** What the main process knows about the desktop app, sent to the renderer over IPC. */\nexport interface ElectronAppInfo {\n  /** `app.getName()`. */\n  appName: string;\n  /** `app.getVersion()` (from package.json). */\n  appVersion: string;\n  /** `process.platform`: `darwin`, `win32`, `linux`. */\n  platform: string;\n  /** `process.arch`: `x64`, `arm64`, … */\n  arch: string;\n  /** `os.release()` / `process.getSystemVersion()`, when available. */\n  osVersion?: string;\n  electronVersion?: string;\n  chromeVersion?: string;\n  /** `app.getLocale()`. */\n  locale?: string;\n  /** `app.isPackaged`: false while running from source (`electron .`). */\n  packaged?: boolean;\n}\n\n/** The API the preload script exposes on `window.guidelyElectron`. */\nexport interface GuidelyElectronBridge {\n  getAppInfo(): Promise<ElectronAppInfo>;\n}\n\n/** IPC channel used between the main-process handler and the preload bridge. */\nexport const APP_INFO_CHANNEL = \"guidely:app-info\";\n/** Global the preload bridge is exposed as (`contextBridge.exposeInMainWorld`). */\nexport const BRIDGE_KEY = \"guidelyElectron\";\n\n/** Desktop operating system names used in Guidely device properties. */\nexport function osName(platform: string): string {\n  if (platform === \"darwin\") return \"macos\";\n  if (platform === \"win32\") return \"windows\";\n  if (platform === \"linux\") return \"linux\";\n  return platform;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC0BO,IAAM,mBAAmB;AAEzB,IAAM,aAAa;;;ADAnB,SAAS,cAAc,MAAgF;AAC5G,MAAI,SAA0C;AAC9C,QAAM,SAAgC;AAAA,IACpC,YAAY,MAAO,oBAAW,KAAK,YAAY,OAAO,gBAAgB;AAAA,EACxE;AACA,OAAK,cAAc,kBAAkB,YAAY,MAAM;AACzD;","names":[]}

package/dist/preload.d.cts

@@ -0,0 +1,30 @@
+export { E as ElectronAppInfo, G as GuidelyElectronBridge } from './types-BEnWCecg.cjs';
+
+/** The parts of Electron's `contextBridge` the helper uses. */
+interface ContextBridgeLike {
+    exposeInMainWorld(key: string, api: unknown): void;
+}
+/** The parts of Electron's `ipcRenderer` the helper uses. */
+interface IpcRendererLike {
+    invoke(channel: string, ...args: unknown[]): Promise<unknown>;
+}
+/**
+ * Preload script: exposes `window.guidelyElectron.getAppInfo()` to the page (works with
+ * `contextIsolation: true`; the page gets a function, never `ipcRenderer` itself).
+ *
+ * ```ts
+ * // preload.ts
+ * import { contextBridge, ipcRenderer } from "electron";
+ * import { exposeGuidely } from "@guidelytech/electron/preload";
+ * exposeGuidely({ contextBridge, ipcRenderer });
+ * ```
+ *
+ * Sandboxed preloads (Electron's default since 20) can't `require` npm packages: bundle the preload
+ * (esbuild, Vite, webpack), or copy these few lines into it.
+ */
+declare function exposeGuidely(opts: {
+    contextBridge: ContextBridgeLike;
+    ipcRenderer: IpcRendererLike;
+}): void;
+
+export { type ContextBridgeLike, type IpcRendererLike, exposeGuidely };

package/dist/preload.d.ts

@@ -0,0 +1,30 @@
+export { E as ElectronAppInfo, G as GuidelyElectronBridge } from './types-BEnWCecg.js';
+
+/** The parts of Electron's `contextBridge` the helper uses. */
+interface ContextBridgeLike {
+    exposeInMainWorld(key: string, api: unknown): void;
+}
+/** The parts of Electron's `ipcRenderer` the helper uses. */
+interface IpcRendererLike {
+    invoke(channel: string, ...args: unknown[]): Promise<unknown>;
+}
+/**
+ * Preload script: exposes `window.guidelyElectron.getAppInfo()` to the page (works with
+ * `contextIsolation: true`; the page gets a function, never `ipcRenderer` itself).
+ *
+ * ```ts
+ * // preload.ts
+ * import { contextBridge, ipcRenderer } from "electron";
+ * import { exposeGuidely } from "@guidelytech/electron/preload";
+ * exposeGuidely({ contextBridge, ipcRenderer });
+ * ```
+ *
+ * Sandboxed preloads (Electron's default since 20) can't `require` npm packages: bundle the preload
+ * (esbuild, Vite, webpack), or copy these few lines into it.
+ */
+declare function exposeGuidely(opts: {
+    contextBridge: ContextBridgeLike;
+    ipcRenderer: IpcRendererLike;
+}): void;
+
+export { type ContextBridgeLike, type IpcRendererLike, exposeGuidely };

package/dist/preload.js

@@ -0,0 +1,17 @@
+import {
+  APP_INFO_CHANNEL,
+  BRIDGE_KEY
+} from "./chunk-AGZOVF3N.js";
+
+// src/preload.ts
+function exposeGuidely(opts) {
+  let cached = null;
+  const bridge = {
+    getAppInfo: () => cached ?? (cached = opts.ipcRenderer.invoke(APP_INFO_CHANNEL))
+  };
+  opts.contextBridge.exposeInMainWorld(BRIDGE_KEY, bridge);
+}
+export {
+  exposeGuidely
+};
+//# sourceMappingURL=preload.js.map

package/dist/preload.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/preload.ts"],"sourcesContent":["import { APP_INFO_CHANNEL, BRIDGE_KEY, type ElectronAppInfo, type GuidelyElectronBridge } from \"./types\";\n\nexport type { ElectronAppInfo, GuidelyElectronBridge } from \"./types\";\n\n/** The parts of Electron's `contextBridge` the helper uses. */\nexport interface ContextBridgeLike {\n  exposeInMainWorld(key: string, api: unknown): void;\n}\n\n/** The parts of Electron's `ipcRenderer` the helper uses. */\nexport interface IpcRendererLike {\n  invoke(channel: string, ...args: unknown[]): Promise<unknown>;\n}\n\n/**\n * Preload script: exposes `window.guidelyElectron.getAppInfo()` to the page (works with\n * `contextIsolation: true`; the page gets a function, never `ipcRenderer` itself).\n *\n * ```ts\n * // preload.ts\n * import { contextBridge, ipcRenderer } from \"electron\";\n * import { exposeGuidely } from \"@guidelytech/electron/preload\";\n * exposeGuidely({ contextBridge, ipcRenderer });\n * ```\n *\n * Sandboxed preloads (Electron's default since 20) can't `require` npm packages: bundle the preload\n * (esbuild, Vite, webpack), or copy these few lines into it.\n */\nexport function exposeGuidely(opts: { contextBridge: ContextBridgeLike; ipcRenderer: IpcRendererLike }): void {\n  let cached: Promise<ElectronAppInfo> | null = null;\n  const bridge: GuidelyElectronBridge = {\n    getAppInfo: () => (cached ??= opts.ipcRenderer.invoke(APP_INFO_CHANNEL) as Promise<ElectronAppInfo>),\n  };\n  opts.contextBridge.exposeInMainWorld(BRIDGE_KEY, bridge);\n}\n"],"mappings":";;;;;;AA4BO,SAAS,cAAc,MAAgF;AAC5G,MAAI,SAA0C;AAC9C,QAAM,SAAgC;AAAA,IACpC,YAAY,MAAO,oBAAW,KAAK,YAAY,OAAO,gBAAgB;AAAA,EACxE;AACA,OAAK,cAAc,kBAAkB,YAAY,MAAM;AACzD;","names":[]}

package/dist/types-BEnWCecg.d.cts

@@ -0,0 +1,31 @@
+/** What the main process knows about the desktop app, sent to the renderer over IPC. */
+interface ElectronAppInfo {
+    /** `app.getName()`. */
+    appName: string;
+    /** `app.getVersion()` (from package.json). */
+    appVersion: string;
+    /** `process.platform`: `darwin`, `win32`, `linux`. */
+    platform: string;
+    /** `process.arch`: `x64`, `arm64`, … */
+    arch: string;
+    /** `os.release()` / `process.getSystemVersion()`, when available. */
+    osVersion?: string;
+    electronVersion?: string;
+    chromeVersion?: string;
+    /** `app.getLocale()`. */
+    locale?: string;
+    /** `app.isPackaged`: false while running from source (`electron .`). */
+    packaged?: boolean;
+}
+/** The API the preload script exposes on `window.guidelyElectron`. */
+interface GuidelyElectronBridge {
+    getAppInfo(): Promise<ElectronAppInfo>;
+}
+/** IPC channel used between the main-process handler and the preload bridge. */
+declare const APP_INFO_CHANNEL = "guidely:app-info";
+/** Global the preload bridge is exposed as (`contextBridge.exposeInMainWorld`). */
+declare const BRIDGE_KEY = "guidelyElectron";
+/** Desktop operating system names used in Guidely device properties. */
+declare function osName(platform: string): string;
+
+export { APP_INFO_CHANNEL as A, BRIDGE_KEY as B, type ElectronAppInfo as E, type GuidelyElectronBridge as G, osName as o };

package/dist/types-BEnWCecg.d.ts

@@ -0,0 +1,31 @@
+/** What the main process knows about the desktop app, sent to the renderer over IPC. */
+interface ElectronAppInfo {
+    /** `app.getName()`. */
+    appName: string;
+    /** `app.getVersion()` (from package.json). */
+    appVersion: string;
+    /** `process.platform`: `darwin`, `win32`, `linux`. */
+    platform: string;
+    /** `process.arch`: `x64`, `arm64`, … */
+    arch: string;
+    /** `os.release()` / `process.getSystemVersion()`, when available. */
+    osVersion?: string;
+    electronVersion?: string;
+    chromeVersion?: string;
+    /** `app.getLocale()`. */
+    locale?: string;
+    /** `app.isPackaged`: false while running from source (`electron .`). */
+    packaged?: boolean;
+}
+/** The API the preload script exposes on `window.guidelyElectron`. */
+interface GuidelyElectronBridge {
+    getAppInfo(): Promise<ElectronAppInfo>;
+}
+/** IPC channel used between the main-process handler and the preload bridge. */
+declare const APP_INFO_CHANNEL = "guidely:app-info";
+/** Global the preload bridge is exposed as (`contextBridge.exposeInMainWorld`). */
+declare const BRIDGE_KEY = "guidelyElectron";
+/** Desktop operating system names used in Guidely device properties. */
+declare function osName(platform: string): string;
+
+export { APP_INFO_CHANNEL as A, BRIDGE_KEY as B, type ElectronAppInfo as E, type GuidelyElectronBridge as G, osName as o };

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@guidelytech/electron",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.12.0",
+  "description": "Guidely for Electron apps: page paths for file:// and custom protocols, app version and OS metadata, preload bridge",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./main": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/main.js",
+      "require": "./dist/main.cjs"
+    },
+    "./preload": {
+      "types": "./dist/preload.d.ts",
+      "import": "./dist/preload.js",
+      "require": "./dist/preload.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@guidelytech/sdk-core": "0.12.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.20.5",
+    "eslint": "^9.39.5",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.0",
+    "vitest": "^3.2.7",
+    "happy-dom": "^17.6.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuidelyTech/Guidely.git",
+    "directory": "packages/electron"
+  },
+  "homepage": "https://github.com/GuidelyTech/Guidely/tree/main/packages/electron#readme",
+  "bugs": {
+    "url": "https://github.com/GuidelyTech/Guidely/issues"
+  },
+  "keywords": [
+    "guidely",
+    "electron",
+    "desktop",
+    "analytics",
+    "onboarding"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rm -rf dist"
+  }
 }