@levo-so/insights 0.3.10 → 0.3.12

package/dist/lib/identityHeaders.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The identity headers a consumer should attach to a Levo API call it makes
+ * itself, resolved from the SDK's current state in one read.
+ *
+ * Exists so chat, popups and other surfaces never reach into the stores or
+ * re-derive the transport rules. The header names and the mode gate live in
+ * utils/getAuthHeaders.ts, which this wraps with a state read; the transport
+ * uses that formatter directly with flush-time ids. The rules in one place:
+ *
+ * - Confirmed proxy: empty. The request is same-origin, the browser attaches
+ *   `id_i_cd`/`id_i_cs` itself, and the server reads those. Adding headers
+ *   would say the same thing twice.
+ * - Anything else, an unproven candidate included: the client headers carry
+ *   the ids, plus the legacy device JWT when one is still around, which the
+ *   server ranks above the client mint.
+ *
+ * Call it per request, never once at setup. `getIdentity()` applies the idle
+ * cut at read time, so a chat message sent after a rotation carries the new
+ * session where a snapshot taken at mount would still name the old one.
+ */
+declare const getIdentityHeaders: () => Record<string, string>;
+export { getIdentityHeaders, };

package/dist/lib/insights.d.ts

@@ -7,7 +7,8 @@ import { IInsightOptions } from '../types/options';
  * Two independent pipelines run on init():
  *   - Identity pipeline: session hydration → user properties + referrer.
  *     Always runs. Powers DOM trackers and store-only consumers (popups).
- *   - Network pipeline: detectMode → /welcome → event flushing.
+ *   - Network pipeline: detectMode → event flushing. No separate
+ *     establishment step. The first event resolves identity server-side.
  *     Runs only when insightsUrl is configured.
  *
  * @param client - The Levo control instance containing workspace config

package/dist/lib/rotation.d.ts

@@ -0,0 +1,42 @@
+import { IClientIdentity, rotateSession as rotate } from '../stores/identity';
+/**
+ * The public rotation API: the same three calls as `stores/identity`, but each
+ * drains the event queue before rotating.
+ *
+ * Why they live in their own module rather than on the store.
+ *
+ * `stores/events` already imports `stores/identity` (peekIdentity and
+ * touchActivity are read at queue and flush time), so the store cannot import
+ * the queue back without creating a cycle. That cycle is not a theoretical
+ * concern dressed up as one: it survives development and bundling, because
+ * both sides only reach each other from inside function bodies, and it breaks
+ * silently the first time anyone adds a call at module scope. This module is
+ * the third party that depends on both and is depended on by neither, which is
+ * the only shape that removes the cycle rather than hiding it.
+ *
+ * The store's own `rotateSession` also stays flush-free, so that nothing in the
+ * identity layer can re-enter the queue. That is a property worth keeping
+ * rather than a live hazard: the read-time idle cut mints inline instead of
+ * calling `rotateSession`, and `flushEventQueue` reads through `peekIdentity`,
+ * so neither reaches it today.
+ *
+ * Why drain first at all: the session id is resolved at SEND time, not when an
+ * event was queued. A click queued 200ms before sign-out would otherwise land
+ * on the post-sign-out anonymous session, and on an account switch the
+ * outgoing account's events would be attributed to the incoming one, the
+ * exact confusion the rotation exists to prevent.
+ */
+/**
+ * Note a sign-in, draining anything still queued onto the pre-sign-in session.
+ *
+ * Stores nothing and never rotates: the server binds the user itself from the
+ * membership cookie on every proxied request, and rotation is the host
+ * application's sign-out calling {@link reset}. `accountId` is accepted only so
+ * existing callers keep compiling; it is logged in debug and otherwise unused.
+ */
+declare const identify: (accountId?: string) => IClientIdentity;
+/** Sign-out. Drains the queue onto the old session, then starts a new one. */
+declare const reset: () => IClientIdentity;
+/** Low-level escape hatch for cases `identify`/`reset` don't cover. */
+declare const rotateSession: (reason?: Parameters<typeof rotate>[0]) => IClientIdentity;
+export { identify, reset, rotateSession, };

package/dist/lib/transport.d.ts

