@reopt-ai/data-contract 0.1.0

package/dist/query.d.cts

@@ -0,0 +1,374 @@
+import { z } from 'zod';
+export { zDate, zInstant } from './index.cjs';
+
+/**
+ * `POST /api/v1/query/*` — the read contract.
+ *
+ * Server credentials, project-scoped: the authenticated client's projectId must
+ * equal the `projectId` in the body, or the request is refused. Reads are POSTs
+ * because the inputs nest (funnel steps, channel filters) and would not survive
+ * a query string; consumers cache on their own side, so HTTP cache semantics
+ * buy nothing here.
+ *
+ * Response shapes mirror the existing dashboard computations exactly — this
+ * plane re-exposes them, it does not add new math.
+ */
+
+/** Bucket width for a time series. */
+declare const zGranularity: z.ZodEnum<{
+    hour: "hour";
+    day: "day";
+    week: "week";
+    month: "month";
+}>;
+type Granularity = z.infer<typeof zGranularity>;
+/**
+ * IANA time zone name, e.g. `Asia/Seoul`. Decides two things at once: where a
+ * calendar day starts, and therefore which bucket an event falls in.
+ *
+ * A Korean brand reading "23 Aug: 120 visits" means 23 Aug in Seoul. Computed
+ * in UTC, that headline silently covers 23 Aug 09:00 through 24 Aug 09:00 —
+ * wrong by nine hours in a way nothing on the page reveals.
+ *
+ * Validated against the runtime's own zone database rather than a regex, so an
+ * unknown name fails here with a clear message instead of deep inside a query.
+ */
+declare const zTimezone: z.ZodString;
+declare function isValidTimeZone(value: string): boolean;
+/**
+ * Acquisition-channel filter. Every field is a set — an event matches when its
+ * value is in the set; omitted fields do not constrain. Mirrors the dashboard's
+ * `channelFilterSchema` field-for-field.
+ */
+declare const zChannelFilter: z.ZodOptional<z.ZodObject<{
+    referrerTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    channelTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    utmSources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    utmMediums: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    utmCampaigns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>>;
+type ChannelFilter = z.infer<typeof zChannelFilter>;
+/**
+ * Staleness is reported as two independent numbers, never as one sum, because
+ * the two have different remedies: a stale cache resolves itself at the next
+ * TTL, while ingest lag means the read model is genuinely behind and the right
+ * response is an "aggregating" badge, not a refresh.
+ */
+declare const zQueryMeta: z.ZodObject<{
+    projectId: z.ZodString;
+    computedAt: z.ZodString;
+    cacheAgeSeconds: z.ZodNumber;
+    ingestLagSeconds: z.ZodNumber;
+    cached: z.ZodBoolean;
+    timezone: z.ZodString;
+    requestId: z.ZodString;
+}, z.core.$strip>;
+type QueryMeta = z.infer<typeof zQueryMeta>;
+/** Every query response is `{ data, meta }`. */
+declare function zQueryEnvelope<T extends z.ZodTypeAny>(data: T): z.ZodObject<{
+    data: T;
+    meta: z.ZodObject<{
+        projectId: z.ZodString;
+        computedAt: z.ZodString;
+        cacheAgeSeconds: z.ZodNumber;
+        ingestLagSeconds: z.ZodNumber;
+        cached: z.ZodBoolean;
+        timezone: z.ZodString;
+        requestId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * v1 breaks down by `properties` JSON keys only. Built-in columns
+ * (country / os / browser / utm_*) have a totals breakdown in the backend but
+ * no *time series* variant, and this plane does not add new computations.
+ */
+declare const zTimeseriesBreakdown: z.ZodObject<{
+    kind: z.ZodLiteral<"property">;
+    key: z.ZodString;
+    topN: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type TimeseriesBreakdown = z.infer<typeof zTimeseriesBreakdown>;
+declare const zEventsTimeseriesInput: z.ZodObject<{
+    projectId: z.ZodString;
+    startDate: z.ZodString;
+    endDate: z.ZodString;
+    granularity: z.ZodDefault<z.ZodEnum<{
+        hour: "hour";
+        day: "day";
+        week: "week";
+        month: "month";
+    }>>;
+    eventName: z.ZodOptional<z.ZodString>;
+    breakdown: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"property">;
+        key: z.ZodString;
+        topN: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    segmentId: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type EventsTimeseriesInput = z.input<typeof zEventsTimeseriesInput>;
+declare const zTimeseriesPoint: z.ZodObject<{
+    date: z.ZodString;
+    count: z.ZodNumber;
+}, z.core.$strip>;
+type TimeseriesPoint = z.infer<typeof zTimeseriesPoint>;
+declare const zEventsTimeseriesData: z.ZodObject<{
+    granularity: z.ZodEnum<{
+        hour: "hour";
+        day: "day";
+        week: "week";
+        month: "month";
+    }>;
+    timezone: z.ZodString;
+    series: z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+    breakdown: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        points: z.ZodArray<z.ZodObject<{
+            date: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type EventsTimeseriesData = z.infer<typeof zEventsTimeseriesData>;
+declare const zEventsTimeseriesResponse: z.ZodObject<{
+    data: z.ZodObject<{
+        granularity: z.ZodEnum<{
+            hour: "hour";
+            day: "day";
+            week: "week";
+            month: "month";
+        }>;
+        timezone: z.ZodString;
+        series: z.ZodArray<z.ZodObject<{
+            date: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
+        breakdown: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            points: z.ZodArray<z.ZodObject<{
+                date: z.ZodString;
+                count: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    meta: z.ZodObject<{
+        projectId: z.ZodString;
+        computedAt: z.ZodString;
+        cacheAgeSeconds: z.ZodNumber;
+        ingestLagSeconds: z.ZodNumber;
+        cached: z.ZodBoolean;
+        timezone: z.ZodString;
+        requestId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type EventsTimeseriesResponse = z.infer<typeof zEventsTimeseriesResponse>;
+declare const zFunnelInput: z.ZodObject<{
+    projectId: z.ZodString;
+    steps: z.ZodArray<z.ZodString>;
+    startDate: z.ZodString;
+    endDate: z.ZodString;
+    windowSeconds: z.ZodDefault<z.ZodNumber>;
+    segmentId: z.ZodOptional<z.ZodString>;
+    channelFilter: z.ZodOptional<z.ZodObject<{
+        referrerTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        channelTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        utmSources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        utmMediums: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        utmCampaigns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    timezone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type FunnelInput = z.input<typeof zFunnelInput>;
+declare const zFunnelStep: z.ZodObject<{
+    step: z.ZodNumber;
+    name: z.ZodString;
+    users: z.ZodNumber;
+    conversionRate: z.ZodNumber;
+    dropoffRate: z.ZodNumber;
+    dropoffUsers: z.ZodNumber;
+}, z.core.$strip>;
+declare const zFunnelData: z.ZodObject<{
+    steps: z.ZodArray<z.ZodObject<{
+        step: z.ZodNumber;
+        name: z.ZodString;
+        users: z.ZodNumber;
+        conversionRate: z.ZodNumber;
+        dropoffRate: z.ZodNumber;
+        dropoffUsers: z.ZodNumber;
+    }, z.core.$strip>>;
+    totalUsers: z.ZodNumber;
+    overallConversionRate: z.ZodNumber;
+}, z.core.$strip>;
+type FunnelData = z.infer<typeof zFunnelData>;
+declare const zFunnelResponse: z.ZodObject<{
+    data: z.ZodObject<{
+        steps: z.ZodArray<z.ZodObject<{
+            step: z.ZodNumber;
+            name: z.ZodString;
+            users: z.ZodNumber;
+            conversionRate: z.ZodNumber;
+            dropoffRate: z.ZodNumber;
+            dropoffUsers: z.ZodNumber;
+        }, z.core.$strip>>;
+        totalUsers: z.ZodNumber;
+        overallConversionRate: z.ZodNumber;
+    }, z.core.$strip>;
+    meta: z.ZodObject<{
+        projectId: z.ZodString;
+        computedAt: z.ZodString;
+        cacheAgeSeconds: z.ZodNumber;
+        ingestLagSeconds: z.ZodNumber;
+        cached: z.ZodBoolean;
+        timezone: z.ZodString;
+        requestId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type FunnelResponse = z.infer<typeof zFunnelResponse>;
+declare const zRetentionInterval: z.ZodEnum<{
+    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<{
+        day: "day";
+        week: "week";
+        month: "month";
+    }>>;
+    periods: z.ZodDefault<z.ZodNumber>;
+    startEvent: z.ZodOptional<z.ZodString>;
+    returnEvent: z.ZodOptional<z.ZodString>;
+    retentionType: z.ZodDefault<z.ZodEnum<{
+        bounded: "bounded";
+        unbounded: "unbounded";
+    }>>;
+    cohortMode: z.ZodDefault<z.ZodEnum<{
+        "first-ever": "first-ever";
+        "first-in-window": "first-in-window";
+    }>>;
+    segmentId: z.ZodOptional<z.ZodString>;
+    channelFilter: z.ZodOptional<z.ZodObject<{
+        referrerTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        channelTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        utmSources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        utmMediums: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        utmCampaigns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    timezone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type RetentionInput = z.input<typeof zRetentionInput>;
+declare const zRetentionCell: z.ZodObject<{
+    period: z.ZodNumber;
+    users: z.ZodNumber;
+    rate: z.ZodNumber;
+}, z.core.$strip>;
+declare const zRetentionData: z.ZodObject<{
+    matrix: z.ZodArray<z.ZodObject<{
+        cohortDate: z.ZodString;
+        cohortSize: z.ZodNumber;
+        retention: z.ZodArray<z.ZodObject<{
+            period: z.ZodNumber;
+            users: z.ZodNumber;
+            rate: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    averageRetention: z.ZodArray<z.ZodObject<{
+        period: z.ZodNumber;
+        rate: z.ZodNumber;
+    }, z.core.$strip>>;
+    interval: z.ZodEnum<{
+        day: "day";
+        week: "week";
+        month: "month";
+    }>;
+    periods: z.ZodNumber;
+    retentionType: z.ZodEnum<{
+        bounded: "bounded";
+        unbounded: "unbounded";
+    }>;
+    timezone: z.ZodString;
+}, z.core.$strip>;
+type RetentionData = z.infer<typeof zRetentionData>;
+declare const zRetentionResponse: z.ZodObject<{
+    data: z.ZodObject<{
+        matrix: z.ZodArray<z.ZodObject<{
+            cohortDate: z.ZodString;
+            cohortSize: z.ZodNumber;
+            retention: z.ZodArray<z.ZodObject<{
+                period: z.ZodNumber;
+                users: z.ZodNumber;
+                rate: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        averageRetention: z.ZodArray<z.ZodObject<{
+            period: z.ZodNumber;
+            rate: z.ZodNumber;
+        }, z.core.$strip>>;
+        interval: z.ZodEnum<{
+            day: "day";
+            week: "week";
+            month: "month";
+        }>;
+        periods: z.ZodNumber;
+        retentionType: z.ZodEnum<{
+            bounded: "bounded";
+            unbounded: "unbounded";
+        }>;
+        timezone: z.ZodString;
+    }, z.core.$strip>;
+    meta: z.ZodObject<{
+        projectId: z.ZodString;
+        computedAt: z.ZodString;
+        cacheAgeSeconds: z.ZodNumber;
+        ingestLagSeconds: z.ZodNumber;
+        cached: z.ZodBoolean;
+        timezone: z.ZodString;
+        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"];
+declare const zQueryErrorCode: z.ZodEnum<{
+    unauthorized: "unauthorized";
+    project_scope_mismatch: "project_scope_mismatch";
+    query_scope_missing: "query_scope_missing";
+    validation_failed: "validation_failed";
+    unsupported_combination: "unsupported_combination";
+    rate_limited: "rate_limited";
+    query_timeout: "query_timeout";
+    internal_error: "internal_error";
+}>;
+type QueryErrorCode = z.infer<typeof zQueryErrorCode>;
+declare const zQueryError: z.ZodObject<{
+    status: z.ZodNumber;
+    code: z.ZodEnum<{
+        unauthorized: "unauthorized";
+        project_scope_mismatch: "project_scope_mismatch";
+        query_scope_missing: "query_scope_missing";
+        validation_failed: "validation_failed";
+        unsupported_combination: "unsupported_combination";
+        rate_limited: "rate_limited";
+        query_timeout: "query_timeout";
+        internal_error: "internal_error";
+    }>;
+    error: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    errors: z.ZodOptional<z.ZodUnknown>;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type QueryError = z.infer<typeof zQueryError>;
+/** Paths, so the client and the route handlers cannot drift apart. */
+declare const QUERY_API_PATHS: {
+    readonly eventsTimeseries: "/api/v1/query/events/timeseries";
+    readonly funnel: "/api/v1/query/funnel";
+    readonly retention: "/api/v1/query/retention";
+};
+
+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 };