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

package/dist/exporter/delivery-response.js

@@ -92,32 +92,13 @@ const invalidResponse = () => ({
     acceptedPartial: false,
     reason: "invalid_response",
 });
-/**
- * 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 const classifyIngestHttpStatus = (status) => {
-    // A 2xx that got this far means the body did not match the contract. That can
-    // be a transient rewrite in transit, so it stays replayable.
     if (status >= 200 && status < 300)
         return "retry_same_batch";
     if (status === 409)
         return "mark_failed";
     if (status === 413)
         return "split_batch";
-    // Deterministic refusals: the request is wrong, unauthorized, or aimed at
-    // something that is not there. Replaying it changes nothing.
     if ([400, 401, 403, 404, 405, 406, 410, 415].includes(status)) {
         return "stop_and_report";
     }

package/dist/exporter/frontend-resource.d.ts

@@ -6,15 +6,6 @@ export type FrontendResourceInput = FrontendResourceAttributes | {
 type ResourceRecord = {
     [key: string]: string;
 };
-/**
- * Build the only Resource attributes emitted by the browser SDK's own OTel
- * provider. Values are intentionally strings so the same snapshot can be
- * used to construct an OTel Resource and to enrich raw source signals.
- */
 export declare const createFrontendResourceAttributes: (resolved: ResolvedCluebaseConfig) => FrontendResourceAttributes;
-/**
- * Copy only approved frontend Resource attributes into the serialized source
- * signal. The returned object is a detached, bounded JSON-safe snapshot.
- */
 export declare const toFrontendSourceResource: (resource: FrontendResourceInput | undefined, deniedKeys?: readonly string[]) => ResourceRecord;
 export {};

package/dist/exporter/frontend-resource.js