@@ -0,0 +1,45 @@
+import { IEndpoint } from '../types/endpoint';
+/**
+ * Getting one batch to Levo, and working out where Levo actually is.
+ *
+ * Separate from the event queue on purpose: the queue decides WHAT to send and
+ * WHEN, this decides WHERE and deals with the answer. It is the only place that
+ * promotes an endpoint or adopts a device id, so "what happens when the proxy
+ * 404s?" is one file, not a paragraph inside a store.
+ *
+ * fetch+keepalive, not sendBeacon: sendBeacon can't read a response body, and
+ * the device-adoption signal (content.meta.device) only exists there. keepalive
+ * fetch has the same unload-survival guarantee sendBeacon does (it was designed
+ * as sendBeacon's superset), so this isn't a reliability downgrade.
+ */
+interface ISendBatch {
+    /** Legacy direct-mode device JWT, forwarded when present. */
+    deviceToken: string | null;
+    deviceId: string;
+    endpoint: IEndpoint;
+    /** Events in this batch, for the log line when it is lost. */
+    eventCount: number;
+    onFailure: () => void;
+    onSuccess: () => void;
+    /** Already-serialized envelope. Serializing is the queue's job, not ours. */
+    serialized: string;
+    sessionId: string;
+    workspace: string;
+}
+/**
+ * Send one batch, proving the endpoint on the way if it is unproven.
+ *
+ * A batch is sent at most twice, and the second attempt only happens while the
+ * endpoint is still unproven. Once an endpoint is proven, a rejected batch is
+ * gone and stays gone: re-sending it would spend the per-IP abuse budget that
+ * blocks the visitor once enough failures land in a short window.
+ *
+ * The unproven case deliberately resends on ANY non-ours answer, including a
+ * 4xx from our own API. That costs one strike when the proxy really was ours,
+ * which is the price of not stranding a visitor whose proxy is not wired up.
+ *
+ * Exactly one of `onSuccess`/`onFailure` fires, which is what lets the caller
+ * hand over a chunk of session traits and learn whether the server got it.
+ */
+declare const sendBatch: (options: ISendBatch) => void;
+export { sendBatch, };

package/dist/stores/events.d.ts

@@ -3,7 +3,7 @@ import { ILevoAudience } from '../types/analytics';
  * An event pending delivery in the queue.
  *
  * track() captures every per-event field at track time (host/page/tab context,
- * resource, identifier, timestamp), so they are all required here — flush trusts
+ * resource, identifier, timestamp), so they are all required here, flush trusts
  * the queued event and does not re-default them. The only fields absent are the
  * session/config ones, which {@link flushEventQueue} merges in at send time.
  */
@@ -13,22 +13,18 @@ declare const $lifetimePageCount: import('nanostores').PreinitializedWritableAto
 declare const $totalEventCount: import('nanostores').ReadableAtom<number>;
 declare const getEventQueue: () => IQueuedEvent[];
 /**
- * Flush all queued events to the server.
+ * Build the envelope from everything currently queued and hand it to the
+ * transport.
  *
- * This function:
- * 1. Takes all events from the queue
- * 2. Merges context from stores (workspace, session, tab info)
- * 3. Sends to /v1/insights/event/bulk via sendBeacon (preferred) or fetch
+ * The queue is the source of truth. It is read and cleared here, never passed
+ * in. The request describes the VISIT once (the `session` key) and the actions
+ * as an array; a bare array is not a stale-but-tolerated shape, the server logs
+ * it as a security event and 400s the whole request.
  *
- * sendBeacon is preferred because:
- * - It survives page unload (critical for page exit events)
- * - It doesn't block the main thread
- * - Browser queues it and sends when convenient
- *
- * fetch with keepalive is the fallback for when sendBeacon fails or
- * isn't available.
+ * No identification gate: identity is resolved client-side, synchronously,
+ * before this ever runs. The only readiness this waits on is a usable endpoint.
  */
-declare const flushEventQueue: (_eventQueue: IQueuedEvent[]) => void;
+declare const flushEventQueue: () => void;
 /**
  * Add an event to the queue for batched sending.
  * Only stores in-time data (event, properties, page context).
@@ -39,6 +35,5 @@ declare const resetRateLimit: () => void;
 /**
  * Clear all pending events and reset state.
  */
