@genn-inc/cluebase-frontend-sdk 0.0.6 → 0.0.9

package/dist/exporter/delivery-pipeline.js

@@ -0,0 +1,199 @@
+import { applyTransportResult, attemptRequest, beginClose, capturePermit, closeDriver, adoptRestoredBatch as coreAdoptRestoredBatch, setConsent as coreSetConsent, enqueueEvent, fenceQueue, openConsent, openDriver, pendingEventCount, planNextStep, queueDepth, setBrowserToken, } from "./sdk-core-delivery.js";
+const RELEASED_PERMIT = Object.freeze({
+    generation: "",
+    gate_id: "",
+    permitted_at_start: false,
+    capture_open_at_start: false,
+});
+const RELEASED_ENQUEUE_REPORT = Object.freeze({
+    retained: false,
+    overflowed_event_keys: [],
+    diagnostics: [],
+});
+const RELEASED_RESTORE_REPORT = Object.freeze({
+    adopted: false,
+    event_keys: [],
+});
+const RELEASED_QUEUE_DEPTH = Object.freeze({
+    draft_count: 0,
+    draft_body_bytes: 0,
+    pending_bytes: 0,
+});
+const RELEASED_FENCE_REPORT = Object.freeze({
+    target_ordinal: 0,
+    oversized_event_keys: [],
+    frame_admits_no_event: true,
+    diagnostics: [],
+});
+const RELEASED_RUN_SUMMARY = Object.freeze({
+    observations: [],
+    attempts: 0,
+    stop: "queue_drained",
+});
+export class DeliveryPipeline {
+    constructor(options) {
+        this.released = false;
+        this.consentHandle = openConsent(options.initialConsent);
+        this.driverOptions = {
+            transport: {
+                surface: "frontend",
+                endpoint: options.endpoint,
+                project_key: options.projectKey,
+                sdk_request: options.sdkRequest,
+                sdk_version: options.sdkVersion,
+                source_schema_version: options.sourceSchemaVersion,
+            },
+            queue_limits: options.queueLimits,
+            ...(options.requestTimeoutMs === undefined
+                ? {}
+                : { request_timeout_ms: options.requestTimeoutMs }),
+        };
+        this.handle = openDriver(this.driverOptions, this.consentHandle);
+        this.transport = options.transport;
+        this.clock = options.clock;
+    }
+    reset() {
+        if (this.released)
+            return;
+        closeDriver(this.handle);
+        this.handle = openDriver(this.driverOptions, this.consentHandle);
+    }
+    permit() {
+        return this.released ? RELEASED_PERMIT : capturePermit(this.handle);
+    }
+    admit(event, permit) {
+        if (this.released)
+            return RELEASED_ENQUEUE_REPORT;
+        return enqueueEvent(this.handle, {
+            event_key: event.eventKey,
+            byte_length: event.byteLength,
+            permit,
+            ...(event.diagnosticCanonicalBytes === undefined
+                ? {}
+                : { diagnostic_canonical_bytes: event.diagnosticCanonicalBytes }),
+        });
+    }
+    adoptRestoredBatch(ordinal, events) {
+        if (this.released)
+            return RELEASED_RESTORE_REPORT;
+        return coreAdoptRestoredBatch(this.handle, ordinal, events);
+    }
+    depth(envelopeOverheadBytes) {
+        if (this.released)
+            return RELEASED_QUEUE_DEPTH;
+        return queueDepth(this.handle, envelopeOverheadBytes);
+    }
+    pendingCount() {
+        return this.released ? 0 : pendingEventCount(this.handle);
+    }
+    fence(envelopeOverheadBytes) {
+        if (this.released)
+            return RELEASED_FENCE_REPORT;
+        return fenceQueue(this.handle, envelopeOverheadBytes);
+    }
+    rememberBrowserToken(token) {
+        if (this.released)
+            return;
+        setBrowserToken(this.handle, token);
+    }
+    declareConsent(consent) {
+        return coreSetConsent(this.consentHandle, consent);
+    }
+    beginClose() {
+        if (this.released)
+            return;
+        beginClose(this.handle);
+    }
+    dispose() {
+        if (this.released)
+            return false;
+        this.released = true;
+        return closeDriver(this.handle);
+    }
+    async run(input) {
+        if (this.released)
+            return RELEASED_RUN_SUMMARY;
+        const observations = [];
+        let attempts = 0;
+        let stop = "queue_drained";
+        const deadlineMs = () => typeof input.deadlineMs === "function"
+            ? input.deadlineMs()
+            : input.deadlineMs;
+        while (true) {
+            if (this.released)
+                break;
+            const step = planNextStep(this.handle, this.clock.nowMs(), deadlineMs());
+            if (step.kind === "idle")
+                break;
+            if (step.kind === "blocked") {
+                stop = step.reason;
+                break;
+            }
+            if (step.kind === "wait_retry") {
+                await this.clock.sleep(step.delay_ms);
+                if (this.clock.nowMs() < step.resume_at_ms) {
+                    stop = "retry_not_due";
+                    break;
+                }
+                continue;
+            }
+            const batch = input.body(step.batch_id, step.event_keys);
+            if (!batch) {
+                stop = "batch_unavailable";
+                break;
+            }
+            attempts += 1;
+            const request = attemptRequest(this.handle, {
+                attemptId: step.attempt_id,
+                body: batch.body,
+                timeoutMs: step.timeout_ms,
+                ...(batch.diagnosticCanonicalBytes === undefined
+                    ? {}
+                    : { batchCanonicalBytes: batch.diagnosticCanonicalBytes }),
+            });
+            const outcome = await this.transport(request);
+            if (this.released)
+                break;
+            const report = applyTransportResult(this.handle, step.attempt_id, outcome, this.clock.nowMs());
+            const observation = observe(report);
+            observations.push(observation);
+            input.onObservation?.(observation);
+            if (report.progress.kind === "retries_exhausted") {
+                stop = "retries_exhausted";
+                break;
+            }
+            if (report.progress.kind === "consent_revoked") {
+                stop = "consent_revoked";
+                break;
+            }
+        }
+        return { observations, attempts, stop };
+    }
+}
+const observe = (report) => {
+    const progress = report.progress;
+    const settled = progress.kind === "settled" ? progress.settled_event_keys : [];
+    const dropped = progress.kind === "settled"
+        ? progress.dropped_event_keys
+        : progress.kind === "dropped_oversized"
+            ? [progress.event_key]
+            : [];
+    const droppedEventCount = Math.max(dropped.length, report.decision?.result.dropped_event_count ?? 0);
+    return {
+        progress,
+        diagnostics: report.diagnostics,
+        settledEventKeys: settled,
+        droppedEventKeys: dropped,
+        droppedEventCount,
+        httpStatus: report.decision?.http_status ?? null,
+        reason: report.decision?.result.reason ?? null,
+        ...(report.decision?.privacy_policy === undefined
+            ? {}
+            : { privacyPolicy: report.decision.privacy_policy }),
+        ...(report.decision?.sdk_encryption === undefined
+            ? {}
+            : { sdkEncryption: report.decision.sdk_encryption }),
+        directiveUnreadable: report.decision?.directive_unreadable === true,
+        diagnosticCodes: report.decision?.diagnostic_codes ?? [],
+    };
+};

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