@@ -4,11 +4,6 @@ import { CLUEBASE_OTEL_SDK_SOURCE_REQUIRED_RESOURCE_KEYS, CLUEBASE_OTEL_SDK_SOUR
 const FRONTEND_RESOURCE_KEYS = new Set(CLUEBASE_OTEL_SDK_SOURCE_RESOURCE_KEYS);
 const FRONTEND_REQUIRED_RESOURCE_KEYS = new Set(CLUEBASE_OTEL_SDK_SOURCE_REQUIRED_RESOURCE_KEYS);
 const MAX_RESOURCE_VALUE_BYTES = 512;
-/**
- * Build the only Resource attributes emitted by the browser SDK's own OTel
- * provider. Values are intentionally strings so the same snapshot can be
- * used to construct an OTel Resource and to enrich raw source signals.
- */
 export const createFrontendResourceAttributes = (resolved) => ({
     "service.name": resolved.producerId,
     "service.version": resolved.release.frontendRelease ?? "unknown",
@@ -20,10 +15,6 @@ export const createFrontendResourceAttributes = (resolved) => ({
     "cluebase.sdk.collection_mode": resolved.collection?.mode ?? "standard",
     "cluebase.runtime_language": "browser",
 });
-/**
- * Copy only approved frontend Resource attributes into the serialized source
- * signal. The returned object is a detached, bounded JSON-safe snapshot.
- */
 export const toFrontendSourceResource = (resource, deniedKeys = []) => {
     const input = resource && "attributes" in resource ? resource.attributes : resource;
     const output = {};

package/dist/exporter/observation-source-event-exporter.d.ts

@@ -1,15 +1,3 @@
-/**
- * Browser-SDK observation source event exporter.
- *
- * Production OTel {@link SpanExporter} for the Frontend SDK. Forwards each
- * {@link ReadableSpan} as a source-signal envelope and routes it onto the
- * SDK's existing transport buffer. Final classification and canonical shaping
- * happen in the Cluebase backend ingestion core.
- *
- * The exporter is registered onto the global `WebTracerProvider` in
- * `provider/sdk.ts:cluebase.init`. `enqueue(event)` accepts source-signal
- * envelopes from capture modules.
- */
 import { type ExportResult, ExportResultCode } from "@opentelemetry/core";
 import type { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
 import type { CluebaseContext } from "../provider/types.js";
@@ -22,20 +10,8 @@ export interface ObservationSourceEventExporterOptions {
     getCollectionPermit?: (span: ReadableSpan | null) => CollectionPermit | undefined;
     flushImpl: () => Promise<void>;
     shutdownImpl?: () => Promise<void>;
-    /**
-     * Returns the active {@link CluebaseContext} for the current SDK instance.
-     * Called once per `export()` invocation so browser-environment fields
-     * (device, browser, locale, etc.) reflect the SDK state at export time.
-     */
     getContext: () => CluebaseContext;
     deniedKeys?: readonly string[];
-    /**
-     * URL prefixes that should NOT produce source-signal events.
-     * Used to skip spans that the Cluebase ingest BatchTransport itself
-     * generates when the host installs ``@opentelemetry/instrumentation-fetch``
-     * (otherwise Cluebase's own POSTs would loop back through the exporter as
-     * fetch spans, generating duplicate ingest events ad-infinitum).
-     */
     ignoreUrlPrefixes?: readonly string[];
 }
 export declare class ObservationSourceEventExporter implements SpanExporter {
@@ -52,10 +28,6 @@ export declare class ObservationSourceEventExporter implements SpanExporter {
     private skippedLoopSpanCount;
     constructor(options: ObservationSourceEventExporterOptions);
     private ignoreSpanReason;
-    /**
-     * Enqueue a source-signal event emitted by capture modules through
-     * `context.onEvent`.
-     */
     enqueue(event: BrowserSourceSignalEvent): void;
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
     forceFlush(): Promise<void>;

package/dist/exporter/observation-source-event-exporter.js

@@ -1,15 +1,3 @@
-/**
- * Browser-SDK observation source event exporter.
- *
- * Production OTel {@link SpanExporter} for the Frontend SDK. Forwards each
- * {@link ReadableSpan} as a source-signal envelope and routes it onto the
- * SDK's existing transport buffer. Final classification and canonical shaping
- * happen in the Cluebase backend ingestion core.
- *
- * The exporter is registered onto the global `WebTracerProvider` in
- * `provider/sdk.ts:cluebase.init`. `enqueue(event)` accepts source-signal
- * envelopes from capture modules.
- */
 import { ExportResultCode } from "@opentelemetry/core";
 import { logSwallowed } from "../internal/internal-log.js";
 import { spanToSourceSignalEvent } from "./span-to-source-signal.js";
@@ -50,10 +38,6 @@ export class ObservationSourceEventExporter {
         }
         return null;
     }
-    /**
-     * Enqueue a source-signal event emitted by capture modules through
-     * `context.onEvent`.
-     */
     enqueue(event) {
         if (this.closed)
             return;
@@ -122,7 +106,6 @@ export class ObservationSourceEventExporter {
             await this.flushImpl();
         }
         catch (cause) {
-            // forceFlush is best-effort; swallow to keep the OTel contract.
             logSwallowed("forceFlush", cause);
         }
     }
@@ -139,7 +122,6 @@ export class ObservationSourceEventExporter {
             }
         }
         catch (cause) {
-            // shutdown is non-raising per the OTel contract.
             logSwallowed("shutdown", cause);
         }
     }

package/dist/exporter/parameter-snapshot.js

@@ -36,21 +36,13 @@ const measureSerializedBytes = (value) => {
         return undefined;
     }
 };
-/**
- * 値をそのまま載せてよいのは、**顧客が画面で名指しした項目だけ**。
- *
- * 載せるのは文字・数・真偽に限ります。入れ子は葉に来ないので、それ以外の形が
- * ここへ来たら伏せた側へ倒します。
- */
 const releasedLeafValue = (value) => value === null ||
     typeof value === "string" ||
     typeof value === "number" ||
     typeof value === "boolean"
     ? value
     : MASKED_VALUE;
-const buildLeaf = (value, captureMode, 
-// 顧客がこの項目を名指ししたか。**既定は false = 伏せる。**
-released = false) => {
+const buildLeaf = (value, captureMode, released = false) => {
     const leafType = inferLeafType(value);
     const originalSizeBytes = captureMode === PARAMETER_CAPTURE_MODE.forbidden
         ? undefined
@@ -71,20 +63,6 @@ released = false) => {
 export const buildUnavailableParameterSnapshot = () => ({
     [SNAPSHOT_UNAVAILABLE_KEY]: buildLeaf("snapshot_unavailable", PARAMETER_CAPTURE_MODE.maskedFingerprint),
 });
-/**
- * その節は葉か、降りる枝か。
- *
- * **見分ける手順をここに書きません。** ここには鍵の有無だけを見る版が書かれており、
- * 受付側は型まで見ていました。`{ type: 123, capture_mode: null, value: 1 }` が
- * **送る側にとって葉、受け取る側にとって枝**という状態で、受け取った側は中へ降りて
- * `type` / `value` / `capture_mode` を項目名として扱っていました。降りる側の 1 つは
- * 伏せる判定です。
- *
- * 手順は正本（`packages/cluebase-schema/.../observation-classification.schema.ts`）から
- * 生成され、受付側も同じものを受け取ります。共有の部品は顧客の手元で解決できない
- * ので取り込めず、**生成して同梱する**のがこの repo の作法です
- * （`_generated/ingest-privacy-tables.ts` と同じ）。
- */
 const isParameterSnapshotLeaf = (value) => hasParameterSnapshotLeafShape(value);
 export const truncateParameterSnapshotValue = (value) => {
     if (Array.isArray(value)) {
@@ -197,7 +175,6 @@ export const buildParameterSnapshotBundle = (value, options) => {
             : null;
         const captureMode = PARAMETER_CAPTURE_MODE.maskedFingerprint;
         return {
-            // 名指しされた項目だけ値を持つ。名指ししていない項目は伏せたまま。
             snapshot: buildLeaf(current, captureMode, matchedAllowedPath !== null),
             allowedValueKeys: matchedAllowedPath ? [matchedAllowedPath] : [],
         };

package/dist/exporter/raw-event-to-source-signal.js

@@ -1,6 +1,3 @@
-// 相関のために残す属性名は、正本から生成した部品を読みます。ここには手で書かれて
-// おり、もう 1 か所の写しと 15 語食い違い、`cluebase.session_id` `mcp.session.id` が
-// 欠けていて**落ちていました**（`session` を含むため落とす側に当たる）。
 import { CLUEBASE_CORRELATION_ATTRIBUTE_KEYS } from "../_generated/correlation-attribute-keys.js";
 import { cluebaseAuthoredPropertyAttribute } from "../instrumentation/cluebase-authored-attributes.js";
 import { EVENT_SOURCE, EVENT_VERSION, SOURCE_SCHEMA_VERSION, } from "../provider/constants.js";
@@ -11,7 +8,7 @@ import { SDK_SOURCE_SIGNAL_EVENT_NAME, SDK_SOURCE_SIGNAL_EVENT_TYPE, } from "./s
 export const RAW_FRONTEND_SOURCE_SIGNAL_KIND = "frontend_raw_event";
 const PUBLIC_CUSTOM_EVENT_NAME_PATTERN = /^[A-Za-z0-9_.:-]{1,128}$/;
 const isDynamicPayloadObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-function toJsonValue(value, deniedKeys = [], onMaskingError) {
+function toJsonValue(value, deniedKeys = [], onMaskingError, preserveExplicitProperties = false) {
     if (value === null)
         return null;
     if (typeof value === "string" ||
@@ -20,7 +17,7 @@ function toJsonValue(value, deniedKeys = [], onMaskingError) {
         return typeof value === "number" && !Number.isFinite(value) ? null : value;
     }
     if (Array.isArray(value)) {
-        return value.map((entry) => toJsonValue(entry, deniedKeys, onMaskingError));
+        return value.map((entry) => toJsonValue(entry, deniedKeys, onMaskingError, preserveExplicitProperties));
     }
     if (isDynamicPayloadObject(value)) {
         const record = {};
@@ -33,11 +30,12 @@ function toJsonValue(value, deniedKeys = [], onMaskingError) {
             return record;
         }
         for (const [key, entry] of entries) {
-            if (!CLUEBASE_CORRELATION_ATTRIBUTE_KEYS.has(key) &&
+            if (!preserveExplicitProperties &&
+                !CLUEBASE_CORRELATION_ATTRIBUTE_KEYS.has(key) &&
                 isDeniedKey(key, deniedKeys)) {
                 continue;
             }
-            record[key] = toJsonValue(entry, deniedKeys, onMaskingError);
+            record[key] = toJsonValue(entry, deniedKeys, onMaskingError, preserveExplicitProperties);
         }
         return record;
     }
@@ -45,7 +43,7 @@ function toJsonValue(value, deniedKeys = [], onMaskingError) {
         return value.toString();
     return null;
 }
-function toJsonRecord(value, deniedKeys = [], onMaskingError) {
+function toJsonRecord(value, deniedKeys = [], onMaskingError, preserveExplicitProperties = false) {
     const record = {};
     let entries;
     try {
@@ -60,7 +58,10 @@ function toJsonRecord(value, deniedKeys = [], onMaskingError) {
             isDeniedKey(key, deniedKeys)) {
             continue;
         }
-        record[key] = toJsonValue(entry, deniedKeys, onMaskingError);
+        record[key] =
+            preserveExplicitProperties && key === "properties"
+                ? toJsonValue(entry, deniedKeys, onMaskingError, true)
+                : toJsonValue(entry, deniedKeys, onMaskingError);
     }
     return record;
 }
@@ -111,6 +112,7 @@ function contextRecord(context, overrides = {}) {
         trace_id: overrides.trace_id ?? context.trace_id,
         request_id: overrides.request_id ?? context.request_id,
         request_span_id: overrides.request_span_id ?? context.request_span_id,
+        action_id: overrides.action_id ?? context.action_id,
         interaction_id: overrides.interaction_id ?? context.interaction_id,
         correlation_id: context.correlation_id,
         sdk_collection_mode: context.sdk_collection_mode,
@@ -146,7 +148,8 @@ export function rawEventToSourceSignalEvent(raw, options) {
     const eventId = generateEventId();
     const occurredAtMs = raw.occurredAtMs ?? Date.now();
     const occurredAt = new Date(occurredAtMs).toISOString();
-    const payload = toJsonRecord(raw.payload, options.deniedKeys, options.onMaskingError);
+    const customEventOrigin = raw.type === "custom_emitted" ? trustedCustomOrigin(raw.payload) : null;
+    const payload = toJsonRecord(raw.payload, options.deniedKeys, options.onMaskingError, customEventOrigin === "explicit_track");
     dropNonFiniteMetrics(payload);
     const requestId = stringPayload(raw.payload, "requestId") ??
         context.request_id ??
@@ -154,6 +157,7 @@ export function rawEventToSourceSignalEvent(raw, options) {
     const requestSpanId = stringPayload(raw.payload, "requestSpanId") ??
         context.request_span_id ??
         generateRequestSpanId();
+    const actionId = stringPayload(raw.payload, "actionId") ?? context.action_id ?? null;
     const traceId = stringPayload(raw.payload, "traceId") ??
         context.trace_id ??
         generateTraceId();
@@ -169,7 +173,6 @@ export function rawEventToSourceSignalEvent(raw, options) {
         "cluebase.raw_event.payload": payload,
         "cluebase.event_source": EVENT_SOURCE,
     };
-    const customEventOrigin = raw.type === "custom_emitted" ? trustedCustomOrigin(raw.payload) : null;
     const customEventName = raw.type === "custom_emitted" && customEventOrigin
         ? stringPayload(raw.payload, "eventName")
         : null;
@@ -186,6 +189,8 @@ export function rawEventToSourceSignalEvent(raw, options) {
         attributes["cluebase.request.id"] = requestId;
     if (requestSpanId)
         attributes["cluebase.request_span_id"] = requestSpanId;
+    if (actionId)
+        attributes["cluebase.action.id"] = actionId;
     if (interactionId)
         attributes["cluebase.interaction.id"] = interactionId;
     if (occurrenceKind)
@@ -264,6 +269,7 @@ export function rawEventToSourceSignalEvent(raw, options) {
         trace_id: traceId,
         request_id: requestId,
         request_span_id: requestSpanId,
+        action_id: actionId,
         interaction_id: interactionId,
         frontend_release: context.frontend_release,
         backend_release: null,
@@ -290,6 +296,7 @@ export function rawEventToSourceSignalEvent(raw, options) {
                 trace_id: traceId,
                 request_id: requestId,
                 request_span_id: requestSpanId,
+                action_id: actionId,
                 interaction_id: interactionId,
             }),
         },

package/dist/exporter/sanitize.d.ts

@@ -6,7 +6,7 @@ export type SanitizationAccumulator = {
 };
 export declare const isDeniedKey: (key: string, deniedKeys?: readonly string[]) => boolean;
 export declare const sanitizeHeaders: (headers: Record<string, string>, deniedKeys?: string[]) => Record<string, string>;
-export declare const sanitizeObject: (value: unknown, deniedKeys?: string[], summary?: SanitizationAccumulator, pathPrefix?: string) => unknown;
+export declare const sanitizeObject: (value: unknown, deniedKeys?: string[], summary?: SanitizationAccumulator, pathPrefix?: string, maskIdentityPii?: boolean, preserveExplicitTraits?: boolean) => unknown;
 export declare const parseUrlForNetwork: (rawUrl: string) => {
     host: string;
     pathTemplate: string;
@@ -16,15 +16,4 @@ export declare const parseUrlForNetwork: (rawUrl: string) => {
 };
 export declare const maybeParseJson: (value: unknown) => unknown;
 export { detectIdentityPII };
-/**
- * Synchronous deterministic SHA-256 hash for identity values that look
- * like PII. The identity sanitization path must remain synchronous
- * because `identify(userId)` is sync-only by SDK contract.
- *
- * Output format: `cluebase_pii_hashed:<32-hex>`.
- *
- * The algorithm name, the digest length and the prefix are read from the
- * generated policy, not written here, so the three SDKs produce the same
- * token for the same input by construction rather than by assertion.
- */
 export declare const hashIdentityValue: (value: string) => string;

package/dist/exporter/sanitize.js

@@ -1,9 +1,6 @@
 import { sha256 } from "@noble/hashes/sha256";
 import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
-// 個人情報の形を見分ける規則も、正本から生成した部品を読みます。
 import { detectIdentityPII, PII_HASH_HEX_LENGTH, PII_HASH_PREFIX, } from "../_generated/identity-pii-policy.js";
-// 落とす項目名・同形異字を畳む表・突き合わせの手順は、正本から生成した部品を
-// 読みます。ここへ写すと受付側とずれます（AGENTS §0.2）。
 import { isDeniedLookupKey, toDeniedLookupKeySet, } from "../_generated/ingest-privacy-tables.js";
 import { toPathTemplate } from "../exporter/path-template.js";
 import { ALWAYS_DENIED_KEYS, MASKED_VALUE, MAX_SANITIZE_DEPTH, } from "../provider/constants.js";
@@ -25,7 +22,7 @@ export const sanitizeHeaders = (headers, deniedKeys = []) => {
     }
     return sanitized;
 };
-export const sanitizeObject = (value, deniedKeys = [], summary, pathPrefix = "") => {
+export const sanitizeObject = (value, deniedKeys = [], summary, pathPrefix = "", maskIdentityPii = true, preserveExplicitTraits = false) => {
     const deniedSet = toDeniedSet(deniedKeys);
     const seen = new WeakSet();
     const walk = (current, depth, path) => {
@@ -49,7 +46,7 @@ export const sanitizeObject = (value, deniedKeys = [], summary, pathPrefix = "")
             seen.add(objectValue);
             const sanitized = {};
             for (const [key, child] of Object.entries(objectValue)) {
-                if (isDeniedKeyWithSet(key, deniedSet)) {
+                if (!preserveExplicitTraits && isDeniedKeyWithSet(key, deniedSet)) {
                     if (summary)
                         summary.droppedFieldCount += 1;
                     continue;
@@ -67,13 +64,10 @@ export const sanitizeObject = (value, deniedKeys = [], summary, pathPrefix = "")
         if (typeof current === "function" || typeof current === "symbol") {
             return undefined;
         }
-        // Value-level PII shape detection. The denied-key gate above catches
-        // `email = "..."`, but a non-denied key like
-        // `metadata.customer_contact = "alice@example.com"` would still leak
-        // the email verbatim. Replace any string whose shape matches an
-        // identity-PII pattern (email / phone / SSN / credit_card with
-        // Luhn) with the canonical masked sentinel.
-        if (typeof current === "string" && detectIdentityPII(current) !== null) {
+        if (maskIdentityPii &&
+            !preserveExplicitTraits &&
+            typeof current === "string" &&
+            detectIdentityPII(current) !== null) {
             if (current === MASKED_VALUE)
                 return current;
             if (summary) {
@@ -146,32 +140,5 @@ export const maybeParseJson = (value) => {
         return null;
     }
 };
-// ---------------------------------------------------------------------------
-// Identity-value PII detection for browser payloads.
-//
-// The frontend SDK does not propagate identity via W3C Baggage (browser-side
-// never opens outgoing HTTP to non-Cluebase services), so the leak vector here is
-// the canonical span attribute `cluebase.actor.user_id` getting captured in raw
-// observation storage / facts_json. Hashing PII-shaped identity values
-// prevents that.
-//
-// この面は値の**中**を走査します（裏の配る部品は両端で留めます）。違いは本物で、
-// 意図したものです——**問いが違うからです。** ここは「この文字列が個人情報を
-// 含むか」、裏は「この値そのものが個人情報か」。正本
-// （`identity-pii-policy.v1.json` の面 `text_contains_pii`）に 1 度だけ書かれ、
-// 下の生成物から読みます。**面の名前は生成物の `PII_SURFACE` が名乗ります。**
-// 判定の手順は**正本から出した部品が持ちます**。ここには手順が手で書かれており、
-// 受付側にも同じ手順の 2 本目が手で書かれていました（AGENTS §0.2）。
 export { detectIdentityPII };
-/**
- * Synchronous deterministic SHA-256 hash for identity values that look
- * like PII. The identity sanitization path must remain synchronous
- * because `identify(userId)` is sync-only by SDK contract.
- *
- * Output format: `cluebase_pii_hashed:<32-hex>`.
- *
- * The algorithm name, the digest length and the prefix are read from the
- * generated policy, not written here, so the three SDKs produce the same
- * token for the same input by construction rather than by assertion.
- */
 export const hashIdentityValue = (value) => `${PII_HASH_PREFIX}${bytesToHex(sha256(utf8ToBytes(value))).slice(0, PII_HASH_HEX_LENGTH)}`;

package/dist/exporter/source-event.d.ts

@@ -12,6 +12,7 @@ export type BrowserSdkSignalContext = {
     trace_id: string;
     request_id: string;
     request_span_id: string;
+    action_id: string | null;
     interaction_id: string;
     correlation_id: string | null;
     sdk_collection_mode: SdkCollectionMode;
@@ -88,6 +89,7 @@ export type BrowserSourceSignalEvent = {
     parent_span_id?: string | null;
     request_id: string;
     request_span_id: string;
+    action_id: string | null;
     interaction_id: string;
     frontend_release: string | null;
     backend_release: string | null;

package/dist/exporter/span-to-source-signal.js

@@ -1,6 +1,3 @@
-// 相関のために残す属性名は、正本から生成した部品を読みます。ここには手で書かれて
-// おり、もう 1 か所の写しと 15 語食い違い、`cluebase.session_id` `mcp.session.id` が
-// 欠けていて**落ちていました**（`session` を含むため落とす側に当たる）。
 import { CLUEBASE_CORRELATION_ATTRIBUTE_KEYS } from "../_generated/correlation-attribute-keys.js";
 import { attrString, hrTimeToUnixNano, nanosToIso, parentSpanId, } from "../_generated/otel-span-conversion.js";
 import { EVENT_SOURCE, EVENT_VERSION, SOURCE_SCHEMA_VERSION, } from "../provider/constants.js";
@@ -59,6 +56,7 @@ function contextRecord(context, overrides) {
         trace_id: overrides.trace_id,
         request_id: overrides.request_id,
         request_span_id: overrides.request_span_id,
+        action_id: overrides.action_id,
         interaction_id: overrides.interaction_id,
         correlation_id: context.correlation_id,
         sdk_collection_mode: context.sdk_collection_mode,
@@ -109,6 +107,10 @@ export function spanToSourceSignalEvent(span, options) {
         attrString(attributes, "cluebase.request_id") ??
         context.request_id ??
         generateRequestId();
+    const actionId = attrString(attributes, "cluebase.action.id") ??
+        attrString(attributes, "cluebase.action_id") ??
+        context.action_id ??
+        null;
     const interactionId = attrString(attributes, "cluebase.interaction.id") ??
         attrString(attributes, "cluebase.interaction_id") ??
         context.interaction_id ??
@@ -139,6 +141,7 @@ export function spanToSourceSignalEvent(span, options) {
         parent_span_id: parentId,
         request_id: requestId,
         request_span_id: requestSpanId,
+        action_id: actionId,
         interaction_id: interactionId,
         frontend_release: context.frontend_release,
         backend_release: null,
@@ -167,6 +170,7 @@ export function spanToSourceSignalEvent(span, options) {
                 trace_id: traceId,
                 request_id: requestId,
                 request_span_id: requestSpanId,
+                action_id: actionId,
                 interaction_id: interactionId,
             }),
         },

package/dist/exporter/text-fingerprint.d.ts

@@ -1,9 +1 @@
-/**
- * 文字列を短い印にたたむ。
- *
- * 中身そのものは残さない（項目の並びや入力欄の値は、そのままでは送れない）。
- * 同じ入力なら必ず同じ印になり、印から元へは戻らない。
- * FNV-1a の 32 bit 版。**衝突しない保証は無い**ので、突合の鍵ではなく
- * 「同じか違うか」を見るための印としてのみ使う。
- */
 export declare const fingerprintText: (value: string) => string;

package/dist/exporter/text-fingerprint.js

@@ -1,11 +1,3 @@
-/**
- * 文字列を短い印にたたむ。
- *
- * 中身そのものは残さない（項目の並びや入力欄の値は、そのままでは送れない）。
- * 同じ入力なら必ず同じ印になり、印から元へは戻らない。
- * FNV-1a の 32 bit 版。**衝突しない保証は無い**ので、突合の鍵ではなく
- * 「同じか違うか」を見るための印としてのみ使う。
- */
 export const fingerprintText = (value) => {
     let hash = 0x811c9dc5;
     for (let index = 0; index < value.length; index += 1) {

package/dist/index.d.ts

@@ -2,10 +2,6 @@ import type { InternalMetricsSnapshot } from "./internal/metrics.js";
 import { createCluebaseBrowserSdk } from "./provider/sdk.js";
 import type { CluebaseBrowserSdk, CluebaseConsentState, CluebaseGroupTraits, CluebaseGroupType, CluebaseInitOptions, CluebaseSubjectTraits, CluebaseTrackMetrics, CluebaseTrackProperties } from "./provider/types.js";
 declare const cluebase: {
-    /**
-     * SDK を初期化する。 `endpoint` / `projectKey` は必須で、 欠けていれば送信を
-     * 黙って捨てずに throw する。
-     */
     init(options: CluebaseInitOptions): void;
     identify(userId: string, traits?: CluebaseSubjectTraits): void;
     group(groupType: CluebaseGroupType, groupKey: string, traits?: CluebaseGroupTraits): void;

package/dist/index.js

@@ -1,7 +1,5 @@
 import { parseSendableUrl } from "./provider/config.js";
 import { createCluebaseBrowserSdk } from "./provider/sdk.js";
-// SDK は host application 内で singleton として動く。
-// 同じ tab で複数回 import されても 1 instance に統合する。
 const GLOBAL_SDK_KEY = "__cluebase_frontend_sdk_singleton__";
 const globalWithCluebaseSdk = globalThis;
 const existingSdk = globalWithCluebaseSdk[GLOBAL_SDK_KEY];
@@ -18,7 +16,6 @@ const reportPublicSdkError = (operation) => {
         }
     }
     catch {
-        // Cluebase は host application を絶対に失敗させない。
     }
 };
 const safeCall = (operation, callback) => {
@@ -37,10 +34,6 @@ const safeAsyncCall = async (operation, callback) => {
         reportPublicSdkError(operation);
     }
 };
-// `privacy.allowedValuePaths` used to let the caller name the request/response
-// fields that may leave the browser in clear text. That choice now belongs to
-// the Cluebase privacy screen and reaches the SDK through the delivered privacy
-// policy, so the option has nothing left to apply to.
 const REMOVED_PRIVACY_OPTIONS = {
     allowedValuePaths: "cluebase.init: 'privacy.allowedValuePaths' was removed in " +
         "@genn-inc/cluebase-frontend-sdk 0.0.1. The fields allowed to leave the browser in " +
@@ -49,22 +42,7 @@ const REMOVED_PRIVACY_OPTIONS = {
         "and select those fields in the Cluebase privacy screen instead. Until then " +
         "every value stays masked.",
 };
-const REQUIRED_INIT_OPTIONS = [
-    "endpoint",
-    "projectKey",
-];
-/**
- * Raise on a setup mistake instead of collecting nothing and warning once.
- *
- * This is the one place `cluebase.init` is allowed to throw. The `cluebase.*`
- * never-propagate contract exists so a telemetry fault cannot break a page the
- * visitor is using; it is not there to hide a setting that quietly stopped
- * applying, nor a key the caller forgot. Both mistakes come from the build's
- * own configuration, so they surface on the developer's first page load rather
- * than on a visitor's — and left silent they are invisible afterwards: the page
- * renders, `getDiagnostics()` reports an open lifecycle with no errors, and not
- * one event is ever delivered.
- */
+const REQUIRED_INIT_OPTIONS = ["projectKey"];
 const validateInitOptions = (options) => {
     const privacy = options.privacy ?? {};
     for (const [name, message] of Object.entries(REMOVED_PRIVACY_OPTIONS)) {
@@ -72,8 +50,6 @@ const validateInitOptions = (options) => {
             throw new Error(message);
         }
     }
-    // Anything that is not a string reads as absent, so a stray `undefined` from
-    // the bundler's env replacement cannot become the literal "undefined" endpoint.
     const missing = REQUIRED_INIT_OPTIONS.filter((name) => {
         const value = options[name];
         return typeof value !== "string" || value.trim() === "";
@@ -83,12 +59,15 @@ const validateInitOptions = (options) => {
             `${missing.length === 1 ? "is" : "are"} required and must be a non-empty ` +
             "string. Cluebase collects nothing until every required option is set. Pass " +
             "them from your environment, for example " +
-            "endpoint=NEXT_PUBLIC_CLUEBASE_API_BASE_URL and " +
-            "projectKey=NEXT_PUBLIC_CLUEBASE_PROJECT_KEY.");
+            "projectKey=NEXT_PUBLIC_CLUEBASE_PROJECT_KEY. The endpoint is optional " +
+            "and defaults to the hosted Cluebase API.");
     }
-    // Reporting a typo against the setting that caused it, rather than letting
-    // it surface later as delivery that never arrives.
-    if (parseSendableUrl(options.endpoint) === null) {
+    if (options.endpoint !== undefined &&
+        typeof options.endpoint !== "string") {
+        throw new Error("cluebase.init: 'endpoint' must be a string when provided. Omit it to " +
+            "use the hosted Cluebase endpoint.");
+    }
+    if (options.endpoint?.trim() && parseSendableUrl(options.endpoint) === null) {
         throw new Error(`cluebase.init: 'endpoint' must be an absolute http:// or https:// URL, but ` +
             `received ${JSON.stringify(options.endpoint)}. An endpoint the SDK cannot ` +
             "send to loses every event just as silently as one that was never passed. " +
@@ -96,15 +75,8 @@ const validateInitOptions = (options) => {
             "endpoint=NEXT_PUBLIC_CLUEBASE_API_BASE_URL.");
     }
 };
-// Public API — namespace `cluebase` の 8 method
 const cluebase = {
-    /**
-     * SDK を初期化する。 `endpoint` / `projectKey` は必須で、 欠けていれば送信を
-     * 黙って捨てずに throw する。
-     */
     init(options) {
-        // Thrown before `safeCall` so the caller actually sees it; see
-        // `validateInitOptions`.
         validateInitOptions(options);
         safeCall("init", () => {
             internalSdk.init(options);
@@ -142,7 +114,6 @@ const cluebase = {
     async close() {
         await safeAsyncCall("close", () => internalSdk.close());
     },
-    // 内部 metrics 取得 (= 顧客 debug 用、 production では通常不要)
     getInternalMetrics() {
         return internalSdk.getInternalMetrics();
     },
@@ -150,7 +121,6 @@ const cluebase = {
         return internalSdk.getDiagnostics();
     },
 };
-// OTel-core exporter surface for advanced host integrations.
 export { EXPORT_RESULT_FAILED, EXPORT_RESULT_SUCCESS, ObservationSourceEventExporter, } from "./exporter/observation-source-event-exporter.js";
 export { attachNextRouterIntegration } from "./integrations/next-router.js";
 export { attachReactRouterIntegration } from "./integrations/react-router.js";