@levo-so/insights 0.3.10 → 0.3.11

package/dist/types/endpoint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Where events go, and whether that has been proven.
+ *
+ * A union rather than three nullable urls on the session. The three states are
+ * mutually exclusive, and the old shape (`insightsBaseUrl` / `candidateBaseUrl`
+ * / `fallbackBaseUrl`) let every reader re-derive which one it was in, and
+ * made "insightsBaseUrl is set" a comment-enforced invariant that `resolveApi`
+ * in the SDK app depended on. Here the invariant is the type.
+ */
+type IEndpoint = 
+/** Nothing usable was configured. Events queue and are never sent. */
+{
+    status: "none";
+}
+/**
+ * A proxy url that nothing has confirmed reaches Levo yet. The first event is
+ * the probe: its response either promotes this to `proven` or falls back.
+ * Always proxy, a direct host needs no proving.
+ */
+ | {
+    status: "unproven";
+    url: string;
+    fallback: string;
+}
+/** Confirmed: a request to this url came back as ours. */
+ | {
+    status: "proven";
+    url: string;
+    mode: "proxy" | "direct";
+};
+/** The url to send to, or null when there is nowhere to send. */
+declare const endpointUrl: (endpoint: IEndpoint) => string | null;
+/**
+ * How to authenticate to this endpoint. An unproven candidate is always proxy,
+ * where the browser attaches the identity cookies on a same-origin request.
+ */
+declare const endpointMode: (endpoint: IEndpoint) => "proxy" | "direct";
+export { type IEndpoint, endpointMode, endpointUrl, };

package/dist/types/identity.d.ts

@@ -6,7 +6,6 @@ export interface IIdentity {
     locale: ILevoAudience.Traits["locale"] | null;
     timezone: ILevoAudience.Traits["timezone"] | null;
     darkMode: ILevoAudience.Traits["dark_mode"] | null;
-    privateMode: ILevoAudience.Traits["private_mode"] | null;
     referrer: IIdentityReferrer | null;
     properties: ILevoAudience.Traits["properties"] | null;
 }

package/dist/utils/cookies.d.ts

@@ -0,0 +1,23 @@
+/**
+ * First-party cookie helpers.
+ *
+ * Cookies are the only client store that is shared across tabs *and* readable by
+ * the server on the same request, which is why identity mirrors into them: the
+ * proxy-mode backend resolves `id_i_cd`/`id_i_cs` straight off the `Cookie`
+ * header without the SDK having to attach anything.
+ *
+ * All writes are host-only (no `Domain` attribute) and `path=/`, matching the
+ * scope the server uses for its own `id_i_d`/`id_i_s` cookies.
+ */
+/** Read a cookie by name. Returns null when absent, blocked, or empty. */
+declare const readCookie: (name: string) => string | null;
+/**
+ * Write a host-only, path=/ cookie.
+ *
+ * `SameSite=Lax` (not `Strict`) so identity survives a cross-site entry, an ad
+ * or social click landing on the site is exactly the visit attribution cares
+ * about. `Secure` only on https, because localhost testbeds run over http and a
+ * Secure cookie there is silently dropped.
+ */
+declare const writeCookie: (name: string, value: string, maxAgeSeconds: number) => void;
+export { readCookie, writeCookie, };

package/dist/utils/detectMode.d.ts

@@ -1,10 +1,23 @@
+import { IEndpoint } from '../types/endpoint';
 import { IInsightOptions } from '../types/options';
-type DetectionResult = {
-    mode: "proxy" | "direct";
-    url: string | null;
-};
 /**
- * Detect the insights mode (proxy vs direct).
+ * Decide where events should go, without asking the network first.
+ *
+ * This used to race a `GET /ping` against both endpoints and wait up to a
+ * second for the answer, and events queued for the whole of it. That cost the
+ * first-ever page load of every visitor a round trip *before* anything could
+ * be sent, which is the exact window a bouncing visitor leaves in, the ping
+ * had replaced `/welcome` as the thing standing between a quick exit and any
+ * record of it.
+ *
+ * The first event is now the probe. If the proxy is not really forwarding,
+ * that request fails on its own. Usually faster than a ping would have
+ * answered, because a missing route fails at the customer's edge, and the
+ * transport retries it against the direct host. A working proxy costs nothing
+ * at all: the event that proves it is an event that had to be sent anyway.
+ *
+ * Only "auto" with both urls configured needs proving. Anything else is
+ * already certain, and comes back `proven`.
  */