@@ -6,6 +6,7 @@ declare const ingestRetryStrategySchema: z.ZodEnum<{
     mark_failed: "mark_failed";
     drop_event: "drop_event";
 }>;
+export type IngestRetryStrategy = z.infer<typeof ingestRetryStrategySchema>;
 export declare const ingestPrivacyPolicySchema: z.ZodObject<{
     token: z.ZodString;
     entries: z.ZodArray<z.ZodObject<{
@@ -19,85 +20,8 @@ export declare const ingestPrivacyPolicySchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type IngestPrivacyPolicy = z.output<typeof ingestPrivacyPolicySchema>;
-export declare const observationSourceEventBatchResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    accepted: z.ZodLiteral<true>;
-    observation_ingest_batch_id: z.ZodString;
-    status: z.ZodLiteral<"received">;
-    submitted_event_count: z.ZodNumber;
-    accepted_event_count: z.ZodNumber;
-    dropped_event_count: z.ZodNumber;
-    dropped_events: z.ZodArray<z.ZodObject<{
-        event_index: z.ZodNumber;
-        reason: z.ZodString;
-        source_event_payload_fingerprint: z.ZodNullable<z.ZodString>;
-    }, z.core.$strict>>;
-    duplicate: z.ZodBoolean;
-    governor: z.ZodOptional<z.ZodObject<{
-        disabledCapabilities: z.ZodArray<z.ZodEnum<{
-            event_collection: "event_collection";
-            replay_storage: "replay_storage";
-            ai_generation: "ai_generation";
-            raw_observation_storage: "raw_observation_storage";
-            retention_growth: "retention_growth";
-        }>>;
-        limitReasons: z.ZodArray<z.ZodObject<{
-            limitKind: z.ZodEnum<{
-                monthly_overage_amount_limit: "monthly_overage_amount_limit";
-                internal_cost_limit: "internal_cost_limit";
-                internal_limit: "internal_limit";
-                operator_global_monthly_cost_limit: "operator_global_monthly_cost_limit";
-            }>;
-            meterKey: z.ZodString;
-            thresholdStage: z.ZodEnum<{
-                info: "info";
-                warning: "warning";
-                urgent: "urgent";
-                reached: "reached";
-            }>;
-            currentValue: z.ZodNumber;
-            limitValue: z.ZodNumber;
-            retryAfterAt: z.ZodNullable<z.ZodString>;
-        }, z.core.$strip>>;
-        retryAfterAt: z.ZodNullable<z.ZodString>;
-    }, z.core.$strip>>;
-    privacy_policy: z.ZodOptional<z.ZodObject<{
-        token: z.ZodString;
-        entries: z.ZodArray<z.ZodObject<{
-            method: z.ZodString;
-            path_template: z.ZodString;
-            direction: z.ZodEnum<{
-                request: "request";
-                response: "response";
-            }>;
-            field_path: z.ZodString;
-        }, z.core.$strict>>;
-    }, z.core.$strict>>;
-}, z.core.$strip>, z.ZodObject<{
-    accepted: z.ZodLiteral<false>;
-    status: z.ZodEnum<{
-        rejected: "rejected";
-        failed: "failed";
-    }>;
-    reason: z.ZodString;
-    retry_strategy: z.ZodEnum<{
-        split_batch: "split_batch";
-        retry_same_batch: "retry_same_batch";
-        stop_and_report: "stop_and_report";
-        mark_failed: "mark_failed";
-        drop_event: "drop_event";
-    }>;
-    submitted_event_count: z.ZodOptional<z.ZodNumber>;
-    accepted_event_count: z.ZodOptional<z.ZodNumber>;
-    dropped_event_count: z.ZodOptional<z.ZodNumber>;
-    dropped_events: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        event_index: z.ZodNumber;
-        reason: z.ZodString;
-        source_event_payload_fingerprint: z.ZodNullable<z.ZodString>;
-    }, z.core.$strict>>>;
-    limits: z.ZodOptional<z.ZodObject<{
-        hard_max_payload_bytes: z.ZodNumber;
-        max_event_bytes: z.ZodNumber;
-    }, z.core.$strip>>;
-}, z.core.$strip>], "accepted">;
-export type IngestRetryStrategy = z.infer<typeof ingestRetryStrategySchema>;
+export declare const ingestSdkEncryptionSchema: z.ZodObject<{
+    key_version: z.ZodNumber;
+    public_key: z.ZodString;
+}, z.core.$strict>;
 export {};

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

