@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/provider/types.d.ts

@@ -0,0 +1,323 @@
+import type { InternalMetricsSnapshot } from "../internal/metrics.js";
+import type { DiagnosticsSnapshot } from "../exporter/diagnostics.js";
+import type { FrontendEventName, ParameterCaptureMode, SdkCollectionMode } from "./contracts.js";
+export type { FrontendEventCategory, FrontendEventName, FrontendEventStatus, ParameterCaptureMode, SdkCollectionMode, } from "./contracts.js";
+export type CluebaseConsentState = "granted" | "denied" | "unknown";
+/**
+ * MVP group taxonomy. Public `cluebase.group(...)` accepts only the customer
+ * company concept. `account` / `workspace` are future concepts and are not
+ * exposed as MVP group inputs.
+ */
+export type CluebaseGroupType = "organization";
+export type CanonicalJsonValue = string | number | boolean | null | CanonicalJsonValue[] | {
+    [key: string]: CanonicalJsonValue;
+};
+export type CluebaseTrackProperties = {
+    [propertyName: string]: CanonicalJsonValue;
+};
+export type CluebaseTrackMetrics = {
+    [metricName: string]: number;
+};
+export type CanonicalJsonInputValue = CanonicalJsonValue | undefined;
+export type CluebaseGroupTraits = {
+    name?: string | null;
+} & {
+    [traitName: string]: CanonicalJsonInputValue;
+};
+export type TransportProfile = "standard";
+export type RequestLifecycleOutcome = "completed" | "failed" | "aborted" | "unknown";
+export type DiagnosticCollectionConfig = {
+    enabledCollectors?: string[];
+    scope?: Record<string, string | number | boolean | null>;
+    ttlMs?: number;
+    expiresAt?: string;
+    budgetWindowMs?: number;
+    maxEventsPerWindow?: number;
+    sampleRate?: number;
+    reason?: string;
+    enabledBy?: string;
+};
+/**
+ * Public bootstrap options accepted by `cluebase.init`.
+ *
+ * The SDK derives dev/prod from the `projectKey` prefix. Browser ingest obtains
+ * short-lived tokens from `POST <endpoint>/api/v1/ingest/browser-tokens`.
+ */
+export type CluebaseInitOptions = {
+    endpoint: string;
+    projectKey: string;
+    autocapture?: boolean;
+    captureNetwork?: boolean;
+    captureErrors?: boolean;
+    capturePerformance?: boolean;
+    network?: {
+        tracePropagationOrigins?: string[];
+    };
+    batch?: {
+        enabled?: boolean;
+        maxSize?: number;
+        flushIntervalMs?: number;
+        maxEventBytes?: number;
+        maxPayloadBytes?: number;
+    };
+    privacy?: {
+        deniedKeys?: string[];
+    };
+    sampling?: {
+        sessionSampleRate?: number;
+    };
+    release?: {
+        frontendRelease?: string;
+    };
+    contextTraitsProvider?: () => CluebaseTrackProperties;
+    /**
+     * Controls how the SDK's internal ``WebTracerProvider`` interacts with
+     * the page's global OTel context.
+     *
+     * - ``"register"`` (default for SDKs initialised on pages without
+     *   pre-existing OTel): call ``WebTracerProvider#register()`` so any
+     *   ``trace.getTracer(...)`` call in the page routes through Cluebase's
+     *   exporter, including Cluebase's own runtime span emissions.
+     * - ``"standalone"``: do not register globally. Cluebase's pipeline is
+     *   private; only spans created via the SDK's own internal tracer
+     *   reach the exporter. Use this when the host app already manages an
+     *   OTel TracerProvider (Sentry, Datadog, Honeycomb, etc.) and Cluebase
+     *   must not hijack it.
+     * - ``"detect"`` (recommended): inspect ``trace.getTracerProvider()``;
+     *   if a non-proxy provider is already installed, behave as
+     *   ``standalone``; otherwise behave as ``register``.
+     */
+    otelProviderMode?: "register" | "standalone" | "detect";
+};
+export type ResolvedCluebaseConfig = {
+    endpoint: string;
+    originalEndpoint: string;
+    localSetupCheckEndpoint: string | null;
+    projectKey: string;
+    producerId: string;
+    transportProfile: TransportProfile;
+    autocapture: boolean;
+    captureNetwork: boolean;
+    captureErrors: boolean;
+    capturePerformance: boolean;
+    network: {
+        tracePropagationOrigins: string[];
+    };
+    batch: {
+        enabled: boolean;
+        maxSize: number;
+        flushIntervalMs: number;
+        maxEventBytes: number;
+        maxPayloadBytes: number;
+    };
+    privacy: {
+        deniedKeys: string[];
+    };
+    sampling: {
+        sessionSampleRate: number;
+    };
+    collection: {
+        mode: SdkCollectionMode;
+        diagnostic: {
+            enabledCollectors: string[];
+            scope: Record<string, string | number | boolean | null>;
+            ttlMs: number;
+            expiresAt: string | null;
+            budgetWindowMs: number;
+            maxEventsPerWindow: number;
+            sampleRate: number;
+            reason: string | null;
+            enabledBy: string | null;
+        };
+    };
+    release: {
+        frontendRelease: string | null;
+    };
+    contextTraitsProvider?: () => CluebaseTrackProperties;
+    otelProviderMode: "register" | "standalone" | "detect";
+};
+export type CluebaseBrowserSdk = {
+    init(options: CluebaseInitOptions): void;
+    identify(userId: string, traits?: CluebaseSubjectTraits): void;
+    setOrganization(organizationId: string, traits?: CluebaseGroupTraits): void;
+    logout(): void;
+    reset(): void;
+    track(eventName: string, properties?: CluebaseTrackProperties, metrics?: CluebaseTrackMetrics): void;
+    setConsent(consent: CluebaseConsentState): void;
+    getInternalMetrics(): InternalMetricsSnapshot;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    getDiagnostics(): DiagnosticsSnapshot;
+};
+export type { CostCapability } from "../_generated/usage-governor-tables.js";
+import type { CostCapability } from "../_generated/usage-governor-tables.js";
+export type LimitKind = "monthly_overage_amount_limit" | "internal_cost_limit" | "internal_limit" | "operator_global_monthly_cost_limit";
+export type ThresholdStage = "info" | "warning" | "urgent" | "reached";
+export type LimitReason = {
+    limitKind: LimitKind;
+    meterKey: string;
+    thresholdStage: ThresholdStage;
+    currentValue: number;
+    limitValue: number;
+    retryAfterAt: string | null;
+};
+export type IngestUsageGovernorFeedback = {
+    disabledCapabilities: CostCapability[];
+    limitReasons: LimitReason[];
+    retryAfterAt: string | null;
+};
+export type ParameterSnapshotLeafType = "string" | "number" | "boolean" | "null" | "object" | "array";
+export type ParameterSnapshotLeaf = {
+    type: ParameterSnapshotLeafType;
+    value: unknown;
+    capture_mode: ParameterCaptureMode;
+    truncated_reason?: "max_event_bytes";
+    original_size_bytes?: number;
+};
+export type ParameterSnapshotValue = ParameterSnapshotLeaf | ParameterSnapshotValue[] | {
+    [key: string]: ParameterSnapshotValue;
+};
+export type SdkIdentityLinkType = "anonymous_to_user" | "user_to_organization" | "logout";
+export type SdkIdentityLinkHint = {
+    link_type: SdkIdentityLinkType;
+    anonymous_id?: string | null;
+    user_id?: string | null;
+    organization_id?: string | null;
+};
+export type CluebaseContext = {
+    producer_id: string | null;
+    anonymous_id: string | null;
+    user_id: string | null;
+    organization_id?: string | null;
+    user_profile: CluebaseSubjectProfile | null;
+    session_id: string | null;
+    tab_id: string;
+    trace_id: string;
+    request_id: string;
+    request_span_id: string;
+    interaction_id: string;
+    correlation_id: string | null;
+    sdk_collection_mode: SdkCollectionMode;
+    frontend_release: string | null;
+    locale: string | null;
+    country: string | null;
+    device_type: string | null;
+    browser: string | null;
+    os: string | null;
+    referrer: string | null;
+    browser_family?: string | null;
+    browser_major_version?: string | null;
+    browser_engine?: string | null;
+    os_family?: string | null;
+    os_major_version?: string | null;
+    timezone?: string | null;
+    pointer_type_candidate?: string | null;
+    touch_capable?: boolean | null;
+    cookies_enabled?: boolean | null;
+    local_storage_available?: boolean | null;
+    session_storage_available?: boolean | null;
+    service_worker_supported?: boolean | null;
+    webgl_supported?: boolean | null;
+    reduced_motion?: string | null;
+    color_scheme?: string | null;
+    subject_traits: CluebaseSanitizedTraits;
+    organization_traits: CluebaseSanitizedTraits;
+    context_traits: CluebaseSanitizedTraits;
+    privacy_summary: CluebasePrivacySummary;
+};
+export type SessionContext = {
+    sessionId: string | null;
+    startedAtMs: number | null;
+    lastActivityAtMs: number | null;
+};
+export type CluebaseSanitizedTraits = {
+    [traitName: string]: CanonicalJsonValue;
+};
+export type CluebasePrivacySummary = {
+    level: "masked";
+    masked_value_count: number;
+    dropped_field_count: number;
+    masked_fields: string[];
+    rule_set_version: string | null;
+};
+export type IdentityContext = {
+    anonymousId: string | null;
+    userId: string | null;
+    traits: CluebaseSanitizedTraits;
+};
+export type OrganizationContext = {
+    organizationId: string | null;
+    traits: CluebaseSanitizedTraits;
+};
+export type CluebaseSubjectProfile = {
+    display_name: string | null;
+    avatar_url: string | null;
+    contact_identity_hash: string | null;
+    contact_domain: string | null;
+};
+/**
+ * Customer-facing trait dict accepted by `cluebase.identify` /
+ * `cluebase.setOrganization`.
+ *
+ * Customers use the camelCase form on every SDK. The ingest core normalizes
+ * these values after receiving the SDK source signal.
+ *
+ * `displayName`, `email`, and `emailAddress` are accepted alternate keys.
+ * Email traits are transported only as privacy-safe contact-derived fields.
+ */
+export type CluebaseSubjectTraits = {
+    name?: string | null;
+    email?: string | null;
+    emailAddress?: string | null;
+    displayName?: string | null;
+    avatarUrl?: string | null;
+} & {
+    [traitName: string]: CanonicalJsonInputValue;
+};
+export type CluebaseLoggerDetails = {
+    [detailName: string]: CanonicalJsonValue;
+};
+export type CluebaseInternalLogger = {
+    debug: (message: string, details?: CluebaseLoggerDetails) => void;
+    warn: (message: string, details?: CluebaseLoggerDetails) => void;
+    error: (message: string, details?: CluebaseLoggerDetails) => void;
+};
+export type RawEventName = FrontendEventName;
+export type RawCapturedPayload = {
+    [payloadKey: string]: CanonicalJsonValue | undefined;
+};
+export type RawCapturedEvent = {
+    type: RawEventName;
+    occurredAtMs?: number;
+    payload: RawCapturedPayload;
+};
+export type CaptureEventHandler = (event: RawCapturedEvent) => void;
+export type CaptureModuleContext = {
+    onEvent: CaptureEventHandler;
+    onInternalError: (source: string, error: unknown) => void;
+    getViewId: () => string | null;
+    getConsent: () => CluebaseConsentState;
+    getObservationContext?: () => {
+        anonymousId: string | null;
+        userId: string | null;
+        organizationId?: string | null;
+        sessionId: string | null;
+        tabId: string | null;
+    };
+    shouldIgnoreElement?: (element: Element) => boolean;
+    startInteraction?: (input: {
+        interactionId?: string | null;
+        interactionInitiator?: string | null;
+        interactionStartEventKind?: string | null;
+        targetStableKey?: string | null;
+        formKey?: string | null;
+        interactionScopeKind?: string | null;
+        interactionScopeKey?: string | null;
+        nowMs?: number;
+    }) => string | null;
+    requestFlush?: () => void;
+};
+export type CaptureStopHandle = {
+    stop: () => void;
+    flush?: (reason: string) => void | Promise<void>;
+};