-export declare const clearEventQueue: () => void;
-export type { IQueuedEvent };
-export { $eventQueue, $lifetimePageCount, $totalEventCount, queueEvent, resetRateLimit, getEventQueue, flushEventQueue, };
+declare const clearEventQueue: () => void;
+export { type IQueuedEvent, $eventQueue, $lifetimePageCount, $totalEventCount, clearEventQueue, flushEventQueue, getEventQueue, queueEvent, resetRateLimit, };

package/dist/stores/identity.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Client-minted identity: two ids, and nothing else.
+ *
+ * Everything a visit needs beyond the ids is derived on the page that needs it.
+ * The session's start time and landing url are read from the clock and the
+ * address bar when the traits are staged, because the server sets `created_at`
+ * and `url` only when it CREATES the session row and never patches them after
+ *, so they are correct exactly on the page where the session begins, which is
+ * the page that creates the row. Liveness is the session cookie's own expiry.
+ * The signed-in account is the server's business: it reads the membership
+ * access-token cookie on every proxied request and binds the user itself.
+ *
+ * Dropping the rest removed a whole class of bug rather than guarding it. There
+ * are no persisted timestamps left, so a corrected phone clock cannot pin a
+ * session or date one in the future; there is no session-scoped metadata, so
+ * nothing can be paired with the wrong session id.
+ *
+ * NOTE FOR FUTURE EDITS: this module must never import from `stores/events`.
+ * `stores/events` imports THIS module, so an import back is a cycle, one that
+ * survives dev and bundling, because both sides only call each other from
+ * inside function bodies, and breaks the day someone adds a call at module
+ * scope. The public flush-then-rotate API lives in `lib/rotation.ts`.
+ */
+interface IClientIdentity {
+    /** Durable per-browser id. Minted once, never rotated by the SDK. */
+    device_id: string;
+    session_id: string;
+}
+/**
+ * 30 minutes of inactivity ends a session, matching the server's cut
+ * (`create_or_reset_session`) and GA4's session timeout.
+ */
+declare const SESSION_IDLE_MS: number;
+/**
+ * The last identity this page resolved.
+ *
+ * A write-through copy for consumers that want to react to a change, and the
+ * source for {@link peekIdentity}. It is NOT the source of truth: the store is,
+ * and it is read on demand so a rotation in another tab is visible here without
+ * a `storage` listener or a handshake.
+ */
+declare const $identity: import('nanostores').PreinitializedWritableAtom<IClientIdentity | null> & object;
+/**
+ * Resolve identity for this page load and write it back.
+ *
+ * Writing back is what refreshes the session cookie's expiry, so a page load
+ * counts as activity.
+ */
+declare const hydrateIdentity: () => IClientIdentity;
+/**
+ * The current identity, re-read from the store.
+ *
+ * Reading resolves the idle cut for free: an abandoned session's cookie has
+ * expired and its stored expiry has passed, so `resolve()` mints a new session
+ * id without anything having to compare timestamps.
+ */
+declare const getIdentity: () => IClientIdentity;
+/**
+ * The last resolved identity, without re-reading the store.
+ *
+ * Exists for exit events. `page.bounce` and `user.idle` report the visitor's
+ * absence, and a tab left open past the idle window then closed would otherwise
+ * resolve to a freshly minted session and hand it the bounce, one phantom
+ * single-event session per abandoned tab. An exit event belongs to the session
+ * that was alive when the page was.
+ */
+declare const peekIdentity: () => IClientIdentity;
+/**
+ * Keep the session alive.
+ *
+ * Called on page loads, SPA route changes, and any event that signals a person
+ * is there (see IDLE_CLOCK_EXEMPT_EVENTS in stores/events.ts). The work is
+ * rewriting the session cookie's Max-Age and the stored expiry, the clock is
+ * the storage layer's, not a field this module maintains.
+ */
+declare const touchActivity: () => void;
+/**
+ * Mint a new session id, keeping the device.
+ *
+ * `reason` surfaces only in debug logging: a rotation is indistinguishable
+ * server-side however it was triggered, so it exists to make one explainable to
+ * somebody watching the console.
+ */
+declare const rotateSession: (reason?: "idle" | "reset" | "account-switch") => IClientIdentity;
+/**
+ * Adopt a device id the server resolved and echoed back
+ * (`content.meta.device` on a `/v2/insights/event/bulk` response), because it
+ * differs from what this SDK sent. Legacy adoption or Safari-purge repair. The
+ * session is never touched: the server never echoes one.
+ */
+declare const adoptDevice: (deviceId: string) => void;
+/**
+ * Note that a visitor has signed in.
+ *
+ * Binding the account is the SERVER's job: it reads the membership
+ * access-token cookie on every proxied request and writes `user_id` onto the
+ * session row itself. So this stores nothing, and `accountId` is accepted only
+ * so an existing caller keeps compiling. It is logged in debug and otherwise
+ * unused.
+ *
+ * Rotation is left to {@link reset}, which the host application calls on
+ * sign-out. That is what keeps two accounts off one session: A signs out and
+ * rotates, then B signs in on a session that was never A's. Rotating here as
+ * well would start a second session for a visitor who merely reloaded a page
+ * while signed in, and would truncate the backend's device-keyed walk over the
+ * anonymous history that precedes a first sign-in.
+ */
+declare const identify: (accountId?: string) => IClientIdentity;
+/** Sign-out. New session id, same device. */
+declare const reset: () => IClientIdentity;
+export { type IClientIdentity, $identity, SESSION_IDLE_MS, adoptDevice, getIdentity, hydrateIdentity, identify, peekIdentity, reset, rotateSession, touchActivity, };

