@reopt-ai/data-contract 0.2.0 → 0.5.0

package/dist/query.d.ts

@@ -16,10 +16,10 @@ export { zDate, zInstant } from './index.js';
 
 /** Bucket width for a time series. */
 declare const zGranularity: z.ZodEnum<{
-    hour: "hour";
+    month: "month";
     day: "day";
+    hour: "hour";
     week: "week";
-    month: "month";
 }>;
 type Granularity = z.infer<typeof zGranularity>;
 /**
@@ -54,13 +54,29 @@ type ChannelFilter = z.infer<typeof zChannelFilter>;
  * TTL, while ingest lag means the read model is genuinely behind and the right
  * response is an "aggregating" badge, not a refresh.
  */
+declare const zQuerySource: z.ZodEnum<{
+    rollup: "rollup";
+    raw: "raw";
+    mixed: "mixed";
+}>;
+type QuerySource = z.infer<typeof zQuerySource>;
 declare const zQueryMeta: z.ZodObject<{
     projectId: z.ZodString;
     computedAt: z.ZodString;
     cacheAgeSeconds: z.ZodNumber;
-    ingestLagSeconds: z.ZodNumber;
+    ingestLagSeconds: z.ZodNullable<z.ZodNumber>;
+    ingestLagStatus: z.ZodEnum<{
+        unknown: "unknown";
+        known: "known";
+    }>;
+    ingestDeadLetterCount: z.ZodNullable<z.ZodNumber>;
     cached: z.ZodBoolean;
     timezone: z.ZodString;
+    source: z.ZodEnum<{
+        rollup: "rollup";
+        raw: "raw";
+        mixed: "mixed";
+    }>;
     requestId: z.ZodString;
 }, z.core.$strip>;
 type QueryMeta = z.infer<typeof zQueryMeta>;
@@ -71,9 +87,19 @@ declare function zQueryEnvelope<T extends z.ZodTypeAny>(data: T): z.ZodObject<{
         projectId: z.ZodString;
         computedAt: z.ZodString;
         cacheAgeSeconds: z.ZodNumber;
-        ingestLagSeconds: z.ZodNumber;
+        ingestLagSeconds: z.ZodNullable<z.ZodNumber>;
+        ingestLagStatus: z.ZodEnum<{
+            unknown: "unknown";
+            known: "known";
+        }>;
+        ingestDeadLetterCount: z.ZodNullable<z.ZodNumber>;
         cached: z.ZodBoolean;
         timezone: z.ZodString;
+        source: z.ZodEnum<{
+            rollup: "rollup";
+            raw: "raw";
+            mixed: "mixed";
+        }>;
         requestId: z.ZodString;
     }, z.core.$strip>;
 }, z.core.$strip>;
