@genn-inc/cluebase-frontend-sdk 0.0.3 → 0.0.8

package/dist/exporter/browser-outbox.js

@@ -1,14 +1,14 @@
+import { canonicalize as canonicalJsonStringify } from "json-canonicalize";
+import { addStorageListener, consentRecordKey, createConsentChannel, createConsentRecord, createDraft, createGeneration, createLegacyTombstone, createPending, draftRecordKey, LEGACY_TOMBSTONE_LIMIT, nowIso, outboxEventCount, parseRecord, pendingRecordKey, readLocks, readStorage, sentByteLength, sha256Hex, tombstoneRecordKey, UNANCHORED_COLLECTION_GENERATION, verifyHash, } from "./browser-outbox-records.js";
 import { DiagnosticStore } from "./diagnostics.js";
 import { isBrowserSourceSignalEvent } from "./source-event.js";
-import { canonicalize as canonicalJsonStringify } from "json-canonicalize";
-import { addStorageListener, browserEventsByteLength, createConsentChannel, createConsentRecord, createDraft, createGeneration, createLegacyTombstone, createPending, consentRecordKey, draftRecordKey, hasLegacyTombstone, largestFittingPrefix, nowIso, outboxEventCount, parseRecord, readLocks, readStorage, recordBatchId, sha256Hex, toHeadBatch, splitPendingRecord, pendingRecordKey, tombstoneRecordKey, UNANCHORED_COLLECTION_GENERATION, verifyHash, withChecksum, withoutChecksum, LEGACY_TOMBSTONE_LIMIT, } from "./browser-outbox-records.js";
 export class BrowserOutbox {
     constructor(options) {
         this.drafts = [];
         this.pending = [];
+        this.pendingByBatchId = new Map();
         this.tombstones = [];
         this.nextOrdinal = 1;
-        this.nextPermitOrdinal = 1;
         this.legacyImportBlocked = false;
         this.consentAnchorEstablished = false;
         this.memoryOnly = false;
@@ -21,10 +21,9 @@ export class BrowserOutbox {
         this.consentKey = consentRecordKey(this.prefix);
         this.legacyKey = `cluebase:source_event_outbox:${options.projectKey}`;
         this.lockName = `cluebase:source-event-outbox:v2:${this.projectHash}`;
-        this.storage = "storage" in options ? options.storage ?? null : readStorage();
+        this.storage =
+            "storage" in options ? (options.storage ?? null) : readStorage();
         this.durableOutboxSupported = readLocks() !== null;
-        this.maxBytes = Math.max(1024, options.maxBytes);
-        this.maxEvents = Math.max(1, options.maxEvents);
         this.metrics = options.metrics ?? null;
         this.diagnostics = options.diagnostics ?? new DiagnosticStore();
         this.onConsentRevoked = options.onConsentRevoked ?? (() => undefined);
@@ -50,19 +49,10 @@ export class BrowserOutbox {
     currentConsent() {
         return this.consent;
     }
-    capturePermit() {
-        return Object.freeze({
-            generation: this.consentAnchorEstablished
-                ? this.generation
-                : UNANCHORED_COLLECTION_GENERATION,
-            permittedAtStart: this.consent !== "denied",
-            captureOrdinal: this.nextPermitOrdinal++,
-        });
-    }
-    permits(permit) {
-        return (permit.permittedAtStart &&
-            this.consent !== "denied" &&
-            permit.generation === this.generation);
+    collectionGeneration() {
+        return this.consentAnchorEstablished
+            ? this.generation
+            : UNANCHORED_COLLECTION_GENERATION;
     }
     setConsent(next) {
         const recoveryExpectedRaw = this.consentStateUnavailable
@@ -78,7 +68,10 @@ export class BrowserOutbox {
             this.generation = createGeneration();
             this.legacyImportBlocked = true;
             this.diagnostics.rotateForConsentPurge(purged);
-            this.consentChannel?.postMessage({ type: "denied", generation: this.generation });
+            this.consentChannel?.postMessage({
+                type: "denied",
+                generation: this.generation,
+            });
             this.clearMemory();
             return Object.freeze({
                 state: this.consent,
@@ -181,149 +174,124 @@ export class BrowserOutbox {
         const purged = transition.purge ? this.purgeAll() : true;
         return persisted && purged;
     }
-    addDraft(event, permit = this.capturePermit()) {
-        const resolvedPermit = this.resolvePermit(permit);
-        if (!resolvedPermit)
-            return false;
+    holdDraft(event) {
+        if (this.consent === "denied" || !this.consentAnchorEstablished)
+            return null;
         const draft = createDraft({
             event,
-            permit: resolvedPermit,
+            permit: { generation: this.generation, permittedAtStart: true },
             projectHash: this.projectHash,
             createdAt: nowIso(),
         });
         if (!draft)
-            return false;
+            return null;
         const key = draftRecordKey(this.prefix, draft.eventKeyHash);
         const existing = this.readRecord(key);
         if (existing) {
             if (existing.kind === "draft" &&
                 existing.recordVerifierSha256 === draft.recordVerifierSha256) {
-                return true;
+                return draft;
             }
             this.diagnostics.record({ code: "outbox_key_collision" });
-            return false;
+            return null;
         }
         this.drafts.push(draft);
-        this.enforceCapacity();
         if (!this.writeRecord(key, draft)) {
             this.memoryOnly = true;
             this.warnDurableUnavailable();
         }
-        return this.drafts.some((item) => item.eventId === draft.eventId);
-    }
-    estimatedDraftBytes(measure, metadata) {
-        return measure(this.drafts.map((draft) => draft.event), metadata);
-    }
-    prepareFence(input) {
-        const claimedEventKeyHashes = new Set(this.pending.flatMap((record) => record.eventKeyHashes));
-        const candidates = this.drafts.filter((draft) => !claimedEventKeyHashes.has(draft.eventKeyHash) &&
-            this.permits({
-                generation: draft.collectionGeneration,
-                permittedAtStart: draft.permittedAtStart,
-                captureOrdinal: 0,
-            }) &&
-            (draft.origin !== "legacy_v1" ||
-                hasLegacyTombstone(draft, this.tombstones)));
-        let oversized = 0;
-        let cursor = 0;
-        let targetOrdinal = this.pending[this.pending.length - 1]?.ordinal ?? 0;
-        while (cursor < candidates.length) {
-            const remaining = candidates.slice(cursor);
-            const metadata = input.createMetadata();
-            const count = largestFittingPrefix(remaining, input.maxPayloadBytes, metadata, input.measure);
-            if (count === 0) {
-                const draft = remaining[0];
-                if (draft) {
-                    this.removeDraft(draft);
-                    this.metrics?.increment("oversized_event_count");
-                    this.diagnostics.record({
-                        code: "event_oversize",
-                        event_fingerprint: this.diagnostics.eventFingerprint(canonicalJsonStringify(draft.event)),
-                    });
-                }
-                oversized += 1;
-                cursor += 1;
-                continue;
-            }
-            const selected = remaining.slice(0, count);
-            const record = createPending({
+        return draft;
+    }
+    claimBatch(input) {
+        const held = this.pendingByBatchId.get(input.batchId);
+        if (held)
+            return { record: held, minted: false };
+        const drafts = input.eventKeys.flatMap((eventKey) => {
+            const draft = this.drafts.find((item) => item.eventKeyHash === eventKey);
+            return draft ? [draft] : [];
+        });
+        if (drafts.length !== input.eventKeys.length)
+            return null;
+        const record = createPending({
+            projectHash: this.projectHash,
+            metadata: input.createMetadata(),
+            drafts,
+            ordinal: this.nextOrdinal,
+        });
+        if (!this.writeRecord(pendingRecordKey(this.prefix, record.batchId), record))
+            return null;
+        this.nextOrdinal += 1;
+        this.pending.push(record);
+        this.pendingByBatchId.set(input.batchId, record);
+        for (const draft of drafts) {
+            this.removeRecord(draftRecordKey(this.prefix, draft.eventKeyHash));
+        }
+        this.drafts = this.drafts.filter((draft) => !drafts.includes(draft));
+        return { record, minted: true };
+    }
+    releaseBatch(batchId) {
+        const record = this.pendingByBatchId.get(batchId);
+        if (!record)
+            return;
+        this.pendingByBatchId.delete(batchId);
+        if (!this.removeClaimedDraftRecords(record))
+            return;
+        if (!this.removeRecord(pendingRecordKey(this.prefix, record.batchId)))
+            return;
+        this.pending = this.pending.filter((item) => item !== record);
+    }
+    reopenBatch(batchId) {
+        const record = this.pendingByBatchId.get(batchId);
+        if (!record)
+            return;
+        this.pendingByBatchId.delete(batchId);
+        this.pending = this.pending.filter((item) => item !== record);
+        this.removeRecord(pendingRecordKey(this.prefix, record.batchId));
+        for (const stored of record.events) {
+            const draft = createDraft({
+                event: stored.event,
+                permit: {
+                    generation: record.collectionGeneration,
+                    permittedAtStart: stored.permittedAtStart,
+                },
                 projectHash: this.projectHash,
-                metadata,
-                drafts: selected,
-                ordinal: this.nextOrdinal,
+                createdAt: nowIso(),
             });
-            const key = pendingRecordKey(this.prefix, record.batchId);
-            if (!this.writeRecord(key, record)) {
+            if (!draft)
+                continue;
+            this.drafts.push(draft);
+            if (!this.writeRecord(draftRecordKey(this.prefix, draft.eventKeyHash), draft)) {
                 this.memoryOnly = true;
                 this.warnDurableUnavailable();
-                break;
-            }
-            this.pending.push(record);
-            for (const draft of selected) {
-                this.removeRecord(draftRecordKey(this.prefix, draft.eventKeyHash));
             }
-            this.drafts = this.drafts.filter((draft) => !selected.includes(draft));
-            targetOrdinal = record.ordinal;
-            this.nextOrdinal += 1;
-            cursor += count;
-        }
-        return { targetOrdinal, oversized };
-    }
-    headThrough(targetOrdinal) {
-        const record = this.pending
-            .sort((left, right) => left.ordinal - right.ordinal)
-            .find((item) => item.ordinal <= targetOrdinal);
-        if (!record)
-            return null;
-        return toHeadBatch(record, pendingRecordKey(this.prefix, record.batchId));
-    }
-    removeHead(expected) {
-        const record = this.pending.find((item) => item.ordinal === expected.ordinal &&
-            item.batchId === recordBatchId(expected));
-        if (!record || !this.permitsBatch(expected))
-            return false;
-        const key = pendingRecordKey(this.prefix, record.batchId);
-        if (record.kind === "pending" ||
-            record.nextOrdinal === record.children.length - 1) {
-            if (!this.removeClaimedDraftRecords(record))
-                return false;
-            if (!this.removeRecord(key))
-                return false;
-            this.pending = this.pending.filter((item) => item !== record);
-            return true;
         }
-        const progressed = withChecksum({
-            ...withoutChecksum(record),
-            nextOrdinal: record.nextOrdinal + 1,
-        });
-        if (!this.writeRecord(key, progressed))
-            return false;
-        this.pending = this.pending.map((item) => item === record ? progressed : item);
-        return true;
-    }
-    retainHead(expected) {
-        return (this.permitsBatch(expected) &&
-            this.headThrough(expected.ordinal)?.recordKey === expected.recordKey);
     }
-    splitHead(expected, createMetadata) {
-        const record = this.pending.find((item) => item.ordinal === expected.ordinal &&
-            item.batchId === recordBatchId(expected));
-        if (!record)
-            return false;
-        const plan = splitPendingRecord(record, createMetadata);
-        if (!plan)
-            return false;
-        const key = pendingRecordKey(this.prefix, record.batchId);
-        if (!this.writeRecord(key, plan))
-            return false;
-        this.pending = this.pending.map((item) => (item === record ? plan : item));
-        this.diagnostics.record({
-            code: "batch_split",
-            batch_fingerprint: expected.diagnosticCanonicalBytes
-                ? this.diagnostics.batchFingerprint(expected.diagnosticCanonicalBytes)
-                : undefined,
-        });
-        return true;
+    releaseEvents(eventKeys) {
+        for (const eventKey of eventKeys) {
+            this.removeRecord(draftRecordKey(this.prefix, eventKey));
+        }
+        this.drafts = this.drafts.filter((draft) => !eventKeys.includes(draft.eventKeyHash));
+    }
+    restorable() {
+        return {
+            batches: this.pending
+                .filter((record) => record.collectionGeneration === this.generation)
+                .map((record) => ({
+                ordinal: record.ordinal,
+                storedBatchId: record.batchId,
+                events: record.events.map((event) => ({
+                    event_key: event.eventKeyHash,
+                    byte_length: sentByteLength(event.event),
+                    diagnostic_canonical_bytes: canonicalJsonStringify(event.event),
+                })),
+            })),
+            drafts: this.drafts.filter((draft) => draft.collectionGeneration === this.generation),
+        };
+    }
+    bindRestoredBatch(storedBatchId, batchId) {
+        const record = this.pending.find((item) => item.batchId === storedBatchId);
+        if (record)
+            this.pendingByBatchId.set(batchId, record);
     }
     clear() {
         let removed = true;
@@ -355,12 +323,6 @@ export class BrowserOutbox {
     pendingEventCount() {
         return outboxEventCount(this.drafts, this.pending);
     }
-    pendingBytes() {
-        return browserEventsByteLength([
-            ...this.drafts.map((item) => item.event),
-            ...this.pending.flatMap((item) => item.events.map((event) => event.event)),
-        ]);
-    }
     async withDeliveryLock(operation, options = {}) {
         const locks = readLocks();
         if (!locks) {
@@ -387,23 +349,6 @@ export class BrowserOutbox {
             }
         });
     }
-    permitsBatch(batch) {
-        return batch.events.every((event) => this.permits(event.permit));
-    }
-    resolvePermit(permit) {
-        if (!permit.permittedAtStart || this.consent === "denied")
-            return null;
-        if (permit.generation === UNANCHORED_COLLECTION_GENERATION) {
-            if (!this.consentAnchorEstablished)
-                return null;
-            return Object.freeze({
-                generation: this.generation,
-                permittedAtStart: true,
-                captureOrdinal: permit.captureOrdinal,
-            });
-        }
-        return this.permits(permit) ? permit : null;
-    }
     initializeConsentForDelivery() {
         if (this.consentStateUnavailable) {
             this.consent = "denied";
@@ -434,20 +379,6 @@ export class BrowserOutbox {
         }
         this.restoreOutbox();
     }
-    enforceCapacity() {
-        while (this.pendingEventCount() > this.maxEvents ||
-            this.pendingBytes() > this.maxBytes) {
-            const dropped = this.drafts.shift();
-            if (!dropped)
-                return;
-            this.removeRecord(draftRecordKey(this.prefix, dropped.eventKeyHash));
-            this.metrics?.increment("dropped_count");
-            this.diagnostics.record({
-                code: "queue_overflow",
-                event_fingerprint: this.diagnostics.eventFingerprint(canonicalJsonStringify(dropped.event)),
-            });
-        }
-    }
     purgeAll() {
         const count = this.pendingEventCount();
         let removed = this.clear();
@@ -649,7 +580,7 @@ export class BrowserOutbox {
             const draft = existingDraft ??
                 createDraft({
                     event,
-                    permit: this.capturePermit(),
+                    permit: { generation: this.generation, permittedAtStart: true },
                     projectHash: this.projectHash,
                     createdAt: nowIso(),
                     origin: "legacy_v1",
@@ -770,12 +701,6 @@ export class BrowserOutbox {
             return false;
         }
     }
-    removeDraft(draft) {
-        if (!this.removeRecord(draftRecordKey(this.prefix, draft.eventKeyHash)))
-            return false;
-        this.drafts = this.drafts.filter((item) => item !== draft);
-        return true;
-    }
     removeClaimedDraftRecords(record) {
         let removed = true;
         for (const eventKeyHash of record.eventKeyHashes) {

package/dist/exporter/client.d.ts

@@ -1,15 +1,13 @@
 import type { InternalMetricsStore } from "../internal/metrics.js";
-import { type BrowserSourceEvent } from "./source-event.js";
 import { type IngestRetryStrategy } from "./delivery-response.js";
 import type { DiagnosticStore } from "./diagnostics.js";
-import type { IngestUsageGovernorFeedback } from "../provider/types.js";
+import type { TransportAbortCause, TransportOutcome, TransportRequest } from "./sdk-core-delivery.js";
+import { type IngestEndpointDescription } from "./sdk-core-wasm.js";
+import { type BrowserSourceEvent } from "./source-event.js";
 export declare const CLUEBASE_SDK_REQUEST_HEADER = "x-cluebase-sdk-request";
 export declare const CLUEBASE_SDK_VERSION_HEADER = "x-cluebase-sdk-version";
 export declare const CLUEBASE_SOURCE_SCHEMA_VERSION_HEADER = "x-cluebase-source-schema-version";
 export declare const CLUEBASE_BROWSER_TOKEN_HEADER = "x-cluebase-browser-token";
-export declare const CANONICAL_BROWSER_INGEST_PATH = "/api/v1/ingest/browser";
-export declare const CANONICAL_BROWSER_TOKEN_PATH = "/api/v1/ingest/browser-tokens";
-export declare const resolveCanonicalIngestEndpoint: (endpoint: string) => string;
 export type IngestClientOptions = {
     endpoint: string;
     projectKey: string;
@@ -18,27 +16,14 @@ export type IngestClientOptions = {
     schemaVersion: number;
     metrics?: InternalMetricsStore;
     diagnostics?: DiagnosticStore;
+    onEndpointsResolved?: (endpoints: IngestEndpointDescription) => void;
 };
-export declare const resolveBrowserTokenEndpoint: (endpoint: string) => string;
-export type SendEventsOptions = {
-    keepalive?: boolean;
-    useBeacon?: boolean;
-    signal?: AbortSignal;
-    requireCachedBrowserToken?: boolean;
-    maxPayloadBytes?: number;
-    metadata?: BatchEnvelopeMetadata;
-    deadlineAt?: number;
-};
-export type SendEventsResult = {
-    ok: boolean;
-    status: number | null;
-    attempts: number;
-    governor: IngestUsageGovernorFeedback | null;
-    retryStrategy: IngestRetryStrategy | null;
-    observationIngestBatchId?: string;
-    partial?: boolean;
-    droppedEventCount?: number;
-    reason?: string | null;
+export type DeliveryTokenResult = {
+    readonly ok: true;
+    readonly token: string;
+} | {
+    readonly ok: false;
+    readonly retryStrategy?: IngestRetryStrategy;
 };
 export type BatchEnvelopeMetadata = {
     batch_id: string;
@@ -47,30 +32,35 @@ export type BatchEnvelopeMetadata = {
 };
 export type { IngestRetryStrategy } from "./delivery-response.js";
 export declare class IngestClient {
-    private readonly endpoint;
-    private readonly browserTokenEndpoint;
+    private readonly configuredEndpoint;
+    private describedEndpoint;
+    private describePromise;
     private readonly projectKey;
-    private readonly sourceIdentifier;
     private readonly producerId;
     private readonly sdkType;
     private readonly sdkVersion;
     private readonly schemaVersion;
     private readonly metrics;
     private readonly diagnostics;
+    private readonly onEndpointsResolved;
     private cachedToken;
     private pendingTokenRequest;
+    private inFlight;
     constructor(options: IngestClientOptions);
-    send(events: BrowserSourceEvent[], options?: SendEventsOptions): Promise<SendEventsResult>;
+    private endpoints;
+    knownEndpoints(): IngestEndpointDescription | null;
+    perform(request: TransportRequest): Promise<TransportOutcome>;
+    abortAttempt(cause: TransportAbortCause): void;
     measurePayloadBytes(events: BrowserSourceEvent[], metadata?: BatchEnvelopeMetadata): number;
-    private stringifyPayload;
-    private withSourceEvidence;
+    stringifyPayload(events: BrowserSourceEvent[], metadata: BatchEnvelopeMetadata): string;
     createBatchEnvelopeMetadata(): BatchEnvelopeMetadata;
+    diagnosticCanonicalPayload(payload: string): string;
+    ensureDeliveryToken(options?: {
+        readonly requireCachedToken?: boolean;
+        readonly signal?: AbortSignal;
+    }): Promise<DeliveryTokenResult>;
     hasUsableBrowserToken(nowMs?: number): boolean;
     warmupBrowserToken(signal?: AbortSignal): Promise<boolean>;
-    private failedSend;
-    private recordDecision;
-    private postBatch;
-    private createId;
     private getUsableCachedBrowserToken;
     private ensureBrowserToken;
     private safeEnsureBrowserToken;