@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/context/trace.js

@@ -0,0 +1,163 @@
+import { generateEventId, generateInteractionId, generateRequestId, generateRequestSpanId, generateTraceId, } from "../exporter/event-id.js";
+const generateSpanId = () => {
+    return `span_${generateEventId()}`;
+};
+export class TraceManager {
+    constructor() {
+        this.traceId = generateTraceId();
+        this.activeSpanId = null;
+        this.activeInteraction = null;
+        this.recentInteraction = null;
+        this.latestTrigger = null;
+    }
+    reset(options) {
+        this.traceId = generateTraceId();
+        this.activeSpanId = null;
+        if (!options?.preserveActiveInteraction) {
+            this.activeInteraction = null;
+            this.recentInteraction = null;
+            this.latestTrigger = null;
+        }
+    }
+    getSnapshot() {
+        return {
+            traceId: this.traceId,
+            activeSpanId: this.activeSpanId,
+        };
+    }
+    startRootSpan() {
+        const spanId = generateSpanId();
+        this.activeSpanId = spanId;
+        return {
+            traceId: this.traceId,
+            spanId,
+        };
+    }
+    setActiveSpan(spanId) {
+        this.activeSpanId = spanId;
+    }
+    startFrontendAction(input = {}) {
+        const nowMs = input.nowMs ?? Date.now();
+        const interactionId = input.interactionId ?? generateInteractionId();
+        this.traceId = generateTraceId();
+        this.activeInteraction = {
+            interactionId,
+            interactionInitiator: input.interactionInitiator ?? null,
+            interactionStartEventKind: input.interactionStartEventKind ?? null,
+            targetStableKey: input.targetStableKey ?? null,
+            formKey: input.formKey ?? null,
+            interactionScopeKind: input.interactionScopeKind ?? null,
+            interactionScopeKey: input.interactionScopeKey ?? null,
+            viewId: input.viewId ?? null,
+        };
+        this.recentInteraction = {
+            ...this.snapshotOf(this.activeInteraction),
+            lastSeenAtMs: nowMs,
+        };
+        this.latestTrigger = null;
+        return interactionId;
+    }
+    endFrontendAction(interactionId) {
+        if (!this.activeInteraction)
+            return;
+        if (interactionId && this.activeInteraction.interactionId !== interactionId) {
+            return;
+        }
+        this.recentInteraction = {
+            ...this.snapshotOf(this.activeInteraction),
+            lastSeenAtMs: Date.now(),
+        };
+        this.activeInteraction = null;
+        this.latestTrigger = null;
+    }
+    getOrStartFrontendAction(input) {
+        if (!this.activeInteraction) {
+            return this.startFrontendAction(input);
+        }
+        if (input.viewId && this.activeInteraction.viewId !== input.viewId) {
+            return this.startFrontendAction(input);
+        }
+        return this.activeInteraction.interactionId;
+    }
+    recordTrigger(input) {
+        this.latestTrigger = {
+            interactionInitiator: input.interactionInitiator ?? null,
+            interactionStartEventKind: input.interactionStartEventKind ?? null,
+            targetStableKey: input.targetStableKey ?? null,
+            formKey: input.formKey ?? null,
+            interactionScopeKind: input.interactionScopeKind ?? null,
+            interactionScopeKey: input.interactionScopeKey ?? null,
+        };
+    }
+    // UI 操作はページ visit interaction に参加する。request はこの id を共有せず、
+    // createRequestContext() で request ごとに fresh な interaction_id を持つ。
+    startInteraction(input) {
+        const interactionId = this.getOrStartFrontendAction(input);
+        this.recordTrigger(input);
+        return interactionId;
+    }
+    joinOrStartInteraction(input) {
+        return this.startInteraction(input);
+    }
+    joinClickInteractionForSubmit(input) {
+        if (!this.activeInteraction)
+            return null;
+        this.recordTrigger({
+            formKey: input.formKey,
+            interactionInitiator: "submit",
+            interactionStartEventKind: "submit",
+            nowMs: input.nowMs,
+        });
+        return this.activeInteraction.interactionId;
+    }
+    getActiveInteractionId() {
+        return this.getActiveInteractionSnapshot()?.interactionId ?? null;
+    }
+    getActiveInteractionSnapshot() {
+        const active = this.getActiveInteractionState();
+        return active ? this.snapshotOf(active) : null;
+    }
+    getRecentInteractionSnapshot(nowMs = Date.now(), maxAgeMs) {
+        const active = this.getActiveInteractionSnapshot();
+        if (active) {
+            return active;
+        }
+        if (!this.recentInteraction) {
+            return null;
+        }
+        if (nowMs - this.recentInteraction.lastSeenAtMs > maxAgeMs) {
+            this.recentInteraction = null;
+            return null;
+        }
+        const { lastSeenAtMs: _lastSeenAtMs, ...snapshot } = this.recentInteraction;
+        return snapshot;
+    }
+    createRequestContext(input) {
+        const active = this.getActiveInteractionState();
+        const trigger = this.latestTrigger;
+        return {
+            traceId: generateTraceId(),
+            parentSpanId: this.activeSpanId,
+            requestId: input?.requestId ?? generateRequestId(),
+            requestSpanId: generateRequestSpanId(),
+            interactionId: generateInteractionId(),
+            interactionInitiator: trigger?.interactionInitiator ?? "background",
+            interactionStartEventKind: trigger?.interactionStartEventKind ?? "background_request",
+            originFrontendInteractionId: active?.interactionId ?? null,
+        };
+    }
+    getActiveInteractionState() {
+        return this.activeInteraction;
+    }
+    snapshotOf(state) {
+        return {
+            interactionId: state.interactionId,
+            interactionInitiator: state.interactionInitiator,
+            interactionStartEventKind: state.interactionStartEventKind,
+            targetStableKey: state.targetStableKey,
+            formKey: state.formKey,
+            interactionScopeKind: state.interactionScopeKind,
+            interactionScopeKey: state.interactionScopeKey,
+        };
+    }
+}