@@ -88,17 +114,29 @@ declare const zTimeseriesBreakdown: z.ZodObject<{
     topN: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 type TimeseriesBreakdown = z.infer<typeof zTimeseriesBreakdown>;
+/** Exact-match filter for a top-level event `properties` key. Multiple filters are ANDed. */
+declare const zEventPropertyFilter: z.ZodObject<{
+    key: z.ZodString;
+    operator: z.ZodDefault<z.ZodLiteral<"eq">>;
+    value: z.ZodString;
+}, z.core.$strip>;
+type EventPropertyFilter = z.infer<typeof zEventPropertyFilter>;
 declare const zEventsTimeseriesInput: z.ZodObject<{
     projectId: z.ZodString;
     startDate: z.ZodString;
     endDate: z.ZodString;
     granularity: z.ZodDefault<z.ZodEnum<{
-        hour: "hour";
+        month: "month";
         day: "day";
+        hour: "hour";
         week: "week";
-        month: "month";
     }>>;
     eventName: z.ZodOptional<z.ZodString>;
+    propertyFilters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        operator: z.ZodDefault<z.ZodLiteral<"eq">>;
+        value: z.ZodString;
+    }, z.core.$strip>>>;
     breakdown: z.ZodOptional<z.ZodObject<{
         kind: z.ZodLiteral<"property">;
         key: z.ZodString;
@@ -106,8 +144,23 @@ declare const zEventsTimeseriesInput: z.ZodObject<{
     }, z.core.$strip>>;
     segmentId: z.ZodOptional<z.ZodString>;
     timezone: z.ZodOptional<z.ZodString>;
+    includeInternal: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 type EventsTimeseriesInput = z.input<typeof zEventsTimeseriesInput>;
+/**
+ * Bucket start as wall-clock time in `meta.timezone`, `YYYY-MM-DD HH:MM:SS`.
+ *
+ * Pinned rather than left to the backend, because a consumer keys its chart on
+ * this string: an unspecified format is one where two backends, or two
+ * granularities, can quietly disagree and produce two different keys for the
+ * same bucket.
+ *
+ * It is wall time, not an instant — for `Asia/Seoul` a day bucket reads
+ * `2026-08-24 00:00:00`, which is `2026-08-23T15:00:00Z`. Day, week and month
+ * buckets always carry `00:00:00`, so slicing the first ten characters is a
+ * safe way to get a date key.
+ */
+declare const zBucketStart: z.ZodString;
 declare const zTimeseriesPoint: z.ZodObject<{
     date: z.ZodString;
     count: z.ZodNumber;
@@ -115,10 +168,10 @@ declare const zTimeseriesPoint: z.ZodObject<{
 type TimeseriesPoint = z.infer<typeof zTimeseriesPoint>;
 declare const zEventsTimeseriesData: z.ZodObject<{
     granularity: z.ZodEnum<{
-        hour: "hour";
+        month: "month";
         day: "day";
+        hour: "hour";
         week: "week";
-        month: "month";
     }>;
     timezone: z.ZodString;
     series: z.ZodArray<z.ZodObject<{
@@ -137,10 +190,10 @@ type EventsTimeseriesData = z.infer<typeof zEventsTimeseriesData>;
 declare const zEventsTimeseriesResponse: z.ZodObject<{
     data: z.ZodObject<{
         granularity: z.ZodEnum<{
-            hour: "hour";
+            month: "month";
             day: "day";
+            hour: "hour";
             week: "week";
-            month: "month";
         }>;
         timezone: z.ZodString;
         series: z.ZodArray<z.ZodObject<{
@@ -159,9 +212,19 @@ declare const zEventsTimeseriesResponse: z.ZodObject<{
         projectId: z.ZodString;
         computedAt: z.ZodString;
         cacheAgeSeconds: z.ZodNumber;
-        ingestLagSeconds: z.ZodNumber;
+        ingestLagSeconds: z.ZodNullable<z.ZodNumber>;
+        ingestLagStatus: z.ZodEnum<{
+            unknown: "unknown";
+            known: "known";
+        }>;
+        ingestDeadLetterCount: z.ZodNullable<z.ZodNumber>;
         cached: z.ZodBoolean;
         timezone: z.ZodString;
+        source: z.ZodEnum<{
+            rollup: "rollup";
+            raw: "raw";
+            mixed: "mixed";
+        }>;
         requestId: z.ZodString;
     }, z.core.$strip>;
 }, z.core.$strip>;
@@ -181,6 +244,7 @@ declare const zFunnelInput: z.ZodObject<{
         utmCampaigns: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     timezone: z.ZodOptional<z.ZodString>;
+    includeInternal: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 type FunnelInput = z.input<typeof zFunnelInput>;
 declare const zFunnelStep: z.ZodObject<{
@@ -221,26 +285,36 @@ declare const zFunnelResponse: z.ZodObject<{
         projectId: z.ZodString;
         computedAt: z.ZodString;
         cacheAgeSeconds: z.ZodNumber;
-        ingestLagSeconds: z.ZodNumber;
+        ingestLagSeconds: z.ZodNullable<z.ZodNumber>;
+        ingestLagStatus: z.ZodEnum<{
+            unknown: "unknown";
+            known: "known";
+        }>;
+        ingestDeadLetterCount: z.ZodNullable<z.ZodNumber>;
         cached: z.ZodBoolean;
         timezone: z.ZodString;
+        source: z.ZodEnum<{
+            rollup: "rollup";
+            raw: "raw";
+            mixed: "mixed";
+        }>;
         requestId: z.ZodString;
     }, z.core.$strip>;
 }, z.core.$strip>;
 type FunnelResponse = z.infer<typeof zFunnelResponse>;
 declare const zRetentionInterval: z.ZodEnum<{
+    month: "month";
     day: "day";
     week: "week";
-    month: "month";
 }>;
 declare const zRetentionInput: z.ZodObject<{
     projectId: z.ZodString;
     startDate: z.ZodString;
     endDate: z.ZodString;
     interval: z.ZodDefault<z.ZodEnum<{
+        month: "month";
         day: "day";
         week: "week";
-        month: "month";
     }>>;
     periods: z.ZodDefault<z.ZodNumber>;
     startEvent: z.ZodOptional<z.ZodString>;
@@ -262,6 +336,7 @@ declare const zRetentionInput: z.ZodObject<{
         utmCampaigns: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     timezone: z.ZodOptional<z.ZodString>;
+    includeInternal: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 type RetentionInput = z.input<typeof zRetentionInput>;
 declare const zRetentionCell: z.ZodObject<{
@@ -284,9 +359,9 @@ declare const zRetentionData: z.ZodObject<{
         rate: z.ZodNumber;
     }, z.core.$strip>>;
     interval: z.ZodEnum<{
+        month: "month";
         day: "day";
         week: "week";
-        month: "month";
     }>;
     periods: z.ZodNumber;
     retentionType: z.ZodEnum<{
@@ -312,9 +387,9 @@ declare const zRetentionResponse: z.ZodObject<{
             rate: z.ZodNumber;
         }, z.core.$strip>>;
         interval: z.ZodEnum<{
+            month: "month";
             day: "day";
             week: "week";
-            month: "month";
         }>;
         periods: z.ZodNumber;
         retentionType: z.ZodEnum<{
@@ -327,19 +402,237 @@ declare const zRetentionResponse: z.ZodObject<{
         projectId: z.ZodString;
         computedAt: z.ZodString;
         cacheAgeSeconds: z.ZodNumber;
-        ingestLagSeconds: z.ZodNumber;
+        ingestLagSeconds: z.ZodNullable<z.ZodNumber>;
+        ingestLagStatus: z.ZodEnum<{
+            unknown: "unknown";
+            known: "known";
+        }>;
+        ingestDeadLetterCount: z.ZodNullable<z.ZodNumber>;
         cached: z.ZodBoolean;
         timezone: z.ZodString;
+        source: z.ZodEnum<{
+            rollup: "rollup";
+            raw: "raw";
+            mixed: "mixed";
+        }>;
         requestId: z.ZodString;
     }, z.core.$strip>;
 }, z.core.$strip>;
 type RetentionResponse = z.infer<typeof zRetentionResponse>;
-declare const QUERY_ERROR_CODES: readonly ["unauthorized", "project_scope_mismatch", "query_scope_missing", "validation_failed", "unsupported_combination", "rate_limited", "query_timeout", "internal_error"];
+/**
+ * Session-level traffic for a brand site, served from the hourly rollups.
+ * `newVisitors` counts sessions whose device was first seen inside them;
+ * `returningVisitors` is the rest. Both are session counts, not people —
+ * "visitor" is the vocabulary the dashboards already use.
+ */
+declare const zTrafficOverviewInput: z.ZodObject<{
+    projectId: z.ZodString;
+    startDate: z.ZodString;
+    endDate: z.ZodString;
+    granularity: z.ZodDefault<z.ZodEnum<{
+        month: "month";
+        day: "day";
+        hour: "hour";
+        week: "week";
+    }>>;
+    timezone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TrafficOverviewInput = z.input<typeof zTrafficOverviewInput>;
+declare const zTrafficTotals: z.ZodObject<{
+    sessions: z.ZodNumber;
+    pageviews: z.ZodNumber;
+    newVisitors: z.ZodNumber;
+    returningVisitors: z.ZodNumber;
+    bounceRate: z.ZodNumber;
+}, z.core.$strip>;
+type TrafficTotals = z.infer<typeof zTrafficTotals>;
+declare const zTrafficSeriesPoint: z.ZodObject<{
+    sessions: z.ZodNumber;
+    pageviews: z.ZodNumber;
+    newVisitors: z.ZodNumber;
+    returningVisitors: z.ZodNumber;
+    bounceRate: z.ZodNumber;
+    date: z.ZodString;
+}, z.core.$strip>;
+declare const zTrafficOverviewData: z.ZodObject<{
+    granularity: z.ZodEnum<{
+        month: "month";
+        day: "day";
+        hour: "hour";
+        week: "week";
+    }>;
+    timezone: z.ZodString;
+    totals: z.ZodObject<{
+        sessions: z.ZodNumber;
+        pageviews: z.ZodNumber;
+        newVisitors: z.ZodNumber;
+        returningVisitors: z.ZodNumber;
+        bounceRate: z.ZodNumber;
+    }, z.core.$strip>;
+    series: z.ZodArray<z.ZodObject<{
+        sessions: z.ZodNumber;
+        pageviews: z.ZodNumber;
+        newVisitors: z.ZodNumber;
+        returningVisitors: z.ZodNumber;
+        bounceRate: z.ZodNumber;
+        date: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type TrafficOverviewData = z.infer<typeof zTrafficOverviewData>;
+declare const zTrafficOverviewResponse: z.ZodObject<{
+    data: z.ZodObject<{
+        granularity: z.ZodEnum<{
+            month: "month";
+            day: "day";
+            hour: "hour";
+            week: "week";
+        }>;
+        timezone: z.ZodString;
+        totals: z.ZodObject<{
+            sessions: z.ZodNumber;
+            pageviews: z.ZodNumber;
+            newVisitors: z.ZodNumber;
+            returningVisitors: z.ZodNumber;
+            bounceRate: z.ZodNumber;
+        }, z.core.$strip>;
+        series: z.ZodArray<z.ZodObject<{
+            sessions: z.ZodNumber;
+            pageviews: z.ZodNumber;
+            newVisitors: z.ZodNumber;
+            returningVisitors: z.ZodNumber;
+            bounceRate: z.ZodNumber;
+            date: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    meta: z.ZodObject<{
+        projectId: z.ZodString;
+        computedAt: z.ZodString;
+        cacheAgeSeconds: z.ZodNumber;
+        ingestLagSeconds: z.ZodNullable<z.ZodNumber>;
+        ingestLagStatus: z.ZodEnum<{
+            unknown: "unknown";
+            known: "known";
+        }>;
+        ingestDeadLetterCount: z.ZodNullable<z.ZodNumber>;
+        cached: z.ZodBoolean;
+        timezone: z.ZodString;
+        source: z.ZodEnum<{
+            rollup: "rollup";
+            raw: "raw";
+            mixed: "mixed";
+        }>;
+        requestId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type TrafficOverviewResponse = z.infer<typeof zTrafficOverviewResponse>;
+declare const zTrafficDimension: z.ZodEnum<{
+    channel: "channel";
+    referrer: "referrer";
+    utm: "utm";
+}>;
+type TrafficDimension = z.infer<typeof zTrafficDimension>;
+declare const zTrafficSourcesInput: z.ZodObject<{
+    projectId: z.ZodString;
+    startDate: z.ZodString;
+    endDate: z.ZodString;
+    dimension: z.ZodEnum<{
+        channel: "channel";
+        referrer: "referrer";
+        utm: "utm";
+    }>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    timezone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TrafficSourcesInput = z.input<typeof zTrafficSourcesInput>;
+declare const zTrafficSourceRow: z.ZodObject<{
+    sessions: z.ZodNumber;
+    pageviews: z.ZodNumber;
+    newVisitors: z.ZodNumber;
+    returningVisitors: z.ZodNumber;
+    bounceRate: z.ZodNumber;
+    key: z.ZodString;
+    channelType: z.ZodOptional<z.ZodString>;
+    referrerName: z.ZodOptional<z.ZodString>;
+    referrerType: z.ZodOptional<z.ZodString>;
+    utmSource: z.ZodOptional<z.ZodString>;
+    utmMedium: z.ZodOptional<z.ZodString>;
+    utmCampaign: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TrafficSourceRow = z.infer<typeof zTrafficSourceRow>;
+declare const zTrafficSourcesData: z.ZodObject<{
+    dimension: z.ZodEnum<{
+        channel: "channel";
+        referrer: "referrer";
+        utm: "utm";
+    }>;
+    timezone: z.ZodString;
+    rows: z.ZodArray<z.ZodObject<{
+        sessions: z.ZodNumber;
+        pageviews: z.ZodNumber;
+        newVisitors: z.ZodNumber;
+        returningVisitors: z.ZodNumber;
+        bounceRate: z.ZodNumber;
+        key: z.ZodString;
+        channelType: z.ZodOptional<z.ZodString>;
+        referrerName: z.ZodOptional<z.ZodString>;
+        referrerType: z.ZodOptional<z.ZodString>;
+        utmSource: z.ZodOptional<z.ZodString>;
+        utmMedium: z.ZodOptional<z.ZodString>;
+        utmCampaign: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type TrafficSourcesData = z.infer<typeof zTrafficSourcesData>;
+declare const zTrafficSourcesResponse: z.ZodObject<{
+    data: z.ZodObject<{
+        dimension: z.ZodEnum<{
+            channel: "channel";
+            referrer: "referrer";
+            utm: "utm";
+        }>;
+        timezone: z.ZodString;
+        rows: z.ZodArray<z.ZodObject<{
+            sessions: z.ZodNumber;
+            pageviews: z.ZodNumber;
+            newVisitors: z.ZodNumber;
+            returningVisitors: z.ZodNumber;
+            bounceRate: z.ZodNumber;
+            key: z.ZodString;
+            channelType: z.ZodOptional<z.ZodString>;
+            referrerName: z.ZodOptional<z.ZodString>;
+            referrerType: z.ZodOptional<z.ZodString>;
+            utmSource: z.ZodOptional<z.ZodString>;
+            utmMedium: z.ZodOptional<z.ZodString>;
+            utmCampaign: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    meta: z.ZodObject<{
+        projectId: z.ZodString;
+        computedAt: z.ZodString;
+        cacheAgeSeconds: z.ZodNumber;
+        ingestLagSeconds: z.ZodNullable<z.ZodNumber>;
+        ingestLagStatus: z.ZodEnum<{
+            unknown: "unknown";
+            known: "known";
+        }>;
+        ingestDeadLetterCount: z.ZodNullable<z.ZodNumber>;
+        cached: z.ZodBoolean;
+        timezone: z.ZodString;
+        source: z.ZodEnum<{
+            rollup: "rollup";
+            raw: "raw";
+            mixed: "mixed";
+        }>;
+        requestId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type TrafficSourcesResponse = z.infer<typeof zTrafficSourcesResponse>;
+declare const QUERY_ERROR_CODES: readonly ["unauthorized", "project_scope_mismatch", "query_scope_missing", "validation_failed", "unsupported_combination", "project_purging", "rate_limited", "query_timeout", "internal_error"];
 declare const zQueryErrorCode: z.ZodEnum<{
-    validation_failed: "validation_failed";
     unauthorized: "unauthorized";
+    validation_failed: "validation_failed";
     rate_limited: "rate_limited";
     internal_error: "internal_error";
+    project_purging: "project_purging";
     project_scope_mismatch: "project_scope_mismatch";
     query_scope_missing: "query_scope_missing";
     unsupported_combination: "unsupported_combination";
@@ -349,10 +642,11 @@ type QueryErrorCode = z.infer<typeof zQueryErrorCode>;
 declare const zQueryError: z.ZodObject<{
     status: z.ZodNumber;
     code: z.ZodEnum<{
-        validation_failed: "validation_failed";
         unauthorized: "unauthorized";
+        validation_failed: "validation_failed";
         rate_limited: "rate_limited";
         internal_error: "internal_error";
+        project_purging: "project_purging";
         project_scope_mismatch: "project_scope_mismatch";
         query_scope_missing: "query_scope_missing";
         unsupported_combination: "unsupported_combination";
@@ -369,6 +663,8 @@ declare const QUERY_API_PATHS: {
     readonly eventsTimeseries: "/api/v1/query/events/timeseries";
     readonly funnel: "/api/v1/query/funnel";
     readonly retention: "/api/v1/query/retention";
+    readonly trafficOverview: "/api/v1/query/traffic/overview";
+    readonly trafficSources: "/api/v1/query/traffic/sources";
 };
 
-export { type ChannelFilter, type EventsTimeseriesData, type EventsTimeseriesInput, type EventsTimeseriesResponse, type FunnelData, type FunnelInput, type FunnelResponse, type Granularity, QUERY_API_PATHS, QUERY_ERROR_CODES, type QueryError, type QueryErrorCode, type QueryMeta, type RetentionData, type RetentionInput, type RetentionResponse, type TimeseriesBreakdown, type TimeseriesPoint, isValidTimeZone, zChannelFilter, zEventsTimeseriesData, zEventsTimeseriesInput, zEventsTimeseriesResponse, zFunnelData, zFunnelInput, zFunnelResponse, zFunnelStep, zGranularity, zQueryEnvelope, zQueryError, zQueryErrorCode, zQueryMeta, zRetentionCell, zRetentionData, zRetentionInput, zRetentionInterval, zRetentionResponse, zTimeseriesBreakdown, zTimeseriesPoint, zTimezone };
+export { type ChannelFilter, type EventPropertyFilter, type EventsTimeseriesData, type EventsTimeseriesInput, type EventsTimeseriesResponse, type FunnelData, type FunnelInput, type FunnelResponse, type Granularity, QUERY_API_PATHS, QUERY_ERROR_CODES, type QueryError, type QueryErrorCode, type QueryMeta, type QuerySource, type RetentionData, type RetentionInput, type RetentionResponse, type TimeseriesBreakdown, type TimeseriesPoint, type TrafficDimension, type TrafficOverviewData, type TrafficOverviewInput, type TrafficOverviewResponse, type TrafficSourceRow, type TrafficSourcesData, type TrafficSourcesInput, type TrafficSourcesResponse, type TrafficTotals, isValidTimeZone, zBucketStart, zChannelFilter, zEventPropertyFilter, zEventsTimeseriesData, zEventsTimeseriesInput, zEventsTimeseriesResponse, zFunnelData, zFunnelInput, zFunnelResponse, zFunnelStep, zGranularity, zQueryEnvelope, zQueryError, zQueryErrorCode, zQueryMeta, zQuerySource, zRetentionCell, zRetentionData, zRetentionInput, zRetentionInterval, zRetentionResponse, zTimeseriesBreakdown, zTimeseriesPoint, zTimezone, zTrafficDimension, zTrafficOverviewData, zTrafficOverviewInput, zTrafficOverviewResponse, zTrafficSeriesPoint, zTrafficSourceRow, zTrafficSourcesData, zTrafficSourcesInput, zTrafficSourcesResponse, zTrafficTotals };

package/dist/query.js

@@ -2,7 +2,9 @@ import {
   QUERY_API_PATHS,
   QUERY_ERROR_CODES,
   isValidTimeZone,
+  zBucketStart,
   zChannelFilter,
+  zEventPropertyFilter,
   zEventsTimeseriesData,
   zEventsTimeseriesInput,
   zEventsTimeseriesResponse,
@@ -15,6 +17,7 @@ import {
   zQueryError,
   zQueryErrorCode,
   zQueryMeta,
+  zQuerySource,
   zRetentionCell,
   zRetentionData,
   zRetentionInput,
@@ -22,18 +25,30 @@ import {
   zRetentionResponse,
   zTimeseriesBreakdown,
   zTimeseriesPoint,
-  zTimezone
-} from "./chunk-SC7TFGTO.js";
+  zTimezone,
+  zTrafficDimension,
+  zTrafficOverviewData,
+  zTrafficOverviewInput,
+  zTrafficOverviewResponse,
+  zTrafficSeriesPoint,
+  zTrafficSourceRow,
+  zTrafficSourcesData,
+  zTrafficSourcesInput,
+  zTrafficSourcesResponse,
+  zTrafficTotals
+} from "./chunk-BCGR27G2.js";
 import {
   zDate,
   zInstant
-} from "./chunk-IKOEYZVT.js";
+} from "./chunk-2LZBZXBF.js";
 export {
   QUERY_API_PATHS,
   QUERY_ERROR_CODES,
   isValidTimeZone,
+  zBucketStart,
   zChannelFilter,
   zDate,
+  zEventPropertyFilter,
   zEventsTimeseriesData,
   zEventsTimeseriesInput,
   zEventsTimeseriesResponse,
@@ -47,6 +62,7 @@ export {
   zQueryError,
   zQueryErrorCode,
   zQueryMeta,
+  zQuerySource,
   zRetentionCell,
   zRetentionData,
   zRetentionInput,
@@ -54,6 +70,16 @@ export {
   zRetentionResponse,
   zTimeseriesBreakdown,
   zTimeseriesPoint,
-  zTimezone
+  zTimezone,
+  zTrafficDimension,
+  zTrafficOverviewData,
+  zTrafficOverviewInput,
+  zTrafficOverviewResponse,
+  zTrafficSeriesPoint,
+  zTrafficSourceRow,
+  zTrafficSourcesData,
+  zTrafficSourcesInput,
+  zTrafficSourcesResponse,
+  zTrafficTotals
 };
 //# sourceMappingURL=query.js.map

package/dist/report.cjs

@@ -0,0 +1,85 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/report.ts
+var _zod = require('zod');
+var REPORT_SPEC_VERSION = 1;
+var zReportRange = _zod.z.string().regex(/^\d+[dhm]$/, "expected a relative range such as 7d or 24h");
+var zReportInterval = _zod.z.enum(["minute", "hour", "day", "week", "month"]);
+var zLegacyChartType = _zod.z.enum([
+  "linear",
+  "bar",
+  "pie",
+  "metric",
+  "area",
+  "gauge",
+  "scatter",
+  "table",
+  "sparkline"
+]);
+var zCommon = {
+  version: _zod.z.literal(REPORT_SPEC_VERSION),
+  range: zReportRange.default("30d"),
+  segmentId: _zod.z.string().min(1).optional()
+};
+var zTimeseriesReportSpec = _zod.z.object({
+  ...zCommon,
+  kind: _zod.z.literal("timeseries"),
+  chartType: zLegacyChartType,
+  interval: zReportInterval,
+  events: _zod.z.array(_zod.z.object({ name: _zod.z.string().min(1).max(200) })).min(1).max(20),
+  breakdowns: _zod.z.array(_zod.z.string().min(1).max(200)).max(5).default([]),
+  comparePrevious: _zod.z.boolean().default(false)
+});
+var zFunnelReportSpec = _zod.z.object({
+  ...zCommon,
+  kind: _zod.z.literal("funnel"),
+  steps: _zod.z.array(_zod.z.string().min(1).max(200)).min(2).max(10),
+  windowSeconds: _zod.z.number().int().min(60).max(2592e3).default(86400)
+});
+var zRetentionReportSpec = _zod.z.object({
+  ...zCommon,
+  kind: _zod.z.literal("retention"),
+  interval: _zod.z.enum(["day", "week", "month"]).default("day"),
+  periods: _zod.z.number().int().min(1).max(30).default(7),
+  startEvent: _zod.z.string().min(1).max(200).optional(),
+  returnEvent: _zod.z.string().min(1).max(200).optional(),
+  retentionType: _zod.z.enum(["bounded", "unbounded"]).default("bounded"),
+  cohortMode: _zod.z.enum(["first-ever", "first-in-window"]).default("first-ever")
+});
+var zPathReportSpec = _zod.z.object({
+  ...zCommon,
+  kind: _zod.z.literal("path"),
+  limit: _zod.z.number().int().min(1).max(100).default(30),
+  startPage: _zod.z.string().max(2e3).optional(),
+  endPage: _zod.z.string().max(2e3).optional()
+});
+var zReportSpec = _zod.z.discriminatedUnion("kind", [
+  zTimeseriesReportSpec,
+  zFunnelReportSpec,
+  zRetentionReportSpec,
+  zPathReportSpec
+]);
+function legacyReportToSpec(input) {
+  const events = _zod.z.array(_zod.z.object({ name: _zod.z.string().min(1).max(200) })).safeParse(input.events);
+  const breakdowns = _zod.z.array(_zod.z.string().min(1).max(200)).safeParse(input.breakdowns);
+  return zTimeseriesReportSpec.parse({
+    version: REPORT_SPEC_VERSION,
+    kind: "timeseries",
+    chartType: input.chartType,
+    interval: input.interval,
+    range: input.range,
+    events: events.success && events.data.length > 0 ? events.data : [{ name: "$pageview" }],
+    breakdowns: breakdowns.success ? breakdowns.data : []
+  });
+}
+
+
+
+
+
+
+
+
+
+
+
+exports.REPORT_SPEC_VERSION = REPORT_SPEC_VERSION; exports.legacyReportToSpec = legacyReportToSpec; exports.zFunnelReportSpec = zFunnelReportSpec; exports.zLegacyChartType = zLegacyChartType; exports.zPathReportSpec = zPathReportSpec; exports.zReportInterval = zReportInterval; exports.zReportRange = zReportRange; exports.zReportSpec = zReportSpec; exports.zRetentionReportSpec = zRetentionReportSpec; exports.zTimeseriesReportSpec = zTimeseriesReportSpec;
+//# sourceMappingURL=report.cjs.map

package/dist/report.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/eric/reopt-ai/reopt-data/packages/data-contract/dist/report.cjs","../src/report.ts"],"names":[],"mappings":"AAAA;ACAA,0BAAkB;AAEX,IAAM,oBAAA,EAAsB,CAAA;AAE5B,IAAM,aAAA,EAAe,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,KAAA,CAAM,YAAA,EAAc,6CAA6C,CAAA;AACjG,IAAM,gBAAA,EAAkB,MAAA,CAAE,IAAA,CAAK,CAAC,QAAA,EAAU,MAAA,EAAQ,KAAA,EAAO,MAAA,EAAQ,OAAO,CAAC,CAAA;AACzE,IAAM,iBAAA,EAAmB,MAAA,CAAE,IAAA,CAAK;AAAA,EACrC,QAAA;AAAA,EACA,KAAA;AAAA,EACA,KAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAC,CAAA;AAED,IAAM,QAAA,EAAU;AAAA,EACd,OAAA,EAAS,MAAA,CAAE,OAAA,CAAQ,mBAAmB,CAAA;AAAA,EACtC,KAAA,EAAO,YAAA,CAAa,OAAA,CAAQ,KAAK,CAAA;AAAA,EACjC,SAAA,EAAW,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,QAAA,CAAS;AACxC,CAAA;AAEO,IAAM,sBAAA,EAAwB,MAAA,CAAE,MAAA,CAAO;AAAA,EAC5C,GAAG,OAAA;AAAA,EACH,IAAA,EAAM,MAAA,CAAE,OAAA,CAAQ,YAAY,CAAA;AAAA,EAC5B,SAAA,EAAW,gBAAA;AAAA,EACX,QAAA,EAAU,eAAA;AAAA,EACV,MAAA,EAAQ,MAAA,CACL,KAAA,CAAM,MAAA,CAAE,MAAA,CAAO,EAAE,IAAA,EAAM,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,GAAG,EAAE,CAAC,CAAC,CAAA,CACpD,GAAA,CAAI,CAAC,CAAA,CACL,GAAA,CAAI,EAAE,CAAA;AAAA,EACT,UAAA,EAAY,MAAA,CAAE,KAAA,CAAM,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,GAAG,CAAC,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,OAAA,CAAQ,CAAC,CAAC,CAAA;AAAA,EACjE,eAAA,EAAiB,MAAA,CAAE,OAAA,CAAQ,CAAA,CAAE,OAAA,CAAQ,KAAK;AAC5C,CAAC,CAAA;AAEM,IAAM,kBAAA,EAAoB,MAAA,CAAE,MAAA,CAAO;AAAA,EACxC,GAAG,OAAA;AAAA,EACH,IAAA,EAAM,MAAA,CAAE,OAAA,CAAQ,QAAQ,CAAA;AAAA,EACxB,KAAA,EAAO,MAAA,CAAE,KAAA,CAAM,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,GAAG,CAAC,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,EAAE,CAAA;AAAA,EACxD,aAAA,EAAe,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAA,CAAE,GAAA,CAAI,EAAE,CAAA,CAAE,GAAA,CAAI,MAAS,CAAA,CAAE,OAAA,CAAQ,KAAM;AACvE,CAAC,CAAA;AAEM,IAAM,qBAAA,EAAuB,MAAA,CAAE,MAAA,CAAO;AAAA,EAC3C,GAAG,OAAA;AAAA,EACH,IAAA,EAAM,MAAA,CAAE,OAAA,CAAQ,WAAW,CAAA;AAAA,EAC3B,QAAA,EAAU,MAAA,CAAE,IAAA,CAAK,CAAC,KAAA,EAAO,MAAA,EAAQ,OAAO,CAAC,CAAA,CAAE,OAAA,CAAQ,KAAK,CAAA;AAAA,EACxD,OAAA,EAAS,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,EAAE,CAAA,CAAE,OAAA,CAAQ,CAAC,CAAA;AAAA,EAClD,UAAA,EAAY,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,GAAG,CAAA,CAAE,QAAA,CAAS,CAAA;AAAA,EAChD,WAAA,EAAa,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,GAAG,CAAA,CAAE,QAAA,CAAS,CAAA;AAAA,EACjD,aAAA,EAAe,MAAA,CAAE,IAAA,CAAK,CAAC,SAAA,EAAW,WAAW,CAAC,CAAA,CAAE,OAAA,CAAQ,SAAS,CAAA;AAAA,EACjE,UAAA,EAAY,MAAA,CAAE,IAAA,CAAK,CAAC,YAAA,EAAc,iBAAiB,CAAC,CAAA,CAAE,OAAA,CAAQ,YAAY;AAC5E,CAAC,CAAA;AAEM,IAAM,gBAAA,EAAkB,MAAA,CAAE,MAAA,CAAO;AAAA,EACtC,GAAG,OAAA;AAAA,EACH,IAAA,EAAM,MAAA,CAAE,OAAA,CAAQ,MAAM,CAAA;AAAA,EACtB,KAAA,EAAO,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,GAAG,CAAA,CAAE,OAAA,CAAQ,EAAE,CAAA;AAAA,EAClD,SAAA,EAAW,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,GAAK,CAAA,CAAE,QAAA,CAAS,CAAA;AAAA,EAC1C,OAAA,EAAS,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,GAAK,CAAA,CAAE,QAAA,CAAS;AAC1C,CAAC,CAAA;AAEM,IAAM,YAAA,EAAc,MAAA,CAAE,kBAAA,CAAmB,MAAA,EAAQ;AAAA,EACtD,qBAAA;AAAA,EACA,iBAAA;AAAA,EACA,oBAAA;AAAA,EACA;AACF,CAAC,CAAA;AAMM,SAAS,kBAAA,CAAmB,KAAA,EAMV;AACvB,EAAA,MAAM,OAAA,EAAS,MAAA,CAAE,KAAA,CAAM,MAAA,CAAE,MAAA,CAAO,EAAE,IAAA,EAAM,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,GAAG,EAAE,CAAC,CAAC,CAAA,CAAE,SAAA,CAAU,KAAA,CAAM,MAAM,CAAA;AAC7F,EAAA,MAAM,WAAA,EAAa,MAAA,CAAE,KAAA,CAAM,MAAA,CAAE,MAAA,CAAO,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,GAAG,CAAC,CAAA,CAAE,SAAA,CAAU,KAAA,CAAM,UAAU,CAAA;AACjF,EAAA,OAAO,qBAAA,CAAsB,KAAA,CAAM;AAAA,IACjC,OAAA,EAAS,mBAAA;AAAA,IACT,IAAA,EAAM,YAAA;AAAA,IACN,SAAA,EAAW,KAAA,CAAM,SAAA;AAAA,IACjB,QAAA,EAAU,KAAA,CAAM,QAAA;AAAA,IAChB,KAAA,EAAO,KAAA,CAAM,KAAA;AAAA,IACb,MAAA,EAAQ,MAAA,CAAO,QAAA,GAAW,MAAA,CAAO,IAAA,CAAK,OAAA,EAAS,EAAA,EAAI,MAAA,CAAO,KAAA,EAAO,CAAC,EAAE,IAAA,EAAM,YAAY,CAAC,CAAA;AAAA,IACvF,UAAA,EAAY,UAAA,CAAW,QAAA,EAAU,UAAA,CAAW,KAAA,EAAO,CAAC;AAAA,EACtD,CAAC,CAAA;AACH;ADpBA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,ycAAC","file":"/Users/eric/reopt-ai/reopt-data/packages/data-contract/dist/report.cjs","sourcesContent":[null,"import { z } from \"zod\";\n\nexport const REPORT_SPEC_VERSION = 1 as const;\n\nexport const zReportRange = z.string().regex(/^\\d+[dhm]$/, \"expected a relative range such as 7d or 24h\");\nexport const zReportInterval = z.enum([\"minute\", \"hour\", \"day\", \"week\", \"month\"]);\nexport const zLegacyChartType = z.enum([\n  \"linear\",\n  \"bar\",\n  \"pie\",\n  \"metric\",\n  \"area\",\n  \"gauge\",\n  \"scatter\",\n  \"table\",\n  \"sparkline\",\n]);\n\nconst zCommon = {\n  version: z.literal(REPORT_SPEC_VERSION),\n  range: zReportRange.default(\"30d\"),\n  segmentId: z.string().min(1).optional(),\n};\n\nexport const zTimeseriesReportSpec = z.object({\n  ...zCommon,\n  kind: z.literal(\"timeseries\"),\n  chartType: zLegacyChartType,\n  interval: zReportInterval,\n  events: z\n    .array(z.object({ name: z.string().min(1).max(200) }))\n    .min(1)\n    .max(20),\n  breakdowns: z.array(z.string().min(1).max(200)).max(5).default([]),\n  comparePrevious: z.boolean().default(false),\n});\n\nexport const zFunnelReportSpec = z.object({\n  ...zCommon,\n  kind: z.literal(\"funnel\"),\n  steps: z.array(z.string().min(1).max(200)).min(2).max(10),\n  windowSeconds: z.number().int().min(60).max(2_592_000).default(86_400),\n});\n\nexport const zRetentionReportSpec = z.object({\n  ...zCommon,\n  kind: z.literal(\"retention\"),\n  interval: z.enum([\"day\", \"week\", \"month\"]).default(\"day\"),\n  periods: z.number().int().min(1).max(30).default(7),\n  startEvent: z.string().min(1).max(200).optional(),\n  returnEvent: z.string().min(1).max(200).optional(),\n  retentionType: z.enum([\"bounded\", \"unbounded\"]).default(\"bounded\"),\n  cohortMode: z.enum([\"first-ever\", \"first-in-window\"]).default(\"first-ever\"),\n});\n\nexport const zPathReportSpec = z.object({\n  ...zCommon,\n  kind: z.literal(\"path\"),\n  limit: z.number().int().min(1).max(100).default(30),\n  startPage: z.string().max(2_000).optional(),\n  endPage: z.string().max(2_000).optional(),\n});\n\nexport const zReportSpec = z.discriminatedUnion(\"kind\", [\n  zTimeseriesReportSpec,\n  zFunnelReportSpec,\n  zRetentionReportSpec,\n  zPathReportSpec,\n]);\n\nexport type ReportSpec = z.infer<typeof zReportSpec>;\nexport type TimeseriesReportSpec = z.infer<typeof zTimeseriesReportSpec>;\n\n/** Convert a pre-ReportSpec row into the canonical v1 representation. */\nexport function legacyReportToSpec(input: {\n  chartType: z.infer<typeof zLegacyChartType>;\n  interval: z.infer<typeof zReportInterval>;\n  range: string;\n  events: unknown;\n  breakdowns: unknown;\n}): TimeseriesReportSpec {\n  const events = z.array(z.object({ name: z.string().min(1).max(200) })).safeParse(input.events);\n  const breakdowns = z.array(z.string().min(1).max(200)).safeParse(input.breakdowns);\n  return zTimeseriesReportSpec.parse({\n    version: REPORT_SPEC_VERSION,\n    kind: \"timeseries\",\n    chartType: input.chartType,\n    interval: input.interval,\n    range: input.range,\n    events: events.success && events.data.length > 0 ? events.data : [{ name: \"$pageview\" }],\n    breakdowns: breakdowns.success ? breakdowns.data : [],\n  });\n}\n"]}