package/dist/stores/readiness.d.ts

@@ -1,22 +1,22 @@
 /**
- * Identity pipeline gate — flipped when getUserProperties + getReferrer
+ * Identity pipeline gate. Flipped when getUserProperties + getReferrer
  * have settled and the result has been written to $session.identity.
  * Independent of network configuration.
  */
 declare const $isIdentityReady: import('nanostores').PreinitializedWritableAtom<boolean> & object;
 /**
- * Network pipeline gate — flipped when detectMode has resolved (or was
- * skipped because $session.insightsBaseUrl was already cached). Stays
- * false forever when no insightsUrl is configured.
+ * Network pipeline gate, flipped once an endpoint has been chosen, whether by
+ * detectMode or by reusing the proven one already in $session. Stays false
+ * forever when no insightsUrl is configured.
  */
 declare const $isBaseUrlReady: import('nanostores').PreinitializedWritableAtom<boolean> & object;
 /**
  * Local-store readiness. Trackers and tracker-only consumers (popups) gate
- * on this — they need session + identity, not a resolved base URL.
+ * on this. They need session + identity, not a resolved base URL.
  */
 declare const $isIdentityContextReady: import('nanostores').ReadableAtom<boolean>;
 /**
- * Network readiness. /welcome and the initial page view gate on this.
+ * Network readiness. The initial page view gates on this.
  * Implies identity context is ready and a usable base URL is known.
  */
 declare const $isNetworkReady: import('nanostores').ReadableAtom<boolean>;

package/dist/stores/session.d.ts

@@ -1,35 +1,26 @@
+import { IEndpoint } from '../types/endpoint';
 import { IIdentity } from '../types/identity';
 interface ISession {
     /**
-     * True once /welcome has succeeded for this browser session.
-     * Persisted in sessionStorage (not localStorage) so it resets when the browser
-     * session ends — matching the lifetime of the HttpOnly proxy cookie.
+     * Legacy direct-mode device JWT, restored from localStorage on hydration.
+     * Written only by an old SDK version, never by this one. Forwarded as the
+     * primary device credential pre-adoption, see identity model, Part 2.
      */
-    isIdentified: boolean;
+    deviceToken: string | null;
     /**
-     * True while a /welcome request is in flight.
-     * Always reset to false on page load; no fetch survives a reload, so a
-     * persisted true is always a stale lock from a previous page load or crash.
+     * Where events go for this session, and whether that is proven. Persisted,
+     * so a proven endpoint never has to be re-proven on a later page load.
      */
-    isIdentifying: boolean;
-    sessionId: string | null;
-    deviceId: string | null;
-    /** Direct-mode JWT. Stored in localStorage; survives browser restarts. */
-    deviceToken: string | null;
-    /** Direct-mode JWT. Stored in localStorage; survives browser restarts. */
-    sessionToken: string | null;
-    mode: "proxy" | "direct";
-    insightsBaseUrl: string | null;
+    endpoint: IEndpoint;
     identity: IIdentity | null;
 }
 declare const $session: import('nanostores').PreinitializedWritableAtom<ISession> & object;
 /**
- * Becomes true once the session is loaded from storage (synchronous for
- * localStorage, up to 150ms for BroadcastChannel handshake). Downstream
- * pipelines (identity, network) gate on this so writes via updateSession
- * survive the BroadcastChannel full-replace handshake.
+ * Becomes true once the session is loaded from storage. Synchronous in every
+ * path now that the cross-tab handshake is gone; downstream pipelines still
+ * gate on it so they read hydrated state rather than defaults.
  */
 declare const $isSessionHydrated: import('nanostores').PreinitializedWritableAtom<boolean> & object;
 declare const getSession: () => ISession;
 declare const updateSession: (v: Partial<ISession>) => void;
