@reopt-ai/data-contract 0.1.0

package/dist/ingest.d.ts

@@ -0,0 +1,270 @@
+import { z } from 'zod';
+
+/**
+ * `POST /api/track` — the ingest contract.
+ *
+ * The request shape is shared by both credential modes. The *response* shape
+ * is where server-ingest differs: it reports per-event rejections instead of
+ * failing a whole batch, because a forwarder that stalls on one malformed row
+ * stops forwarding forever.
+ *
+ * Absorbed from the former internal `@reopt/ingest-contract`; that package is
+ * now a deprecated re-export of this module.
+ */
+
+/** Event names the pipeline reserves for its own session bookkeeping. */
+declare const RESERVED_EVENT_NAMES: readonly ["session_start", "session_end", "screen_view"];
+/** Hard cap enforced by the route before the body is even parsed. */
+declare const MAX_TRACK_PAYLOAD_BYTES = 512000;
+declare const zTrackPayload: z.ZodObject<{
+    name: z.ZodString;
+    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    profileId: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>;
+declare const zIdentifyPayload: z.ZodObject<{
+    profileId: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    firstName: z.ZodOptional<z.ZodString>;
+    lastName: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodEmail>;
+    avatar: z.ZodOptional<z.ZodURL>;
+    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const zIncrementPayload: z.ZodObject<{
+    profileId: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    property: z.ZodString;
+    value: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const zDecrementPayload: z.ZodObject<{
+    profileId: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    property: z.ZodString;
+    value: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const zTrackHandlerPayload: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    eventId: z.ZodUUID;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"track">;
+    payload: z.ZodObject<{
+        name: z.ZodString;
+        properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        profileId: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    eventId: z.ZodUUID;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"identify">;
+    payload: z.ZodObject<{
+        profileId: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+        firstName: z.ZodOptional<z.ZodString>;
+        lastName: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodEmail>;
+        avatar: z.ZodOptional<z.ZodURL>;
+        properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    eventId: z.ZodUUID;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"increment">;
+    payload: z.ZodObject<{
+        profileId: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+        property: z.ZodString;
+        value: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    eventId: z.ZodUUID;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"decrement">;
+    payload: z.ZodObject<{
+        profileId: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+        property: z.ZodString;
+        value: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "type">;
+type ITrackPayload = z.infer<typeof zTrackPayload>;
+type IIdentifyPayload = z.infer<typeof zIdentifyPayload>;
+type IIncrementPayload = z.infer<typeof zIncrementPayload>;
+type IDecrementPayload = z.infer<typeof zDecrementPayload>;
+type ITrackHandlerPayload = z.infer<typeof zTrackHandlerPayload>;
+/**
+ * Decided by the credential presented, never by a header the caller sets:
+ * `reopt-write-key` alone → `browser`, `reopt-client-id` + `reopt-client-secret`
+ * → `server`. A separate mode header could disagree with the credential; this
+ * cannot.
+ *
+ * `browser` keeps the 5-second click dedup and device-scoped sessions.
+ * `server` drops both and relies solely on `eventId` idempotency — a server
+ * batch legitimately contains the same event name many times within one second,
+ * and its "device" is a process, not a person.
+ */
+declare const INGEST_MODES: readonly ["browser", "server"];
+declare const zIngestMode: z.ZodEnum<{
+    browser: "browser";
+    server: "server";
+}>;
+type IngestMode = z.infer<typeof zIngestMode>;
+/**
+ * Why a single event in a batch was dropped. These are permanent: re-sending
+ * the same row produces the same rejection, so a forwarder should count it as
+ * skipped and advance its cursor rather than retry.
+ */
+declare const INGEST_REJECTION_REASONS: readonly ["validation_failed", "reserved_name", "duplicate_in_batch"];
+declare const zIngestRejectionReason: z.ZodEnum<{
+    validation_failed: "validation_failed";
+    reserved_name: "reserved_name";
+    duplicate_in_batch: "duplicate_in_batch";
+}>;
+type IngestRejectionReason = z.infer<typeof zIngestRejectionReason>;
+declare const zIngestRejection: z.ZodObject<{
+    eventId: z.ZodString;
+    index: z.ZodNumber;
+    reason: z.ZodEnum<{
+        validation_failed: "validation_failed";
+        reserved_name: "reserved_name";
+        duplicate_in_batch: "duplicate_in_batch";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type IngestRejection = z.infer<typeof zIngestRejection>;
+/** 200 — accepted and handed to the materialize queue. */
+declare const zIngestOkResponse: z.ZodObject<{
+    queued: z.ZodBoolean;
+    accepted: z.ZodNumber;
+    duplicates: z.ZodNumber;
+    rejected: z.ZodArray<z.ZodObject<{
+        eventId: z.ZodString;
+        index: z.ZodNumber;
+        reason: z.ZodEnum<{
+            validation_failed: "validation_failed";
+            reserved_name: "reserved_name";
+            duplicate_in_batch: "duplicate_in_batch";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    status: z.ZodLiteral<"ok">;
+    requestId: z.ZodString;
+    mode: z.ZodEnum<{
+        browser: "browser";
+        server: "server";
+    }>;
+}, z.core.$strip>;
+/**
+ * 202 — raw events landed, but enqueueing the materialize task failed. No data
+ * is lost: the `replay-unmaterialized` cron picks these up. A forwarder should
+ * treat this as success and advance its cursor. Carries the same counts as 200
+ * so the reconciliation below works here too.
+ */
+declare const zIngestAcceptedResponse: z.ZodObject<{
+    backgroundQueued: z.ZodLiteral<false>;
+    replay: z.ZodLiteral<"unmaterialized-raw-events">;
+    accepted: z.ZodNumber;
+    duplicates: z.ZodNumber;
+    rejected: z.ZodArray<z.ZodObject<{
+        eventId: z.ZodString;
+        index: z.ZodNumber;
+        reason: z.ZodEnum<{
+            validation_failed: "validation_failed";
+            reserved_name: "reserved_name";
+            duplicate_in_batch: "duplicate_in_batch";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    status: z.ZodLiteral<"accepted">;
+    requestId: z.ZodString;
+    mode: z.ZodEnum<{
+        browser: "browser";
+        server: "server";
+    }>;
+}, z.core.$strip>;
+declare const zIngestResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    queued: z.ZodBoolean;
+    accepted: z.ZodNumber;
+    duplicates: z.ZodNumber;
+    rejected: z.ZodArray<z.ZodObject<{
+        eventId: z.ZodString;
+        index: z.ZodNumber;
+        reason: z.ZodEnum<{
+            validation_failed: "validation_failed";
+            reserved_name: "reserved_name";
+            duplicate_in_batch: "duplicate_in_batch";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    status: z.ZodLiteral<"ok">;
+    requestId: z.ZodString;
+    mode: z.ZodEnum<{
+        browser: "browser";
+        server: "server";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    backgroundQueued: z.ZodLiteral<false>;
+    replay: z.ZodLiteral<"unmaterialized-raw-events">;
+    accepted: z.ZodNumber;
+    duplicates: z.ZodNumber;
+    rejected: z.ZodArray<z.ZodObject<{
+        eventId: z.ZodString;
+        index: z.ZodNumber;
+        reason: z.ZodEnum<{
+            validation_failed: "validation_failed";
+            reserved_name: "reserved_name";
+            duplicate_in_batch: "duplicate_in_batch";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    status: z.ZodLiteral<"accepted">;
+    requestId: z.ZodString;
+    mode: z.ZodEnum<{
+        browser: "browser";
+        server: "server";
+    }>;
+}, z.core.$strip>], "status">;
+type IngestOkResponse = z.infer<typeof zIngestOkResponse>;
+type IngestAcceptedResponse = z.infer<typeof zIngestAcceptedResponse>;
+type IngestResponse = z.infer<typeof zIngestResponse>;
+/**
+ * The reconciliation a forwarder runs on every 2xx:
+ *
+ *     accepted + duplicates + rejected.length === events sent
+ *
+ * A mismatch means the server silently dropped something, which is exactly the
+ * failure mode this contract exists to make impossible to miss.
+ */
+declare function reconcileIngestResponse(response: IngestResponse, sentCount: number): boolean;
+/**
+ * Stable machine-readable codes. Branch on these, never on `error`/`message`,
+ * which are prose and may be reworded.
+ */
+declare const INGEST_ERROR_CODES: readonly ["unauthorized", "invalid_json", "payload_too_large", "empty_batch", "alias_unsupported", "project_without_organization", "validation_failed", "rate_limited", "quota_exceeded", "internal_error"];
+declare const zIngestErrorCode: z.ZodEnum<{
+    unauthorized: "unauthorized";
+    validation_failed: "validation_failed";
+    rate_limited: "rate_limited";
+    internal_error: "internal_error";
+    invalid_json: "invalid_json";
+    payload_too_large: "payload_too_large";
+    empty_batch: "empty_batch";
+    alias_unsupported: "alias_unsupported";
+    project_without_organization: "project_without_organization";
+    quota_exceeded: "quota_exceeded";
+}>;
+type IngestErrorCode = z.infer<typeof zIngestErrorCode>;
+declare const zIngestError: z.ZodObject<{
+    status: z.ZodNumber;
+    code: z.ZodEnum<{
+        unauthorized: "unauthorized";
+        validation_failed: "validation_failed";
+        rate_limited: "rate_limited";
+        internal_error: "internal_error";
+        invalid_json: "invalid_json";
+        payload_too_large: "payload_too_large";
+        empty_batch: "empty_batch";
+        alias_unsupported: "alias_unsupported";
+        project_without_organization: "project_without_organization";
+        quota_exceeded: "quota_exceeded";
+    }>;
+    error: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    errors: z.ZodOptional<z.ZodUnknown>;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type IngestError = z.infer<typeof zIngestError>;
+
+export { type IDecrementPayload, type IIdentifyPayload, type IIncrementPayload, INGEST_ERROR_CODES, INGEST_MODES, INGEST_REJECTION_REASONS, type ITrackHandlerPayload, type ITrackPayload, type IngestAcceptedResponse, type IngestError, type IngestErrorCode, type IngestMode, type IngestOkResponse, type IngestRejection, type IngestRejectionReason, type IngestResponse, MAX_TRACK_PAYLOAD_BYTES, RESERVED_EVENT_NAMES, reconcileIngestResponse, zDecrementPayload, zIdentifyPayload, zIncrementPayload, zIngestAcceptedResponse, zIngestError, zIngestErrorCode, zIngestMode, zIngestOkResponse, zIngestRejection, zIngestRejectionReason, zIngestResponse, zTrackHandlerPayload, zTrackPayload };

package/dist/ingest.js

@@ -0,0 +1,43 @@
+import {
+  INGEST_ERROR_CODES,
+  INGEST_MODES,
+  INGEST_REJECTION_REASONS,
+  MAX_TRACK_PAYLOAD_BYTES,
+  RESERVED_EVENT_NAMES,
+  reconcileIngestResponse,
+  zDecrementPayload,
+  zIdentifyPayload,
+  zIncrementPayload,
+  zIngestAcceptedResponse,
+  zIngestError,
+  zIngestErrorCode,
+  zIngestMode,
+  zIngestOkResponse,
+  zIngestRejection,
+  zIngestRejectionReason,
+  zIngestResponse,
+  zTrackHandlerPayload,
+  zTrackPayload
+} from "./chunk-FRJK7OCQ.js";
+export {
+  INGEST_ERROR_CODES,
+  INGEST_MODES,
+  INGEST_REJECTION_REASONS,
+  MAX_TRACK_PAYLOAD_BYTES,
+  RESERVED_EVENT_NAMES,
+  reconcileIngestResponse,
+  zDecrementPayload,
+  zIdentifyPayload,
+  zIncrementPayload,
+  zIngestAcceptedResponse,
+  zIngestError,
+  zIngestErrorCode,
+  zIngestMode,
+  zIngestOkResponse,
+  zIngestRejection,
+  zIngestRejectionReason,
+  zIngestResponse,
+  zTrackHandlerPayload,
+  zTrackPayload
+};
+//# sourceMappingURL=ingest.js.map

package/dist/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/query.cjs

@@ -0,0 +1,59 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+var _chunkDHSMXB54cjs = require('./chunk-DHSMXB54.cjs');
+
+
+
+var _chunkZQVRSCTWcjs = require('./chunk-ZQVRSCTW.cjs');
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.QUERY_API_PATHS = _chunkDHSMXB54cjs.QUERY_API_PATHS; exports.QUERY_ERROR_CODES = _chunkDHSMXB54cjs.QUERY_ERROR_CODES; exports.isValidTimeZone = _chunkDHSMXB54cjs.isValidTimeZone; exports.zChannelFilter = _chunkDHSMXB54cjs.zChannelFilter; exports.zDate = _chunkZQVRSCTWcjs.zDate; exports.zEventsTimeseriesData = _chunkDHSMXB54cjs.zEventsTimeseriesData; exports.zEventsTimeseriesInput = _chunkDHSMXB54cjs.zEventsTimeseriesInput; exports.zEventsTimeseriesResponse = _chunkDHSMXB54cjs.zEventsTimeseriesResponse; exports.zFunnelData = _chunkDHSMXB54cjs.zFunnelData; exports.zFunnelInput = _chunkDHSMXB54cjs.zFunnelInput; exports.zFunnelResponse = _chunkDHSMXB54cjs.zFunnelResponse; exports.zFunnelStep = _chunkDHSMXB54cjs.zFunnelStep; exports.zGranularity = _chunkDHSMXB54cjs.zGranularity; exports.zInstant = _chunkZQVRSCTWcjs.zInstant; exports.zQueryEnvelope = _chunkDHSMXB54cjs.zQueryEnvelope; exports.zQueryError = _chunkDHSMXB54cjs.zQueryError; exports.zQueryErrorCode = _chunkDHSMXB54cjs.zQueryErrorCode; exports.zQueryMeta = _chunkDHSMXB54cjs.zQueryMeta; exports.zRetentionCell = _chunkDHSMXB54cjs.zRetentionCell; exports.zRetentionData = _chunkDHSMXB54cjs.zRetentionData; exports.zRetentionInput = _chunkDHSMXB54cjs.zRetentionInput; exports.zRetentionInterval = _chunkDHSMXB54cjs.zRetentionInterval; exports.zRetentionResponse = _chunkDHSMXB54cjs.zRetentionResponse; exports.zTimeseriesBreakdown = _chunkDHSMXB54cjs.zTimeseriesBreakdown; exports.zTimeseriesPoint = _chunkDHSMXB54cjs.zTimeseriesPoint; exports.zTimezone = _chunkDHSMXB54cjs.zTimezone;
+//# sourceMappingURL=query.cjs.map

package/dist/query.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/eric/reopt-ai/reopt-data/packages/data-contract/dist/query.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,uhDAAC","file":"/Users/eric/reopt-ai/reopt-data/packages/data-contract/dist/query.cjs"}