package/dist/exporter/batch.d.ts

@@ -0,0 +1,94 @@
+import type { InternalMetricsStore } from "../internal/metrics.js";
+import type { CluebaseConsentState, IngestUsageGovernorFeedback } from "../provider/types.js";
+import { type CollectionPermit } from "./browser-outbox.js";
+import { DiagnosticStore, type DiagnosticsSnapshot } from "./diagnostics.js";
+import type { IngestClient } from "./client.js";
+import type { BrowserSourceEvent } from "./source-event.js";
+/**
+ * 束ねて送る側が、送信の口に実際に求めるもの。
+ *
+ * **`IngestClient` 全体（26 member）を求めていました。** ここで使うのは 4 つだけ
+ * なので、試験の作り物は残り 22 個を持てず、`as unknown as IngestClient` で
+ * 嘘をつくしかない状態でした（`tests/README.md` §10）。求める口を実際に使うものへ
+ * 狭めると、作り物は嘘なしで満たせます。**5 つ目を使い始めたら、ここが変わって
+ * 作り物が落ちます。** それが狙いです。
+ *
+ * 一覧は `Pick` で本体から引きます。**member の形を書き写しません**
+ * （`CLAUDE.md` §0.2）。
+ */
+export type BatchIngestClient = Pick<IngestClient, "send" | "hasUsableBrowserToken" | "createBatchEnvelopeMetadata" | "measurePayloadBytes">;
+export type BatchTransportOptions = {
+    enabled: boolean;
+    flushIntervalMs: number;
+    maxPayloadBytes: number;
+    flushThresholdBytes?: number;
+    client: BatchIngestClient;
+    metrics?: InternalMetricsStore;
+    queueMaxBytes?: number;
+    queueMaxItems?: number;
+    projectKey?: string;
+    initialConsent?: CluebaseConsentState;
+    diagnostics?: DiagnosticStore;
+    onGovernorFeedback?: (feedback: IngestUsageGovernorFeedback) => void;
+};
+export type FlushDeadline = {
+    readonly signal: AbortSignal;
+    readonly deadlineAt: number;
+};
+export declare class BatchTransport {
+    private readonly outbox;
+    private readonly client;
+    private readonly enabled;
+    private readonly flushIntervalMs;
+    private readonly maxPayloadBytes;
+    private readonly flushThresholdBytes;
+    private readonly metrics;
+    private readonly diagnostics;
+    private readonly onGovernorFeedback;
+    private idleHandle;
+    private flushing;
+    private flushAgainAfterCurrent;
+    private activeSendController;
+    private closeDeadlineController;
+    private closeDeadlineTimer;
+    private closeDeadlineAt;
+    private closePermitOrdinal;
+    private flushDeadlineController;
+    private flushDeadlineTimer;
+    private flushDeadlineAt;
+    private lifecycle;
+    private closeHadTerminalDisposition;
+    private activeFlushPromise;
+    private enqueueTail;
+    private readonly seenEventIds;
+    private static readonly DEDUP_CAPACITY;
+    constructor(options: BatchTransportOptions);
+    getDiagnostics(): DiagnosticsSnapshot;
+    start(): void;
+    stop(): void;
+    dispose(): void;
+    currentConsent(): CluebaseConsentState;
+    capturePermit(): CollectionPermit;
+    setConsent(consent: CluebaseConsentState): void;
+    enqueue(event: BrowserSourceEvent, permit?: CollectionPermit): void;
+    private scheduleFlushDeadline;
+    beginFlushDeadline(): FlushDeadline | null;
+    endFlushDeadline(deadline: FlushDeadline | null | undefined): void;
+    flush(deadline?: FlushDeadline | null): Promise<void>;
+    private runFlushUntilIdle;
+    beginClose(): AbortSignal | null;
+    close(): Promise<void>;
+    private runFlushCycle;
+    private sendBatchWhilePermitted;
+    private applyDeliveryResult;
+    private applyFailedDelivery;
+    private applySuccessfulDelivery;
+    flushOnUnload(): void;
+    clear(): void;
+    private abortActiveSendForConsent;
+    private recordPendingBatchCount;
+    private clearCloseDeadline;
+    private currentDeadline;
+    private queueOutboxMutation;
+    private shouldRetainFailedBatch;
+}