-export { $session, $isSessionHydrated, getSession, updateSession, type ISession };
+export { type ISession, $isSessionHydrated, $session, getSession, updateSession, };

package/dist/stores/sessionProperties.d.ts

@@ -0,0 +1,116 @@
+import { ILevoAudience } from '../types/analytics';
+/**
+ * The visit's facts, waiting to be sent.
+ *
+ * They do not all arrive at once. The referrer and screen size are there as
+ * soon as identity resolves, the battery and camera answers a few hundred
+ * milliseconds later, and each is sent once, never resent.
+ *
+ * Two buckets:
+ *
+ * - `staged` waiting to ride the next request.
+ * - `sent`   the server has them, so they are not sent again.
+ *
+ * `sent` is NOT a dedup filter for repeated offers, facts are staged exactly
+ * once, at init, and nothing re-offers them. It exists for ROTATION: a new
+ * session row must be told everything the old one was told, and the late
+ * device probes (battery, GPU, camera) exist nowhere else once sent. Without
+ * `sent`, a rotated session silently loses its referrer, locale, timezone and
+ * device bag. Verified against a capture server, not theorised.
+ *
+ * A chunk handed to a request in flight is held by that request's own closure
+ * rather than a third bucket: that is what makes overlapping flushes safe, and
+ * it means a failed request puts back precisely what it was carrying.
+ */
+interface ISessionPropertiesState {
+    /**
+     * The session `staged` describes. A rotation makes it meaningless, so the id
+     * is stored beside it rather than assumed.
+     */
+    session_id: string | null;
+    /** Acknowledged by the server. Kept only so a rotation can re-send them. */
+    sent: ILevoAudience.SessionTraits;
+    staged: ILevoAudience.SessionTraits;
+}
+/**
+ * Not persisted, deliberately. A battery reading is a point in time and what a
+ * visit has already told the server is a fact about this page load's requests,
+ * so restoring either from a previous load would be wrong in both directions.
+ */
+declare const $sessionProperties: import('nanostores').PreinitializedWritableAtom<ISessionPropertiesState> & object;
+/**
+ * Offer facts about the visit. Merged into whatever is already waiting;
+ * `properties` key-merges rather than replacing, because the device bag is
+ * assembled from two independent sources and the late half must not erase the
+ * early half.
+ *
+ * A different session id replaces everything: after a rotation the new visit
+ * has its own row, and what the previous one was told is not true of it.
+ */
+declare const stageSessionTraits: (sessionId: string, traits: ILevoAudience.SessionTraits) => void;
+/**
+ * Hand the staged facts to a request that is about to go out, and clear them.
+ *
+ * Returns null when there is nothing to send, so the caller can leave the
+ * `session` key off the envelope entirely, an empty object still reads to the
+ * server as a trait-carrying request and fires its patch path for nothing.
+ *
+ * The caller owns what it is given until the request settles, and must hand it
+ * back to exactly one of {@link commitSentTraits} or {@link restageTraits}.
+ * Clearing here is what makes an overlapping second flush carry nothing rather
+ * than duplicate the first one's chunk.
+ */
+declare const takeStagedTraits: (sessionId: string) => ILevoAudience.SessionTraits | null;
+/**
+ * The request landed: remember the chunk it carried, so a later rotation can
+ * tell the new session row the same things. This is the ONLY reason `sent`
+ * exists. Nothing consults it to decide what to send now.
+ *
+ * When the session rotated while the request was in flight, the chunk is put
+ * back for the NEW session instead of being recorded. It reached the old
+ * session's row, not the new one, and the new row starts blank, dropping it
+ * here is what used to cost every sign-out and account switch its referrer,
+ * locale and device bag, because `rotation.ts` flushes immediately before
+ * rotating and so all but guarantees a request is open at that moment.
+ */
+declare const commitSentTraits: (sessionId: string, chunk: ILevoAudience.SessionTraits | null) => void;
+/**
+ * The request did not land: put its chunk back for the next one.
+ *
+ * Without this a single failed request would cost the visit its referrer,
+ * landing url and device bag permanently, each is offered once, so a chunk
+ * marked delivered by a request that never arrived is never offered again, and
+ * the visit stays "direct" with no landing page while the visitor keeps
+ * browsing. Re-staging is not a retry: nothing is re-sent on its own and no
+ * extra request is made; the facts simply ride whatever goes out next.
+ */
+declare const restageTraits: (sessionId: string, chunk: ILevoAudience.SessionTraits | null) => void;
+/**
+ * Carry the visit's facts onto a new session id after a rotation.
+ *
+ * The new visit needs the same referrer, locale and device bag the old one had.
+ * The server tracks them per session row, so they have to be told again. What it
+ * does NOT need is the old landing url or start time. Those two describe the session, not
+ * the visitor, and the caller passes the new ones in. Re-collecting the rest
+ * instead would lose what cannot be re-read cheaply (the referrer of a page the
+ * visitor has already navigated away from).
+ */
+declare const restageForSession: (sessionId: string, sessionScoped: Pick<ILevoAudience.SessionTraits, "created_at" | "url">) => void;
+/**
+ * Forget the visit entirely. Reached only from destroy(), via clearEventQueue().
+ * A sign-out deliberately does NOT come here: reset() rotates, and rotation
+ * carries the visitor's facts onto the new session rather than dropping them.
+ */
+declare const clearSessionProperties: () => void;
+/**
+ * Collect the half of the device picture the browser cannot answer
+ * synchronously, and stage it when it arrives.
+ *
+ * Fire-and-forget by design: nothing awaits this and no gate depends on it, so
+ * a visitor who leaves first keeps everything that matters and loses only
+ * battery/camera/private-mode.
+ *
+ * Takes a getter, not an id: see the resolve-time note below.
+ */
+declare const loadAsyncProperties: (currentSessionId: () => string) => void;
+export { type ISessionPropertiesState, $sessionProperties, clearSessionProperties, commitSentTraits, loadAsyncProperties, restageForSession, restageTraits, stageSessionTraits, takeStagedTraits, };

