@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/exporter/browser-outbox-records.js

@@ -0,0 +1,341 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
+import { canonicalize as canonicalJsonStringify } from "json-canonicalize";
+import { isBrowserSourceSignalEvent, } from "./source-event.js";
+export const UNANCHORED_COLLECTION_GENERATION = "__cluebase_unanchored_generation__";
+export const LEGACY_TOMBSTONE_LIMIT = 10000;
+export const createDraft = (input) => {
+    const owned = ownEvent(input.event, input.permit);
+    if (!owned)
+        return null;
+    const event = owned.value();
+    const eventId = event.event_id;
+    if (typeof eventId !== "string" || eventId.length === 0)
+        return null;
+    const eventKeyHash = keyHash(eventId);
+    return withChecksum({
+        storageVersion: 2,
+        kind: "draft",
+        projectHash: input.projectHash,
+        createdAt: input.createdAt,
+        recordVerifierSha256: verifyHash(eventId),
+        origin: input.origin ?? "v2",
+        eventId,
+        eventKeyHash,
+        event,
+        collectionGeneration: input.permit.generation,
+        permittedAtStart: input.permit.permittedAtStart,
+    });
+};
+export const createLegacyTombstone = (input) => withChecksum({
+    storageVersion: 2,
+    kind: "legacy_tombstone",
+    projectHash: input.projectHash,
+    createdAt: nowIso(),
+    recordVerifierSha256: input.verifier,
+    eventKeyHash: input.eventKeyHash,
+    importedAt: nowIso(),
+});
+export const createConsentRecord = (input) => withChecksum({
+    storageVersion: 2,
+    kind: "consent",
+    projectHash: input.projectHash,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+    recordVerifierSha256: null,
+    state: input.state,
+    collectionGeneration: input.collectionGeneration,
+    legacyImportBlocked: input.legacyImportBlocked,
+});
+export const createPending = (input) => {
+    const events = input.drafts.map((draft) => ({
+        eventId: draft.eventId,
+        eventKeyHash: draft.eventKeyHash,
+        recordVerifierSha256: draft.recordVerifierSha256 ?? verifyHash(draft.eventId),
+        event: draft.event,
+        permittedAtStart: draft.permittedAtStart,
+    }));
+    return withChecksum({
+        storageVersion: 2,
+        kind: "pending",
+        projectHash: input.projectHash,
+        createdAt: nowIso(),
+        recordVerifierSha256: verifyHash(input.metadata.batch_id),
+        batchId: input.metadata.batch_id,
+        idempotencyKey: input.metadata.idempotency_key,
+        sentAt: input.metadata.sent_at,
+        collectionGeneration: input.drafts[0]?.collectionGeneration ?? "",
+        events,
+        eventKeyHashes: events.map((event) => event.eventKeyHash),
+        lifetimeAttemptTotal: 0,
+        ordinal: input.ordinal,
+    });
+};
+export const toPendingBatch = (record, recordKey, events, metadata, planOrdinal) => {
+    const owned = events
+        .map((event) => ownEvent(event.event, {
+        generation: record.collectionGeneration,
+        permittedAtStart: event.permittedAtStart,
+        captureOrdinal: 0,
+    }))
+        .filter(isOwnedEvent);
+    return Object.freeze({
+        events: Object.freeze(owned),
+        metadata: Object.freeze({ ...metadata }),
+        generation: record.collectionGeneration,
+        ordinal: record.ordinal,
+        diagnosticCanonicalBytes: canonicalJsonStringify({
+            sourceType: "frontend_sdk",
+            sourceSchemaVersion: "1",
+            batchId: metadata.batch_id,
+            idempotencyKey: metadata.idempotency_key,
+            sentAt: metadata.sent_at,
+            events: owned.map((event) => event.value()),
+        }),
+        recordKey,
+        ownerBatchId: record.batchId,
+        planOrdinal,
+    });
+};
+export const toHeadBatch = (record, recordKey) => {
+    if (record.kind === "pending") {
+        return toPendingBatch(record, recordKey, record.events, {
+            batch_id: record.batchId,
+            idempotency_key: record.idempotencyKey,
+            sent_at: record.sentAt,
+        }, null);
+    }
+    const child = record.children[record.nextOrdinal];
+    if (!child)
+        return null;
+    return toPendingBatch(record, recordKey, record.events.slice(child.start, child.end), child.metadata, record.nextOrdinal);
+};
+export const splitPendingRecord = (record, createMetadata) => {
+    const child = record.kind === "pending"
+        ? {
+            start: 0,
+            end: record.events.length,
+            metadata: {
+                batch_id: record.batchId,
+                idempotency_key: record.idempotencyKey,
+                sent_at: record.sentAt,
+            },
+        }
+        : record.children[record.nextOrdinal];
+    if (!child || child.end - child.start < 2)
+        return null;
+    const boundary = child.start + Math.ceil((child.end - child.start) / 2);
+    const replacements = [
+        { start: child.start, end: boundary, metadata: createMetadata() },
+        { start: boundary, end: child.end, metadata: createMetadata() },
+    ];
+    return withChecksum({
+        ...withoutChecksum(record),
+        kind: "split_plan",
+        children: record.kind === "pending"
+            ? replacements
+            : [
+                ...record.children.slice(0, record.nextOrdinal),
+                ...replacements,
+                ...record.children.slice(record.nextOrdinal + 1),
+            ],
+        nextOrdinal: record.kind === "pending" ? 0 : record.nextOrdinal,
+    });
+};
+export const largestFittingPrefix = (drafts, maxBytes, metadata, measure) => {
+    let low = 1;
+    let high = drafts.length;
+    let largest = 0;
+    while (low <= high) {
+        const count = Math.floor((low + high) / 2);
+        if (measure(drafts.slice(0, count).map((draft) => draft.event), metadata) <= maxBytes) {
+            largest = count;
+            low = count + 1;
+        }
+        else {
+            high = count - 1;
+        }
+    }
+    return largest;
+};
+export const ownEvent = (event, permit) => {
+    try {
+        const json = JSON.stringify(event);
+        const parsed = JSON.parse(json);
+        if (!isBrowserSourceSignalEvent(parsed))
+            return null;
+        return Object.freeze({
+            byteLength: new TextEncoder().encode(json).byteLength,
+            permit: Object.freeze({ ...permit }),
+            diagnosticCanonicalBytes: canonicalJsonStringify(parsed),
+            value: () => JSON.parse(json),
+        });
+    }
+    catch {
+        return null;
+    }
+};
+export const isOwnedEvent = (value) => value !== null;
+export const recordBatchId = (batch) => batch.ownerBatchId;
+export const withChecksum = (record) => ({
+    ...record,
+    checksumSha256: sha256Hex(canonicalJsonStringify(record)),
+});
+export const withoutChecksum = (record) => {
+    const { checksumSha256: _checksumSha256, ...unsigned } = record;
+    return unsigned;
+};
+export const parseRecord = (raw, projectHash) => {
+    try {
+        const value = JSON.parse(raw);
+        if (!isRecord(value) || value.storageVersion !== 2 || value.projectHash !== projectHash)
+            return null;
+        const checksumSha256 = value.checksumSha256;
+        if (typeof checksumSha256 !== "string")
+            return null;
+        const { checksumSha256: _checksum, ...unsigned } = value;
+        if (sha256Hex(canonicalJsonStringify(unsigned)) !== checksumSha256)
+            return null;
+        return isValidRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+const isValidRecord = (value) => {
+    const base = typeof value.createdAt === "string" &&
+        (typeof value.recordVerifierSha256 === "string" || value.recordVerifierSha256 === null);
+    if (!base)
+        return false;
+    if (value.kind === "consent") {
+        return ((value.state === "granted" || value.state === "denied" || value.state === "unknown") &&
+            typeof value.collectionGeneration === "string" &&
+            typeof value.legacyImportBlocked === "boolean" &&
+            typeof value.updatedAt === "string" &&
+            value.recordVerifierSha256 === null);
+    }
+    if (value.kind === "draft") {
+        return ((value.origin === "v2" || value.origin === "legacy_v1") &&
+            typeof value.eventId === "string" &&
+            typeof value.eventKeyHash === "string" &&
+            value.eventKeyHash === keyHash(value.eventId) &&
+            value.recordVerifierSha256 === verifyHash(value.eventId) &&
+            typeof value.collectionGeneration === "string" &&
+            typeof value.permittedAtStart === "boolean" &&
+            isBrowserSourceSignalEvent(value.event));
+    }
+    if (value.kind === "legacy_tombstone") {
+        return typeof value.eventKeyHash === "string" && typeof value.importedAt === "string";
+    }
+    if (value.kind === "pending" || value.kind === "split_plan") {
+        if (typeof value.batchId !== "string" ||
+            typeof value.idempotencyKey !== "string" ||
+            typeof value.sentAt !== "string" ||
+            typeof value.collectionGeneration !== "string" ||
+            !Array.isArray(value.events) ||
+            !Array.isArray(value.eventKeyHashes) ||
+            !Number.isInteger(value.lifetimeAttemptTotal) ||
+            !Number.isInteger(value.ordinal))
+            return false;
+        const events = value.events;
+        const eventKeyHashes = value.eventKeyHashes;
+        if (value.recordVerifierSha256 !== verifyHash(value.batchId) ||
+            eventKeyHashes.length !== events.length ||
+            !events.every(isStoredEvent) ||
+            !events.every((event, index) => eventKeyHashes[index] === event.eventKeyHash))
+            return false;
+        if (value.kind === "pending")
+            return true;
+        const children = value.children;
+        return (Array.isArray(children) &&
+            children.length >= 2 &&
+            children.every((child) => isPlanSide(child, events.length)) &&
+            children[0]?.start === 0 &&
+            children.every((child, index) => index === 0 || children[index - 1]?.end === child.start) &&
+            children[children.length - 1]?.end === events.length &&
+            Number.isInteger(value.nextOrdinal) &&
+            typeof value.nextOrdinal === "number" &&
+            value.nextOrdinal >= 0 &&
+            value.nextOrdinal < children.length);
+    }
+    return false;
+};
+const isStoredEvent = (value) => isRecord(value) &&
+    typeof value.eventId === "string" &&
+    typeof value.eventKeyHash === "string" &&
+    value.eventKeyHash === keyHash(value.eventId) &&
+    typeof value.recordVerifierSha256 === "string" &&
+    value.recordVerifierSha256 === verifyHash(value.eventId) &&
+    typeof value.permittedAtStart === "boolean" &&
+    isBrowserSourceSignalEvent(value.event);
+const isPlanSide = (value, eventCount) => isRecord(value) &&
+    typeof value.start === "number" &&
+    typeof value.end === "number" &&
+    Number.isInteger(value.start) &&
+    Number.isInteger(value.end) &&
+    value.start >= 0 &&
+    value.end > value.start &&
+    value.end <= eventCount &&
+    isMetadata(value.metadata);
+const isMetadata = (value) => isRecord(value) &&
+    typeof value.batch_id === "string" &&
+    typeof value.idempotency_key === "string" &&
+    typeof value.sent_at === "string";
+export const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+export const sha256Hex = (value) => bytesToHex(sha256(utf8ToBytes(value)));
+export const keyHash = (id) => sha256Hex(`cluebase:outbox-key:v2\0${id}`);
+export const verifyHash = (id) => sha256Hex(`cluebase:outbox-verify:v2\0${id}`);
+export const nowIso = () => new Date().toISOString();
+export const consentRecordKey = (prefix) => `${prefix}consent`;
+export const draftRecordKey = (prefix, eventKeyHash) => `${prefix}draft:${eventKeyHash}`;
+export const pendingRecordKey = (prefix, batchId) => `${prefix}pending:${keyHash(batchId)}`;
+export const tombstoneRecordKey = (prefix, eventKeyHash) => `${prefix}legacy-tombstone:${eventKeyHash}`;
+export const browserEventsByteLength = (events) => events.reduce((total, event) => total + new TextEncoder().encode(JSON.stringify(event)).byteLength, 0);
+export const outboxEventCount = (drafts, pending) => drafts.length + pending.reduce((count, record) => count + record.events.length, 0);
+export const hasLegacyTombstone = (draft, tombstones) => tombstones.some((record) => record.eventKeyHash === draft.eventKeyHash &&
+    record.recordVerifierSha256 === draft.recordVerifierSha256);
+export const createGeneration = () => typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+    ? crypto.randomUUID()
+    : `${Date.now()}-${Math.random()}`;
+export const readStorage = () => {
+    try {
+        return typeof localStorage === "undefined" ? null : localStorage;
+    }
+    catch {
+        return null;
+    }
+};
+export const readLocks = () => {
+    const navigatorValue = globalThis.navigator;
+    return navigatorValue?.locks ?? null;
+};
+export const createConsentChannel = (projectHash, onDenied) => {
+    if (typeof BroadcastChannel === "undefined")
+        return null;
+    try {
+        const channel = new BroadcastChannel(`cluebase:source-event-consent:v2:${projectHash}`);
+        channel.addEventListener("message", (event) => {
+            const data = event.data;
+            if (isRecord(data) &&
+                data.type === "denied" &&
+                typeof data.generation === "string" &&
+                data.generation.length > 0) {
+                onDenied(data.generation);
+            }
+        });
+        return channel;
+    }
+    catch {
+        return null;
+    }
+};
+export const addStorageListener = (key, onChanged) => {
+    if (typeof globalThis.addEventListener !== "function")
+        return () => undefined;
+    const listener = (event) => {
+        if (event.key === key)
+            onChanged();
+    };
+    globalThis.addEventListener("storage", listener);
+    return () => globalThis.removeEventListener("storage", listener);
+};

package/dist/exporter/browser-outbox.d.ts

@@ -0,0 +1,112 @@
+import type { InternalMetricsStore } from "../internal/metrics.js";
+import type { CluebaseConsentState } from "../provider/types.js";
+import type { BatchEnvelopeMetadata } from "./client.js";
+import { DiagnosticStore } from "./diagnostics.js";
+import type { BrowserSourceEvent } from "./source-event.js";
+import { type CollectionPermit, type PendingBrowserBatch, type StorageLike } from "./browser-outbox-records.js";
+export type { CollectionPermit, OwnedBrowserEvent, PendingBrowserBatch } from "./browser-outbox-records.js";
+export type ConsentTransition = {
+    readonly state: CluebaseConsentState;
+    readonly generation: string;
+    readonly expectedGeneration: string | null;
+    readonly recoveryExpectedRaw?: string | null | false;
+    readonly legacyImportBlocked: boolean;
+    readonly purge: boolean;
+};
+export declare class BrowserOutbox {
+    private readonly projectHash;
+    private readonly prefix;
+    private readonly consentKey;
+    private readonly legacyKey;
+    private readonly lockName;
+    private readonly storage;
+    private readonly durableOutboxSupported;
+    private readonly maxBytes;
+    private readonly maxEvents;
+    private readonly metrics;
+    private readonly diagnostics;
+    private drafts;
+    private pending;
+    private tombstones;
+    private nextOrdinal;
+    private consent;
+    private generation;
+    private nextPermitOrdinal;
+    private legacyImportBlocked;
+    private consentAnchorEstablished;
+    private initialDenialPending;
+    private memoryOnly;
+    private durableWarningRecorded;
+    private deliveryLockHeld;
+    private purgePending;
+    private consentStateUnavailable;
+    private readonly onConsentRevoked;
+    private readonly consentChannel;
+    private readonly removeConsentStorageListener;
+    private readonly removeLegacyStorageListener;
+    constructor(options: {
+        readonly projectKey: string;
+        readonly initialConsent: CluebaseConsentState;
+        readonly maxBytes: number;
+        readonly maxEvents: number;
+        readonly metrics?: InternalMetricsStore;
+        readonly diagnostics?: DiagnosticStore;
+        readonly storage?: StorageLike | null;
+        readonly onConsentRevoked?: () => void;
+    });
+    currentConsent(): CluebaseConsentState;
+    capturePermit(): CollectionPermit;
+    permits(permit: CollectionPermit): boolean;
+    setConsent(next: CluebaseConsentState): ConsentTransition;
+    commitConsentTransition(transition: ConsentTransition): void;
+    private persistCommittedConsent;
+    addDraft(event: BrowserSourceEvent, permit?: CollectionPermit): boolean;
+    estimatedDraftBytes(measure: (events: readonly BrowserSourceEvent[], metadata: BatchEnvelopeMetadata) => number, metadata: BatchEnvelopeMetadata): number;
+    prepareFence(input: {
+        readonly maxPayloadBytes: number;
+        readonly createMetadata: () => BatchEnvelopeMetadata;
+        readonly measure: (events: readonly BrowserSourceEvent[], metadata: BatchEnvelopeMetadata) => number;
+    }): {
+        readonly targetOrdinal: number;
+        readonly oversized: number;
+    };
+    headThrough(targetOrdinal: number): PendingBrowserBatch | null;
+    removeHead(expected: PendingBrowserBatch): boolean;
+    retainHead(expected: PendingBrowserBatch): boolean;
+    splitHead(expected: PendingBrowserBatch, createMetadata: () => BatchEnvelopeMetadata): boolean;
+    clear(): boolean;
+    close(): void;
+    pendingEventCount(): number;
+    pendingBytes(): number;
+    withDeliveryLock<T>(operation: () => Promise<T>, options?: {
+        readonly restore?: boolean;
+    }): Promise<T>;
+    private permitsBatch;
+    private resolvePermit;
+    private initializeConsentForDelivery;
+    private enforceCapacity;
+    private purgeAll;
+    clearMemory(): void;
+    private restore;
+    private restoreOutbox;
+    private readConsent;
+    private peekConsentRaw;
+    private restoreConsentFromStorage;
+    private reconcileRemotePermittedConsent;
+    private adoptConsentRecord;
+    private repairDeniedConsentState;
+    private importLegacy;
+    private readLegacyEvents;
+    private applyRemoteDenial;
+    private persistConsent;
+    private writeRecord;
+    private removeRecord;
+    private removeDraft;
+    private removeClaimedDraftRecords;
+    private readRecord;
+    private failClosedConsentState;
+    private storageKeys;
+    private rawStorageKeys;
+    private removeRawRecord;
+    private warnDurableUnavailable;
+}