catence 0.0.0 → 0.1.0

package/dist/contracts/staging.d.ts

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+export declare const PROVIDERS: readonly ["intervals", "garmin", "strava"];
+export type Provider = (typeof PROVIDERS)[number];
+export declare const STAGING_SCHEMA_VERSION = 1;
+export declare const rawObjectSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"raw_object">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    endpoint: z.ZodString;
+    remoteId: z.ZodNullable<z.ZodString>;
+    fetchedAt: z.ZodString;
+    contentHash: z.ZodString;
+    contentType: z.ZodString;
+    relativePath: z.ZodString;
+    scope: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const runManifestSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"run_manifest">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    runId: z.ZodString;
+    fromDate: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export declare const sourceEntitySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"source_entity">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    entityType: z.ZodString;
+    remoteId: z.ZodString;
+    parentRemoteId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    occurredOn: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    sourceUpdatedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    rawObjectHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    extension: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const streamManifestSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"stream_manifest">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    activityRemoteId: z.ZodString;
+    relativePath: z.ZodString;
+    contentHash: z.ZodString;
+    rowCount: z.ZodNumber;
+    startAt: z.ZodNullable<z.ZodString>;
+    endAt: z.ZodNullable<z.ZodString>;
+    columns: z.ZodArray<z.ZodString>;
+    rawObjectHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const activitySyncStateSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"activity_sync_state">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    activityRemoteId: z.ZodString;
+    summaryHash: z.ZodString;
+    detailsFetched: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const extractionErrorSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"extraction_error">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    endpoint: z.ZodString;
+    remoteId: z.ZodNullable<z.ZodString>;
+    message: z.ZodString;
+    retryable: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const stagingRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"run_manifest">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    runId: z.ZodString;
+    fromDate: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"raw_object">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    endpoint: z.ZodString;
+    remoteId: z.ZodNullable<z.ZodString>;
+    fetchedAt: z.ZodString;
+    contentHash: z.ZodString;
+    contentType: z.ZodString;
+    relativePath: z.ZodString;
+    scope: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"source_entity">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    entityType: z.ZodString;
+    remoteId: z.ZodString;
+    parentRemoteId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    occurredOn: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    sourceUpdatedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    rawObjectHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    extension: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"stream_manifest">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    activityRemoteId: z.ZodString;
+    relativePath: z.ZodString;
+    contentHash: z.ZodString;
+    rowCount: z.ZodNumber;
+    startAt: z.ZodNullable<z.ZodString>;
+    endAt: z.ZodNullable<z.ZodString>;
+    columns: z.ZodArray<z.ZodString>;
+    rawObjectHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"activity_sync_state">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    activityRemoteId: z.ZodString;
+    summaryHash: z.ZodString;
+    detailsFetched: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"extraction_error">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    endpoint: z.ZodString;
+    remoteId: z.ZodNullable<z.ZodString>;
+    message: z.ZodString;
+    retryable: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>], "kind">;
+export type StagingRecord = z.infer<typeof stagingRecordSchema>;
+export type SourceEntity = z.infer<typeof sourceEntitySchema>;
+export type EndpointSpec = {
+    readonly provider: Provider;
+    readonly name: string;
+    readonly scope: 'singleton' | 'date_range' | 'activity' | 'collection' | 'child';
+    readonly entityType: string;
+    readonly readOnly: true;
+    readonly pagination: 'none' | 'offset' | 'provider';
+};

