@reopt-ai/data-contract 0.3.0 → 0.6.0

package/dist/query.d.cts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 export { zDate, zInstant } from './index.cjs';
+import './version-CC4_BBvq.cjs';
 
 /**
  * `POST /api/v1/query/*` — the read contract.
@@ -16,10 +17,10 @@ export { zDate, zInstant } from './index.cjs';
 
 /** 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 +55,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 +88,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 +115,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,6 +145,7 @@ 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>;
 /**
@@ -129,10 +169,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<{
@@ -151,10 +191,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<{
@@ -173,9 +213,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>;
@@ -195,6 +245,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<{
@@ -235,26 +286,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>;
@@ -276,6 +337,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<{
@@ -298,9 +360,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<{
@@ -326,9 +388,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<{
@@ -341,13 +403,230 @@ 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>;
+/**
+ * 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<{
+    referrer: "referrer";
+    channel: "channel";
+    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<{
+        referrer: "referrer";
+        channel: "channel";
+        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<{
+        referrer: "referrer";
+        channel: "channel";
+        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<{
+            referrer: "referrer";
+            channel: "channel";
+            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";
@@ -385,6 +664,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, zBucketStart, 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 };