@arsel.sa/web-sdk 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,14 +1,6 @@
 import type { ArselConfig, ArselDiagnostics, ArselIdentity, EventProperties } from './types';
-export type { ArselConfig, ArselDiagnostics, ArselIdentity, EventProperties, } from './types';
+export type { ArselConfig, ArselDiagnostics, ArselIdentity, EventProperties, InAppOptions, } from './types';
 export { SDK_VERSION } from './version';
-/**
- * Start the SDK. Idempotent — a second call returns the first one's promise, so
- * a framework that mounts twice does not mint two identities.
- *
- * Deliberately does **not** request notification permission. A prompt on page
- * load is what gets an origin permanently blocked by Chrome's abusive-
- * notification heuristics; call {@link promptForPush} from a user gesture.
- */
 export declare function init(config: ArselConfig): Promise<void>;
 /**
  * Record something the user did.
@@ -21,6 +13,23 @@ export declare function init(config: ArselConfig): Promise<void>;
  * Names beginning `arsel.` are reserved for the SDK and ignored.
  */
 export declare function track(name: string, properties?: EventProperties): Promise<void>;
+/**
+ * Record a screen or page view.
+ *
+ * One POST, two consumers: the event reaches segments and automations exactly
+ * as `track()` would, and it is the trigger source for SCREEN_VIEW in-app
+ * messages. Deliberately does NOT call `track()` — that would enqueue a second
+ * event and observe the trigger twice.
+ */
+export declare function screen(name: string, properties?: EventProperties): Promise<void>;
+/**
+ * Hold in-app messages back, or let them through again.
+ *
+ * For the moments a host app knows are wrong — a checkout step, a video
+ * playing full-screen. Not persisted: it describes the current page, not the
+ * device.
+ */
+export declare function suppressInAppMessages(suppressed: boolean): void;
 /**
  * The person using this browser, as an id you already have.
  *
@@ -69,6 +78,8 @@ export declare function flushNow(): Promise<void>;
 export declare const Arsel: {
     init: typeof init;
     track: typeof track;
+    screen: typeof screen;
+    suppressInAppMessages: typeof suppressInAppMessages;
     identify: typeof identify;
     reset: typeof reset;
     optOut: typeof optOut;

package/dist/push.d.ts

@@ -37,3 +37,19 @@ export declare function optOut(): Promise<boolean>;
  */
 export declare function reconcile(): Promise<void>;
 export declare function isSubscribed(): Promise<boolean>;
+/**
+ * Register this browser WITHOUT a push subscription.
+ *
+ * In-app messaging needs an `installationId` and a `deviceSecret` to
+ * authenticate its bundle fetch, and needs no notification permission at all.
+ * Gating that behind `promptForPush()` would restrict the whole channel to the
+ * minority who accept notifications — throwing away most of its reach.
+ *
+ * Deliberately does NOT prompt, subscribe, or touch the service worker. The
+ * refusal to prompt on load is what keeps an origin out of Chrome's abusive-
+ * notification heuristics, and this path must not become a back door to it.
+ *
+ * Single-flighted: `promptForPush()` racing `init()` must not post twice, which
+ * would mint a second `deviceSecret` and strand the first.
+ */
+export declare function registerDevice(): Promise<boolean>;

package/dist/session.d.ts

@@ -18,4 +18,8 @@ export declare const SESSION_GAP_MS: number;
  */
 export declare function onVisible(now?: number): Promise<void>;
 export declare function onHidden(now?: number): Promise<void>;
-export declare function attach(): void;
+/**
+ * @param onOpen invoked AFTER `onVisible()` resolves, so the session-start write
+ * has already landed and anything keyed on the session window reads the new one.
+ */
+export declare function attach(onOpen?: () => void): void;

package/dist/store.d.ts

@@ -7,6 +7,19 @@
  * unreachable from a worker. Splitting state across both stores would put the
  * two halves of one fact in two places.
  */