package/dist/contracts/staging.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+export const PROVIDERS = ['intervals', 'garmin', 'strava'];
+export const STAGING_SCHEMA_VERSION = 1;
+export const rawObjectSchema = z.object({
+    kind: z.literal('raw_object'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    endpoint: z.string().min(1), remoteId: z.string().nullable(), fetchedAt: z.string().datetime(),
+    contentHash: z.string().length(64), contentType: z.string().min(1), relativePath: z.string().min(1),
+    scope: z.record(z.string(), z.unknown()).default({}),
+});
+export const runManifestSchema = z.object({
+    kind: z.literal('run_manifest'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    runId: z.string().uuid(), fromDate: z.string().date(), createdAt: z.string().datetime(),
+});
+export const sourceEntitySchema = z.object({
+    kind: z.literal('source_entity'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    entityType: z.string().min(1), remoteId: z.string().min(1), parentRemoteId: z.string().nullable().default(null),
+    occurredOn: z.string().nullable().default(null), sourceUpdatedAt: z.string().nullable().default(null),
+    rawObjectHash: z.string().length(64).nullable().default(null), payload: z.record(z.string(), z.unknown()),
+    extension: z.record(z.string(), z.unknown()).default({}),
+});
+export const streamManifestSchema = z.object({
+    kind: z.literal('stream_manifest'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    activityRemoteId: z.string().min(1), relativePath: z.string().min(1), contentHash: z.string().length(64),
+    rowCount: z.number().int().nonnegative(), startAt: z.string().nullable(), endAt: z.string().nullable(),
+    columns: z.array(z.string()), rawObjectHash: z.string().length(64).nullable().default(null),
+});
+export const activitySyncStateSchema = z.object({
+    kind: z.literal('activity_sync_state'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    activityRemoteId: z.string().min(1), summaryHash: z.string().length(64), detailsFetched: z.boolean(),
+});
+export const extractionErrorSchema = z.object({
+    kind: z.literal('extraction_error'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    endpoint: z.string().min(1), remoteId: z.string().nullable(), message: z.string().min(1), retryable: z.boolean().default(true),
+});
+export const stagingRecordSchema = z.discriminatedUnion('kind', [runManifestSchema, rawObjectSchema, sourceEntitySchema, streamManifestSchema, activitySyncStateSchema, extractionErrorSchema]);
+//# sourceMappingURL=staging.js.map

package/dist/contracts/storage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Storage boundary used by Catence core. Implementations may use DuckDB or a
+ * test double, but core logic does not depend on a database driver.
+ */
+export type QueryValues = Record<string, unknown>;
+export type QueryBindings = QueryValues | unknown[];
+export interface ReadDataStore {
+    close(): Promise<void>;
+    rows<T extends Record<string, unknown>>(sql: string, values?: QueryBindings): Promise<T[]>;
+    tableNames(query: string): Promise<string[]>;
+    interrupt(): void;
+}
+export interface WriteDataStore extends ReadDataStore {
+    run(sql: string, values?: QueryBindings): Promise<void>;
+}

package/dist/contracts/storage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage.js.map

package/dist/core/dashboard/snapshot.d.ts

@@ -0,0 +1,16 @@
+import type { ReadOnlyRepository } from '../query/repository.js';
+export type DashboardOptions = {
+    endDate: string;
+    days: number;
+};
+/**
+ * Fixed dashboard facts for the local Console.
+ *
+ * The service deliberately reads Catence's existing canonical projections
+ * instead of adding a visualization-specific store or materialized mirror.
+ */
+export declare class DashboardSnapshotService {
+    private readonly repository;
+    constructor(repository: ReadOnlyRepository);
+    snapshot(options: DashboardOptions): Promise<Record<string, unknown>>;
+}

package/dist/core/dashboard/snapshot.js

@@ -0,0 +1,65 @@
+function subtractDays(date, days) {
+    const value = new Date(`${date}T00:00:00.000Z`);
+    value.setUTCDate(value.getUTCDate() - days);
+    return value.toISOString().slice(0, 10);
+}
+/**
+ * Fixed dashboard facts for the local Console.
+ *
+ * The service deliberately reads Catence's existing canonical projections
+ * instead of adding a visualization-specific store or materialized mirror.
+ */
+export class DashboardSnapshotService {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async snapshot(options) {
+        const startDate = subtractDays(options.endDate, options.days - 1);
+        // DuckDB's native Node binding shares statement state on one connection.
+        // Keep dashboard reads sequential just like the existing status service.
+        const health = await this.repository.rows(`
+        SELECT cast(metric_date AS VARCHAR) AS metric_date, provider,
+          resting_hr_bpm, hrv_ms, sleep_seconds, sleep_score, stress, body_battery, readiness, steps
+        FROM daily_health
+        WHERE metric_date BETWEEN $startDate AND $endDate
+        ORDER BY metric_date ASC
+      `, { startDate, endDate: options.endDate });
+        const weeklyTraining = await this.repository.rows(`
+        SELECT cast(cast(date_trunc('week', started_at_utc) AS DATE) AS VARCHAR) AS week_start,
+          count(*)::INTEGER AS activity_count,
+          sum(distance_m) AS distance_m,
+          sum(moving_s) AS moving_s,
+          sum(elevation_gain_m) AS elevation_gain_m,
+          sum(training_load) AS training_load
+        FROM canonical_activity_training
+        WHERE cast(started_at_utc AS DATE) BETWEEN $startDate AND $endDate
+        GROUP BY week_start
+        ORDER BY week_start ASC
+      `, { startDate, endDate: options.endDate });
+        const recentActivities = await this.repository.rows(`
+        SELECT activity_id, cast(started_at_utc AS VARCHAR) AS started_at_utc, sport, name,
+          distance_m, moving_s, elevation_gain_m, training_load, provider
+        FROM canonical_activity_training
+        WHERE cast(started_at_utc AS DATE) <= $endDate
+        ORDER BY started_at_utc DESC
+        LIMIT 12
+      `, { endDate: options.endDate });
+        const status = await this.repository.status();
+        const coverage = await this.repository.coverage();
+        return {
+            generatedAt: new Date().toISOString(),
+            period: { startDate, endDate: options.endDate, days: options.days },
+            health,
+            training: { weeks: weeklyTraining },
+            activities: recentActivities,
+            status,
+            coverage,
+            caveats: [
+                'Dashboard values are read from Catence canonical daily-health and activity projections.',
+                'Missing metrics or periods are returned as null or absent rows and are never estimated for visualization.',
+            ],
+        };
+    }
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/core/query/activity-discovery.d.ts

@@ -0,0 +1,21 @@
+import { ReadOnlyRepository } from './repository.js';
+export type FindActivitiesRequest = {
+    sports?: string[];
+    distanceKm?: [number, number];
+    nameContains?: string[];
+    startDate?: string;
+    endDate?: string;
+    sort?: 'date_desc' | 'date_asc';
+    limit?: number;
+    cursor?: string;
+};
+/**
+ * Finds one canonical source-backed activity per logical activity. Race
+ * classification is transparent heuristics, not a claim that a provider
+ * recorded an event as a race.
+ */
+export declare class ActivityDiscoveryService {
+    private readonly repository;
+    constructor(repository: ReadOnlyRepository);
+    findActivities(request?: FindActivitiesRequest): Promise<Record<string, unknown>>;
+}

package/dist/core/query/activity-discovery.js

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { QueryValidationError } from './catalog.js';
+import { jsonSafe } from './repository.js';
+function hash(request) {
+    return createHash('sha256').update(JSON.stringify(request)).digest('base64url');
+}
+function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor)).toString('base64url');
+}
+function decodeCursor(cursor, expectedHash) {
+    try {
+        const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (!Number.isInteger(decoded.offset) || decoded.offset < 0 || decoded.hash !== expectedHash)
+            throw new Error();
+        return decoded;
+    }
+    catch {
+        throw new QueryValidationError('Invalid or mismatched cursor. Start the activity search again.');
+    }
+}
+function raceSignals(row, requestedDistance) {
+    const name = row.name?.toLowerCase() ?? '';
+    const nameSuggestsRace = /\b(race|marathon|half[ -]?marathon|media(?:[ -]?marat[oó]n)?|corrida|competition|10k|5k|hm)\b/i.test(name);
+    const distanceKm = row.distance_m === null ? null : row.distance_m / 1_000;
+    const uninterrupted = row.moving_s !== null && row.elapsed_s !== null && row.moving_s > 0
+        ? { ratio: row.moving_s / row.elapsed_s, likely: row.elapsed_s - row.moving_s <= 180 || row.moving_s / row.elapsed_s >= 0.97 }
+        : { ratio: null, likely: false };
+    const distanceMatchesRequestedRange = Boolean(distanceKm !== null && requestedDistance && distanceKm >= requestedDistance[0] && distanceKm <= requestedDistance[1]);
+    const hasHeartRate = row.avg_hr !== null || row.max_hr !== null;
+    const hasTrainingLoad = row.training_load !== null;
+    const likelyRace = nameSuggestsRace || (distanceMatchesRequestedRange && uninterrupted.likely && hasHeartRate && hasTrainingLoad);
+    return {
+        likelyRace,
+        nameSuggestsRace,
+        distanceMatchesRequestedRange,
+        uninterruptedMovingTime: uninterrupted,
+        heartRateAvailable: hasHeartRate,
+        trainingLoadAvailable: hasTrainingLoad,
+    };
+}
+/**
+ * Finds one canonical source-backed activity per logical activity. Race
+ * classification is transparent heuristics, not a claim that a provider
+ * recorded an event as a race.
+ */
+export class ActivityDiscoveryService {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async findActivities(request = {}) {
+        const sports = [...new Set((request.sports ?? []).map((sport) => sport.trim()).filter(Boolean))];
+        const names = [...new Set((request.nameContains ?? []).map((name) => name.trim()).filter(Boolean))];
+        if (sports.length > 12 || names.length > 12)
+            throw new QueryValidationError('sports and nameContains each permit at most 12 values.');
+        if (request.distanceKm && (!Number.isFinite(request.distanceKm[0]) || !Number.isFinite(request.distanceKm[1]) || request.distanceKm[0] < 0 || request.distanceKm[0] > request.distanceKm[1])) {
+            throw new QueryValidationError('distanceKm must contain an ascending, non-negative [minimum, maximum] range.');
+        }
+        const limit = Math.min(Math.max(request.limit ?? 50, 1), 100);
+        const { cursor: ignoredCursor, limit: ignoredLimit, ...fingerprintRequest } = request;
+        void ignoredCursor;
+        void ignoredLimit;
+        const fingerprint = hash(fingerprintRequest);
+        const offset = request.cursor ? decodeCursor(request.cursor, fingerprint).offset : 0;
+        const values = {};
+        const clauses = [];
+        if (sports.length) {
+            const placeholders = sports.map((sport, index) => {
+                const key = `sport${index}`;
+                values[key] = sport;
+                return `lower(activity.sport) = lower($${key})`;
+            });
+            clauses.push(`(${placeholders.join(' OR ')})`);
+        }
+        if (request.distanceKm) {
+            values.minDistanceM = request.distanceKm[0] * 1_000;
+            values.maxDistanceM = request.distanceKm[1] * 1_000;
+            clauses.push('summary.distance_m BETWEEN $minDistanceM AND $maxDistanceM');
+        }
+        if (names.length) {
+            const placeholders = names.map((name, index) => {
+                const key = `name${index}`;
+                values[key] = name;
+                return `activity.name ILIKE '%' || $${key} || '%'`;
+            });
+            clauses.push(`(${placeholders.join(' OR ')})`);
+        }
+        if (request.startDate) {
+            values.startDate = request.startDate;
+            clauses.push('activity.started_at_utc >= cast($startDate AS TIMESTAMPTZ)');
+        }
+        if (request.endDate) {
+            values.endDate = `${request.endDate}T23:59:59.999Z`;
+            clauses.push('activity.started_at_utc <= cast($endDate AS TIMESTAMPTZ)');
+        }
+        const direction = request.sort === 'date_asc' ? 'ASC' : 'DESC';
+        const base = `
+      SELECT activity.activity_id, source.activity_source_id, source.provider,
+        cast(activity.started_at_utc AS VARCHAR) AS started_at_utc, activity.sport, activity.name,
+        summary.distance_m, summary.moving_s, summary.elapsed_s, summary.avg_hr, summary.max_hr,
+        coalesce(summary.training_load, canonical.intervals_training_load) AS training_load, activity.link_state
+      FROM activities AS activity
+      JOIN activity_sources AS source USING (activity_id)
+      LEFT JOIN activity_summaries AS summary USING (activity_source_id)
+      LEFT JOIN canonical_activity_training AS canonical ON canonical.activity_id = activity.activity_id
+      WHERE source.activity_source_id = canonical.activity_source_id
+        ${clauses.length ? `AND ${clauses.join(' AND ')}` : ''}
+    `;
+        // canonical_activity_training supplies the same canonical-source rule used
+        // by reports, so linked Garmin/Intervals duplicates appear once.
+        const total = await this.repository.rows(`SELECT count(*) AS total_rows FROM (${base}) AS matches`, values);
+        const totalRows = Number(total[0]?.total_rows ?? 0);
+        values.limit = limit;
+        values.offset = offset;
+        const rows = await this.repository.rows(`${base} ORDER BY started_at_utc ${direction}, activity_source_id ASC LIMIT $limit OFFSET $offset`, values);
+        const returnedRows = rows.length;
+        const truncated = offset + returnedRows < totalRows;
+        return jsonSafe({
+            returnedRows,
+            totalRows,
+            truncated,
+            nextCursor: truncated ? encodeCursor({ hash: fingerprint, offset: offset + returnedRows }) : undefined,
+            data: rows.map((row) => ({ ...row, raceSignals: raceSignals(row, request.distanceKm) })),
+            provenance: { relations: ['activities', 'activity_sources', 'activity_summaries', 'canonical_activity_training'], canonicalSource: true },
+            query: { sports, distanceKm: request.distanceKm, nameContains: names, startDate: request.startDate, endDate: request.endDate, sort: request.sort ?? 'date_desc', limit },
+            caveats: [
+                'likelyRace is a transparent heuristic based on name, distance, uninterrupted moving time, heart-rate availability, and training-load availability; it is not provider-confirmed race metadata.',
+                ...(truncated ? ['Results are incomplete. Do not draw exhaustive conclusions; retrieve remaining pages with nextCursor or narrow the search.'] : []),
+            ],
+        });
+    }
+}
+//# sourceMappingURL=activity-discovery.js.map

package/dist/core/query/analytics.d.ts

@@ -0,0 +1,59 @@
+import type { QueryValues } from '../../contracts/storage.js';
+import { type DatasetDefinition } from './catalog.js';
+import { ReadOnlyRepository } from './repository.js';
+export type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'between' | 'contains';
+export type DataFilter = {
+    column: string;
+    op: FilterOperator;
+    value: unknown;
+};
+export type Resolution = 'raw' | '1m' | '5m' | '15m' | '1h' | 'day' | 'week' | 'auto';
+export type SeriesRequest = {
+    dataset: string;
+    metrics: string[];
+    filters?: DataFilter[];
+    startDate?: string;
+    endDate?: string;
+    activityId?: string;
+    resolution?: Resolution;
+    cursor?: string;
+    pageSize?: number;
+};
+export declare function compileFilters(dataset: DatasetDefinition, filters?: DataFilter[], startDate?: string, endDate?: string, activityId?: string): {
+    where: string;
+    values: QueryValues;
+};
+export declare class AnalyticsService {
+    private readonly repository;
+    constructor(repository: ReadOnlyRepository);
+    readSeries(request: SeriesRequest): Promise<Record<string, unknown>>;
+    aggregate(request: {
+        dataset: string;
+        metrics: Array<{
+            column: string;
+            operation: 'count' | 'sum' | 'mean' | 'min' | 'max' | 'percentile';
+            percentile?: number;
+            as?: string;
+        }>;
+        dimensions?: string[];
+        filters?: DataFilter[];
+        startDate?: string;
+        endDate?: string;
+        timeBucket?: 'day' | 'week' | 'month';
+        orderBy?: {
+            column: string;
+            direction?: 'asc' | 'desc';
+        };
+        limit?: number;
+    }): Promise<Record<string, unknown>>;
+    analyzeSeries(request: SeriesRequest & {
+        analysis: 'rolling_mean' | 'rolling_median' | 'baseline_change' | 'z_score' | 'pearson' | 'spearman' | 'seasonal_comparison' | 'linear_trend' | 'theil_sen_trend';
+        compareMetric?: string;
+        window?: number;
+    }): Promise<Record<string, unknown>>;
+    fitSeriesModel(request: SeriesRequest & {
+        model: 'ols_linear' | 'theil_sen_linear' | 'polynomial_2' | 'polynomial_3';
+        xMetric?: string;
+        yMetric?: string;
+    }): Promise<Record<string, unknown>>;
+}