@genn-inc/cluebase-frontend-sdk 0.0.1 → 0.0.2

package/dist/context/tab.js

@@ -14,7 +14,6 @@ const resolveClaimStorage = () => {
         }
     }
     catch {
-        // Ignore and continue without duplicate-tab coordination.
     }
     return null;
 };
@@ -33,7 +32,6 @@ const parseTabClaim = (value) => {
         }
     }
     catch {
-        // Ignore invalid claim records and let the current document reclaim it.
     }
     return null;
 };
@@ -64,7 +62,6 @@ export class TabManager {
             this.storage.setItem(STORAGE_KEYS.tabId, tabId);
         }
         catch {
-            // Swallow to keep SDK non-blocking.
         }
         return tabId;
     }
@@ -89,7 +86,6 @@ export class TabManager {
             }));
         }
         catch {
-            // Swallow to keep SDK non-blocking.
         }
     }
     installLifecycleCleanup() {
@@ -111,7 +107,6 @@ export class TabManager {
             globalThis.addEventListener("beforeunload", cleanup, { once: true });
         }
         catch {
-            // Swallow to keep SDK non-blocking.
         }
     }
 }

package/dist/context/trace.d.ts

@@ -1,3 +1,4 @@
+import { type ActionContextSnapshot } from "./action-context.js";
 export type TraceContextSnapshot = {
     traceId: string;
     activeSpanId: string | null;
@@ -7,12 +8,14 @@ export type RequestTraceContext = {
     parentSpanId: string | null;
     requestId: string;
     requestSpanId: string;
+    actionId: string | null;
     interactionId: string;
     interactionInitiator: string | null;
     interactionStartEventKind: string | null;
     originFrontendInteractionId: string | null;
 };
 export type ActiveInteractionSnapshot = {
+    actionId: string | null;
     interactionId: string;
     interactionInitiator: string | null;
     interactionStartEventKind: string | null;
@@ -22,6 +25,7 @@ export type ActiveInteractionSnapshot = {
     interactionScopeKey: string | null;
 };
 export type InteractionStartInput = {
+    actionId?: string | null;
     interactionId?: string | null;
     viewId?: string | null;
     interactionInitiator?: string | null;
@@ -41,6 +45,7 @@ export declare class TraceManager {
     private activeInteraction;
     private recentInteraction;
     private latestTrigger;
+    private readonly actionContextManager;
     constructor();
     reset(options?: {
         preserveActiveInteraction?: boolean;
@@ -53,7 +58,6 @@ export declare class TraceManager {
     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;
@@ -62,6 +66,7 @@ export declare class TraceManager {
         nowMs?: number;
     }): string | null;
     getActiveInteractionId(): string | null;
+    getActiveActionId(): string | null;
     getActiveInteractionSnapshot(): ActiveInteractionSnapshot | null;
     getRecentInteractionSnapshot(nowMs: number | undefined, maxAgeMs: number): ActiveInteractionSnapshot | null;
     createRequestContext(input?: {
@@ -70,7 +75,14 @@ export declare class TraceManager {
         urlKey?: string | null;
         nowMs?: number;
     }): RequestTraceContext;
+    getCurrentActionContext(): ActionContextSnapshot | null;
+    getBoundActionContext(): ActionContextSnapshot | null;
+    bindEventContext(event: Event): void;
+    runWithActionContext<T>(snapshot: ActionContextSnapshot, callback: () => T): T;
+    enableAsyncContext(): void;
+    disableAsyncContext(): void;
     private getActiveInteractionState;
+    private readAmbientActionContext;
     private snapshotOf;
 }
 export {};

package/dist/context/trace.js

@@ -1,7 +1,10 @@
 import { generateEventId, generateInteractionId, generateRequestId, generateRequestSpanId, generateTraceId, } from "../exporter/event-id.js";
+import { PrivateActionContextManager, } from "./action-context.js";
 const generateSpanId = () => {
     return `span_${generateEventId()}`;
 };
+const generateActionId = () => `action_${generateEventId()}`;
+const CLICK_SUBMIT_ACTIVATION_WINDOW_MS = 1000;
 export class TraceManager {
     constructor() {
         this.traceId = generateTraceId();
@@ -9,6 +12,7 @@ export class TraceManager {
         this.activeInteraction = null;
         this.recentInteraction = null;
         this.latestTrigger = null;
+        this.actionContextManager = new PrivateActionContextManager(() => this.readAmbientActionContext());
     }
     reset(options) {
         this.traceId = generateTraceId();
@@ -38,9 +42,11 @@ export class TraceManager {
     }
     startFrontendAction(input = {}) {
         const nowMs = input.nowMs ?? Date.now();
-        const interactionId = input.interactionId ?? generateInteractionId();
+        const actionId = input.actionId === undefined ? null : input.actionId?.trim() || null;
+        const interactionId = input.interactionId?.trim() || generateInteractionId();
         this.traceId = generateTraceId();
         this.activeInteraction = {
+            actionId,
             interactionId,
             interactionInitiator: input.interactionInitiator ?? null,
             interactionStartEventKind: input.interactionStartEventKind ?? null,
@@ -70,15 +76,6 @@ export class TraceManager {
         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,
@@ -89,10 +86,35 @@ export class TraceManager {
             interactionScopeKey: input.interactionScopeKey ?? null,
         };
     }
-    // UI 操作はページ visit interaction に参加する。request はこの id を共有せず、
-    // createRequestContext() で request ごとに fresh な interaction_id を持つ。
     startInteraction(input) {
-        const interactionId = this.getOrStartFrontendAction(input);
+        const nowMs = input.nowMs ?? Date.now();
+        const active = this.activeInteraction;
+        const formKey = input.formKey ?? null;
+        if (input.interactionId && active?.interactionId === input.interactionId) {
+            this.recordTrigger(input);
+            return active.interactionId;
+        }
+        const isSubmitActivation = input.interactionStartEventKind === "submit" &&
+            active?.interactionInitiator === "click" &&
+            active.formKey !== null &&
+            formKey !== null &&
+            active.formKey === formKey &&
+            this.recentInteraction !== null &&
+            nowMs - this.recentInteraction.lastSeenAtMs <=
+                CLICK_SUBMIT_ACTIVATION_WINDOW_MS;
+        const interactionId = isSubmitActivation
+            ? active.interactionId
+            : this.startFrontendAction({
+                ...input,
+                actionId: input.actionId?.trim() || generateActionId(),
+                nowMs,
+            });
+        if (isSubmitActivation && active) {
+            this.recentInteraction = {
+                ...this.snapshotOf(active),
+                lastSeenAtMs: nowMs,
+            };
+        }
         this.recordTrigger(input);
         return interactionId;
     }
@@ -100,20 +122,54 @@ export class TraceManager {
         return this.startInteraction(input);
     }
     joinClickInteractionForSubmit(input) {
-        if (!this.activeInteraction)
+        const nowMs = input.nowMs ?? Date.now();
+        const formKey = input.formKey ?? null;
+        if (!this.activeInteraction ||
+            this.activeInteraction.interactionInitiator !== "click" ||
+            this.activeInteraction.formKey === null ||
+            formKey === null ||
+            this.activeInteraction.formKey !== formKey ||
+            !this.recentInteraction ||
+            nowMs - this.recentInteraction.lastSeenAtMs >
+                CLICK_SUBMIT_ACTIVATION_WINDOW_MS) {
             return null;
+        }
         this.recordTrigger({
             formKey: input.formKey,
             interactionInitiator: "submit",
             interactionStartEventKind: "submit",
             nowMs: input.nowMs,
         });
+        this.recentInteraction = {
+            ...this.snapshotOf(this.activeInteraction),
+            lastSeenAtMs: nowMs,
+        };
         return this.activeInteraction.interactionId;
     }
     getActiveInteractionId() {
-        return this.getActiveInteractionSnapshot()?.interactionId ?? null;
+        return (this.actionContextManager.getCurrent()?.interactionId ??
+            this.activeInteraction?.interactionId ??
+            null);
+    }
+    getActiveActionId() {
+        return (this.actionContextManager.getCurrent()?.actionId ??
+            this.activeInteraction?.actionId ??
+            null);
     }
     getActiveInteractionSnapshot() {
+        const current = this.actionContextManager.getCurrent();
+        if (current) {
+            return {
+                actionId: current.actionId,
+                interactionId: current.interactionId,
+                interactionInitiator: current.interactionInitiator,
+                interactionStartEventKind: current.interactionStartEventKind,
+                targetStableKey: current.targetStableKey,
+                formKey: current.formKey,
+                interactionScopeKind: current.interactionScopeKind,
+                interactionScopeKey: current.interactionScopeKey,
+            };
+        }
         const active = this.getActiveInteractionState();
         return active ? this.snapshotOf(active) : null;
     }
@@ -133,24 +189,66 @@ export class TraceManager {
         return snapshot;
     }
     createRequestContext(input) {
-        const active = this.getActiveInteractionState();
-        const trigger = this.latestTrigger;
+        const current = this.actionContextManager.getCurrent();
+        const synchronousEvent = this.actionContextManager.getSynchronousEventContext();
+        const active = current ??
+            synchronousEvent ??
+            (this.actionContextManager.isEnabled()
+                ? null
+                : this.getActiveInteractionState());
+        const trigger = !this.actionContextManager.isEnabled() && active
+            ? this.latestTrigger
+            : null;
         return {
-            traceId: generateTraceId(),
-            parentSpanId: this.activeSpanId,
+            traceId: current?.traceId ?? generateTraceId(),
+            parentSpanId: current?.activeSpanId ?? this.activeSpanId,
             requestId: input?.requestId ?? generateRequestId(),
             requestSpanId: generateRequestSpanId(),
+            actionId: active?.actionId ?? null,
             interactionId: generateInteractionId(),
-            interactionInitiator: trigger?.interactionInitiator ?? "background",
-            interactionStartEventKind: trigger?.interactionStartEventKind ?? "background_request",
+            interactionInitiator: trigger?.interactionInitiator ??
+                active?.interactionInitiator ??
+                "background",
+            interactionStartEventKind: trigger?.interactionStartEventKind ??
+                active?.interactionStartEventKind ??
+                "background_request",
             originFrontendInteractionId: active?.interactionId ?? null,
         };
     }
+    getCurrentActionContext() {
+        return (this.actionContextManager.getCurrent() ?? this.readAmbientActionContext());
+    }
+    getBoundActionContext() {
+        return this.actionContextManager.getCurrent();
+    }
+    bindEventContext(event) {
+        this.actionContextManager.bindEvent(event);
+    }
+    runWithActionContext(snapshot, callback) {
+        return this.actionContextManager.run(snapshot, callback);
+    }
+    enableAsyncContext() {
+        this.actionContextManager.enable();
+    }
+    disableAsyncContext() {
+        this.actionContextManager.disable();
+    }
     getActiveInteractionState() {
         return this.activeInteraction;
     }
+    readAmbientActionContext() {
+        const active = this.activeInteraction;
+        if (!active)
+            return null;
+        return {
+            ...this.snapshotOf(active),
+            traceId: this.traceId,
+            activeSpanId: this.activeSpanId,
+        };
+    }
     snapshotOf(state) {
         return {
+            actionId: state.actionId,
             interactionId: state.interactionId,
             interactionInitiator: state.interactionInitiator,
             interactionStartEventKind: state.interactionStartEventKind,

package/dist/exporter/batch.d.ts

@@ -4,18 +4,6 @@ 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;

package/dist/exporter/batch.js

@@ -14,18 +14,8 @@ export class BatchTransport {
         this.flushDeadlineAt = null;
         this.lifecycle = "open";
         this.closeHadTerminalDisposition = false;
-        // Promise tracking the currently executing flush cycle. Awaiters that
-        // arrive while a flush is in flight await this promise so the SDK's public
-        // `flush()` resolves after token issuance and canonical ingest have
-        // completed.
         this.activeFlushPromise = null;
-        // A public enqueue cannot await Web Locks, so it appends its durable draft
-        // mutation here. A flush snapshots and awaits this chain before acquiring
-        // the same project lock, which prevents a flush from racing an enqueue.
         this.enqueueTail = Promise.resolve();
-        // Capture modules and OTel span export both feed source signals into this
-        // transport. The bounded ring prevents duplicate event_id rows from being
-        // sent to ingest.
         this.seenEventIds = new Set();
         this.enabled = options.enabled;
         this.flushIntervalMs = Math.max(100, options.flushIntervalMs);
@@ -93,10 +83,6 @@ export class BatchTransport {
             this.metrics?.increment("dropped_count");
             return;
         }
-        // Take ownership of the event before enqueue returns: `ownEvent` deep
-        // clones and validates it, so a caller mutating the object afterwards
-        // cannot taint what is retained and sent. Events without a usable
-        // event_id cannot be deduped or retained, so drop them here.
         const collectionPermit = permit ?? this.outbox.capturePermit();
         const owned = ownEvent(event, collectionPermit);
         const eventId = event.event_id;
@@ -105,11 +91,6 @@ export class BatchTransport {
             return;
         }
         void this.queueOutboxMutation(async () => {
-            // Dedup by event_id with a bounded LRU so converged capture and OTel
-            // emission cannot produce duplicate ingest rows. Registration is
-            // committed on the serialized mutation queue only after retention
-            // succeeds, so a rejected retention (capacity or stale generation)
-            // leaves the id retriable instead of silently swallowing the retry.
             if (this.seenEventIds.has(eventId)) {
                 return;
             }
@@ -120,8 +101,6 @@ export class BatchTransport {
             }
             this.seenEventIds.add(eventId);
             if (this.seenEventIds.size > BatchTransport.DEDUP_CAPACITY) {
-                // Drop the oldest entry to keep the set bounded. Set iteration
-                // order is insertion order in JS, so the first key is the oldest.
                 const oldest = this.seenEventIds.values().next().value;
                 if (oldest !== undefined)
                     this.seenEventIds.delete(oldest);
@@ -175,8 +154,6 @@ export class BatchTransport {
     async flush(deadline = this.currentDeadline()) {
         if (this.lifecycle === "closed")
             return;
-        // Link onto the in-flight flush so awaiters resolve after the token and
-        // ingest pipeline has actually drained.
         if (this.flushing) {
             this.flushAgainAfterCurrent = true;
             if (this.activeFlushPromise) {
@@ -210,10 +187,6 @@ export class BatchTransport {
     }
     async runFlushUntilIdle(deadline) {
         while (true) {
-            // Enqueue mutations acquire the same project Web Lock as the flush
-            // cycle. Wait for mutations outside that lock; awaiting `enqueueTail`
-            // from inside `withDeliveryLock` deadlocks when a capture event arrives
-            // while the first batch is being sent.
             const enqueuesAtCycleStart = this.enqueueTail;
             await enqueuesAtCycleStart;
             await this.outbox.withDeliveryLock(() => this.runFlushCycle(deadline));

package/dist/exporter/browser-outbox.js

@@ -33,9 +33,6 @@ export class BrowserOutbox {
         this.initialDenialPending = options.initialConsent === "denied";
         if (this.initialDenialPending)
             this.legacyImportBlocked = true;
-        // Consent is the only state that must be available before the first lock
-        // acquisition. All outbox scans and mutations happen under the project
-        // Web Lock in `withDeliveryLock`.
         if (!this.initialDenialPending)
             this.restore(false);
         if (!this.durableOutboxSupported) {
@@ -262,11 +259,6 @@ export class BrowserOutbox {
                 break;
             }
             this.pending.push(record);
-            // The pending record now owns these events. Drop the drafts from the
-            // in-memory list unconditionally so a failed storage removal cannot
-            // leave them as live candidates for a duplicate send; the pending
-            // record carries the responsibility to delete any surviving draft
-            // record when it is finalized (`removeClaimedDraftRecords`).
             for (const draft of selected) {
                 this.removeRecord(draftRecordKey(this.prefix, draft.eventKeyHash));
             }
@@ -293,11 +285,6 @@ export class BrowserOutbox {
         const key = pendingRecordKey(this.prefix, record.batchId);
         if (record.kind === "pending" ||
             record.nextOrdinal === record.children.length - 1) {
-            // Delete any draft record still claimed by this batch before dropping
-            // the pending record. If a claimed draft cannot be removed, keep the
-            // pending record so the draft stays covered and cannot resurrect as a
-            // fresh event on the next restore; the batch is retried idempotently
-            // instead.
             if (!this.removeClaimedDraftRecords(record))
                 return false;
             if (!this.removeRecord(key))
@@ -346,8 +333,6 @@ export class BrowserOutbox {
                     removed;
         }
         for (const pending of this.pending) {
-            // Also remove any draft record the batch still claims so a draft that
-            // survived its commit cannot outlive the clear and resurrect on restore.
             removed = this.removeClaimedDraftRecords(pending) && removed;
             removed =
                 this.removeRecord(pendingRecordKey(this.prefix, pending.batchId)) &&
@@ -436,8 +421,6 @@ export class BrowserOutbox {
             });
             return;
         }
-        // A synchronous revocation must fence mutations that were queued before
-        // its durable commit. Never restore an older permitted record over it.
         if (this.consent === "denied")
             return;
         const restored = this.restore(false);

package/dist/exporter/client.d.ts

@@ -27,7 +27,6 @@ export type SendEventsOptions = {
     requireCachedBrowserToken?: boolean;
     maxPayloadBytes?: number;
     metadata?: BatchEnvelopeMetadata;
-    /** Absolute monotonic deadline shared by one SDK flush or close operation. */
     deadlineAt?: number;
 };
 export type SendEventsResult = {
@@ -72,20 +71,6 @@ export declare class IngestClient {
     private recordDecision;
     private postBatch;
     private createId;
-    /**
-     * Obtain a browser ingest token directly from the Cluebase backend.
-     *
-     * The SDK POSTs `{ projectKey }` to
-     * `<endpoint>/api/v1/ingest/browser-tokens`; the browser stamps the `Origin`
-     * header automatically and the Cluebase backend validates project key + origin
-     * before minting a short-lived token.
-     *
-     * Tokens are cached in-memory until they are within
-     * `BROWSER_TOKEN_REFRESH_LEEWAY_MS` of expiry, at which point the next
-     * `ensureBrowserToken()` call transparently refreshes them. The function
-     * throws on transport / HTTP errors so the caller (`send`) can mark the
-     * batch as failed without bypassing the credentialled boundary.
-     */
     private getUsableCachedBrowserToken;
     private ensureBrowserToken;
     private safeEnsureBrowserToken;

package/dist/exporter/client.js

@@ -19,17 +19,10 @@ export const resolveCanonicalIngestEndpoint = (endpoint) => {
     if (endpoint.endsWith(CANONICAL_INGEST_PATH_SUFFIX)) {
         return endpoint;
     }
-    // Strip a trailing slash if the host app provided only the base URL.
     const trimmed = endpoint.endsWith("/") ? endpoint.slice(0, -1) : endpoint;
     if (trimmed.endsWith("/api/v1")) {
         return `${trimmed}${CANONICAL_INGEST_PATH_SUFFIX}`;
     }
-    // Host apps typically pass the bare API origin (e.g. `http://api.example.com`
-    // or `http://127.0.0.1:4000`). Append the full canonical ingest path so the
-    // SDK can POST to a real Cluebase endpoint instead of the origin root. This
-    // mirrors `resolveBrowserTokenEndpoint`, which already rewrites the pathname
-    // unconditionally — keeping the two resolvers in sync prevents the SDK from
-    // silently posting events to `/` while still successfully fetching tokens.
     try {
         const parsed = new URL(trimmed);
         if (parsed.pathname === "" || parsed.pathname === "/") {
@@ -40,12 +33,9 @@ export const resolveCanonicalIngestEndpoint = (endpoint) => {
         }
     }
     catch {
-        // Relative / malformed endpoints fall through unchanged.
     }
     return endpoint;
 };
-// Refresh the cached token this many milliseconds before its real expiry so
-// transports do not race a token that expires mid-flight.
 const BROWSER_TOKEN_REFRESH_LEEWAY_MS = 60000;
 class BrowserTokenRequestError extends Error {
     constructor(status) {
@@ -58,8 +48,6 @@ export const resolveBrowserTokenEndpoint = (endpoint) => {
     if (!endpoint) {
         return CANONICAL_BROWSER_TOKEN_PATH;
     }
-    // `endpoint` may already point at an ingest path. Derive the API root, then
-    // append the canonical browser-tokens path.
     try {
         const parsed = new URL(endpoint);
         parsed.pathname = CANONICAL_BROWSER_TOKEN_PATH;
@@ -68,7 +56,6 @@ export const resolveBrowserTokenEndpoint = (endpoint) => {
         return parsed.toString();
     }
     catch {
-        // Fall back to a string-based rewrite for unusual / relative endpoints.
         const trimmed = endpoint.endsWith("/") ? endpoint.slice(0, -1) : endpoint;
         const apiV1Idx = trimmed.indexOf("/api/v1");
         if (apiV1Idx >= 0) {
@@ -82,8 +69,6 @@ export class IngestClient {
     constructor(options) {
         this.sourceIdentifier = DEFAULT_FRONTEND_SOURCE_IDENTIFIER;
         this.producerId = DEFAULT_FRONTEND_SOURCE_IDENTIFIER;
-        // Memory-only token cache. Refreshed before expiry so the next ingest POST
-        // always has a live token.
         this.cachedToken = null;
         this.pendingTokenRequest = null;
         this.endpoint = resolveCanonicalIngestEndpoint(options.endpoint);
@@ -231,16 +216,12 @@ export class IngestClient {
             .byteLength;
     }
     stringifyPayload(events, metadata) {
-        // Emit the canonical batch envelope against `/ingest/browser`. Field names
-        // follow the camelCase `observationSourceEventBatchRequestSchema`.
         return JSON.stringify({
             sourceType: "frontend_sdk",
             sourceSchemaVersion: String(this.schemaVersion),
             batchId: metadata.batch_id,
             idempotencyKey: metadata.idempotency_key,
             sentAt: metadata.sent_at,
-            // いま適用している方針の合印。受付側は違う時だけ本体を返す。持っていなければ
-            // 省く（= まだ全部伏せている）ので、受付側は必ず本体を返してくれる。
             privacyPolicyToken: appliedPrivacyPolicyToken(),
             producerMetadata: {
                 producer_id: this.producerId,
@@ -251,9 +232,6 @@ export class IngestClient {
         });
     }
     withSourceEvidence(event) {
-        // Privacy metadata is explicit at the transport boundary. Re-apply the
-        // strictest fallback so malformed upstream events never ship without
-        // privacy declaration.
         return {
             ...event,
             source_event_id: event.source_event_id ?? event.event_id,
@@ -333,7 +311,6 @@ export class IngestClient {
                 bodyText: await response.text(),
                 localSubmittedCount: input.localSubmittedCount,
             });
-            // 受付側が方針を返した時だけ適用する。読めない形なら全部伏せた側へ戻る。
             if (decision.privacyPolicy !== undefined) {
                 applyDeliveredPrivacyPolicy(decision.privacyPolicy);
             }
@@ -364,20 +341,6 @@ export class IngestClient {
     createId() {
         return generateEventId();
     }
-    /**
-     * Obtain a browser ingest token directly from the Cluebase backend.
-     *
-     * The SDK POSTs `{ projectKey }` to
-     * `<endpoint>/api/v1/ingest/browser-tokens`; the browser stamps the `Origin`
-     * header automatically and the Cluebase backend validates project key + origin
-     * before minting a short-lived token.
-     *
-     * Tokens are cached in-memory until they are within
-     * `BROWSER_TOKEN_REFRESH_LEEWAY_MS` of expiry, at which point the next
-     * `ensureBrowserToken()` call transparently refreshes them. The function
-     * throws on transport / HTTP errors so the caller (`send`) can mark the
-     * batch as failed without bypassing the credentialled boundary.
-     */
     getUsableCachedBrowserToken(nowMs = Date.now()) {
         if (this.cachedToken &&
             this.cachedToken.expiresAtMs > nowMs + BROWSER_TOKEN_REFRESH_LEEWAY_MS) {
@@ -394,8 +357,6 @@ export class IngestClient {
         if (this.pendingTokenRequest) {
             return await awaitWithAbort(this.pendingTokenRequest, signal);
         }
-        // `x-cluebase-project-key` lets the Cluebase API resolve project-scoped CORS and
-        // token issuance consistently with the JSON body.
         const request = (async () => {
             const response = await fetchWithDeadline(this.browserTokenEndpoint, {
                 method: "POST",
@@ -455,10 +416,6 @@ export class IngestClient {
             if (isConsentAbort(options.signal)) {
                 return { ok: false, retryStrategy: "drop_event" };
             }
-            // A transport failure carries no status and may succeed later. Anything
-            // that did reach Cluebase is classified by the same owner batch delivery
-            // uses, so a refusal the token endpoint will repeat forever — a malformed
-            // body, a bad key, a wrong path — stops instead of being replayed.
             if (!(error instanceof BrowserTokenRequestError) || error.status === null) {
                 return { ok: false, retryStrategy: "retry_same_batch" };
             }

package/dist/exporter/delivery-response-contract.js

@@ -1,4 +1,3 @@
-// 止める対象と上限の種類は正本から生成した部品を読みます。
 import { COST_CAPABILITIES, LIMIT_KINDS } from "../_generated/usage-governor-tables.js";
 import { z } from "zod";
 const MAX_INGEST_EVENTS_PER_BATCH = 10000;
@@ -33,11 +32,6 @@ const ingestUsageGovernorFeedbackSchema = z.object({
 });
 const boundedCount = z.number().int().nonnegative().max(MAX_INGEST_EVENTS_PER_BATCH);
 const positiveCount = boundedCount.refine((count) => count > 0);
-// 顧客が画面で平文にした項目。**受付側の合印と違う時だけ載ります。**
-// 封筒の契約は受付側が正本 (`ingest-privacy-policy-delivery.schema.ts`)。この配る
-// 部品は `@cluebase/schema` を実行時に持てない (= 顧客の bundle に入れない) ので、
-// この file が受け取る形を持ちます。ここと正本がずれたら、届いた方針は形が
-// 合わずに捨てられ、**全部伏せた側へ倒れます。**
 export const ingestPrivacyPolicySchema = z
     .object({
     token: z.string().trim().min(1).max(200),

package/dist/exporter/delivery-response.d.ts

@@ -4,7 +4,6 @@ export declare const BROWSER_REJECTION_STRATEGIES: Readonly<Record<string, Inges
 export type { IngestRetryStrategy } from "./delivery-response-contract.js";
 export type BrowserDeliveryDecision = {
     readonly ok: boolean;
-    /** 受付側が返した方針。合印が同じなら来ない。 */
     readonly privacyPolicy?: unknown;
     readonly retryStrategy: IngestRetryStrategy | null;
     readonly governor: IngestUsageGovernorFeedback | null;
@@ -19,19 +18,4 @@ export declare const evaluateBrowserDeliveryResponse: (input: {
     readonly bodyText: string;
     readonly localSubmittedCount: number;
 }) => BrowserDeliveryDecision;
-/**
- * Decide from the HTTP status alone whether a failed exchange with Cluebase is
- * worth replaying.
- *
- * This is the single owner of that judgement. Batch delivery consults it when
- * the body carries no usable verdict, and browser-token acquisition consults it
- * because that endpoint carries no verdict at all. Without one owner the same
- * status is permanent on one path and transient on the other, and a request
- * that can never succeed is replayed until the customer's events expire.
- *
- * A status is only replayed when it says "the same request may succeed later".
- * That is the rule the SDK's own core already applies — OpenTelemetry's OTLP
- * exporter retries 429/502/503/504 and nothing else (`isExportRetryable`) —
- * widened here to the statuses this ingest contract additionally defines.
- */
 export declare const classifyIngestHttpStatus: (status: number) => IngestRetryStrategy;