package/dist/provider/types.js

@@ -0,0 +1 @@
+export {};

package/dist/provider/usage-governor.d.ts

@@ -0,0 +1,7 @@
+import type { CostCapability, IngestUsageGovernorFeedback } from "./types.js";
+export declare const DEFAULT_INGEST_USAGE_GOVERNOR_FEEDBACK: IngestUsageGovernorFeedback;
+export declare const normalizeIngestUsageGovernorFeedback: (feedback?: Partial<IngestUsageGovernorFeedback> | null) => IngestUsageGovernorFeedback;
+export declare const mergeIngestUsageGovernorFeedback: (current: IngestUsageGovernorFeedback | null, incoming: IngestUsageGovernorFeedback | null) => IngestUsageGovernorFeedback | null;
+export declare const parseGovernorFeedbackEnvelope: (value: unknown) => IngestUsageGovernorFeedback | null;
+export declare const isCostCapabilityDisabled: (feedback: Pick<IngestUsageGovernorFeedback, "disabledCapabilities">, capability: CostCapability) => boolean;
+export declare const hasUsageGovernorFeedbackChanged: (current: IngestUsageGovernorFeedback, next: IngestUsageGovernorFeedback) => boolean;

package/dist/provider/usage-governor.js

@@ -0,0 +1,116 @@
+import { COST_CAPABILITIES as GENERATED_COST_CAPABILITIES, LIMIT_KINDS as GENERATED_LIMIT_KINDS, THRESHOLD_STAGES as GENERATED_THRESHOLD_STAGES, } from "../_generated/usage-governor-tables.js";
+export const DEFAULT_INGEST_USAGE_GOVERNOR_FEEDBACK = {
+    disabledCapabilities: [],
+    limitReasons: [],
+    retryAfterAt: null,
+};
+// 正本から生成した一覧をそのまま使います。ここへ書き写していたため
+// `replay_storage` が抜け、受付側が「止めよ」と言っても画面側が捨てていました。
+const COST_CAPABILITIES = new Set(GENERATED_COST_CAPABILITIES);
+const LIMIT_KINDS = new Set(GENERATED_LIMIT_KINDS);
+const THRESHOLD_STAGES = new Set(GENERATED_THRESHOLD_STAGES);
+const asObject = (value) => {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+};
+const asCostCapability = (value) => {
+    return typeof value === "string" &&
+        COST_CAPABILITIES.has(value)
+        ? value
+        : null;
+};
+const asLimitKind = (value) => {
+    return typeof value === "string" && LIMIT_KINDS.has(value)
+        ? value
+        : null;
+};
+const asThresholdStage = (value) => {
+    return typeof value === "string" &&
+        THRESHOLD_STAGES.has(value)
+        ? value
+        : null;
+};
+const asNonNegativeNumber = (value) => {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : null;
+};
+const asNullableString = (value) => {
+    return typeof value === "string" ? value : null;
+};
+const parseLimitReason = (value) => {
+    const record = asObject(value);
+    if (!record) {
+        return null;
+    }
+    const limitKind = asLimitKind(record.limitKind);
+    const thresholdStage = asThresholdStage(record.thresholdStage);
+    const currentValue = asNonNegativeNumber(record.currentValue);
+    const limitValue = asNonNegativeNumber(record.limitValue);
+    const retryAfterAt = record.retryAfterAt === null ? null : asNullableString(record.retryAfterAt);
+    if (!limitKind ||
+        typeof record.meterKey !== "string" ||
+        !thresholdStage ||
+        currentValue === null ||
+        limitValue === null ||
+        retryAfterAt === undefined) {
+        return null;
+    }
+    return {
+        limitKind,
+        meterKey: record.meterKey,
+        thresholdStage,
+        currentValue,
+        limitValue,
+        retryAfterAt,
+    };
+};
+const uniqueCapabilities = (capabilities) => [...new Set(capabilities)];
+export const normalizeIngestUsageGovernorFeedback = (feedback) => {
+    const disabledCapabilities = Array.isArray(feedback?.disabledCapabilities)
+        ? feedback.disabledCapabilities
+            .map(asCostCapability)
+            .filter((capability) => capability !== null)
+        : [];
+    const limitReasons = Array.isArray(feedback?.limitReasons)
+        ? feedback.limitReasons
+            .map(parseLimitReason)
+            .filter((reason) => reason !== null)
+        : [];
+    return {
+        disabledCapabilities: uniqueCapabilities(disabledCapabilities),
+        limitReasons,
+        retryAfterAt: typeof feedback?.retryAfterAt === "string" ? feedback.retryAfterAt : null,
+    };
+};
+export const mergeIngestUsageGovernorFeedback = (current, incoming) => {
+    if (!current) {
+        return incoming;
+    }
+    if (!incoming) {
+        return current;
+    }
+    return {
+        disabledCapabilities: uniqueCapabilities([
+            ...current.disabledCapabilities,
+            ...incoming.disabledCapabilities,
+        ]),
+        limitReasons: [...current.limitReasons, ...incoming.limitReasons],
+        retryAfterAt: current.retryAfterAt ?? incoming.retryAfterAt,
+    };
+};
+export const parseGovernorFeedbackEnvelope = (value) => {
+    const payload = asObject(value);
+    const governor = asObject(payload?.governor);
+    if (!governor) {
+        return null;
+    }
+    return normalizeIngestUsageGovernorFeedback(governor);
+};
+export const isCostCapabilityDisabled = (feedback, capability) => feedback.disabledCapabilities.includes(capability);
+export const hasUsageGovernorFeedbackChanged = (current, next) => current.retryAfterAt !== next.retryAfterAt ||
+    current.disabledCapabilities.join("|") !==
+        next.disabledCapabilities.join("|") ||
+    JSON.stringify(current.limitReasons) !== JSON.stringify(next.limitReasons);

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "@genn-inc/cluebase-frontend-sdk",
+	"version": "0.0.1",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/genn-inc/cluebase.git"
+	},
+	"description": "Cluebase Frontend SDK — OTel-based observation-source event capture for frontend apps",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist/",
+		"README.md"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"browser": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "node ./scripts/clean-dist.mjs && node ../../../scripts/generate-shared-contract-tables.mjs && node ./scripts/generate-version-module.mjs && tsc -p tsconfig.build.json && node ./scripts/fix-esm-relative-imports.mjs",
+		"prepack": "pnpm build",
+		"prepublishOnly": "pnpm lint && pnpm test:cov && pnpm typecheck && pnpm test:package-import",
+		"lint": "pnpm exec biome lint src",
+		"test:package-import": "pnpm build && node ../../../tests/distribution/frontend-sdk/check-package-import.mjs",
+		"typecheck": "tsc -p tsconfig.typecheck.json",
+		"_comment_test": "実環境が要る試験 (`*-live.test.ts`) を既定の実行から外します (`tests/README.md` §12.2)。**綴りで拾います** — file 名を並べると、新しい live を足した人がここへ足し忘れて黙ります。**設定側 (`vitest.config.ts`) の `exclude` には置けません**: 実測 (2026-08-21) では、そこへ置くと live を名指しした実行まで `No test files found` で落ちます。script に置けば、手元と CI で対象が同じまま、実環境のあるジョブだけが名指しで拾えます。",
+		"test": "vitest run --config ../../../tests/config/vitest/frontend-sdk.config.ts --exclude \"../../../tests/integration/frontend-sdk/**/*-live.test.ts\"",
+		"test:cov": "vitest run --config ../../../tests/config/vitest/frontend-sdk.config.ts --coverage --exclude \"../../../tests/integration/frontend-sdk/**/*-live.test.ts\"",
+		"_comment_test_live": "実環境がある段だけがここを呼びます。**vitest の位置引数は glob ではなく道筋への部分一致です** — 実測 (2026-08-21): `vitest run \"src/**/*-live.test.ts\"` は `No test files found` で 0 件、`vitest run live.test.ts` は 1 件。綴りを CI ではなくここに置くので、CI 側は script 名を呼ぶだけになります。",
+		"test:live": "vitest run --config ../../../tests/config/vitest/frontend-sdk.config.ts ../../../tests/integration/frontend-sdk"
+	},
+	"devDependencies": {
+		"@cluebase/schema": "workspace:*",
+		"@cluebase/shared": "workspace:*",
+		"@vitest/coverage-v8": "^3.2.4",
+		"jsdom": "^26.1.0",
+		"typescript": "^5.9.3",
+		"vitest": "^3.2.7"
+	},
+	"dependencies": {
+		"@noble/hashes": "1.8.0",
+		"@opentelemetry/api": ">=1.9.1 <1.10.0",
+		"@opentelemetry/api-logs": ">=0.218.0 <1.0.0",
+		"@opentelemetry/browser-instrumentation": ">=0.5.2 <1.0.0",
+		"@opentelemetry/core": ">=2.7.1 <3.0.0",
+		"@opentelemetry/instrumentation-document-load": ">=0.63.0 <1.0.0",
+		"@opentelemetry/instrumentation-fetch": ">=0.218.0 <1.0.0",
+		"@opentelemetry/instrumentation-xml-http-request": ">=0.218.0 <1.0.0",
+		"@opentelemetry/resources": ">=2.7.1 <3.0.0",
+		"@opentelemetry/sdk-trace-base": ">=2.7.1 <3.0.0",
+		"@opentelemetry/sdk-trace-web": ">=2.7.1 <3.0.0",
+		"json-canonicalize": "2.0.0",
+		"zod": "^4.4.3"
+	}
+}