-export declare const detectMode: (options: IInsightOptions) => Promise<DetectionResult>;
-export {};
+declare const detectMode: (options: IInsightOptions) => IEndpoint;
+export { detectMode, };

package/dist/utils/getAsyncUserProperties.d.ts

@@ -0,0 +1,6 @@
+declare const getAsyncUserProperties: () => Promise<{
+    private_mode: boolean | undefined;
+    properties: Record<string, unknown>;
+} | null>;
+type IAsyncUserProperties = NonNullable<Awaited<ReturnType<typeof getAsyncUserProperties>>>;
+export { type IAsyncUserProperties, getAsyncUserProperties, };

package/dist/utils/getAuthHeaders.d.ts

@@ -1,9 +1,22 @@
 /**
- * Get authentication headers for direct mode.
- * Returns empty object in proxy mode (cookies handle auth).
+ * Format identity headers for one request in a known mode. Returns an empty
+ * object in proxy mode: the id_i_cd/id_i_cs cookies ride along automatically
+ * on the same-origin request, so no explicit header is needed there.
+ *
+ * Most callers want {@link getIdentityHeaders} in lib/identityHeaders.ts
+ * instead, which reads the SDK's current state and calls this. The transport
+ * is the exception: it formats the ids it captured at flush time for the mode
+ * of the attempt in hand, never live state.
+ *
+ * deviceToken (legacy direct-mode device JWT, pre-adoption) is sent alongside
+ * the client mint, not instead of it: the server ranks the legacy credential
+ * above the client one and echoes back whichever wins, exactly like proxy
+ * mode's automatic id_i_d/id_i_cd dual-attach. There is no session-JWT
+ * equivalent. Rotation is fully client-owned, sessions are never adopted.
  */
