ialert-web 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,7 @@
+iAlert Web SDK
+Copyright 2026 iAlert.ir
+
+This product includes software developed at iAlert.ir (https://ialert.ir).
+
+The "iAlert" name and logo are trademarks of iAlert.ir and are not
+licensed under the Apache License, Version 2.0.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# ialert-web
 
-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.
+iAlert Web SDK. It registers the browser as a `web` device of your app and receives notifications while the page is open, over iAlert's own channel: a WebSocket to the iAlert Gateway, plus the device Inbox for anything sent while the page was closed. Each notification reaches your listeners once, across both channels and page loads.
+
+Browser Web Push (VAPID, notifications while the site is closed) is not available yet; it will be added to this SDK without changing the API below.
+
+## Install
+
+```bash
+npm install ialert-web
+```
+
+## Usage
+
+```ts
+import { IAlert } from "ialert-web";
+
+const ialert = new IAlert({ publicKey: "ia_pk_live_…" });
+
+ialert.onMessage((message) => {
+    showToast(message.title, message.body, message.data);
+});
+
+await ialert.register({ externalUserId: "user-42", tags: { plan: "gold" } });
+
+// later
+await ialert.setTags({ plan: "silver", trial: null }); // merged; null removes
+await ialert.ack([message.id], "clicked");
+await ialert.unsubscribe();
+```
+
+- Use the app's **public** key (`ia_pk_…`); the constructor refuses secret keys.
+- `register()` is safe on every page load: a stable per-browser installation id maps to the same device.
+- Messages are acknowledged as `delivered` automatically (`autoAckDelivered: false` to turn off). Report `read` / `clicked` yourself.
+- Options: `apiUrl`, `gatewayUrl`, `storage` (defaults to `localStorage`, memory when blocked), `fetch`, `WebSocket`, `autoConnect`.
+- `onConnectionStateChange(state)` reports `connecting` / `ready` / `closed`.
+
+## Development
+
+```bash
+npm install
+npm test        # node --test, no browser needed
+npm run typecheck
+npm run build   # dist/
+```
+
+API reference: `docs/api-v1.md` in the iAlert server repository.
+
+## License
+
+Copyright 2026 iAlert.ir
+
+Licensed under the [Apache License, Version 2.0](LICENSE). See [NOTICE](NOTICE).

package/dist/api.d.ts

@@ -0,0 +1,34 @@
+import type { AckEvent, Device } from "./types.ts";
+type Fetch = typeof globalThis.fetch;
+export interface InboxEntry {
+    id: string;
+    content: {
+        title: string | null;
+        body: string | null;
+        image: string | null;
+        data: Record<string, unknown> | unknown[] | null;
+    };
+    collapse_id: string | null;
+    delivered_at: string | null;
+    read_at: string | null;
+    clicked_at: string | null;
+    created_at: string;
+}
+/** Thin REST client for the public-key endpoints of API v1. */
+export declare class ApiClient {
+    private readonly baseUrl;
+    private readonly publicKey;
+    private readonly fetchFn;
+    constructor(baseUrl: string, publicKey: string, fetchFn: Fetch);
+    register(body: Record<string, unknown>): Promise<{
+        data: Device;
+        device_token: string;
+    }>;
+    update(deviceId: string, deviceToken: string, body: Record<string, unknown>): Promise<Device>;
+    unsubscribe(deviceId: string, deviceToken: string): Promise<Device>;
+    /** Every Inbox page (newest first), following `links.next`, up to `maxPages`. */
+    inbox(deviceId: string, deviceToken: string, unreadOnly: boolean, maxPages?: number): Promise<InboxEntry[]>;
+    ack(deviceId: string, deviceToken: string, ids: string[], event: AckEvent): Promise<number>;
+    private request;
+}
+export {};

package/dist/api.js

@@ -0,0 +1,65 @@
+import { IAlertError } from "./errors.js";
+/** Thin REST client for the public-key endpoints of API v1. */
+export class ApiClient {
+    baseUrl;
+    publicKey;
+    fetchFn;
+    constructor(baseUrl, publicKey, fetchFn) {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.publicKey = publicKey;
+        this.fetchFn = fetchFn;
+    }
+    register(body) {
+        return this.request("POST", "/devices", body);
+    }
+    async update(deviceId, deviceToken, body) {
+        return (await this.request("PATCH", `/devices/${encodeURIComponent(deviceId)}`, body, deviceToken)).data;
+    }
+    async unsubscribe(deviceId, deviceToken) {
+        return (await this.request("POST", `/devices/${encodeURIComponent(deviceId)}/unsubscribe`, undefined, deviceToken)).data;
+    }
+    /** Every Inbox page (newest first), following `links.next`, up to `maxPages`. */
+    async inbox(deviceId, deviceToken, unreadOnly, maxPages = 5) {
+        const entries = [];
+        let url = `${this.baseUrl}/devices/${encodeURIComponent(deviceId)}/inbox?per_page=100${unreadOnly ? "&unread=1" : ""}`;
+        for (let page = 0; url !== null && page < maxPages; page++) {
+            const result = await this.request("GET", url, undefined, deviceToken);
+            entries.push(...result.data);
+            url = result.links?.next ?? null;
+        }
+        return entries;
+    }
+    async ack(deviceId, deviceToken, ids, event) {
+        let acknowledged = 0;
+        for (let start = 0; start < ids.length; start += 100) {
+            const result = await this.request("POST", `/devices/${encodeURIComponent(deviceId)}/inbox/ack`, { ids: ids.slice(start, start + 100), event }, deviceToken);
+            acknowledged += result.acknowledged;
+        }
+        return acknowledged;
+    }
+    async request(method, pathOrUrl, body, deviceToken) {
+        const headers = {
+            Accept: "application/json",
+            Authorization: `Bearer ${this.publicKey}`,
+        };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        if (deviceToken !== undefined) {
+            headers["X-Device-Token"] = deviceToken;
+        }
+        const url = pathOrUrl.startsWith("http") ? pathOrUrl : this.baseUrl + pathOrUrl;
+        let response;
+        try {
+            response = await this.fetchFn(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+        }
+        catch (error) {
+            throw new IAlertError(0, "network_error", error instanceof Error ? error.message : "Network error");
+        }
+        const payload = (await response.json().catch(() => null));
+        if (!response.ok) {
+            throw new IAlertError(response.status, typeof payload?.code === "string" ? payload.code : "server_error", typeof payload?.message === "string" ? payload.message : `HTTP ${response.status}`, payload?.errors);
+        }
+        return payload;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+/** Error returned by the iAlert API: `{ message, code, errors? }`. */
+export declare class IAlertError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly errors: Record<string, string[]> | undefined;
+    constructor(status: number, code: string, message: string, errors?: Record<string, string[]>);
+}

package/dist/errors.js

@@ -0,0 +1,13 @@
+/** Error returned by the iAlert API: `{ message, code, errors? }`. */
+export class IAlertError extends Error {
+    status;
+    code;
+    errors;
+    constructor(status, code, message, errors) {
+        super(message);
+        this.name = "IAlertError";
+        this.status = status;
+        this.code = code;
+        this.errors = errors;
+    }
+}

package/dist/gateway.d.ts

@@ -0,0 +1,47 @@
+import type { AckEvent, ConnectionState } from "./types.ts";
+/** Constructor shape of the browser WebSocket (injectable for tests and other runtimes). */
+export type WebSocketFactory = new (url: string) => WebSocket;
+export interface GatewayHandlers {
+    onReady(): void;
+    onMessage(message: Record<string, unknown>): void;
+    /** The token was rejected: reconnecting would not help. */
+    onUnauthorized(): void;
+    onStateChange(state: ConnectionState): void;
+}
+export interface GatewayOptions {
+    url: string;
+    deviceToken: string;
+    WebSocket: WebSocketFactory;
+    handlers: GatewayHandlers;
+    /** Client ping interval; the Gateway drops a socket after about 75 s of silence. */
+    pingIntervalMs?: number;
+    minReconnectMs?: number;
+    maxReconnectMs?: number;
+}
+/**
+ * One WebSocket to the iAlert Gateway: authenticates with the device token,
+ * answers pings, sends acks and reconnects with jittered exponential backoff.
+ */
+export declare class GatewayConnection {
+    private readonly options;
+    private socket;
+    private stopped;
+    private attempt;
+    private reconnectTimer;
+    private pingTimer;
+    private ready;
+    private readonly pendingAcks;
+    constructor(options: GatewayOptions);
+    get isReady(): boolean;
+    start(): void;
+    stop(): void;
+    /** Sends an ack now, or once the socket is ready again. */
+    ack(ids: string[], event: AckEvent): void;
+    private open;
+    private handleFrame;
+    private send;
+    private flushAcks;
+    private startPinging;
+    private scheduleReconnect;
+    private clearTimers;
+}

package/dist/gateway.js

@@ -0,0 +1,156 @@
+/**
+ * One WebSocket to the iAlert Gateway: authenticates with the device token,
+ * answers pings, sends acks and reconnects with jittered exponential backoff.
+ */
+export class GatewayConnection {
+    options;
+    socket = null;
+    stopped = true;
+    attempt = 0;
+    reconnectTimer = null;
+    pingTimer = null;
+    ready = false;
+    pendingAcks = [];
+    constructor(options) {
+        this.options = { pingIntervalMs: 30_000, minReconnectMs: 1_000, maxReconnectMs: 60_000, ...options };
+    }
+    get isReady() {
+        return this.ready;
+    }
+    start() {
+        if (!this.stopped) {
+            return;
+        }
+        this.stopped = false;
+        this.open();
+    }
+    stop() {
+        this.stopped = true;
+        this.clearTimers();
+        this.ready = false;
+        const socket = this.socket;
+        this.socket = null;
+        socket?.close(1000);
+        this.options.handlers.onStateChange("closed");
+    }
+    /** Sends an ack now, or once the socket is ready again. */
+    ack(ids, event) {
+        for (let start = 0; start < ids.length; start += 100) {
+            const chunk = { ids: ids.slice(start, start + 100), event };
+            if (!this.ready || !this.send({ type: "ack", ...chunk })) {
+                this.pendingAcks.push(chunk);
+            }
+        }
+    }
+    open() {
+        this.options.handlers.onStateChange("connecting");
+        let socket;
+        try {
+            socket = new this.options.WebSocket(this.options.url);
+        }
+        catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        socket.onopen = () => {
+            this.send({ type: "auth", device_token: this.options.deviceToken });
+        };
+        socket.onmessage = (event) => {
+            this.handleFrame(typeof event.data === "string" ? event.data : "");
+        };
+        socket.onclose = () => {
+            if (this.socket !== socket) {
+                return;
+            }
+            this.socket = null;
+            this.ready = false;
+            this.clearTimers();
+            if (!this.stopped) {
+                this.scheduleReconnect();
+            }
+        };
+        socket.onerror = () => {
+            // onclose follows and schedules the reconnect.
+        };
+    }
+    handleFrame(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        switch (frame.type) {
+            case "ready":
+                this.ready = true;
+                this.attempt = 0;
+                this.startPinging();
+                this.flushAcks();
+                this.options.handlers.onStateChange("ready");
+                this.options.handlers.onReady();
+                break;
+            case "message":
+                if (frame.message !== null && typeof frame.message === "object") {
+                    this.options.handlers.onMessage(frame.message);
+                }
+                break;
+            case "ping":
+                this.send({ type: "pong" });
+                break;
+            case "error":
+                if (frame.error === "device_token_invalid" || frame.error === "auth_required") {
+                    this.stopped = true;
+                    this.clearTimers();
+                    this.options.handlers.onUnauthorized();
+                }
+                break;
+        }
+    }
+    send(frame) {
+        if (this.socket === null || this.socket.readyState !== 1) {
+            return false;
+        }
+        try {
+            this.socket.send(JSON.stringify(frame));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    flushAcks() {
+        const pending = this.pendingAcks.splice(0);
+        for (const chunk of pending) {
+            if (!this.send({ type: "ack", ...chunk })) {
+                this.pendingAcks.push(chunk);
+            }
+        }
+    }
+    startPinging() {
+        this.pingTimer = setInterval(() => this.send({ type: "ping" }), this.options.pingIntervalMs);
+    }
+    scheduleReconnect() {
+        this.options.handlers.onStateChange("connecting");
+        const ceiling = Math.min(this.options.maxReconnectMs, this.options.minReconnectMs * 2 ** this.attempt);
+        const delay = ceiling / 2 + Math.random() * (ceiling / 2);
+        this.attempt++;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (!this.stopped) {
+                this.open();
+            }
+        }, delay);
+    }
+    clearTimers() {
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.pingTimer !== null) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+    }
+}

package/dist/ialert.d.ts

@@ -0,0 +1,76 @@
+import { type WebSocketFactory } from "./gateway.ts";
+import type { AckEvent, ConnectionState, Device, IAlertMessage, KeyValueStorage, RegisterOptions, TagValue, UpdateOptions } from "./types.ts";
+export declare const SDK_VERSION = "0.1.0";
+export interface IAlertOptions {
+    /** Public key of the app (`ia_pk_…`); it can only register and manage its own device. */
+    publicKey: string;
+    apiUrl?: string;
+    gatewayUrl?: string;
+    storage?: KeyValueStorage;
+    fetch?: typeof globalThis.fetch;
+    WebSocket?: WebSocketFactory;
+    /** Connect to the Gateway right after `register()`; default true. */
+    autoConnect?: boolean;
+    /** Ack "delivered" for every message handed to listeners; default true. */
+    autoAckDelivered?: boolean;
+}
+type MessageListener = (message: IAlertMessage) => void;
+type StateListener = (state: ConnectionState) => void;
+/**
+ * iAlert Web SDK. Registers the browser as a `web` device, keeps a Gateway
+ * socket open while the page is open, syncs the Inbox after every (re)connect
+ * and hands each notification to listeners exactly once.
+ */
+export declare class IAlert {
+    private readonly api;
+    private readonly store;
+    private readonly options;
+    private readonly messageListeners;
+    private readonly stateListeners;
+    private gateway;
+    private seen;
+    private syncing;
+    constructor(options: IAlertOptions);
+    /** The registered device id, or null before `register()`. */
+    get deviceId(): string | null;
+    /**
+     * Register (or re-register) this browser. Safe to call on every page load:
+     * the same installation id maps to the same device and re-subscribes it.
+     */
+    register(options?: RegisterOptions): Promise<Device>;
+    /** Update the external user id, tags (merged) or locale of this device. */
+    update(options: UpdateOptions): Promise<Device>;
+    setTags(tags: Record<string, TagValue | null>): Promise<Device>;
+    setExternalUserId(externalUserId: string | null): Promise<Device>;
+    /** Stop receiving notifications; call `register()` to subscribe again. */
+    unsubscribe(): Promise<Device>;
+    /** Open the Gateway socket (done by `register()` unless `autoConnect: false`). */
+    connect(): void;
+    disconnect(): void;
+    /**
+     * Pull Inbox entries not yet delivered here (missed while the page was closed)
+     * and hand the new ones to listeners. Concurrent calls share one request.
+     */
+    syncInbox(): Promise<IAlertMessage[]>;
+    /** Report that the user read or clicked notifications (by notification id). */
+    ack(ids: string[], event: AckEvent): Promise<void>;
+    /** Listen for notifications; returns a function that removes the listener. */
+    onMessage(listener: MessageListener): () => void;
+    onConnectionStateChange(listener: StateListener): () => void;
+    private pullInbox;
+    /** Dedupe by notification id across Gateway, Inbox and page loads. */
+    private receive;
+    private hasSeen;
+    private fromGateway;
+    private fromInbox;
+    private deviceFields;
+    /** Locale, timezone and browser details detected when the caller does not set them. */
+    private environmentFields;
+    private installationId;
+    private registration;
+    private requireRegistration;
+    /** A rejected device token means the device was deleted or unsubscribed elsewhere. */
+    private withToken;
+    private emitState;
+}
+export {};

package/dist/ialert.js

@@ -0,0 +1,301 @@
+import { ApiClient } from "./api.js";
+import { IAlertError } from "./errors.js";
+import { GatewayConnection } from "./gateway.js";
+import { Store, defaultStorage } from "./storage.js";
+export const SDK_VERSION = "0.1.0";
+const TAG_KEY = /^[A-Za-z0-9_.:-]{1,64}$/;
+const SEEN_LIMIT = 500;
+/**
+ * iAlert Web SDK. Registers the browser as a `web` device, keeps a Gateway
+ * socket open while the page is open, syncs the Inbox after every (re)connect
+ * and hands each notification to listeners exactly once.
+ */
+export class IAlert {
+    api;
+    store;
+    options;
+    messageListeners = new Set();
+    stateListeners = new Set();
+    gateway = null;
+    seen;
+    syncing = null;
+    constructor(options) {
+        if (!options.publicKey.startsWith("ia_pk_")) {
+            throw new IAlertError(0, "invalid_public_key", "Use the app's public key (ia_pk_…); secret keys must never ship to browsers.");
+        }
+        this.options = options;
+        const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.api = new ApiClient(options.apiUrl ?? "https://api.ialert.ir/api/v1", options.publicKey, fetchFn);
+        this.store = new Store(options.storage ?? defaultStorage(), options.publicKey.slice(-12));
+        this.seen = this.store.get("seen") ?? [];
+    }
+    /** The registered device id, or null before `register()`. */
+    get deviceId() {
+        return this.registration()?.deviceId ?? null;
+    }
+    /**
+     * Register (or re-register) this browser. Safe to call on every page load:
+     * the same installation id maps to the same device and re-subscribes it.
+     */
+    async register(options = {}) {
+        const result = await this.api.register({
+            platform: "web",
+            push_token: options.pushToken ?? this.installationId(),
+            sdk_version: SDK_VERSION,
+            ...this.deviceFields(options),
+            ...this.environmentFields(options),
+        });
+        this.store.set("registration", { deviceId: result.data.id, deviceToken: result.device_token });
+        if (this.options.autoConnect !== false) {
+            this.connect();
+        }
+        return result.data;
+    }
+    /** Update the external user id, tags (merged) or locale of this device. */
+    async update(options) {
+        const registration = this.requireRegistration();
+        return this.withToken(() => this.api.update(registration.deviceId, registration.deviceToken, this.deviceFields(options)));
+    }
+    setTags(tags) {
+        return this.update({ tags });
+    }
+    setExternalUserId(externalUserId) {
+        return this.update({ externalUserId });
+    }
+    /** Stop receiving notifications; call `register()` to subscribe again. */
+    async unsubscribe() {
+        const registration = this.requireRegistration();
+        this.disconnect();
+        return this.withToken(() => this.api.unsubscribe(registration.deviceId, registration.deviceToken));
+    }
+    /** Open the Gateway socket (done by `register()` unless `autoConnect: false`). */
+    connect() {
+        const registration = this.requireRegistration();
+        const WebSocketImpl = this.options.WebSocket ?? globalThis.WebSocket;
+        if (this.gateway !== null || WebSocketImpl === undefined) {
+            return;
+        }
+        this.gateway = new GatewayConnection({
+            url: this.options.gatewayUrl ?? "wss://gw.ialert.ir/v1/connect",
+            deviceToken: registration.deviceToken,
+            WebSocket: WebSocketImpl,
+            handlers: {
+                onReady: () => {
+                    void this.syncInbox().catch(() => undefined);
+                },
+                onMessage: (message) => this.receive(this.fromGateway(message)),
+                onUnauthorized: () => {
+                    this.gateway = null;
+                    this.store.remove("registration");
+                    this.emitState("closed");
+                },
+                onStateChange: (state) => this.emitState(state),
+            },
+        });
+        this.gateway.start();
+    }
+    disconnect() {
+        this.gateway?.stop();
+        this.gateway = null;
+    }
+    /**
+     * Pull Inbox entries not yet delivered here (missed while the page was closed)
+     * and hand the new ones to listeners. Concurrent calls share one request.
+     */
+    syncInbox() {
+        this.syncing ??= this.pullInbox().finally(() => {
+            this.syncing = null;
+        });
+        return this.syncing;
+    }
+    /** Report that the user read or clicked notifications (by notification id). */
+    async ack(ids, event) {
+        if (ids.length === 0) {
+            return;
+        }
+        const registration = this.requireRegistration();
+        if (this.gateway?.isReady) {
+            this.gateway.ack(ids, event);
+            return;
+        }
+        await this.withToken(() => this.api.ack(registration.deviceId, registration.deviceToken, ids, event));
+    }
+    /** Listen for notifications; returns a function that removes the listener. */
+    onMessage(listener) {
+        this.messageListeners.add(listener);
+        return () => this.messageListeners.delete(listener);
+    }
+    onConnectionStateChange(listener) {
+        this.stateListeners.add(listener);
+        return () => this.stateListeners.delete(listener);
+    }
+    async pullInbox() {
+        const registration = this.requireRegistration();
+        const entries = await this.withToken(() => this.api.inbox(registration.deviceId, registration.deviceToken, true));
+        // Oldest first, so listeners see messages in the order they were sent.
+        const received = [...entries]
+            .reverse()
+            .map((entry) => this.fromInbox(entry))
+            .filter((message) => this.receive(message, false));
+        if (this.options.autoAckDelivered !== false) {
+            const undelivered = entries.filter((entry) => entry.delivered_at === null).map((entry) => entry.id);
+            await this.ack(undelivered, "delivered").catch(() => undefined);
+        }
+        return received;
+    }
+    /** Dedupe by notification id across Gateway, Inbox and page loads. */
+    receive(message, ack = true) {
+        if (this.hasSeen(message.id)) {
+            return false;
+        }
+        this.seen.push(message.id);
+        this.seen = this.seen.slice(-SEEN_LIMIT);
+        this.store.set("seen", this.seen);
+        for (const listener of this.messageListeners) {
+            try {
+                listener(message);
+            }
+            catch (error) {
+                queueMicrotask(() => {
+                    throw error;
+                });
+            }
+        }
+        if (ack && this.options.autoAckDelivered !== false) {
+            void this.ack([message.id], "delivered").catch(() => undefined);
+        }
+        return true;
+    }
+    hasSeen(id) {
+        return this.seen.includes(id);
+    }
+    fromGateway(message) {
+        const text = (value) => (typeof value === "string" ? value : null);
+        return {
+            id: String(message.id),
+            title: text(message.title),
+            body: text(message.body),
+            image: text(message.image),
+            data: message.data !== null && typeof message.data === "object" && !Array.isArray(message.data) ? message.data : {},
+            collapse_id: text(message.collapse_id),
+            created_at: text(message.created_at),
+            source: "gateway",
+        };
+    }
+    fromInbox(entry) {
+        const data = entry.content.data;
+        return {
+            id: entry.id,
+            title: entry.content.title,
+            body: entry.content.body,
+            image: entry.content.image,
+            data: data !== null && !Array.isArray(data) ? data : {},
+            collapse_id: entry.collapse_id,
+            created_at: entry.created_at,
+            source: "inbox",
+        };
+    }
+    deviceFields(options) {
+        const fields = {};
+        if (options.externalUserId !== undefined) {
+            fields.external_user_id = options.externalUserId;
+        }
+        if (options.tags !== undefined) {
+            const invalid = Object.keys(options.tags).filter((key) => !TAG_KEY.test(key));
+            if (invalid.length > 0) {
+                throw new IAlertError(0, "invalid_tag_key", `Tag keys must match [A-Za-z0-9_.:-]{1,64}: ${invalid.join(", ")}`);
+            }
+            fields.tags = options.tags;
+        }
+        if (options.locale !== undefined) {
+            fields.locale = options.locale;
+        }
+        if (options.timezone !== undefined) {
+            fields.timezone = options.timezone;
+        }
+        if (options.appVersion !== undefined) {
+            fields.app_version = options.appVersion;
+        }
+        return fields;
+    }
+    /** Locale, timezone and browser details detected when the caller does not set them. */
+    environmentFields(options) {
+        const fields = {};
+        const navigatorInfo = globalThis.navigator;
+        if (options.locale === undefined && navigatorInfo?.language) {
+            fields.locale = navigatorInfo.language;
+        }
+        if (options.timezone === undefined) {
+            try {
+                fields.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+            }
+            catch {
+                // ignore
+            }
+        }
+        const userAgent = navigatorInfo?.userAgent;
+        if (userAgent) {
+            fields.device_model = detectBrowser(userAgent);
+            fields.os_version = navigatorInfo?.userAgentData?.platform ?? detectOs(userAgent);
+        }
+        return Object.fromEntries(Object.entries(fields).filter(([, value]) => typeof value === "string" && value !== ""));
+    }
+    installationId() {
+        let id = this.store.get("installation");
+        if (id === null) {
+            id = `ia_web_${globalThis.crypto.randomUUID()}`;
+            this.store.set("installation", id);
+        }
+        return id;
+    }
+    registration() {
+        return this.store.get("registration");
+    }
+    requireRegistration() {
+        const registration = this.registration();
+        if (registration === null) {
+            throw new IAlertError(0, "not_registered", "Call register() first.");
+        }
+        return registration;
+    }
+    /** A rejected device token means the device was deleted or unsubscribed elsewhere. */
+    async withToken(call) {
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (error instanceof IAlertError && (error.code === "device_token_invalid" || error.status === 404)) {
+                this.disconnect();
+                this.store.remove("registration");
+            }
+            throw error;
+        }
+    }
+    emitState(state) {
+        for (const listener of this.stateListeners) {
+            listener(state);
+        }
+    }
+}
+function detectBrowser(userAgent) {
+    const match = /(Edg|OPR|SamsungBrowser|Firefox|Chrome|Safari)\/(\d+)/.exec(userAgent);
+    if (match === null) {
+        return "Browser";
+    }
+    const names = { Edg: "Edge", OPR: "Opera", SamsungBrowser: "Samsung Internet" };
+    return `${names[match[1] ?? ""] ?? match[1]} ${match[2]}`;
+}
+function detectOs(userAgent) {
+    for (const [pattern, name] of [
+        [/Android/, "Android"],
+        [/iPhone|iPad|iPod/, "iOS"],
+        [/Windows/, "Windows"],
+        [/Mac OS X/, "macOS"],
+        [/Linux/, "Linux"],
+    ]) {
+        if (pattern.test(userAgent)) {
+            return name;
+        }
+    }
+    return "Unknown";
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { IAlert, SDK_VERSION, type IAlertOptions } from "./ialert.ts";
+export { IAlertError } from "./errors.ts";
+export { MemoryStorage } from "./storage.ts";
+export type { AckEvent, ConnectionState, Device, IAlertMessage, KeyValueStorage, RegisterOptions, TagValue, UpdateOptions } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { IAlert, SDK_VERSION } from "./ialert.js";
+export { IAlertError } from "./errors.js";
+export { MemoryStorage } from "./storage.js";

package/dist/storage.d.ts

@@ -0,0 +1,19 @@
+import type { KeyValueStorage } from "./types.ts";
+/** In-memory storage for environments without localStorage (private mode, workers, tests). */
+export declare class MemoryStorage implements KeyValueStorage {
+    private readonly items;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** localStorage when it works, otherwise memory (it throws in some private windows). */
+export declare function defaultStorage(): KeyValueStorage;
+/** Namespaced JSON helpers over a KeyValueStorage; never throws. */
+export declare class Store {
+    private readonly storage;
+    private readonly prefix;
+    constructor(storage: KeyValueStorage, namespace: string);
+    get<T>(key: string): T | null;
+    set(key: string, value: unknown): void;
+    remove(key: string): void;
+}

package/dist/storage.js

@@ -0,0 +1,60 @@
+/** In-memory storage for environments without localStorage (private mode, workers, tests). */
+export class MemoryStorage {
+    items = new Map();
+    getItem(key) {
+        return this.items.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.items.set(key, value);
+    }
+    removeItem(key) {
+        this.items.delete(key);
+    }
+}
+/** localStorage when it works, otherwise memory (it throws in some private windows). */
+export function defaultStorage() {
+    try {
+        const storage = globalThis.localStorage;
+        const probe = "__ialert_probe__";
+        storage.setItem(probe, "1");
+        storage.removeItem(probe);
+        return storage;
+    }
+    catch {
+        return new MemoryStorage();
+    }
+}
+/** Namespaced JSON helpers over a KeyValueStorage; never throws. */
+export class Store {
+    storage;
+    prefix;
+    constructor(storage, namespace) {
+        this.storage = storage;
+        this.prefix = `ialert:${namespace}:`;
+    }
+    get(key) {
+        try {
+            const raw = this.storage.getItem(this.prefix + key);
+            return raw === null ? null : JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    set(key, value) {
+        try {
+            this.storage.setItem(this.prefix + key, JSON.stringify(value));
+        }
+        catch {
+            // Storage full or blocked: the SDK keeps working for this page load.
+        }
+    }
+    remove(key) {
+        try {
+            this.storage.removeItem(this.prefix + key);
+        }
+        catch {
+            // ignore
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+export type TagValue = string | number | boolean;
+/** Device as returned by the iAlert API (the push token itself is never returned). */
+export interface Device {
+    id: string;
+    platform: "android" | "ios" | "web";
+    push_token_suffix: string;
+    external_user_id: string | null;
+    tags: Record<string, TagValue>;
+    locale: string | null;
+    timezone: string | null;
+    app_version: string | null;
+    sdk_version: string | null;
+    device_model: string | null;
+    os_version: string | null;
+    subscribed: boolean;
+    unsubscribed_at: string | null;
+    last_seen_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** A notification as received from the Gateway or the Inbox; `id` is the notification id. */
+export interface IAlertMessage {
+    id: string;
+    title: string | null;
+    body: string | null;
+    image: string | null;
+    data: Record<string, unknown>;
+    collapse_id: string | null;
+    created_at: string | null;
+    /** Where the SDK got it first. */
+    source: "gateway" | "inbox";
+}
+export type AckEvent = "delivered" | "read" | "clicked";
+export interface RegisterOptions {
+    externalUserId?: string | null;
+    /** Merged into existing tags; `null` removes a tag. */
+    tags?: Record<string, TagValue | null>;
+    locale?: string;
+    timezone?: string;
+    appVersion?: string;
+    /** Web Push subscription JSON once Web Push is enabled; defaults to a stable per-browser installation id. */
+    pushToken?: string;
+}
+export interface UpdateOptions {
+    externalUserId?: string | null;
+    tags?: Record<string, TagValue | null>;
+    locale?: string;
+    timezone?: string;
+    appVersion?: string;
+}
+/** Minimal key/value storage; `localStorage` matches it. */
+export interface KeyValueStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export type ConnectionState = "idle" | "connecting" | "ready" | "closed";

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "ialert-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "iAlert Web SDK: register browsers and receive notifications over the iAlert Gateway and Inbox.",
+  "keywords": [
+    "ialert",
+    "push",
+    "push-notifications",
+    "notifications",
+    "websocket",
+    "web-push"
+  ],
+  "homepage": "https://github.com/iAlert-ai/ialert-web#readme",
+  "bugs": {
+    "url": "https://github.com/iAlert-ai/ialert-web/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iAlert-ai/ialert-web.git"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3"
+  }
+}