package/dist/stores.d.ts

@@ -1,5 +1,6 @@
 export { $config } from './stores/config';
 export { $eventQueue, $lifetimePageCount, $totalEventCount } from './stores/events';
+export { $identity, getIdentity } from './stores/identity';
 export { $isIdentityContextReady } from './stores/readiness';
 export { $session } from './stores/session';
 export { $activity } from './tracking/activity';

package/dist/stores.js

@@ -1,2 +1,2 @@
-import { P as e, S as t, _ as n, a as r, b as i, f as a, k as o, m as s, r as c, s as l, t as u, x as d } from "./textSelection-Cwq6lqKg.js";
-export { s as $activity, e as $config, r as $currentTab, i as $eventQueue, n as $isIdentityContextReady, d as $lifetimePageCount, a as $pageLifecycle, c as $scrollBehavior, u as $selectedText, o as $session, t as $totalEventCount, l as getTabCount };
+import { A as e, S as t, W as n, _ as r, a as i, b as a, f as o, k as s, m as c, r as l, s as u, t as d, x as f, z as p } from "./textSelection-CXG4e3wj.js";
+export { c as $activity, n as $config, i as $currentTab, a as $eventQueue, s as $identity, r as $isIdentityContextReady, f as $lifetimePageCount, o as $pageLifecycle, l as $scrollBehavior, d as $selectedText, p as $session, t as $totalEventCount, e as getIdentity, u as getTabCount };