+/**
+ * The two durable queues.
+ *
+ * In-app beacons live in their OWN store, not alongside events. The events
+ * drain stops at the first retryable failure to preserve a user's history
+ * order — so a single stuck beacon sharing that queue would wedge the entire
+ * analytics pipeline behind it.
+ */
+export declare const QUEUE: {
+    readonly events: "events";
+    readonly inAppBeacons: "inapp_beacons";
+};
+export type QueueStore = (typeof QUEUE)[keyof typeof QUEUE];
 export interface PendingEvent {
     /** Monotonic within a tab; the auto-increment key doubles as delivery order. */
     id?: number;
@@ -21,10 +34,12 @@ export interface PendingEvent {
 export declare function get<T>(key: string): Promise<T | null>;
 export declare function set(key: string, value: unknown): Promise<unknown>;
 export declare function remove(key: string): Promise<unknown>;
-export declare function addEvent(body: string, idempotencyKey: string): Promise<unknown>;
-export declare function allEvents(): Promise<PendingEvent[]>;
-export declare function removeEvent(id: number): Promise<unknown>;
-export declare function countEvents(): Promise<number>;
+export declare function addEvent(store: QueueStore, body: string, idempotencyKey?: string): Promise<unknown>;
+export declare function allEvents(store: QueueStore): Promise<PendingEvent[]>;
+export declare function removeEvent(store: QueueStore, id: number): Promise<unknown>;
+export declare function countEvents(store: QueueStore): Promise<number>;
+/** Oldest-first trim, so an offline spell cannot grow the queue without bound. */
+export declare function trimQueue(store: QueueStore, max: number): Promise<void>;
 export declare const KEYS: {
     readonly clientKey: "client_key";
     readonly baseUrl: "base_url";
@@ -36,11 +51,22 @@ export declare const KEYS: {
     readonly deviceSecret: "device_secret";
     readonly vapidKeyVersion: "vapid_key_version";
     readonly endpoint: "endpoint";
+    readonly subscriptionStatus: "subscription_status";
     readonly sessionStartedAt: "session_started_at";
     readonly backgroundedAt: "backgrounded_at";
     readonly lastResponseCode: "last_response_code";
     readonly lastResponsePath: "last_response_path";
     readonly lastResponseAtMs: "last_response_at";
+    /** `{ bundleVersion, ttlSeconds, fetchedAtMs, messages }` — the cached bundle. */
+    readonly inAppBundle: "inapp_bundle";
+    /** messageId -> lifetime counters. Survives `reset()`: it describes the device. */
+    readonly inAppState: "inapp_state";
+    /**
+     * `{ startedAt, counts }`. Persisted rather than held in memory so
+     * `maxPerSession` survives a navigation — on a multi-page site an in-memory
+     * counter makes the cap per-page, which is not a cap at all.
+     */
+    readonly inAppSession: "inapp_session";
 };
 /**
  * Person-shaped identity, minted on first use. Distinct from the installation

package/dist/transport.d.ts

@@ -19,4 +19,4 @@ export declare const CODE_NO_RESPONSE = -1;
  */
 export declare function classify(code: number, authenticated: boolean): Result;
 export declare function post<T = unknown>(baseUrl: string, path: string, body: unknown, headers?: Record<string, string>, authenticated?: boolean): Promise<Response<T>>;
-export declare function getJson<T>(baseUrl: string, path: string): Promise<T | null>;
+export declare function getJson<T>(baseUrl: string, path: string, headers?: Record<string, string>, authenticated?: boolean, init?: RequestInit): Promise<Response<T>>;

package/dist/types.d.ts

@@ -26,6 +26,21 @@ export interface ArselConfig {
     serviceWorker?: 'external';
     /** Emit SDK diagnostics to the console. Off by default. */
     debug?: boolean;
+    /**
+     * In-app messaging. `true` (the default) registers this browser for in-app
+     * messages — which needs no notification permission and shows no prompt —
+     * and renders them. Pass `false` to disable, or an object to tune the layer.
+     */
+    inApp?: boolean | InAppOptions;
+}
+export interface InAppOptions {
+    /**
+     * Stacking context for the message host. Default 2147483000 — deliberately
+     * below the maximum, so a host site's own top-most modal still wins.
+     */
+    zIndex?: number;
+    /** Accessible label for the close control. Default `'Close'`. */
+    closeLabel?: string;
 }
 /** Identifiers accepted by {@link identify}. Supply whichever you hold. */
 export interface ArselIdentity {
@@ -53,6 +68,12 @@ export interface WebPushConfig {
 export interface ArselDiagnostics {
     sdkVersion: string;
     initialized: boolean;
+    /**
+     * Why the SDK refused to start, or null. Set when init() was given an invalid
+     * configuration: nothing is collected and no call has any effect until it is
+     * fixed. Same field, same rules, on all three Arsel SDKs.
+     */
+    configError: string | null;
     anonymousId: string | null;
     hasAssertedIdentity: boolean;
     installationId: string | null;
@@ -61,8 +82,19 @@ export interface ArselDiagnostics {
     pendingEvents: number;
     permission: NotificationPermission | 'unsupported';
     isSubscribed: boolean;
+    /**
+     * The backend's last reported `status` for this device, e.g. `REVOKED` after a
+     * durable opt-out. Named as on the Android SDK. Null before the first register.
+     */
+    subscriptionStatus: string | null;
     vapidKeyVersion: number | null;
     lastResponseCode: number | null;
     lastResponsePath: string | null;
     lastResponseAtMs: number | null;
+    /** Messages currently cached for this device. */
+    inAppMessages: number;
+    inAppBundleVersion: string | null;
+    inAppFetchedAtMs: number | null;
+    /** Beacons persisted but not yet delivered. A number that only grows is the tell. */
+    pendingInAppBeacons: number;
 }

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * In its own module so transport can stamp `X-Arsel-SDK` without importing the
  * public surface (index → events → transport would be a cycle).
  */
-export declare const SDK_VERSION = "1.0.0";
+export declare const SDK_VERSION = "1.1.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arsel.sa/web-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Arsel web SDK — events, identity and web push.",
   "license": "MIT",
   "author": "Arsel (https://arsel.sa)",
@@ -53,6 +53,7 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "fake-indexeddb": "^6.0.0",
+    "happy-dom": "^15.11.0",
     "typescript": "^5.7.2",
     "vite": "^6.0.0",
     "vitest": "^2.1.8"

package/sw/arsel-sw.js

@@ -15,9 +15,11 @@
 
 // Duplicated from src/ on purpose — this file is served as-is, uncompiled, and
 // cannot import from the SDK build. Change a constant there, change it here.
-const SDK_VERSION = '1.0.0';
+const SDK_VERSION = '1.1.0';
 const DB_NAME = 'arsel';
 const KV_STORE = 'kv';
+/** Reserved data key: refresh the in-app bundle, render nothing. */
+const IAM_SYNC_KEY = 'arsel_iam_sync';
 
 /** `showNotification` silently drops anything past this in Chrome. */
 const MAX_ACTIONS = 2;
@@ -48,7 +50,14 @@ function openDb() {
 
 async function readKeys(keys) {
   const db = await openDb();
-  if (!db.objectStoreNames.contains(KV_STORE)) return {};
+  // Closed on every path below. openDb() opens WITHOUT a version, so a
+  // connection left open here holds the database at its current version and
+  // makes the page's next upgrade fire `blocked` — hanging until this worker is
+  // terminated.
+  if (!db.objectStoreNames.contains(KV_STORE)) {
+    db.close();
+    return {};
+  }
   const store = db.transaction(KV_STORE, 'readonly').objectStore(KV_STORE);
   const entries = await Promise.all(
     keys.map(
@@ -60,6 +69,7 @@ async function readKeys(keys) {
         }),
     ),
   );
+  db.close();
   return Object.fromEntries(entries);
 }
 
@@ -132,6 +142,21 @@ self.addEventListener('push', (event) => {
   } catch {
     return; // not ours, and not parseable
   }
+  // The in-app sync ping is checked BEFORE the claim test below: it carries no
+  // messageId and no title, so it must never reach showNotification and must
+  // never report a `delivered` engagement for a message that was never shown.
+  //
+  // Inert-but-ready — nothing on the backend emits this key yet. Bundle refresh
+  // is driven entirely by init, visibility and the bundle's own TTL.
+  if (data[IAM_SYNC_KEY]) {
+    event.waitUntil(
+      (async () => {
+        const clients = await self.clients.matchAll({ type: 'window' });
+        for (const client of clients) client.postMessage({ type: IAM_SYNC_KEY });
+      })(),
+    );
+    return;
+  }
   // Claimed on arsel_v, with arsel_mid as the fallback — the same test the
   // Android parser applies. There is no marker key on the wire.
   if (!data[WIRE.VERSION] && !data[WIRE.MESSAGE_ID]) return;