@@ -1,6 +1,4 @@
 import { z } from "zod";
-import { COST_CAPABILITIES, LIMIT_KINDS, } from "../_generated/usage-governor-tables.js";
-const MAX_INGEST_EVENTS_PER_BATCH = 10000;
 const ingestRetryStrategySchema = z.enum([
     "split_batch",
     "retry_same_batch",
@@ -8,34 +6,6 @@ const ingestRetryStrategySchema = z.enum([
     "mark_failed",
     "drop_event",
 ]);
-const ingestDroppedEventSchema = z
-    .object({
-    event_index: z.number().int().nonnegative(),
-    reason: z.string().trim().min(1).max(128),
-    source_event_payload_fingerprint: z
-        .string()
-        .regex(/^[0-9a-f]{64}$/)
-        .nullable(),
-})
-    .strict();
-const ingestUsageGovernorFeedbackSchema = z.object({
-    disabledCapabilities: z.array(z.enum(COST_CAPABILITIES)),
-    limitReasons: z.array(z.object({
-        limitKind: z.enum(LIMIT_KINDS),
-        meterKey: z.string().trim().min(1),
-        thresholdStage: z.enum(["info", "warning", "urgent", "reached"]),
-        currentValue: z.number().nonnegative(),
-        limitValue: z.number().nonnegative(),
-        retryAfterAt: z.string().datetime({ offset: true }).nullable(),
-    })),
-    retryAfterAt: z.string().datetime({ offset: true }).nullable(),
-});
-const boundedCount = z
-    .number()
-    .int()
-    .nonnegative()
-    .max(MAX_INGEST_EVENTS_PER_BATCH);
-const positiveCount = boundedCount.refine((count) => count > 0);
 export const ingestPrivacyPolicySchema = z
     .object({
     token: z.string().trim().min(1).max(200),
@@ -51,141 +21,9 @@ export const ingestPrivacyPolicySchema = z
         .max(500),
 })
     .strict();
-const observationSourceEventBatchAcceptedResponseSchema = z
+export const ingestSdkEncryptionSchema = z
     .object({
-    accepted: z.literal(true),
-    observation_ingest_batch_id: z.string().trim().min(1),
-    status: z.literal("received"),
-    submitted_event_count: positiveCount,
-    accepted_event_count: positiveCount,
-    dropped_event_count: boundedCount,
-    dropped_events: z
-        .array(ingestDroppedEventSchema)
-        .max(MAX_INGEST_EVENTS_PER_BATCH),
-    duplicate: z.boolean(),
-    governor: ingestUsageGovernorFeedbackSchema.optional(),
-    privacy_policy: ingestPrivacyPolicySchema.optional(),
+    key_version: z.number().int().positive(),
+    public_key: z.string().trim().min(1).max(2048),
 })
-    .superRefine((value, ctx) => {
-    if (value.submitted_event_count !==
-        value.accepted_event_count + value.dropped_event_count) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["submitted_event_count"],
-            message: "submitted count must equal accepted plus dropped counts",
-        });
-    }
-    if (!value.duplicate || value.dropped_events.length > 0) {
-        validateDroppedEventDetails(value.submitted_event_count, value.dropped_event_count, value.dropped_events, ctx);
-    }
-});
-const observationSourceEventBatchRejectedResponseSchema = z
-    .object({
-    accepted: z.literal(false),
-    status: z.enum(["rejected", "failed"]),
-    reason: z.string().trim().min(1),
-    retry_strategy: ingestRetryStrategySchema,
-    submitted_event_count: positiveCount.optional(),
-    accepted_event_count: boundedCount.optional(),
-    dropped_event_count: boundedCount.optional(),
-    dropped_events: z
-        .array(ingestDroppedEventSchema)
-        .max(MAX_INGEST_EVENTS_PER_BATCH)
-        .optional(),
-    limits: z
-        .object({
-        hard_max_payload_bytes: z.number().int().positive(),
-        max_event_bytes: z.number().int().positive(),
-    })
-        .refine((limits) => limits.max_event_bytes <= limits.hard_max_payload_bytes)
-        .optional(),
-})
-    .superRefine((value, ctx) => {
-    const counts = [
-        value.submitted_event_count,
-        value.accepted_event_count,
-        value.dropped_event_count,
-    ];
-    const hasAnyCount = counts.some((count) => count !== undefined);
-    const hasAllCounts = counts.every((count) => count !== undefined);
-    if (hasAnyCount !== hasAllCounts) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["submitted_event_count"],
-            message: "rejected response counts must be all present or all absent",
-        });
-        return;
-    }
-    if (hasAllCounts) {
-        const [submitted, accepted, dropped] = counts;
-        if (accepted > submitted ||
-            dropped > submitted ||
-            accepted + dropped > submitted) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["dropped_event_count"],
-                message: "rejected counts must not exceed submitted count",
-            });
-        }
-    }
-    if (value.retry_strategy === "drop_event") {
-        if (!hasAllCounts) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["submitted_event_count"],
-                message: "drop rejection requires all counts",
-            });
-        }
-        else {
-            const [submitted, accepted, dropped] = counts;
-            if (accepted !== 0 || dropped !== submitted) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    path: ["dropped_event_count"],
-                    message: "drop rejection must reject every submitted event",
-                });
-            }
-            validateDroppedEventDetails(submitted, dropped, value.dropped_events ?? [], ctx);
-        }
-    }
-    else if ((value.dropped_events?.length ?? 0) > 0) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["dropped_events"],
-            message: "non-drop rejection must not contain dropped event details",
-        });
-    }
-    if ((value.retry_strategy === "split_batch") !==
-        (value.limits !== undefined)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["limits"],
-            message: "byte limits are valid only for split rejection",
-        });
-    }
-});
-export const observationSourceEventBatchResponseSchema = z.discriminatedUnion("accepted", [
-    observationSourceEventBatchAcceptedResponseSchema,
-    observationSourceEventBatchRejectedResponseSchema,
-]);
-function validateDroppedEventDetails(submittedCount, droppedCount, droppedEvents, ctx) {
-    if (droppedEvents.length !== droppedCount) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["dropped_events"],
-            message: "dropped event details must match dropped count",
-        });
-    }
-    const indexes = new Set();
-    for (const [detailIndex, detail] of droppedEvents.entries()) {
-        if (detail.event_index >= submittedCount ||
-            indexes.has(detail.event_index)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["dropped_events", detailIndex, "event_index"],
-                message: "dropped event indexes must be valid and unique",
-            });
-        }
-        indexes.add(detail.event_index);
-    }
-}
+    .strict();

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

