@atsignal/browser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NETHRU Inc.
+
+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

@@ -0,0 +1,25 @@
+# `@atsignal/browser`
+
+Browser SDK for Signal analytics with a default singleton, `newInstance()`, browser storage helpers, and plugin registration support.
+
+## Install
+
+```bash
+pnpm add @atsignal/browser
+```
+
+## Usage
+
+```ts
+import signal from "@atsignal/browser";
+
+await signal.init("your-api-key", {
+  persistQueue: false,
+});
+
+await signal.track("PageView");
+```
+
+Optional browser plugins are published as separate packages. For example, install `@atsignal/browser-plugin-enrich-context` and import it before using `signal.plugins.enrichContext()`.
+
+More SDK details live in the monorepo root README.

package/dist/index.cjs

@@ -0,0 +1,192 @@
+"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 src_exports = {};
+__export(src_exports, {
+  BrowserCookieStorage: () => BrowserCookieStorage,
+  BrowserLocalStorage: () => BrowserLocalStorage,
+  SignalBrowserClient: () => SignalBrowserClient,
+  default: () => src_default,
+  newInstance: () => newInstance,
+  registerBrowserPlugin: () => registerBrowserPlugin
+});
+module.exports = __toCommonJS(src_exports);
+var import_js_core2 = require("@atsignal/js-core");
+
+// src/plugin-registry.ts
+var pluginRegistry = /* @__PURE__ */ Object.create(null);
+function browserPluginRegistry() {
+  return pluginRegistry;
+}
+function registerBrowserPlugin(name, factory) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("Browser plugin registration requires a non-empty name");
+  }
+  if (typeof factory !== "function") {
+    throw new Error(`Browser plugin registration requires a factory for ${name}`);
+  }
+  pluginRegistry[name] = factory;
+}
+
+// src/storage.ts
+var import_js_core = require("@atsignal/js-core");
+function canUseDocument() {
+  return typeof document !== "undefined" && typeof document.cookie === "string";
+}
+var BrowserCookieStorage = class {
+  constructor(options = {}) {
+    var _a, _b;
+    this._options = {
+      path: (_a = options.path) != null ? _a : "/",
+      sameSite: (_b = options.sameSite) != null ? _b : "Lax",
+      secure: options.secure,
+      domain: options.domain,
+      maxAgeDays: options.maxAgeDays
+    };
+  }
+  get(key) {
+    if (!canUseDocument()) {
+      return null;
+    }
+    const encodedKey = encodeURIComponent(key);
+    const parts = document.cookie.split(";");
+    for (const part of parts) {
+      const [name, rawValue] = part.trim().split("=");
+      if (name !== encodedKey || !rawValue) {
+        continue;
+      }
+      try {
+        return JSON.parse(decodeURIComponent(rawValue));
+      } catch (e) {
+        return null;
+      }
+    }
+    return null;
+  }
+  set(key, value) {
+    if (!canUseDocument()) {
+      return;
+    }
+    const encodedKey = encodeURIComponent(key);
+    const encodedValue = encodeURIComponent(JSON.stringify(value));
+    const attributes = [`${encodedKey}=${encodedValue}`];
+    if (typeof this._options.maxAgeDays === "number" && Number.isFinite(this._options.maxAgeDays) && this._options.maxAgeDays > 0) {
+      attributes.push(`Max-Age=${Math.floor(this._options.maxAgeDays * 24 * 60 * 60)}`);
+    }
+    if (this._options.domain) {
+      attributes.push(`Domain=${this._options.domain}`);
+    }
+    if (this._options.path) {
+      attributes.push(`Path=${this._options.path}`);
+    }
+    if (this._options.sameSite) {
+      attributes.push(`SameSite=${this._options.sameSite}`);
+    }
+    if (this._options.secure) {
+      attributes.push("Secure");
+    }
+    document.cookie = attributes.join("; ");
+  }
+  remove(key) {
+    if (!canUseDocument()) {
+      return;
+    }
+    const encodedKey = encodeURIComponent(key);
+    const attributes = [`${encodedKey}=`, "Max-Age=0"];
+    if (this._options.domain) {
+      attributes.push(`Domain=${this._options.domain}`);
+    }
+    if (this._options.path) {
+      attributes.push(`Path=${this._options.path}`);
+    }
+    document.cookie = attributes.join("; ");
+  }
+};
+var BrowserLocalStorage = class {
+  constructor(storage) {
+    if (storage) {
+      this._storage = storage;
+      return;
+    }
+    if (typeof localStorage === "undefined") {
+      throw new Error("localStorage is not available in this environment");
+    }
+    this._storage = localStorage;
+  }
+  get(key) {
+    try {
+      const value = this._storage.getItem(key);
+      if (!value) {
+        return null;
+      }
+      return JSON.parse(value);
+    } catch (e) {
+      return null;
+    }
+  }
+  set(key, value) {
+    try {
+      this._storage.setItem(key, JSON.stringify(value));
+    } catch (e) {
+    }
+  }
+  remove(key) {
+    try {
+      this._storage.removeItem(key);
+    } catch (e) {
+    }
+  }
+};
+function createDefaultBrowserIdentityStorage() {
+  return canUseDocument() ? new BrowserCookieStorage() : new import_js_core.InMemoryStorage();
+}
+
+// src/index.ts
+var SignalBrowserClient = class extends import_js_core2.SignalClient {
+  resolveInitConfig(options) {
+    var _a, _b, _c, _d;
+    const identityStorage = (_b = (_a = options.storage) == null ? void 0 : _a.identity) != null ? _b : createDefaultBrowserIdentityStorage();
+    const queueStorage = options.persistQueue === false ? void 0 : (_c = options.storage) == null ? void 0 : _c.queue;
+    return {
+      ...options,
+      transport: (_d = options.transport) != null ? _d : (0, import_js_core2.createFetchTransport)({ keepalive: true }),
+      storage: {
+        identity: identityStorage,
+        ...queueStorage !== void 0 ? { queue: queueStorage } : {}
+      }
+    };
+  }
+};
+function newInstance() {
+  return new SignalBrowserClient();
+}
+var signal = Object.assign(new SignalBrowserClient(), {
+  newInstance,
+  plugins: browserPluginRegistry()
+});
+var src_default = signal;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BrowserCookieStorage,
+  BrowserLocalStorage,
+  SignalBrowserClient,
+  newInstance,
+  registerBrowserPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,47 @@
+import { ClientPlugin, KeyValueStorage, SignalClient, ClientConfig, Transport, QueueStorageInput } from '@atsignal/js-core';
+export { ClientPlugin } from '@atsignal/js-core';
+
+type BrowserPluginFactory = (...args: unknown[]) => ClientPlugin;
+type BrowserPluginRegistry = Record<string, BrowserPluginFactory>;
+declare function registerBrowserPlugin(name: string, factory: BrowserPluginFactory): void;
+
+interface CookieStorageOptions {
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    sameSite?: "Lax" | "Strict" | "None";
+    maxAgeDays?: number;
+}
+declare class BrowserCookieStorage implements KeyValueStorage {
+    private _options;
+    constructor(options?: CookieStorageOptions);
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+}
+declare class BrowserLocalStorage implements KeyValueStorage {
+    private _storage;
+    constructor(storage?: Storage);
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+}
+
+interface SignalBrowserOptions extends Omit<ClientConfig, "storage"> {
+    transport?: Transport;
+    storage?: {
+        identity?: KeyValueStorage;
+        queue?: QueueStorageInput;
+    };
+}
+declare class SignalBrowserClient extends SignalClient<SignalBrowserOptions> {
+    protected resolveInitConfig(options: SignalBrowserOptions): ClientConfig;
+}
+declare function newInstance(): SignalBrowserClient;
+type SignalBrowser = SignalBrowserClient & {
+    newInstance: typeof newInstance;
+    plugins: BrowserPluginRegistry;
+};
+declare const signal: SignalBrowser;
+
+export { BrowserCookieStorage, BrowserLocalStorage, type BrowserPluginRegistry, type CookieStorageOptions, type SignalBrowser, SignalBrowserClient, type SignalBrowserOptions, signal as default, newInstance, registerBrowserPlugin };

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { ClientPlugin, KeyValueStorage, SignalClient, ClientConfig, Transport, QueueStorageInput } from '@atsignal/js-core';
+export { ClientPlugin } from '@atsignal/js-core';
+
+type BrowserPluginFactory = (...args: unknown[]) => ClientPlugin;
+type BrowserPluginRegistry = Record<string, BrowserPluginFactory>;
+declare function registerBrowserPlugin(name: string, factory: BrowserPluginFactory): void;
+
+interface CookieStorageOptions {
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    sameSite?: "Lax" | "Strict" | "None";
+    maxAgeDays?: number;
+}
+declare class BrowserCookieStorage implements KeyValueStorage {
+    private _options;
+    constructor(options?: CookieStorageOptions);
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+}
+declare class BrowserLocalStorage implements KeyValueStorage {
+    private _storage;
+    constructor(storage?: Storage);
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+}
+
+interface SignalBrowserOptions extends Omit<ClientConfig, "storage"> {
+    transport?: Transport;
+    storage?: {
+        identity?: KeyValueStorage;
+        queue?: QueueStorageInput;
+    };
+}
+declare class SignalBrowserClient extends SignalClient<SignalBrowserOptions> {
+    protected resolveInitConfig(options: SignalBrowserOptions): ClientConfig;
+}
+declare function newInstance(): SignalBrowserClient;
+type SignalBrowser = SignalBrowserClient & {
+    newInstance: typeof newInstance;
+    plugins: BrowserPluginRegistry;
+};
+declare const signal: SignalBrowser;
+
+export { BrowserCookieStorage, BrowserLocalStorage, type BrowserPluginRegistry, type CookieStorageOptions, type SignalBrowser, SignalBrowserClient, type SignalBrowserOptions, signal as default, newInstance, registerBrowserPlugin };

