@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/context/identity.d.ts

@@ -0,0 +1,16 @@
+import type { CluebaseSanitizedTraits, CluebaseSubjectTraits, IdentityContext } from "../provider/types.js";
+import { type StorageLike } from "./browser-storage.js";
+export type ContextJsonTraits = CluebaseSanitizedTraits;
+export type ContextTraitInput = CluebaseSubjectTraits;
+export declare const sanitizeContextTraits: (traits: ContextTraitInput | undefined) => ContextJsonTraits;
+export declare class IdentityManager {
+    private readonly storage;
+    private state;
+    constructor(storage?: StorageLike);
+    getContext(): IdentityContext;
+    identify(userId: string, traits?: ContextTraitInput): void;
+    clearUser(): void;
+    rotateAnonymousId(): string;
+    reset(): void;
+    private loadState;
+}

package/dist/context/identity.js

@@ -0,0 +1,139 @@
+import { generateAnonymousId } from "../exporter/event-id.js";
+import { STORAGE_KEYS } from "../provider/constants.js";
+import { resolveWebStorage, } from "./browser-storage.js";
+const CONTEXT_ID_TRAIT_KEYS = new Set([
+    "accountId",
+    "account_id",
+    "workspaceId",
+    "workspace_id",
+    "organizationId",
+    "organization_id",
+]);
+const STRING_TRAIT_KEYS = new Set([
+    "name",
+    "email",
+    "emailAddress",
+    "displayName",
+    "avatarUrl",
+]);
+export const sanitizeContextTraits = (traits) => {
+    if (traits === undefined)
+        return {};
+    if (!isPlainRecord(traits)) {
+        throw new Error("identify traits must be a JSON object");
+    }
+    const sanitizedTraits = {};
+    for (const [key, value] of Object.entries(traits)) {
+        if (CONTEXT_ID_TRAIT_KEYS.has(key))
+            continue;
+        if (value === undefined) {
+            if (STRING_TRAIT_KEYS.has(key))
+                continue;
+            throw new Error(`identify trait ${key} must be JSON-serializable`);
+        }
+        if (STRING_TRAIT_KEYS.has(key) &&
+            value !== null &&
+            typeof value !== "string") {
+            throw new Error(`identify trait ${key} must be a string or null`);
+        }
+        if (!isCanonicalJsonValue(value)) {
+            throw new Error(`identify trait ${key} must be JSON-serializable`);
+        }
+        sanitizedTraits[key] = value;
+    }
+    return sanitizedTraits;
+};
+const isCanonicalJsonValue = (value) => {
+    if (value === null)
+        return true;
+    const valueType = typeof value;
+    if (valueType === "string" ||
+        valueType === "number" ||
+        valueType === "boolean") {
+        return valueType !== "number" || Number.isFinite(value);
+    }
+    if (Array.isArray(value)) {
+        return value.every(isCanonicalJsonValue);
+    }
+    if (!isPlainRecord(value)) {
+        return false;
+    }
+    return Object.values(value).every(isCanonicalJsonValue);
+};
+const isPlainRecord = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+export class IdentityManager {
+    constructor(storage) {
+        this.storage = storage ?? resolveWebStorage("local", "cluebase:probe");
+        this.state = this.loadState();
+    }
+    getContext() {
+        return {
+            anonymousId: this.state.anonymousId,
+            userId: this.state.userId,
+            traits: { ...this.state.traits },
+        };
+    }
+    identify(userId, traits) {
+        const sanitizedTraits = sanitizeContextTraits(traits);
+        this.state.userId = userId;
+        this.state.traits = {
+            ...this.state.traits,
+            ...sanitizedTraits,
+        };
+        try {
+            this.storage.setItem(STORAGE_KEYS.userId, userId);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    clearUser() {
+        this.state.userId = null;
+        this.state.traits = {};
+        try {
+            this.storage.removeItem(STORAGE_KEYS.userId);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    rotateAnonymousId() {
+        const anonymousId = generateAnonymousId();
+        this.state.anonymousId = anonymousId;
+        try {
+            this.storage.setItem(STORAGE_KEYS.anonymousId, anonymousId);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+        return anonymousId;
+    }
+    reset() {
+        this.clearUser();
+        this.rotateAnonymousId();
+    }
+    loadState() {
+        const storedAnonymousId = this.storage.getItem(STORAGE_KEYS.anonymousId);
+        const anonymousId = storedAnonymousId || generateAnonymousId();
+        if (!storedAnonymousId) {
+            try {
+                this.storage.setItem(STORAGE_KEYS.anonymousId, anonymousId);
+            }
+            catch {
+                // Swallow to keep SDK non-blocking.
+            }
+        }
+        const userId = this.storage.getItem(STORAGE_KEYS.userId);
+        return {
+            anonymousId,
+            userId,
+            traits: {},
+        };
+    }
+}

package/dist/context/organization.d.ts

@@ -0,0 +1,16 @@
+import type { OrganizationContext } from "../provider/types.js";
+import { type ContextTraitInput } from "./identity.js";
+import { type StorageLike } from "./browser-storage.js";
+export declare class OrganizationManager {
+    private readonly storage;
+    private state;
+    constructor(storage?: StorageLike);
+    getContext(): OrganizationContext;
+    /**
+     * Set the MVP company context directly. Public `cluebase.group("organization")`
+     * must not create or mutate future account/workspace context.
+     */
+    setOrganization(organizationId: string, traits?: ContextTraitInput): void;
+    reset(): void;
+    private loadState;
+}

package/dist/context/organization.js

@@ -0,0 +1,60 @@
+import { STORAGE_KEYS } from "../provider/constants.js";
+import { sanitizeContextTraits, } from "./identity.js";
+import { resolveWebStorage, } from "./browser-storage.js";
+export class OrganizationManager {
+    constructor(storage) {
+        this.storage = storage ?? resolveWebStorage("local", "cluebase:organization_probe");
+        this.state = this.loadState();
+    }
+    getContext() {
+        return {
+            organizationId: this.state.organizationId,
+            traits: { ...this.state.traits },
+        };
+    }
+    /**
+     * Set the MVP company context directly. Public `cluebase.group("organization")`
+     * must not create or mutate future account/workspace context.
+     */
+    setOrganization(organizationId, traits) {
+        const sanitizedTraits = sanitizeContextTraits(traits);
+        this.state.organizationId = organizationId;
+        this.state.traits = {
+            ...this.state.traits,
+            ...sanitizedTraits,
+        };
+        try {
+            this.storage.setItem(STORAGE_KEYS.organizationId, organizationId);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    reset() {
+        this.state = {
+            organizationId: null,
+            traits: {},
+        };
+        try {
+            this.storage.removeItem(STORAGE_KEYS.organizationId);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    loadState() {
+        const organizationId = this.storage.getItem(STORAGE_KEYS.organizationId);
+        try {
+            if (organizationId) {
+                this.storage.setItem(STORAGE_KEYS.organizationId, organizationId);
+            }
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+        return {
+            organizationId,
+            traits: {},
+        };
+    }
+}

package/dist/context/session.d.ts

@@ -0,0 +1,28 @@
+import type { SessionContext } from "../provider/types.js";
+import { type StorageLike } from "./browser-storage.js";
+type SessionLifecycleResult = {
+    sessionId: string;
+    started: boolean;
+    ended: {
+        sessionId: string;
+        durationMs: number;
+    } | null;
+};
+export declare class SessionManager {
+    private readonly storage;
+    private readonly timeoutMs;
+    private context;
+    constructor(timeoutMs?: number, storage?: StorageLike);
+    getContext(): SessionContext;
+    ensureActiveSession(nowMs?: number): SessionLifecycleResult;
+    touch(nowMs?: number): void;
+    endSession(nowMs?: number): {
+        sessionId: string;
+        durationMs: number;
+    } | null;
+    reset(nowMs?: number): string;
+    private startSession;
+    private clear;
+    private loadState;
+}
+export {};

package/dist/context/session.js

@@ -0,0 +1,130 @@
+import { generateSessionId } from "../exporter/event-id.js";
+import { DEFAULT_SESSION_TIMEOUT_MS, STORAGE_KEYS, } from "../provider/constants.js";
+import { resolveWebStorage, } from "./browser-storage.js";
+const parseMs = (value) => {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+        return parsed;
+    }
+    return null;
+};
+export class SessionManager {
+    constructor(timeoutMs = DEFAULT_SESSION_TIMEOUT_MS, storage) {
+        this.timeoutMs = timeoutMs;
+        this.storage = storage ?? resolveWebStorage("session", "cluebase:session_probe");
+        this.context = this.loadState();
+    }
+    getContext() {
+        return { ...this.context };
+    }
+    ensureActiveSession(nowMs = Date.now()) {
+        const currentSessionId = this.context.sessionId;
+        const currentStartedAt = this.context.startedAtMs;
+        const lastActivityAt = this.context.lastActivityAtMs;
+        if (!currentSessionId || !currentStartedAt || !lastActivityAt) {
+            const started = this.startSession(nowMs);
+            return {
+                sessionId: started,
+                started: true,
+                ended: null,
+            };
+        }
+        const idleMs = nowMs - lastActivityAt;
+        if (idleMs > this.timeoutMs) {
+            const endedDuration = Math.max(0, nowMs - currentStartedAt);
+            const ended = {
+                sessionId: currentSessionId,
+                durationMs: endedDuration,
+            };
+            const newSessionId = this.startSession(nowMs);
+            return {
+                sessionId: newSessionId,
+                started: true,
+                ended,
+            };
+        }
+        this.touch(nowMs);
+        return {
+            sessionId: currentSessionId,
+            started: false,
+            ended: null,
+        };
+    }
+    touch(nowMs = Date.now()) {
+        this.context.lastActivityAtMs = nowMs;
+        try {
+            this.storage.setItem(STORAGE_KEYS.sessionLastActivityAt, String(nowMs));
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    endSession(nowMs = Date.now()) {
+        if (!this.context.sessionId || !this.context.startedAtMs) {
+            this.clear();
+            return null;
+        }
+        const ended = {
+            sessionId: this.context.sessionId,
+            durationMs: Math.max(0, nowMs - this.context.startedAtMs),
+        };
+        this.clear();
+        return ended;
+    }
+    reset(nowMs = Date.now()) {
+        this.clear();
+        return this.startSession(nowMs);
+    }
+    startSession(nowMs) {
+        const sessionId = generateSessionId();
+        this.context = {
+            sessionId,
+            startedAtMs: nowMs,
+            lastActivityAtMs: nowMs,
+        };
+        try {
+            this.storage.setItem(STORAGE_KEYS.sessionId, sessionId);
+            this.storage.setItem(STORAGE_KEYS.sessionStartedAt, String(nowMs));
+            this.storage.setItem(STORAGE_KEYS.sessionLastActivityAt, String(nowMs));
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+        return sessionId;
+    }
+    clear() {
+        this.context = {
+            sessionId: null,
+            startedAtMs: null,
+            lastActivityAtMs: null,
+        };
+        try {
+            this.storage.removeItem(STORAGE_KEYS.sessionId);
+            this.storage.removeItem(STORAGE_KEYS.sessionStartedAt);
+            this.storage.removeItem(STORAGE_KEYS.sessionLastActivityAt);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    loadState() {
+        const sessionId = this.storage.getItem(STORAGE_KEYS.sessionId);
+        const startedAtMs = parseMs(this.storage.getItem(STORAGE_KEYS.sessionStartedAt));
+        const lastActivityAtMs = parseMs(this.storage.getItem(STORAGE_KEYS.sessionLastActivityAt));
+        if (!sessionId || !startedAtMs || !lastActivityAtMs) {
+            return {
+                sessionId: null,
+                startedAtMs: null,
+                lastActivityAtMs: null,
+            };
+        }
+        return {
+            sessionId,
+            startedAtMs,
+            lastActivityAtMs,
+        };
+    }
+}

package/dist/context/tab.d.ts

@@ -0,0 +1,22 @@
+import { type StorageLike } from "./browser-storage.js";
+type TabManagerOptions = {
+    claimStorage?: StorageLike | null;
+    documentClaimId?: string;
+    now?: () => number;
+    bindLifecycleEvents?: boolean;
+};
+export declare class TabManager {
+    private readonly storage;
+    private readonly claimStorage;
+    private readonly documentClaimId;
+    private readonly now;
+    private readonly bindLifecycleEvents;
+    private readonly tabId;
+    constructor(storage?: StorageLike, options?: TabManagerOptions);
+    getTabId(): string;
+    private loadOrCreateTabId;
+    private isClaimedByAnotherDocument;
+    private claimTabId;
+    private installLifecycleCleanup;
+}
+export {};

package/dist/context/tab.js

@@ -0,0 +1,117 @@
+import { generateEventId, generateTabId } from "../exporter/event-id.js";
+import { STORAGE_KEYS } from "../provider/constants.js";
+import { resolveWebStorage, } from "./browser-storage.js";
+const TAB_CLAIM_KEY_PREFIX = "cluebase:tab_claim:";
+const TAB_CLAIM_TTL_MS = 5 * 60 * 1000;
+const DOCUMENT_CLAIM_ID = `doc_${generateEventId()}`;
+const resolveClaimStorage = () => {
+    try {
+        if (typeof globalThis.localStorage !== "undefined") {
+            const probeKey = "cluebase:tab_claim_probe";
+            globalThis.localStorage.setItem(probeKey, "1");
+            globalThis.localStorage.removeItem(probeKey);
+            return globalThis.localStorage;
+        }
+    }
+    catch {
+        // Ignore and continue without duplicate-tab coordination.
+    }
+    return null;
+};
+const parseTabClaim = (value) => {
+    if (!value) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed.claimId === "string" &&
+            typeof parsed.expiresAt === "number") {
+            return {
+                claimId: parsed.claimId,
+                expiresAt: parsed.expiresAt,
+            };
+        }
+    }
+    catch {
+        // Ignore invalid claim records and let the current document reclaim it.
+    }
+    return null;
+};
+export class TabManager {
+    constructor(storage, options) {
+        this.storage = storage ?? resolveWebStorage("session", "cluebase:tab_probe");
+        this.claimStorage =
+            options && "claimStorage" in options
+                ? (options.claimStorage ?? null)
+                : resolveClaimStorage();
+        this.documentClaimId = options?.documentClaimId ?? DOCUMENT_CLAIM_ID;
+        this.now = options?.now ?? Date.now;
+        this.bindLifecycleEvents = options?.bindLifecycleEvents ?? true;
+        this.tabId = this.loadOrCreateTabId();
+        this.claimTabId(this.tabId);
+        this.installLifecycleCleanup();
+    }
+    getTabId() {
+        return this.tabId;
+    }
+    loadOrCreateTabId() {
+        const stored = this.storage.getItem(STORAGE_KEYS.tabId);
+        if (stored && !this.isClaimedByAnotherDocument(stored)) {
+            return stored;
+        }
+        const tabId = generateTabId();
+        try {
+            this.storage.setItem(STORAGE_KEYS.tabId, tabId);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+        return tabId;
+    }
+    isClaimedByAnotherDocument(tabId) {
+        if (!this.claimStorage) {
+            return false;
+        }
+        const claim = parseTabClaim(this.claimStorage.getItem(`${TAB_CLAIM_KEY_PREFIX}${tabId}`));
+        if (!claim || claim.expiresAt <= this.now()) {
+            return false;
+        }
+        return claim.claimId !== this.documentClaimId;
+    }
+    claimTabId(tabId) {
+        if (!this.claimStorage) {
+            return;
+        }
+        try {
+            this.claimStorage.setItem(`${TAB_CLAIM_KEY_PREFIX}${tabId}`, JSON.stringify({
+                claimId: this.documentClaimId,
+                expiresAt: this.now() + TAB_CLAIM_TTL_MS,
+            }));
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    installLifecycleCleanup() {
+        if (!this.bindLifecycleEvents || !this.claimStorage) {
+            return;
+        }
+        try {
+            if (typeof globalThis.addEventListener !== "function") {
+                return;
+            }
+            const cleanup = () => {
+                const claimKey = `${TAB_CLAIM_KEY_PREFIX}${this.tabId}`;
+                const claim = parseTabClaim(this.claimStorage?.getItem(claimKey) ?? null);
+                if (claim?.claimId === this.documentClaimId) {
+                    this.claimStorage?.removeItem(claimKey);
+                }
+            };
+            globalThis.addEventListener("pagehide", cleanup, { once: true });
+            globalThis.addEventListener("beforeunload", cleanup, { once: true });
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+}

package/dist/context/trace.d.ts

@@ -0,0 +1,76 @@
+export type TraceContextSnapshot = {
+    traceId: string;
+    activeSpanId: string | null;
+};
+export type RequestTraceContext = {
+    traceId: string;
+    parentSpanId: string | null;
+    requestId: string;
+    requestSpanId: string;
+    interactionId: string;
+    interactionInitiator: string | null;
+    interactionStartEventKind: string | null;
+    originFrontendInteractionId: string | null;
+};
+export type ActiveInteractionSnapshot = {
+    interactionId: string;
+    interactionInitiator: string | null;
+    interactionStartEventKind: string | null;
+    targetStableKey: string | null;
+    formKey: string | null;
+    interactionScopeKind: string | null;
+    interactionScopeKey: string | null;
+};
+export type InteractionStartInput = {
+    interactionId?: string | null;
+    viewId?: string | null;
+    interactionInitiator?: string | null;
+    interactionStartEventKind?: string | null;
+    targetStableKey?: string | null;
+    formKey?: string | null;
+    interactionScopeKind?: string | null;
+    interactionScopeKey?: string | null;
+    nowMs?: number;
+};
+type FrontendActionInput = InteractionStartInput & {
+    viewId?: string | null;
+};
+export declare class TraceManager {
+    private traceId;
+    private activeSpanId;
+    private activeInteraction;
+    private recentInteraction;
+    private latestTrigger;
+    constructor();
+    reset(options?: {
+        preserveActiveInteraction?: boolean;
+    }): void;
+    getSnapshot(): TraceContextSnapshot;
+    startRootSpan(): {
+        traceId: string;
+        spanId: string;
+    };
+    setActiveSpan(spanId: string | null): void;
+    startFrontendAction(input?: FrontendActionInput): string;
+    endFrontendAction(interactionId?: string | null): void;
+    private getOrStartFrontendAction;
+    private recordTrigger;
+    startInteraction(input: InteractionStartInput): string;
+    joinOrStartInteraction(input: InteractionStartInput): string;
+    joinClickInteractionForSubmit(input: {
+        formKey: string | null;
+        nowMs?: number;
+    }): string | null;
+    getActiveInteractionId(): string | null;
+    getActiveInteractionSnapshot(): ActiveInteractionSnapshot | null;
+    getRecentInteractionSnapshot(nowMs: number | undefined, maxAgeMs: number): ActiveInteractionSnapshot | null;
+    createRequestContext(input?: {
+        requestId?: string;
+        method?: string | null;
+        urlKey?: string | null;
+        nowMs?: number;
+    }): RequestTraceContext;
+    private getActiveInteractionState;
+    private snapshotOf;
+}
+export {};