@palbase/web 1.7.0 → 1.8.0

package/dist/{analytics-facade-CQJ3b-zB.d.ts → analytics-facade-CgURkjpP.d.ts}

@@ -622,6 +622,16 @@ interface PalbeConfig {
     apiKey: string;
     /** Informational — url+apiKey are already branch-specific (endpointRef embeds the branch slug); gen bakes all three consistently. */
     branch?: string;
+    /**
+     * F2 app-registration: the registered app `identifier` from
+     * `palbase-config.json` — for web this is the declared ORIGIN (e.g.
+     * `https://app.example.com`). When non-empty, `configure` REFUSES to build the
+     * runtime if `window.location.origin` does not match (SDK-REFUSES), and the
+     * value rides on `X-Palbase-Bundle` on EVERY request so the Kong gate can match
+     * it (the IDENTICAL header + value the iOS SDK sends). Empty/absent → legacy /
+     * tooling: no guard, no header.
+     */
+    identifier?: string;
     oauth?: PalbeOAuthConfig;
     /** Refresh-token persistence. Default: endpoint-scoped localStorage in browsers, memory elsewhere. */
     storage?: SessionStorageAdapter;
@@ -1436,6 +1446,153 @@ declare class PalbeMessaging {
     onChatsChange(cb: () => void): Unsubscribe$1;
 }
 
+/** The Faz-1 trace kinds plus the Faz-1.5 web-vital family. */
+type PerfTraceType = 'network' | 'app_start' | 'custom' | 'web_vital';
+/**
+ * One perf measurement, shaped EXACTLY as the ingest wire expects. Keys are
+ * snake_case to match the Go decode tags — do not rename to camelCase.
+ */
+interface PerfItem {
+    /** Client-generated UUIDv7 — server dedup key. */
+    row_id: string;
+    trace_type: PerfTraceType;
+    name: string;
+    /** Duration in milliseconds. */
+    value: number;
+    counters?: Record<string, number>;
+    attrs?: Record<string, string>;
+    request_id?: string;
+    /** Unix milliseconds. */
+    timestamp: number;
+}
+
+/**
+ * Bounded FIFO perf-item queue. `enqueue` appends and evicts the oldest on
+ * overflow; `drainAll` returns everything (oldest-first) and clears the store;
+ * `count` is the current depth; `dropped` is the cumulative eviction counter.
+ *
+ * When `localStorage` is present the queue is read-through / write-through to a
+ * fixed key, so a fresh instance after a reload sees the persisted items. With
+ * no `localStorage` it is purely in-memory.
+ */
+declare class PerfOfflineQueue {
+    private items;
+    private _dropped;
+    private readonly maxItems;
+    constructor(maxItems?: number);
+    /** Append items; FIFO-evict the oldest when over `maxItems`. */
+    enqueue(items: PerfItem[]): void;
+    /** Return all queued items (oldest-first) and clear the queue + store. */
+    drainAll(): PerfItem[];
+    /** Current queue depth. */
+    get count(): number;
+    /** Cumulative count of FIFO-evicted items (a `dropped` metric, not silent). */
+    get dropped(): number;
+    /** Drop the oldest items until at most `maxItems` remain, counting each. */
+    private trim;
+    private persist;
+    private clearStore;
+}
+
+/**
+ * The mutable PalPerf state shared between the facade and the network hook.
+ * `testDevice` is signalled to the server via the `X-Palbase-Test-Device: 1`
+ * request header (server-authoritative tagging — the SDK only flips the bit).
+ */
+declare class PerfState {
+    /** Pending, un-flushed perf items (FIFO). */
+    readonly buffer: PerfItem[];
+    /** When true, every flush carries `X-Palbase-Test-Device: 1`. */
+    testDevice: boolean;
+    enqueue(item: PerfItem): void;
+    /** Detach up to `MAX_PERF_BATCH` items for one POST (FIFO order preserved). */
+    take(limit?: number): PerfItem[];
+    get size(): number;
+}
+
+/**
+ * A running custom trace. `putAttribute`/`incrementMetric` accumulate metadata;
+ * `stop()` records ONE `custom` PerfItem whose `value` is the elapsed
+ * milliseconds since `startTrace`. Idempotent: a second `stop()` is a no-op.
+ */
+declare class PerfTrace {
+    private readonly name;
+    private readonly onStop;
+    private readonly attrs;
+    private readonly counters;
+    private readonly startedAt;
+    private stopped;
+    constructor(name: string, onStop: (item: PerfItem) => void);
+    putAttribute(key: string, value: string): void;
+    incrementMetric(name: string, by?: number): void;
+    stop(): void;
+}
+declare class PalbePerf {
+    private readonly rt;
+    private readonly state;
+    /** Durable offline buffer for failed flushes (persist-on-fail). Browser →
+     * localStorage-backed; server → in-memory. */
+    private readonly queue;
+    private flushTimer;
+    /** Browser → buffer + size/timer flush. Server (no document) → immediate
+     * per-item flush, zero timers (nothing leaks into RSC/route handlers). */
+    private readonly browser;
+    /** Bound `online` handler so it can be removed on `dispose()` (no leak). */
+    private readonly onOnline;
+    /** Server-controlled client-side sample rate (0..100). 100 until the config
+     * client fetches `/v1/analytics/perf/config` — the SDK obeys this ceiling and
+     * never raises its own rate (invariant 3). `record` drops an item whose
+     * deterministic `row_id` bucket is >= this pct, mirroring the server's
+     * `SampleDecision` so client + server keep the SAME rows. */
+    private samplePct;
+    constructor(rt: PalbeRuntime, state?: PerfState, 
+    /** Durable offline buffer for failed flushes (persist-on-fail). Browser →
+     * localStorage-backed; server → in-memory. */
+    queue?: PerfOfflineQueue);
+    /** Remove the `online` listener. Called when the runtime is replaced so the
+     * handler does not outlive this facade. No-op outside the browser. */
+    dispose(): void;
+    /** Mark (or unmark) this client's traffic as test — the server tags the rows
+     * when the `X-Palbase-Test-Device: 1` header rides along on flush. */
+    setTestDevice(on: boolean): void;
+    /** Apply the server-resolved client-side sample rate (0..100), clamped. Called
+     * by `PerfConfigClient` after fetching `/v1/analytics/perf/config`. The SDK
+     * OBEYS this value — it is a ceiling, never raised locally. */
+    setSamplePct(pct: number): void;
+    /** Pending (un-flushed) buffer depth. Test-only visibility into the buffer so
+     * the remote-sampling tests can assert how many items were sampled in. */
+    get bufferSizeForTest(): number;
+    /** Opt-in: wrap the global `fetch` so every app-level request is recorded as a
+     * redacted `network` perf item (the `/v1/analytics/*` ingest paths are
+     * self-excluded). OFF by default — swizzling a global is a page-wide side
+     * effect. Returns an `uninstall` that restores the original `fetch`. */
+    enableFetchCapture(): () => void;
+    /** Start a custom trace; the returned handle records a `custom` item on
+     * `.stop()`. */
+    startTrace(name: string): PerfTrace;
+    /** Buffer one perf item. In the browser, flush on size/timer; on the server
+     * flush immediately (no timers). Never throws.
+     *
+     * Client-side remote sampling: an item whose deterministic `row_id` bucket is
+     * NOT below the server-controlled `samplePct` is dropped before buffering —
+     * the SAME FNV-1a-mod-100 decision the server applies at ingest, so the two
+     * keep identical rows and the SDK saves the upload (defense-in-depth: the
+     * server re-samples authoritatively). */
+    record(item: PerfItem): void;
+    /** Buffer a network trace — called by `request.ts` around `rt.http.request`
+     * (the analytics ingest path is excluded by the caller to avoid recursion). */
+    recordNetwork(method: string, url: string, status: number, durationMs: number, requestId?: string): void;
+    /** Drain the offline queue (oldest-first) and the live buffer to
+     * `/v1/analytics/perf` (≤100 items per request, sequential). Resolves when
+     * delivery finished; NEVER rejects. A failed slice is NOT dropped — it goes
+     * to the offline queue (persist-on-fail) so the next flush (size/timer or the
+     * `online` reconnect event) retries it. Items keep their original `row_id`,
+     * so a redelivery dedups server-side (ReplacingMergeTree). */
+    flush(): Promise<void>;
+    private startTimer;
+    private cancelTimer;
+}
+
 /**
  * The connection state of the shared realtime WebSocket (iOS enum parity), plus
  * `'error'` — surfaced when a channel could not be recovered after a
@@ -1533,6 +1690,14 @@ declare class PalbeRealtime {
 
 interface PalbeRuntime {
     config: PalbeConfig;
+    /**
+     * F2 app-registration: the registered app `identifier` (web ORIGIN) stashed at
+     * configure. Rides on `X-Palbase-Bundle` on EVERY request (request.ts) so the
+     * Kong gate can match it. Empty string when the binding is unconfigured/tooling
+     * (no header is sent). Origin-match is enforced in `buildRuntime` BEFORE this
+     * runtime is returned — a mismatch throws there and no runtime is built.
+     */
+    appIdentifier: string;
     http: HttpClient$1;
     tokenManager: TokenManager$1;
     authClient: AuthClient;
@@ -1542,6 +1707,13 @@ interface PalbeRuntime {
     analytics: PalbeAnalytics;
     calls: PalbeCalls;
     messaging: PalbeMessaging;
+    /**
+     * PalPerf surface. EAGER (like analytics identity): `request.ts` records a
+     * `network` trace around EVERY SDK fetch, so the facade must exist from the
+     * first request — never lazy. The buffer/timer it owns is inert until the
+     * first item is recorded.
+     */
+    perf: PalbePerf;
     storage: SessionStorageAdapter;
     /**
      * Destroy the realtime facade if it was already constructed (no-op otherwise).
@@ -1793,4 +1965,4 @@ declare class PalbeAnalytics {
     private post;
 }
 
-export { type AnalyticsProperties as A, type PresenceState as B, Call as C, type RealtimeConnectionState as D, type RealtimeHandler as E, type FlagsView as F, type RealtimePayload as G, type RealtimeStatus as H, type RealtimeStatusSnapshot as I, type RealtimeSubscription as J, type ResolvedMention as K, type ResolvedReply as L, type MagicLinkResult as M, type NotifyScope as N, type OAuthExchangeResult as O, PalbeAnalytics as P, type Unsubscribe as Q, RealtimeChannel as R, type SentReceipt as S, type PalbeRuntime as T, type UnreadView as U, buildRuntime as V, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, type CallChangeCallback as e, type CallParticipant as f, type CallState as g, Chat as h, type ChatBackend as i, type ChatDraft as j, type ChatKind as k, type ChatMember as l, type ChatMessage as m, type ChatMessageKind as n, type ChatRole as o, type ChatState as p, type CommsPrefs as q, type MentionRange as r, type MessageDirection as s, PalbeAuth as t, PalbeCalls as u, type PalbeConfig as v, PalbeFlags as w, PalbeMessaging as x, type PalbeOAuthConfig as y, PalbeRealtime as z };
+export { type AnalyticsProperties as A, type PresenceState as B, Call as C, type RealtimeConnectionState as D, type RealtimeHandler as E, type FlagsView as F, type RealtimePayload as G, type RealtimeStatus as H, type RealtimeStatusSnapshot as I, type RealtimeSubscription as J, type ResolvedMention as K, type ResolvedReply as L, type MagicLinkResult as M, type NotifyScope as N, type OAuthExchangeResult as O, PalbeAnalytics as P, type Unsubscribe as Q, RealtimeChannel as R, type SentReceipt as S, type PalbeRuntime as T, type UnreadView as U, buildRuntime as V, PalbePerf as W, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, type CallChangeCallback as e, type CallParticipant as f, type CallState as g, Chat as h, type ChatBackend as i, type ChatDraft as j, type ChatKind as k, type ChatMember as l, type ChatMessage as m, type ChatMessageKind as n, type ChatRole as o, type ChatState as p, type CommsPrefs as q, type MentionRange as r, type MessageDirection as s, PalbeAuth as t, PalbeCalls as u, type PalbeConfig as v, PalbeFlags as w, PalbeMessaging as x, type PalbeOAuthConfig as y, PalbeRealtime as z };

package/dist/{analytics-facade-9GPSKnVG.d.cts → analytics-facade-DfJ420F5.d.cts}

@@ -622,6 +622,16 @@ interface PalbeConfig {
     apiKey: string;
     /** Informational — url+apiKey are already branch-specific (endpointRef embeds the branch slug); gen bakes all three consistently. */
     branch?: string;
+    /**
+     * F2 app-registration: the registered app `identifier` from
+     * `palbase-config.json` — for web this is the declared ORIGIN (e.g.
+     * `https://app.example.com`). When non-empty, `configure` REFUSES to build the
+     * runtime if `window.location.origin` does not match (SDK-REFUSES), and the
+     * value rides on `X-Palbase-Bundle` on EVERY request so the Kong gate can match
+     * it (the IDENTICAL header + value the iOS SDK sends). Empty/absent → legacy /
+     * tooling: no guard, no header.
+     */
+    identifier?: string;
     oauth?: PalbeOAuthConfig;
     /** Refresh-token persistence. Default: endpoint-scoped localStorage in browsers, memory elsewhere. */
     storage?: SessionStorageAdapter;
@@ -1436,6 +1446,153 @@ declare class PalbeMessaging {
     onChatsChange(cb: () => void): Unsubscribe$1;
 }
 
+/** The Faz-1 trace kinds plus the Faz-1.5 web-vital family. */
+type PerfTraceType = 'network' | 'app_start' | 'custom' | 'web_vital';
+/**
+ * One perf measurement, shaped EXACTLY as the ingest wire expects. Keys are
+ * snake_case to match the Go decode tags — do not rename to camelCase.
+ */
+interface PerfItem {
+    /** Client-generated UUIDv7 — server dedup key. */
+    row_id: string;
+    trace_type: PerfTraceType;
+    name: string;
+    /** Duration in milliseconds. */
+    value: number;
+    counters?: Record<string, number>;
+    attrs?: Record<string, string>;
+    request_id?: string;
+    /** Unix milliseconds. */
+    timestamp: number;
+}
+
+/**
+ * Bounded FIFO perf-item queue. `enqueue` appends and evicts the oldest on
+ * overflow; `drainAll` returns everything (oldest-first) and clears the store;
+ * `count` is the current depth; `dropped` is the cumulative eviction counter.
+ *
+ * When `localStorage` is present the queue is read-through / write-through to a
+ * fixed key, so a fresh instance after a reload sees the persisted items. With
+ * no `localStorage` it is purely in-memory.
+ */
+declare class PerfOfflineQueue {
+    private items;
+    private _dropped;
+    private readonly maxItems;
+    constructor(maxItems?: number);
+    /** Append items; FIFO-evict the oldest when over `maxItems`. */
+    enqueue(items: PerfItem[]): void;
+    /** Return all queued items (oldest-first) and clear the queue + store. */
+    drainAll(): PerfItem[];
+    /** Current queue depth. */
+    get count(): number;
+    /** Cumulative count of FIFO-evicted items (a `dropped` metric, not silent). */
+    get dropped(): number;
+    /** Drop the oldest items until at most `maxItems` remain, counting each. */
+    private trim;
+    private persist;
+    private clearStore;
+}
+
+/**
+ * The mutable PalPerf state shared between the facade and the network hook.
+ * `testDevice` is signalled to the server via the `X-Palbase-Test-Device: 1`
+ * request header (server-authoritative tagging — the SDK only flips the bit).
+ */
+declare class PerfState {
+    /** Pending, un-flushed perf items (FIFO). */
+    readonly buffer: PerfItem[];
+    /** When true, every flush carries `X-Palbase-Test-Device: 1`. */
+    testDevice: boolean;
+    enqueue(item: PerfItem): void;
+    /** Detach up to `MAX_PERF_BATCH` items for one POST (FIFO order preserved). */
+    take(limit?: number): PerfItem[];
+    get size(): number;
+}
+
+/**
+ * A running custom trace. `putAttribute`/`incrementMetric` accumulate metadata;
+ * `stop()` records ONE `custom` PerfItem whose `value` is the elapsed
+ * milliseconds since `startTrace`. Idempotent: a second `stop()` is a no-op.
+ */
+declare class PerfTrace {
+    private readonly name;
+    private readonly onStop;
+    private readonly attrs;
+    private readonly counters;
+    private readonly startedAt;
+    private stopped;
+    constructor(name: string, onStop: (item: PerfItem) => void);
+    putAttribute(key: string, value: string): void;
+    incrementMetric(name: string, by?: number): void;
+    stop(): void;
+}
+declare class PalbePerf {
+    private readonly rt;
+    private readonly state;
+    /** Durable offline buffer for failed flushes (persist-on-fail). Browser →
+     * localStorage-backed; server → in-memory. */
+    private readonly queue;
+    private flushTimer;
+    /** Browser → buffer + size/timer flush. Server (no document) → immediate
+     * per-item flush, zero timers (nothing leaks into RSC/route handlers). */
+    private readonly browser;
+    /** Bound `online` handler so it can be removed on `dispose()` (no leak). */
+    private readonly onOnline;
+    /** Server-controlled client-side sample rate (0..100). 100 until the config
+     * client fetches `/v1/analytics/perf/config` — the SDK obeys this ceiling and
+     * never raises its own rate (invariant 3). `record` drops an item whose
+     * deterministic `row_id` bucket is >= this pct, mirroring the server's
+     * `SampleDecision` so client + server keep the SAME rows. */
+    private samplePct;
+    constructor(rt: PalbeRuntime, state?: PerfState, 
+    /** Durable offline buffer for failed flushes (persist-on-fail). Browser →
+     * localStorage-backed; server → in-memory. */
+    queue?: PerfOfflineQueue);
+    /** Remove the `online` listener. Called when the runtime is replaced so the
+     * handler does not outlive this facade. No-op outside the browser. */
+    dispose(): void;
+    /** Mark (or unmark) this client's traffic as test — the server tags the rows
+     * when the `X-Palbase-Test-Device: 1` header rides along on flush. */
+    setTestDevice(on: boolean): void;
+    /** Apply the server-resolved client-side sample rate (0..100), clamped. Called
+     * by `PerfConfigClient` after fetching `/v1/analytics/perf/config`. The SDK
+     * OBEYS this value — it is a ceiling, never raised locally. */
+    setSamplePct(pct: number): void;
+    /** Pending (un-flushed) buffer depth. Test-only visibility into the buffer so
+     * the remote-sampling tests can assert how many items were sampled in. */
+    get bufferSizeForTest(): number;
+    /** Opt-in: wrap the global `fetch` so every app-level request is recorded as a
+     * redacted `network` perf item (the `/v1/analytics/*` ingest paths are
+     * self-excluded). OFF by default — swizzling a global is a page-wide side
+     * effect. Returns an `uninstall` that restores the original `fetch`. */
+    enableFetchCapture(): () => void;
+    /** Start a custom trace; the returned handle records a `custom` item on
+     * `.stop()`. */
+    startTrace(name: string): PerfTrace;
+    /** Buffer one perf item. In the browser, flush on size/timer; on the server
+     * flush immediately (no timers). Never throws.
+     *
+     * Client-side remote sampling: an item whose deterministic `row_id` bucket is
+     * NOT below the server-controlled `samplePct` is dropped before buffering —
+     * the SAME FNV-1a-mod-100 decision the server applies at ingest, so the two
+     * keep identical rows and the SDK saves the upload (defense-in-depth: the
+     * server re-samples authoritatively). */
+    record(item: PerfItem): void;
+    /** Buffer a network trace — called by `request.ts` around `rt.http.request`
+     * (the analytics ingest path is excluded by the caller to avoid recursion). */
+    recordNetwork(method: string, url: string, status: number, durationMs: number, requestId?: string): void;
+    /** Drain the offline queue (oldest-first) and the live buffer to
+     * `/v1/analytics/perf` (≤100 items per request, sequential). Resolves when
+     * delivery finished; NEVER rejects. A failed slice is NOT dropped — it goes
+     * to the offline queue (persist-on-fail) so the next flush (size/timer or the
+     * `online` reconnect event) retries it. Items keep their original `row_id`,
+     * so a redelivery dedups server-side (ReplacingMergeTree). */
+    flush(): Promise<void>;
+    private startTimer;
+    private cancelTimer;
+}
+
 /**
  * The connection state of the shared realtime WebSocket (iOS enum parity), plus
  * `'error'` — surfaced when a channel could not be recovered after a
@@ -1533,6 +1690,14 @@ declare class PalbeRealtime {
 
 interface PalbeRuntime {
     config: PalbeConfig;
+    /**
+     * F2 app-registration: the registered app `identifier` (web ORIGIN) stashed at
+     * configure. Rides on `X-Palbase-Bundle` on EVERY request (request.ts) so the
+     * Kong gate can match it. Empty string when the binding is unconfigured/tooling
+     * (no header is sent). Origin-match is enforced in `buildRuntime` BEFORE this
+     * runtime is returned — a mismatch throws there and no runtime is built.
+     */
+    appIdentifier: string;
     http: HttpClient$1;
     tokenManager: TokenManager$1;
     authClient: AuthClient;
@@ -1542,6 +1707,13 @@ interface PalbeRuntime {
     analytics: PalbeAnalytics;
     calls: PalbeCalls;
     messaging: PalbeMessaging;
+    /**
+     * PalPerf surface. EAGER (like analytics identity): `request.ts` records a
+     * `network` trace around EVERY SDK fetch, so the facade must exist from the
+     * first request — never lazy. The buffer/timer it owns is inert until the
+     * first item is recorded.
+     */
+    perf: PalbePerf;
     storage: SessionStorageAdapter;
     /**
      * Destroy the realtime facade if it was already constructed (no-op otherwise).
@@ -1793,4 +1965,4 @@ declare class PalbeAnalytics {
     private post;
 }
 
-export { type AnalyticsProperties as A, type PresenceState as B, Call as C, type RealtimeConnectionState as D, type RealtimeHandler as E, type FlagsView as F, type RealtimePayload as G, type RealtimeStatus as H, type RealtimeStatusSnapshot as I, type RealtimeSubscription as J, type ResolvedMention as K, type ResolvedReply as L, type MagicLinkResult as M, type NotifyScope as N, type OAuthExchangeResult as O, PalbeAnalytics as P, type Unsubscribe as Q, RealtimeChannel as R, type SentReceipt as S, type PalbeRuntime as T, type UnreadView as U, buildRuntime as V, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, type CallChangeCallback as e, type CallParticipant as f, type CallState as g, Chat as h, type ChatBackend as i, type ChatDraft as j, type ChatKind as k, type ChatMember as l, type ChatMessage as m, type ChatMessageKind as n, type ChatRole as o, type ChatState as p, type CommsPrefs as q, type MentionRange as r, type MessageDirection as s, PalbeAuth as t, PalbeCalls as u, type PalbeConfig as v, PalbeFlags as w, PalbeMessaging as x, type PalbeOAuthConfig as y, PalbeRealtime as z };
+export { type AnalyticsProperties as A, type PresenceState as B, Call as C, type RealtimeConnectionState as D, type RealtimeHandler as E, type FlagsView as F, type RealtimePayload as G, type RealtimeStatus as H, type RealtimeStatusSnapshot as I, type RealtimeSubscription as J, type ResolvedMention as K, type ResolvedReply as L, type MagicLinkResult as M, type NotifyScope as N, type OAuthExchangeResult as O, PalbeAnalytics as P, type Unsubscribe as Q, RealtimeChannel as R, type SentReceipt as S, type PalbeRuntime as T, type UnreadView as U, buildRuntime as V, PalbePerf as W, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, type CallChangeCallback as e, type CallParticipant as f, type CallState as g, Chat as h, type ChatBackend as i, type ChatDraft as j, type ChatKind as k, type ChatMember as l, type ChatMessage as m, type ChatMessageKind as n, type ChatRole as o, type ChatState as p, type CommsPrefs as q, type MentionRange as r, type MessageDirection as s, PalbeAuth as t, PalbeCalls as u, type PalbeConfig as v, PalbeFlags as w, PalbeMessaging as x, type PalbeOAuthConfig as y, PalbeRealtime as z };