@palbase/web 1.0.0 → 1.1.0

package/dist/analytics-facade-t6UrFdn7.d.cts

@@ -1,454 +0,0 @@
-import { HttpClient, TokenManager, Session } from '@palbase/core';
-import { AuthClient } from '@palbase/auth';
-import { S as SessionStorageAdapter } from './storage-BPaeSG8K.cjs';
-import { FlagValue } from '@palbase/flags';
-
-interface PalbeOAuthConfig {
-    google?: {
-        enabled?: boolean;
-        clientId?: string;
-    };
-    apple?: {
-        enabled?: boolean;
-    };
-}
-/** Baked into palbe.gen.ts by `palbase web link` — the generated web config. */
-interface PalbeConfig {
-    url: string;
-    apiKey: string;
-    /** Informational — url+apiKey are already branch-specific (endpointRef embeds the branch slug); gen bakes all three consistently. */
-    branch?: string;
-    oauth?: PalbeOAuthConfig;
-    /** Refresh-token persistence. Default: endpoint-scoped localStorage in browsers, memory elsewhere. */
-    storage?: SessionStorageAdapter;
-    /** Extra headers on every request. */
-    headers?: Record<string, string>;
-}
-
-/** Frozen view of all cached flag values (what `all()` returns / `changes()` yields). */
-type FlagsView = Readonly<Record<string, FlagValue>>;
-/**
- * `pb.flags` — iOS-parity facade over `FlagsPool` (cache + delta polling +
- * auth binding) and `FlagsClient` (stateless transport).
- *
- * Start semantics: the facade is constructed lazily (first `pb.flags` touch).
- * - Browser: the pool starts right here in the constructor — cold snapshot +
- *   30s delta polling + visibility pause. "First use starts the machinery"
- *   without per-method start checks.
- * - Server (no `document`): NEVER auto-starts. `ready()`/`refresh()` are
- *   one-shot snapshot fetches with zero timers and zero storage access, so a
- *   pbServer request that reads flags pays exactly one HTTP call.
- *
- * localStorage persistence is scoped per endpoint ref (`palbe.flags.<ref>`),
- * mirroring the session-storage key convention.
- */
-declare class PalbeFlags {
-    private readonly transport;
-    private readonly pool;
-    constructor(rt: PalbeRuntime);
-    /** Resolves once the first snapshot (or persisted hydrate) is available. Auto-starts the pool. */
-    ready(): Promise<void>;
-    /** Force an immediate re-snapshot. */
-    refresh(): Promise<void>;
-    /** Frozen snapshot of all cached values (identity-stable until a change). */
-    all(): FlagsView;
-    /** Raw cached value for `key`, or `undefined` when not in the cache. */
-    get(key: string): FlagValue | undefined;
-    /** `true` only when the cached value is strictly `true`; `fallback` when the key is absent. */
-    isEnabled(key: string, fallback?: boolean): boolean;
-    /** Alias of {@link isEnabled} (iOS parity). */
-    bool(key: string, fallback?: boolean): boolean;
-    /** Cached value when it is a string, else `fallback`. */
-    getString(key: string, fallback: string): string;
-    /** Cached value when it is an integer number, else `fallback`. */
-    getInt(key: string, fallback: number): number;
-    /** Cached value when it is a number (integers included), else `fallback`. */
-    getDouble(key: string, fallback: number): number;
-    /**
-     * Resolve the multivariate variant for `key` — the variant name, or `null`
-     * when the flag has no variant (or the read fails).
-     *
-     * Wire failures (network errors, 404, etc.) resolve to `null`.
-     * Invalid flag names throw `BackendError('validation', { code: 'invalid_flag_name' })`.
-     *
-     * DEVIATION from iOS sync-cache parity: the platform does not propagate
-     * variant metadata into the user-flags snapshot/delta cache, so this is an
-     * ASYNC transport read (`GET /v1/flags/{key}/variant`), not a cache lookup.
-     */
-    getVariant(key: string): Promise<string | null>;
-    /** Subscribe to any change in the cached flag set. */
-    onChange(callback: () => void): Unsubscribe;
-    /**
-     * Observe ONE key: fires only when that key's value actually changes
-     * (per {@link sameFlagValue} — structural compare for objects), with the
-     * new value (`undefined` = deleted). P5 React-hook substrate.
-     */
-    subscribeKey(key: string, callback: (value: FlagValue | undefined) => void): Unsubscribe;
-    /**
-     * Async iteration over flag changes: yields the new {@link all} view on
-     * every pool change notification. The listener is detached when the
-     * consumer `break`s/`return`s/`throw`s — including while a `next()` is
-     * still pending (it resolves `{ done: true }` instead of hanging, which a
-     * plain async-generator `finally` would not guarantee).
-     */
-    changes(): AsyncIterableIterator<FlagsView>;
-    /** Stop polling and detach all listeners (auth + visibility + subscribers). */
-    destroy(): void;
-}
-
-/**
- * The connection state of the shared realtime WebSocket (iOS enum parity), plus
- * `'error'` — surfaced when a channel could not be recovered after a
- * token-expiry close exhausted its rejoin attempts (the socket itself may still
- * be up; the app should stop expecting events on the dead channel).
- */
-type RealtimeConnectionState = 'idle' | 'connected' | 'reconnecting' | 'error';
-
-/** An inbound broadcast payload (the inner `payload` of the Phoenix envelope). */
-type RealtimePayload = Record<string, unknown>;
-type RealtimeHandler = (payload: RealtimePayload) => void;
-/** A cancellable realtime subscription. `cancel()` removes the handler and,
- * when it was the channel's last, leaves the channel on the shared socket.
- * Cancelling twice is a no-op. */
-interface RealtimeSubscription {
-    cancel(): void;
-}
-interface RealtimeStatusSnapshot {
-    state: RealtimeConnectionState;
-    lastEventAt: Date | null;
-}
-/**
- * The observable connection status (`pb.realtime.status`) — the plain-JS
- * analogue of the iOS `@Observable RealtimeStatusStore`. `state` drives a
- * live "connected" badge; `lastEventAt` proves a push actually arrived.
- * `onChange` fires on state transitions and on every recorded event.
- */
-interface RealtimeStatus {
-    readonly state: RealtimeConnectionState;
-    readonly lastEventAt: Date | null;
-    onChange(callback: (status: RealtimeStatusSnapshot) => void): Unsubscribe;
-}
-/**
- * A subscription handle for one realtime channel (returned by
- * `pb.realtime.channel(name)` — the SAME instance per name). A channel is
- * joined on the shared socket when its first handler is added (or on the
- * first `send`) and left when its last handler cancels.
- */
-declare class RealtimeChannel {
-    /** The app-defined channel name (bare sub-topic, no "realtime:" prefix). */
-    readonly name: string;
-    private readonly owner;
-    /** @internal — obtain channels via `pb.realtime.channel(name)`. */
-    constructor(name: string, owner: PalbeRealtime);
-    /**
-     * Subscribe `handler` to `event` on this channel. Fire-and-forget: the
-     * join rides the shared socket asynchronously. Hold the returned
-     * subscription and `cancel()` it to stop.
-     */
-    on(event: string, handler: RealtimeHandler): RealtimeSubscription;
-    /**
-     * Broadcast `payload` to the channel's other subscribers (web addition —
-     * iOS is receive-only). Joins the channel if it isn't already; queued
-     * until the join is live on the socket.
-     */
-    send(event: string, payload?: RealtimePayload): void;
-}
-declare class PalbeRealtime {
-    private readonly rt;
-    private socket;
-    private readonly channels;
-    private readonly statusStore;
-    private readonly handlers;
-    private readonly topicRefcount;
-    constructor(rt: PalbeRuntime);
-    /**
-     * Get the handle for an app-defined channel (e.g. "room:42"). The same
-     * name returns the SAME instance. Throws a guided error on server-side
-     * hosts (SSR/RSC/Node) — realtime is client-only.
-     */
-    channel(name: string): RealtimeChannel;
-    /**
-     * Tear down the shared socket and clear all channel state. Called by
-     * `__configure` and `__reset` when the runtime is replaced, so old sockets
-     * are not left open and heartbeat timers do not leak.
-     */
-    destroy(): void;
-    /** The observable connection status. Safe to read anywhere (reports `idle` until a socket exists). */
-    get status(): RealtimeStatus;
-    /** @internal */
-    subscribe(topic: string, event: string, handler: RealtimeHandler): RealtimeSubscription;
-    /** @internal */
-    send(topic: string, event: string, payload: RealtimePayload): void;
-    /** Lazily build + start the shared socket on first subscription/send. */
-    private ensureSocket;
-    private route;
-    /**
-     * A channel died for good (token-expiry rejoin exhausted N attempts). Drop its
-     * handlers + refcount so the app stops expecting events on it, and flip the
-     * status observable to `'error'` (the React `useChannel` hook reports this).
-     * A later `.on()` for the same topic re-joins from scratch (refcount 1).
-     */
-    private handleChannelError;
-}
-
-interface PalbeRuntime {
-    config: PalbeConfig;
-    http: HttpClient;
-    tokenManager: TokenManager;
-    authClient: AuthClient;
-    auth: PalbeAuth;
-    flags: PalbeFlags;
-    realtime: PalbeRealtime;
-    analytics: PalbeAnalytics;
-    storage: SessionStorageAdapter;
-    /**
-     * Destroy the realtime facade if it was already constructed (no-op otherwise).
-     * Called by `__configure` / `__reset` when the runtime is replaced so the old
-     * socket is closed and heartbeat timers do not leak.
-     */
-    destroyRealtime(): void;
-}
-declare function buildRuntime(config: PalbeConfig): PalbeRuntime;
-
-type MagicLinkResult = ({
-    status: 'signedIn';
-} & AuthSuccess) | {
-    status: 'mfaRequired';
-    mfaToken: string;
-    factors: string[];
-};
-type OAuthExchangeResult = ({
-    status: 'signedIn';
-} & AuthSuccess) | {
-    status: 'mfaRequired';
-    mfaToken: string;
-    factors: string[];
-};
-interface AuthUser {
-    id: string;
-    /** null for phone-only users (the server omits email). */
-    email: string | null;
-    emailVerified: boolean;
-    createdAt: string;
-}
-interface AuthSuccess {
-    user: AuthUser;
-    session: Session;
-}
-type AuthState = {
-    status: 'signedIn';
-    user: AuthUser;
-} | {
-    status: 'signedOut';
-};
-type AuthChangeEvent = {
-    type: 'signedIn';
-    user: AuthUser;
-} | {
-    type: 'signedOut';
-    reason: 'userInitiated' | 'sessionExpired';
-} | {
-    type: 'tokenRefreshed';
-};
-type Unsubscribe = () => void;
-declare class PalbeAuth {
-    private readonly rt;
-    private cachedUser;
-    private signingOut;
-    private signingIn;
-    private signedInState;
-    private readonly stateListeners;
-    private readonly eventListeners;
-    private readonly userListeners;
-    constructor(rt: PalbeRuntime);
-    get currentUser(): AuthUser | null;
-    get isSignedIn(): boolean;
-    signUp(params: {
-        email: string;
-        password: string;
-    }): Promise<AuthSuccess>;
-    signIn(params: {
-        email: string;
-        password: string;
-    }): Promise<AuthSuccess>;
-    signOut(): Promise<void>;
-    getUser(): Promise<AuthUser>;
-    refreshUser(): Promise<AuthUser>;
-    /**
-     * Subscribe to signed-in/signed-out state. Fires immediately with the
-     * current snapshot (iOS parity). NOTE: a restored session (page reload) has
-     * no cached user yet, so the immediate snapshot reports signedOut even when
-     * `isSignedIn` is true — call `refreshUser()` on boot to populate the user
-     * and rely on `isSignedIn` for the session truth.
-     */
-    onAuthStateChange(callback: (state: AuthState) => void): Unsubscribe;
-    onAuthEvent(callback: (event: AuthChangeEvent) => void): Unsubscribe;
-    /** Subscribe to user-profile changes. Replays the cached user on subscribe (iOS parity). */
-    onUserChange(callback: (user: AuthUser) => void): Unsubscribe;
-    private snapshotState;
-    /**
-     * Listener exception isolation: a throwing consumer callback must never
-     * break delivery to other listeners nor propagate into the emit caller
-     * (tokenManager.clearSession callers, pb.call paths, signOut, ...).
-     */
-    private safeInvoke;
-    private emitState;
-    private emitEvent;
-    /** Cache the user + announce sign-in. Session was already set by AuthClient. */
-    private adopt;
-    /** Adopt a raw palauth AuthResult wire shape: wire tokens, cache user, announce. */
-    private adoptWire;
-    /** Run a sign-in flow under the signingIn flag to suppress spurious tokenRefreshed. */
-    private withSigningIn;
-    /**
-     * Defensively decode a 200 union body (AuthResult | mfa-required) and
-     * complete the flow. The wire contract promises one of the two shapes, but
-     * a literal-`null` (or otherwise malformed) JSON body must surface as
-     * BackendError('decode') — never a raw TypeError from probing a non-object.
-     * The mfa branch validates its fields: `mfa_token` is required; the factor
-     * list (named `factors` by magic-link verify, `mfa_factors` by the OAuth
-     * callback — extraction-verified against palauth) tolerates a missing or
-     * malformed value as []. The signedIn branch validates the FULL AuthResult
-     * shape (asWireAuthResult) — an incomplete body falls through to decode,
-     * never half-adopts.
-     */
-    private completeAuthUnion;
-    private decodeError;
-    signInWithOTP(params: {
-        phone: string;
-    }): Promise<void>;
-    verifyOTP(params: {
-        phone: string;
-        token: string;
-    }): Promise<AuthSuccess>;
-    resetPassword(email: string): Promise<void>;
-    confirmPasswordReset(params: {
-        token: string;
-        newPassword: string;
-    }): Promise<void>;
-    updatePassword(params: {
-        currentPassword: string;
-        newPassword: string;
-    }): Promise<void>;
-    verifyEmail(params: {
-        token: string;
-    } | {
-        code: string;
-        email: string;
-    }): Promise<void>;
-    resendVerification(email: string): Promise<void>;
-    signInWithMagicLink(email: string): Promise<void>;
-    verifyMagicLink(token: string): Promise<MagicLinkResult>;
-    signInWithCredential(params: {
-        provider: string;
-        credential: string;
-    }): Promise<AuthSuccess>;
-    signInWithOAuth(params: {
-        provider: string;
-        redirectTo?: string;
-        /** Set false to skip the browser redirect (popup/manual flows). Default true. */
-        redirect?: boolean;
-    }): Promise<{
-        url: string;
-    }>;
-    /**
-     * Complete the OAuth redirect flow: trade the provider's `code` + `state`
-     * (from the app's redirect_uri query) for a session. PKCE verifier + state
-     * live server-side in palauth — the client only relays the two values.
-     */
-    exchangeCodeForSession(params: {
-        provider: string;
-        code: string;
-        state: string;
-    }): Promise<OAuthExchangeResult>;
-    /** Config-as-code gate for the zero-arg provider sugar. */
-    private requireProvider;
-    signInWithGoogle(opts?: {
-        redirectTo?: string;
-        redirect?: boolean;
-    }): Promise<{
-        url: string;
-    }>;
-    signInWithApple(opts?: {
-        redirectTo?: string;
-        redirect?: boolean;
-    }): Promise<{
-        url: string;
-    }>;
-}
-
-/** Free-form event property bag (JSON object on the wire). */
-type AnalyticsProperties = Record<string, unknown>;
-/**
- * Runtime-scoped analytics identity — constructed EAGERLY in `buildRuntime`
- * (cheap: listener wiring only, no I/O) because the X-Distinct-Id header
- * interceptor must stamp every request from the first one, even when
- * `pb.analytics` is never touched (iOS: the resolver is wired at
- * PalBackend init). The facade wraps this state lazily.
- *
- * Auth events: while no facade exists, the state maintains identity only
- * (user id for the header, anon rotation on user-initiated sign-out). Once
- * the facade attaches, it takes over wholesale and adds the ingest
- * side-effects (flush + identify / flush + reset).
- */
-declare class AnalyticsState {
-    identifiedUserId: string | null;
-    /** Set by PalbeAnalytics on construction — delegates auth events to it. */
-    facadeAuthHandler: ((event: AuthChangeEvent) => void) | null;
-    private anonId;
-    private readonly store;
-    private readonly idKey;
-    private readonly optOutKey;
-    constructor(rt: PalbeRuntime);
-    /** User id when identified, else the stable anon id. NEVER empty —
-     * this is what `identify()` links, so stamping it on every request lets
-     * the trace pipeline stitch pre-login activity to the user. */
-    distinctId(): string;
-    anonymousId(): string;
-    rotateAnonymousId(): string;
-    isOptedOut(): boolean;
-    setOptOut(on: boolean): void;
-}
-declare class PalbeAnalytics {
-    private readonly rt;
-    private readonly state;
-    private readonly buffer;
-    private flushTimer;
-    /** Browser → buffer + size/timer flush. Server (no document) → immediate
-     * per-call POST, zero timers (nothing leaks into RSC/route handlers). */
-    private readonly browser;
-    constructor(rt: PalbeRuntime, state: AnalyticsState);
-    /** Record an event. Invalid names are dropped (one warn per process). */
-    capture(event: string, properties?: AnalyticsProperties): void;
-    /** Record a screen view — server-canonical `$screen` + `screen_name`.
-     * Validates non-empty only (the live wire at /v1/analytics/screen requires
-     * non-empty screen_name; the event-name regex does NOT apply here). */
-    screen(name: string, properties?: AnalyticsProperties): void;
-    /** Link the current anon id to `userId` and adopt it as the distinct id.
-     * Immediate POST (not buffered). Re-identifying a DIFFERENT user
-     * auto-resets first (iOS K10) so one anon id never links two users. */
-    identify(userId: string, traits?: AnalyticsProperties): void;
-    /** Merge distinct id `from` into `to` (identity stitching). Immediate POST. */
-    alias(from: string, to: string): void;
-    /** Drop the buffer, clear the identified user and rotate the anon id
-     * (sign-out hygiene). Callers wanting pending events delivered flush first
-     * — the auth binding does. */
-    reset(): void;
-    /** Persisted GDPR opt-out. Opting out drops anything pending so nothing
-     * already-buffered leaks after the user said stop. */
-    setOptOut(on: boolean): void;
-    /** Drain the buffer to /v1/analytics/batch (≤100 per request, sequential).
-     * Resolves when delivery finished; NEVER rejects — failed slices are
-     * dropped with one warn per flush. 207 partial-reject is also warned once
-     * (fire-and-forget: no retry for already-delivered batches). */
-    flush(): Promise<void>;
-    private ingest;
-    /** iOS PalBackend auth-binding parity: signedIn → flush + identify;
-     * userInitiated signedOut → flush + reset; sessionExpired → flush only. */
-    private handleAuthEvent;
-    private startTimer;
-    private cancelTimer;
-    private post;
-}
-
-export { type AnalyticsProperties as A, type FlagsView as F, type MagicLinkResult as M, type OAuthExchangeResult as O, PalbeAnalytics as P, RealtimeChannel as R, type Unsubscribe as U, type AuthChangeEvent as a, type AuthState as b, type AuthSuccess as c, type AuthUser as d, PalbeAuth as e, type PalbeConfig as f, PalbeFlags as g, type PalbeOAuthConfig as h, PalbeRealtime as i, type RealtimeConnectionState as j, type RealtimeHandler as k, type RealtimePayload as l, type RealtimeStatus as m, type RealtimeStatusSnapshot as n, type RealtimeSubscription as o, type PalbeRuntime as p, buildRuntime as q };