-export declare const getAuthHeaders: ({ deviceToken, sessionToken, mode, }: {
+export declare const getAuthHeaders: ({ deviceId, sessionId, deviceToken, mode, }: {
+    deviceId?: string | null;
+    sessionId?: string | null;
     deviceToken?: string | null;
-    sessionToken?: string | null;
     mode?: string | null;
 }) => Record<string, string>;

package/dist/utils/getUserProperties.d.ts

@@ -1,7 +1,32 @@
-export declare const getUserProperties: () => Promise<{
+/**
+ * Everything the browser can answer *now*.
+ *
+ * Deliberately synchronous. This used to await three questions before anything
+ * else ran. Private-window detection, battery, and a camera/mic device
+ * enumeration, and only then read the values that were already sitting there.
+ * `enumerateDevices()` alone measured **154ms**, so the referrer, locale,
+ * timezone and screen size that decide a visit's attribution were held behind a
+ * check for whether the device has a webcam. Since the first event is what a
+ * bouncing visitor's whole visit depends on, that delay was the cost of the
+ * fields it was waiting for.
+ *
+ * Those probes live in getAsyncUserProperties() now, staged when they resolve
+ * and merged onto the same session row by the server, so nothing is lost
+ * except for a visitor who leaves inside the first few hundred milliseconds.
+ *
+ * The GPU string went with them despite being synchronous: creating a WebGL
+ * context to read it measured **10.8ms**, the most expensive single thing init
+ * did, and on a low-end phone that lands next to first paint. Nothing on the
+ * first request depends on it.
+ *
+ * What is left is only what is already sitting in memory, locale, timezone,
+ * colour scheme, screen and viewport, cores, memory, network type, all of it
+ * free to read, and all of it either attribution or the frame the visit
+ * happened in.
+ */
+export declare const getUserProperties: () => {
     locale: string;
     timezone: string;
     dark_mode: boolean;
-    private_mode: boolean;
     properties: Record<string, any>;
-}>;
+};

package/dist/utils/sanitizeEvent.d.ts

@@ -0,0 +1,51 @@
+import { ILevoAudience } from '../types/analytics';
+import { IIdentityReferrer } from '../types/identity';
+/** The server's WorkspaceIdSchema: exactly 8 uppercase alphanumerics. */
+declare const SAFE_WORKSPACE: RegExp;
+/**
+ * Whether a url can go on the wire. Mirrors the server's SafeUrlSchema:
+ * parseable, ≤2048, and not a javascript:/data:/vbscript: protocol.
+ */
+declare const isSendableUrl: (value: string | undefined | null) => value is string;
+/**
+ * Coerce the stored referrer into something the server's schema accepts.
+ * Empty hostname is valid (direct traffic); a malformed one is blanked rather
+ * than allowed to fail the batch.
+ */
+declare const sanitizeReferrer: (referrer: IIdentityReferrer | null | undefined) => IIdentityReferrer | undefined;
+/** Clamp the session-scoped traits. Mirrors SessionTraitsSchema. */
+declare const sanitizeTraits: (traits: {
+    created_at: string;
+    darkMode: boolean | null | undefined;
+    landingUrl: string | null | undefined;
+    locale: string | null | undefined;
+    properties: ILevoAudience.Traits["properties"] | null | undefined;
+    referrer: IIdentityReferrer | null | undefined;
+    timezone: string | null | undefined;
+}) => ILevoAudience.SessionTraits;
+/**
+ * An event that has been through {@link sanitizeEvent}.
+ *
+ * A separate type rather than a cast back to the queued shape: sanitizing
+ * genuinely produces something different, because a field that fails the
+ * server's rules is DROPPED. Those fields are optional server-side, so the
+ * honest wire contract has them optional here too.
+ */
+type ISanitizedEvent<T> = Omit<T, "hostname" | "identifier" | "page_title" | "pathname" | "resource" | "url"> & {
+    hostname?: string;
+    identifier?: string;
+    page_title?: string;
+    pathname?: string;
+    resource?: string;
+    url?: string;
+};
+/**
+ * Bring one queued event inside the server's own rules before it goes out.
+ *
+ * Dropped vs truncated is decided per field by what a wrong value costs. A url
+ * or hostname is an identity. Half of one attributes the event to a page or
+ * host nobody visited, so a failing value is omitted. A title or a path is
+ * descriptive, so truncating keeps most of the meaning.
+ */
+declare const sanitizeEvent: <T extends Record<string, unknown>>(event: T) => ISanitizedEvent<T>;
+export { type ISanitizedEvent, SAFE_WORKSPACE, isSendableUrl, sanitizeEvent, sanitizeReferrer, sanitizeTraits, };

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@levo-so/insights",
   "description": "Levo analytics",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "author": "Levo Engineering <devs@theinternetfolks.com>",
   "dependencies": {
     "@analytics/activity-utils": "0.2.2",
     "@analytics/visitor-source": "0.0.7",
+    "@theinternetfolks/snowflake": "1.3.0",
     "analytics": "0.8.14",
     "get-user-locale": "2.3.2",
     "lodash-es": "4.18.1",
@@ -16,8 +17,8 @@
     "typescript": "5.9.3",
     "vite": "8.0.8",
     "vite-plugin-dts": "4.5.4",
-    "@levo/ts-config": "0.0.0",
-    "@levo-so/core": "0.3.10"
+    "@levo-so/core": "0.3.11",
+    "@levo/ts-config": "0.0.0"
   },
   "exports": {
     ".": {
@@ -37,7 +38,7 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "peerDependencies": {
-    "@levo-so/core": "0.3.10"
+    "@levo-so/core": "0.3.11"
   },
   "publishConfig": {
     "access": "public"
@@ -47,9 +48,11 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "build": "vite build",
-    "check-types": "tsc --noEmit",
+    "check-types": "tsc --noEmit && tsc --noEmit -p tsconfig.demo.json",
     "clean": "npx rimraf dist node_modules .turbo",
+    "demo": "vite --config vite.demo.config.ts",
     "dev": "vite build --watch",
-    "lib-dev": "vite"
+    "lib-dev": "vite --config vite.demo.config.ts",
+    "test": "vite build && node --experimental-strip-types --test src/**/*.check.ts"
   }
 }