package/dist/index.js

@@ -0,0 +1,166 @@
+// src/index.ts
+import {
+  SignalClient,
+  createFetchTransport
+} from "@atsignal/js-core";
+
+// src/plugin-registry.ts
+var pluginRegistry = /* @__PURE__ */ Object.create(null);
+function browserPluginRegistry() {
+  return pluginRegistry;
+}
+function registerBrowserPlugin(name, factory) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("Browser plugin registration requires a non-empty name");
+  }
+  if (typeof factory !== "function") {
+    throw new Error(`Browser plugin registration requires a factory for ${name}`);
+  }
+  pluginRegistry[name] = factory;
+}
+
+// src/storage.ts
+import { InMemoryStorage } from "@atsignal/js-core";
+function canUseDocument() {
+  return typeof document !== "undefined" && typeof document.cookie === "string";
+}
+var BrowserCookieStorage = class {
+  constructor(options = {}) {
+    var _a, _b;
+    this._options = {
+      path: (_a = options.path) != null ? _a : "/",
+      sameSite: (_b = options.sameSite) != null ? _b : "Lax",
+      secure: options.secure,
+      domain: options.domain,
+      maxAgeDays: options.maxAgeDays
+    };
+  }
+  get(key) {
+    if (!canUseDocument()) {
+      return null;
+    }
+    const encodedKey = encodeURIComponent(key);
+    const parts = document.cookie.split(";");
+    for (const part of parts) {
+      const [name, rawValue] = part.trim().split("=");
+      if (name !== encodedKey || !rawValue) {
+        continue;
+      }
+      try {
+        return JSON.parse(decodeURIComponent(rawValue));
+      } catch (e) {
+        return null;
+      }
+    }
+    return null;
+  }
+  set(key, value) {
+    if (!canUseDocument()) {
+      return;
+    }
+    const encodedKey = encodeURIComponent(key);
+    const encodedValue = encodeURIComponent(JSON.stringify(value));
+    const attributes = [`${encodedKey}=${encodedValue}`];
+    if (typeof this._options.maxAgeDays === "number" && Number.isFinite(this._options.maxAgeDays) && this._options.maxAgeDays > 0) {
+      attributes.push(`Max-Age=${Math.floor(this._options.maxAgeDays * 24 * 60 * 60)}`);
+    }
+    if (this._options.domain) {
+      attributes.push(`Domain=${this._options.domain}`);
+    }
+    if (this._options.path) {
+      attributes.push(`Path=${this._options.path}`);
+    }
+    if (this._options.sameSite) {
+      attributes.push(`SameSite=${this._options.sameSite}`);
+    }
+    if (this._options.secure) {
+      attributes.push("Secure");
+    }
+    document.cookie = attributes.join("; ");
+  }
+  remove(key) {
+    if (!canUseDocument()) {
+      return;
+    }
+    const encodedKey = encodeURIComponent(key);
+    const attributes = [`${encodedKey}=`, "Max-Age=0"];
+    if (this._options.domain) {
+      attributes.push(`Domain=${this._options.domain}`);
+    }
+    if (this._options.path) {
+      attributes.push(`Path=${this._options.path}`);
+    }
+    document.cookie = attributes.join("; ");
+  }
+};
+var BrowserLocalStorage = class {
+  constructor(storage) {
+    if (storage) {
+      this._storage = storage;
+      return;
+    }
+    if (typeof localStorage === "undefined") {
+      throw new Error("localStorage is not available in this environment");
+    }
+    this._storage = localStorage;
+  }
+  get(key) {
+    try {
+      const value = this._storage.getItem(key);
+      if (!value) {
+        return null;
+      }
+      return JSON.parse(value);
+    } catch (e) {
+      return null;
+    }
+  }
+  set(key, value) {
+    try {
+      this._storage.setItem(key, JSON.stringify(value));
+    } catch (e) {
+    }
+  }
+  remove(key) {
+    try {
+      this._storage.removeItem(key);
+    } catch (e) {
+    }
+  }
+};
+function createDefaultBrowserIdentityStorage() {
+  return canUseDocument() ? new BrowserCookieStorage() : new InMemoryStorage();
+}
+
+// src/index.ts
+var SignalBrowserClient = class extends SignalClient {
+  resolveInitConfig(options) {
+    var _a, _b, _c, _d;
+    const identityStorage = (_b = (_a = options.storage) == null ? void 0 : _a.identity) != null ? _b : createDefaultBrowserIdentityStorage();
+    const queueStorage = options.persistQueue === false ? void 0 : (_c = options.storage) == null ? void 0 : _c.queue;
+    return {
+      ...options,
+      transport: (_d = options.transport) != null ? _d : createFetchTransport({ keepalive: true }),
+      storage: {
+        identity: identityStorage,
+        ...queueStorage !== void 0 ? { queue: queueStorage } : {}
+      }
+    };
+  }
+};
+function newInstance() {
+  return new SignalBrowserClient();
+}
+var signal = Object.assign(new SignalBrowserClient(), {
+  newInstance,
+  plugins: browserPluginRegistry()
+});
+var src_default = signal;
+export {
+  BrowserCookieStorage,
+  BrowserLocalStorage,
+  SignalBrowserClient,
+  src_default as default,
+  newInstance,
+  registerBrowserPlugin
+};