@@ -1,17 +1,18 @@
-import type { IngestUsageGovernorFeedback } from "../provider/types.js";
-import { type IngestRetryStrategy } from "./delivery-response-contract.js";
+import type { IngestRetryStrategy } from "./delivery-response-contract.js";
 import type { DiagnosticCode } from "./diagnostics.js";
-export declare const BROWSER_REJECTION_STRATEGIES: Readonly<Record<string, IngestRetryStrategy>>;
+import { type TransportOutcome } from "./sdk-core-delivery.js";
 export type { IngestRetryStrategy } from "./delivery-response-contract.js";
 export type BrowserDeliveryDecision = {
     readonly ok: boolean;
     readonly privacyPolicy?: unknown;
+    readonly sdkEncryption?: unknown;
+    readonly directiveUnreadable: boolean;
     readonly retryStrategy: IngestRetryStrategy | null;
-    readonly governor: IngestUsageGovernorFeedback | null;
     readonly observationIngestBatchId?: string;
     readonly droppedEventCount: number;
     readonly acceptedEventCount: number;
     readonly acceptedPartial: boolean;
+    readonly acceptedFiltered: boolean;
     readonly reason: string | null;
     readonly diagnosticCodes: readonly DiagnosticCode[];
 };
@@ -20,4 +21,7 @@ export declare const evaluateBrowserDeliveryResponse: (input: {
     readonly bodyText: string;
     readonly localSubmittedCount: number;
 }) => BrowserDeliveryDecision;
+export declare const evaluateBrowserTransportOutcome: (outcome: Exclude<TransportOutcome, {
+    kind: "response";
+}>) => BrowserDeliveryDecision;
 export declare const classifyIngestHttpStatus: (status: number) => IngestRetryStrategy;