catence 0.0.0 → 0.1.0

package/dist/elt/ingestion/importer.js

@@ -0,0 +1,87 @@
+import { createReadStream } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { randomUUID } from 'node:crypto';
+import { stagingRecordSchema } from '../../contracts/staging.js';
+import { importSourceEntity, refreshActivityQuality } from '../normalization/normalizers.js';
+import { normalizeStravaEntity } from '../normalization/segments/strava-normalizer.js';
+import { reconcileActivityLink } from '../normalization/activities/linking.js';
+import { json } from '../storage/sql.js';
+export async function importRecord(database, runId, record) {
+    if (record.kind === 'run_manifest') {
+        if (record.runId !== runId)
+            throw new Error(`Staging manifest run ${record.runId} does not match importer run ${runId}.`);
+        return;
+    }
+    if (record.kind === 'raw_object') {
+        await database.run(`INSERT OR IGNORE INTO raw_objects VALUES
+       ($contentHash, $provider, $endpoint, $remoteId, $fetchedAt, $contentType, $relativePath, $scope, $parserVersion)`, {
+            contentHash: record.contentHash, provider: record.provider, endpoint: record.endpoint, remoteId: record.remoteId,
+            fetchedAt: record.fetchedAt, contentType: record.contentType, relativePath: record.relativePath,
+            scope: json(record.scope), parserVersion: record.schemaVersion,
+        });
+        return;
+    }
+    if (record.kind === 'source_entity') {
+        if (record.provider === 'strava')
+            await normalizeStravaEntity(database, record);
+        else
+            await importSourceEntity(database, record);
+        if (record.entityType === 'activity') {
+            await reconcileActivityLink(database, record.provider + ':' + record.remoteId);
+            const activity = await database.rows('SELECT activity_id FROM activity_sources WHERE activity_source_id = $activitySourceId', { activitySourceId: record.provider + ':' + record.remoteId });
+            if (activity[0]?.activity_id)
+                await refreshActivityQuality(database, activity[0].activity_id);
+        }
+        if (record.provider === 'garmin' && ['activity_detail', 'activity_interval', 'activity_exercise_set'].includes(record.entityType) && record.parentRemoteId) {
+            const activity = await database.rows('SELECT activity_id FROM activity_sources WHERE activity_source_id = $activitySourceId', { activitySourceId: `garmin:${record.parentRemoteId}` });
+            if (activity[0]?.activity_id)
+                await refreshActivityQuality(database, activity[0].activity_id);
+        }
+        return;
+    }
+    if (record.kind === 'stream_manifest') {
+        const activitySourceId = `${record.provider}:${record.activityRemoteId}`;
+        await database.run(`INSERT OR IGNORE INTO stream_manifest VALUES
+       ($provider, $activitySourceId, $contentHash, $relativePath, $rowCount, $startAt, $endAt, $columns, $rawHash)`, {
+            provider: record.provider, activitySourceId, contentHash: record.contentHash, relativePath: record.relativePath,
+            rowCount: record.rowCount, startAt: record.startAt, endAt: record.endAt, columns: json(record.columns), rawHash: record.rawObjectHash,
+        });
+        return;
+    }
+    if (record.kind === 'activity_sync_state') {
+        await database.recordActivitySyncState(record.provider, record.activityRemoteId, record.summaryHash, runId, record.detailsFetched);
+        return;
+    }
+    await database.addError(runId, record.provider, record.endpoint, record.remoteId, record.message, record.retryable);
+}
+export async function importJsonl(database, runId, filePath) {
+    let count = 0;
+    const file = createReadStream(filePath, { encoding: 'utf8' });
+    const lines = createInterface({ input: file, crlfDelay: Infinity });
+    for await (const line of lines) {
+        if (!line.trim())
+            continue;
+        const record = stagingRecordSchema.parse(JSON.parse(line));
+        await importRecord(database, runId, record);
+        count += 1;
+    }
+    return count;
+}
+export async function importSingleStagingFile(database, runId, filePath) {
+    await readFile(filePath, 'utf8');
+    return importJsonl(database, runId, filePath);
+}
+export async function queueWorkItem(database, runId, provider, endpoint, remoteId, scope) {
+    const itemId = randomUUID();
+    await database.run(`INSERT INTO sync_items (item_id, run_id, provider, endpoint, remote_id, scope_json, status)
+     VALUES ($itemId, $runId, $provider, $endpoint, $remoteId, $scope, 'pending')`, { itemId, runId, provider, endpoint, remoteId, scope: json(scope) });
+    return itemId;
+}
+export async function completeWorkItem(database, itemId) {
+    await database.run(`UPDATE sync_items SET status = 'completed', attempts = attempts + 1, completed_at = now() WHERE item_id = $itemId`, { itemId });
+}
+export async function failWorkItem(database, itemId, message) {
+    await database.run(`UPDATE sync_items SET status = 'failed', attempts = attempts + 1, error_message = $message, completed_at = now() WHERE item_id = $itemId`, { itemId, message });
+}
+//# sourceMappingURL=importer.js.map

package/dist/elt/ingestion/providers/intervals.d.ts

@@ -0,0 +1,21 @@
+import type { CatenceDatabase } from '../../storage/database.js';
+import type { CatencePaths } from '../../../contracts/runtime.js';
+export declare class IntervalsExtractor {
+    private readonly database;
+    private readonly paths;
+    private readonly apiKey;
+    private readonly athleteId;
+    private readonly client;
+    constructor(database: CatenceDatabase, paths: CatencePaths, apiKey: string, athleteId: string);
+    sync(runId: string, activityWindow: {
+        fromDate: string;
+        toDate: string;
+    } | null, includeAccount?: boolean): Promise<void>;
+    private captureCollectionChildren;
+    private getCollection;
+    private captureActivity;
+    private capture;
+    private importEntities;
+    private getJson;
+    private getBinary;
+}

package/dist/elt/ingestion/providers/intervals.js

@@ -0,0 +1,224 @@
+import { IntervalsClient } from 'intervals-icu';
+import { randomUUID } from 'node:crypto';
+import { stableJsonHash, storeArtifact, storeJsonArtifact } from '../../storage/artifacts.js';
+import { importRecord, queueWorkItem, completeWorkItem, failWorkItem } from '../importer.js';
+import { intervalsActivityReadEndpoints, intervalsSecondaryReadRegistry, assertReadOnlyRegistry } from './registry.js';
+import { intervalsStreamsToSamples, writeParquetSamples } from '../../streams.js';
+const apiBaseUrl = 'https://intervals.icu/api/v1';
+function asObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function asItems(value) {
+    if (Array.isArray(value))
+        return value.map(asObject);
+    const object = asObject(value);
+    for (const key of ['items', 'data', 'activities', 'events', 'workouts', 'wellness']) {
+        if (Array.isArray(object[key]))
+            return object[key].map(asObject);
+    }
+    return Object.keys(object).length > 0 ? [object] : [];
+}
+function idOf(payload, fallback) {
+    for (const key of ['id', 'activity_id', 'activityId', 'date', 'name']) {
+        const value = payload[key];
+        if (typeof value === 'string' || typeof value === 'number')
+            return String(value);
+    }
+    return fallback;
+}
+function entityDate(payload) {
+    for (const key of ['id', 'date', 'start_date_local', 'start_date', 'updated']) {
+        const value = payload[key];
+        if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value))
+            return value;
+    }
+    return null;
+}
+function basicAuth(apiKey) {
+    return `Basic ${Buffer.from(`API_KEY:${apiKey}`).toString('base64')}`;
+}
+export class IntervalsExtractor {
+    database;
+    paths;
+    apiKey;
+    athleteId;
+    client;
+    constructor(database, paths, apiKey, athleteId) {
+        this.database = database;
+        this.paths = paths;
+        this.apiKey = apiKey;
+        this.athleteId = athleteId;
+        // The typed client is used for provider-compatible authentication and the
+        // primary identity request. Manifest-only calls below intentionally use
+        // the same read-only credentials to cover endpoint families not wrapped by it.
+        this.client = new IntervalsClient({ apiKey, athleteId, maxRetries: 3 });
+    }
+    async sync(runId, activityWindow, includeAccount = true) {
+        assertReadOnlyRegistry();
+        let resolvedAthleteId = this.athleteId;
+        if (includeAccount) {
+            const athlete = await this.capture(runId, 'athlete', null, {}, async () => this.client.athletes.getAthlete());
+            const athletePayload = asObject(athlete);
+            resolvedAthleteId = typeof athletePayload.id === 'string' ? athletePayload.id : this.athleteId;
+            await this.database.insertSourceAccount('intervals', resolvedAthleteId, typeof athletePayload.name === 'string' ? athletePayload.name : null, athletePayload);
+        }
+        for (const endpoint of intervalsSecondaryReadRegistry) {
+            if (endpoint.name === 'athlete')
+                continue;
+            if (!activityWindow)
+                continue;
+            const { fromDate, toDate } = activityWindow;
+            const payload = await this.capture(runId, endpoint.name, null, { fromDate, toDate }, async () => this.getCollection(endpoint.name, resolvedAthleteId, fromDate, toDate));
+            if (payload === undefined)
+                continue;
+            await this.importEntities(endpoint.entityType, endpoint.name, payload, null, runId);
+            if (endpoint.name === 'activities') {
+                for (const activity of asItems(payload)) {
+                    const activityId = idOf(activity, randomUUID());
+                    const summaryHash = stableJsonHash(activity);
+                    // The activity-list payload already contains the Intervals-only
+                    // training calculations. Garmin remains the source of record for
+                    // detail, files, streams, and structured activity data.
+                    await this.database.recordActivitySyncState('intervals', activityId, summaryHash, runId, false);
+                }
+            }
+        }
+    }
+    async captureCollectionChildren(runId, collection, payload, athleteId) {
+        const children = {
+            events: [{ suffix: (id) => `/athlete/${athleteId}/events/${id}`, entityType: 'event' }],
+            workouts: [{ suffix: (id) => `/athlete/${athleteId}/workouts/${id}`, entityType: 'workout' }],
+            folders: [
+                { suffix: (id) => `/athlete/${athleteId}/folders/${id}`, entityType: 'folder' },
+                { suffix: (id) => `/athlete/${athleteId}/folders/${id}/workouts`, entityType: 'workout' },
+                { suffix: (id) => `/athlete/${athleteId}/folders/${id}/shared-with`, entityType: 'folder_share' },
+            ],
+            gear: [
+                { suffix: (id) => `/athlete/${athleteId}/gear/${id}`, entityType: 'gear' },
+                { suffix: (id) => `/athlete/${athleteId}/gear/${id}/reminder`, entityType: 'gear_reminder' },
+            ],
+            routes: [{ suffix: (id) => `/athlete/${athleteId}/routes/${id}`, entityType: 'route' }],
+            sport_settings: [{ suffix: (id) => `/athlete/${athleteId}/sport-settings/${id}`, entityType: 'sport_setting' }],
+            custom_items: [
+                { suffix: (id) => `/athlete/${athleteId}/custom-item/${id}`, entityType: 'custom_item' },
+                { suffix: (id) => `/athlete/${athleteId}/custom-item/${id}/image`, entityType: 'custom_item_image', binary: true },
+            ],
+            chats: [
+                { suffix: (id) => `/chats/${id}`, entityType: 'chat' },
+                { suffix: (id) => `/chats/${id}/messages`, entityType: 'message' },
+            ],
+        };
+        for (const item of asItems(payload)) {
+            const remoteId = idOf(item, 'unknown');
+            for (const child of children[collection] ?? []) {
+                const endpoint = `${collection}_${child.entityType}`;
+                const childPayload = await this.capture(runId, endpoint, remoteId, { parent: collection }, async () => child.binary ? this.getBinary(child.suffix(remoteId)) : this.getJson(child.suffix(remoteId)));
+                if (childPayload === undefined || childPayload instanceof Uint8Array)
+                    continue;
+                await this.importEntities(child.entityType, endpoint, childPayload, remoteId, runId);
+            }
+        }
+    }
+    async getCollection(name, athleteId, fromDate, toDate) {
+        const query = new URLSearchParams({ oldest: fromDate, newest: toDate, resolve: 'true' });
+        const routes = {
+            profile: `/athlete/${athleteId}/profile`, connections: `/athlete/${athleteId}/connections`, sport_settings: `/athlete/${athleteId}/sport-settings`,
+            activities: `/athlete/${athleteId}/activities`, wellness: `/athlete/${athleteId}/wellness`, events: `/athlete/${athleteId}/events`,
+            workouts: `/athlete/${athleteId}/workouts`, folders: `/athlete/${athleteId}/folders`, gear: `/athlete/${athleteId}/gear`, routes: `/athlete/${athleteId}/routes`,
+            custom_items: `/athlete/${athleteId}/custom-item`, fitness: `/athlete/${athleteId}/fitness`, activity_summary: `/athlete/${athleteId}/activity-summary`,
+            power_curves: `/athlete/${athleteId}/power-curves`, pace_curves: `/athlete/${athleteId}/pace-curves`, hr_curves: `/athlete/${athleteId}/hr-curves`,
+            activity_power_curves: `/athlete/${athleteId}/activity-power-curves`, activity_hr_curves: `/athlete/${athleteId}/activity-hr-curves`,
+            weather_config: `/athlete/${athleteId}/weather-config`, weather_forecast: `/athlete/${athleteId}/weather`, chats: `/athlete/${athleteId}/chats`,
+            activity_tags: `/athlete/${athleteId}/activity-tags`, event_tags: `/athlete/${athleteId}/event-tags`, workout_tags: `/athlete/${athleteId}/workout-tags`,
+        };
+        const route = routes[name];
+        if (!route)
+            throw new Error(`Endpoint ${name} is not on the Intervals read-only route map.`);
+        return this.getJson(`${route}?${query.toString()}`);
+    }
+    async captureActivity(runId, activityId, summary) {
+        for (const endpoint of intervalsActivityReadEndpoints) {
+            const payload = await this.capture(runId, `activity_${endpoint}`, activityId, {}, async () => {
+                if (endpoint === 'original_file' || endpoint === 'fit_file' || endpoint === 'gpx_file') {
+                    const route = endpoint === 'original_file' ? `/activity/${activityId}/file` : endpoint === 'fit_file' ? `/activity/${activityId}/fit-file` : `/activity/${activityId}/gpx-file`;
+                    return this.getBinary(route);
+                }
+                const route = endpoint === 'activity' ? `/activity/${activityId}` : `/activity/${activityId}/${endpoint.replaceAll('_', '-')}`;
+                return this.getJson(route);
+            });
+            if (payload === undefined)
+                continue;
+            if (payload instanceof Uint8Array)
+                continue;
+            if (endpoint === 'streams') {
+                const detail = asObject(summary);
+                const samples = intervalsStreamsToSamples(`intervals:${activityId}`, Array.isArray(payload) ? payload.map(asObject) : [], typeof detail.start_date === 'string' ? detail.start_date : null);
+                if (samples.length > 0) {
+                    const parquet = await writeParquetSamples(this.database, this.paths, 'intervals', activityId, typeof detail.start_date_local === 'string' ? detail.start_date_local : new Date().toISOString().slice(0, 10), samples);
+                    await importRecord(this.database, runId, {
+                        kind: 'stream_manifest', schemaVersion: 1, provider: 'intervals', activityRemoteId: activityId,
+                        relativePath: parquet.relativePath, contentHash: parquet.contentHash, rowCount: samples.length,
+                        startAt: samples[0]?.timestamp_utc ?? null, endAt: samples.at(-1)?.timestamp_utc ?? null, columns: parquet.columns, rawObjectHash: null,
+                    });
+                }
+            }
+            if (endpoint === 'intervals') {
+                const intervals = Array.isArray(payload) ? payload : asObject(payload).icu_intervals;
+                if (Array.isArray(intervals))
+                    await this.importEntities('activity_interval', 'activity_intervals', intervals, activityId, runId);
+            }
+            else if (endpoint !== 'streams') {
+                await this.importEntities(`activity_${endpoint}`, `activity_${endpoint}`, payload, activityId, runId);
+            }
+        }
+    }
+    async capture(runId, endpoint, remoteId, scope, action) {
+        const workId = await queueWorkItem(this.database, runId, 'intervals', endpoint, remoteId, scope);
+        try {
+            const value = await action();
+            const artifact = value instanceof Uint8Array
+                ? await storeArtifact(this.paths, 'intervals', endpoint, remoteId, value, endpoint.includes('file') ? 'bin' : 'dat', 'application/octet-stream')
+                : await storeJsonArtifact(this.paths, 'intervals', endpoint, remoteId, value);
+            await importRecord(this.database, runId, {
+                kind: 'raw_object', schemaVersion: 1, provider: 'intervals', endpoint, remoteId, fetchedAt: new Date().toISOString(),
+                contentHash: artifact.contentHash, contentType: artifact.contentType, relativePath: artifact.relativePath, scope,
+            });
+            await completeWorkItem(this.database, workId);
+            return value;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await failWorkItem(this.database, workId, message);
+            await this.database.addError(runId, 'intervals', endpoint, remoteId, message, true);
+            return undefined;
+        }
+    }
+    async importEntities(entityType, endpoint, payload, parentRemoteId, runId) {
+        const artifactHash = (await this.database.rows('SELECT content_hash FROM raw_objects WHERE provider = \'intervals\' AND endpoint = $endpoint AND remote_id IS NOT DISTINCT FROM $remoteId ORDER BY fetched_at DESC LIMIT 1', { endpoint: endpoint.startsWith('activity_') ? endpoint : endpoint, remoteId: parentRemoteId }))[0]?.content_hash ?? null;
+        for (const [index, item] of asItems(payload).entries()) {
+            const remoteId = idOf(item, `${endpoint}:${index}`);
+            const entity = {
+                kind: 'source_entity', schemaVersion: 1, provider: 'intervals', entityType, remoteId, parentRemoteId,
+                occurredOn: entityDate(item), sourceUpdatedAt: typeof item.updated === 'string' ? item.updated : null, rawObjectHash: artifactHash,
+                payload: item, extension: {},
+            };
+            await importRecord(this.database, runId, entity);
+            if (entityType === 'wellness') {
+                await importRecord(this.database, runId, { ...entity, entityType: 'nutrition_day' });
+            }
+        }
+    }
+    async getJson(route) {
+        const response = await fetch(`${apiBaseUrl}${route}`, { headers: { Authorization: basicAuth(this.apiKey), Accept: 'application/json' } });
+        if (!response.ok)
+            throw new Error(`Intervals ${route} failed with HTTP ${response.status}`);
+        return response.json();
+    }
+    async getBinary(route) {
+        const response = await fetch(`${apiBaseUrl}${route}`, { headers: { Authorization: basicAuth(this.apiKey) } });
+        if (!response.ok)
+            throw new Error(`Intervals ${route} failed with HTTP ${response.status}`);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+}
+//# sourceMappingURL=intervals.js.map

package/dist/elt/ingestion/providers/registry.d.ts

@@ -0,0 +1,19 @@
+import type { EndpointSpec } from '../../../contracts/staging.js';
+/**
+ * The only provider operations an extractor may execute. Entries intentionally
+ * describe data families, not mutations: extraction code rejects every route
+ * outside this registry.
+ */
+export declare const intervalsReadRegistry: readonly EndpointSpec[];
+/**
+ * Intervals is an analysis companion to Garmin: its activity-list payload
+ * supplies the separately named training calculations without duplicating
+ * Garmin's activity detail, files, streams, or account data.
+ */
+export declare const intervalsSecondaryReadRegistry: EndpointSpec[];
+export declare const intervalsActivityReadEndpoints: readonly ["activity", "streams", "intervals", "map", "weather", "weather_summary", "best_efforts", "power_curve", "pace_curve", "hr_curve", "power_vs_hr", "hr_load_model", "segments", "messages", "original_file", "fit_file", "gpx_file"];
+/** Read-only methods exposed by python-garminconnect, grouped for manifest tests and worker dispatch. */
+export declare const garminReadRegistry: readonly EndpointSpec[];
+export declare const stravaReadRegistry: readonly EndpointSpec[];
+export declare const allReadOnlyEndpoints: readonly EndpointSpec[];
+export declare function assertReadOnlyRegistry(): void;

package/dist/elt/ingestion/providers/registry.js

@@ -0,0 +1,62 @@
+function registry(provider, entries) {
+    return entries.map(([name, scope, entityType]) => ({ provider, name, scope, entityType, readOnly: true, pagination: scope === 'date_range' ? 'provider' : 'none' }));
+}
+/**
+ * The only provider operations an extractor may execute. Entries intentionally
+ * describe data families, not mutations: extraction code rejects every route
+ * outside this registry.
+ */
+export const intervalsReadRegistry = registry('intervals', [
+    ['athlete', 'singleton', 'athlete'], ['profile', 'singleton', 'profile'], ['connections', 'singleton', 'connection'],
+    ['sport_settings', 'collection', 'sport_setting'], ['activities', 'date_range', 'activity'], ['wellness', 'date_range', 'wellness'],
+    ['events', 'date_range', 'event'], ['workouts', 'collection', 'workout'], ['folders', 'collection', 'folder'], ['gear', 'collection', 'gear'],
+    ['routes', 'collection', 'route'], ['custom_items', 'collection', 'custom_item'], ['fitness', 'date_range', 'fitness_summary'],
+    ['activity_summary', 'date_range', 'fitness_summary'], ['power_curves', 'date_range', 'power_curve'], ['pace_curves', 'date_range', 'pace_curve'],
+    ['hr_curves', 'date_range', 'hr_curve'], ['activity_power_curves', 'date_range', 'activity_power_curve'],
+    ['activity_hr_curves', 'date_range', 'activity_hr_curve'], ['weather_config', 'singleton', 'weather_config'], ['weather_forecast', 'singleton', 'weather_forecast'],
+    ['chats', 'collection', 'chat'], ['activity_tags', 'collection', 'activity_tag'], ['event_tags', 'collection', 'event_tag'], ['workout_tags', 'collection', 'workout_tag'],
+]);
+/**
+ * Intervals is an analysis companion to Garmin: its activity-list payload
+ * supplies the separately named training calculations without duplicating
+ * Garmin's activity detail, files, streams, or account data.
+ */
+export const intervalsSecondaryReadRegistry = intervalsReadRegistry.filter((endpoint) => endpoint.name === 'athlete' || endpoint.name === 'activities');
+export const intervalsActivityReadEndpoints = [
+    'activity', 'streams', 'intervals', 'map', 'weather', 'weather_summary', 'best_efforts', 'power_curve', 'pace_curve', 'hr_curve',
+    'power_vs_hr', 'hr_load_model', 'segments', 'messages', 'original_file', 'fit_file', 'gpx_file',
+];
+/** Read-only methods exposed by python-garminconnect, grouped for manifest tests and worker dispatch. */
+export const garminReadRegistry = registry('garmin', [
+    ['user_profile', 'singleton', 'profile'], ['userprofile_settings', 'singleton', 'profile_setting'], ['devices', 'collection', 'device'],
+    ['device_settings', 'child', 'device_setting'], ['device_solar', 'date_range', 'device_solar'], ['device_alarms', 'collection', 'device_alarm'],
+    ['stats', 'date_range', 'daily_stats'], ['user_summary', 'date_range', 'daily_health'], ['steps', 'date_range', 'steps'],
+    ['heart_rates', 'date_range', 'heart_rate_day'], ['sleep', 'date_range', 'sleep'], ['stress', 'date_range', 'stress'], ['body_battery', 'date_range', 'body_battery'],
+    ['respiration', 'date_range', 'respiration'], ['spo2', 'date_range', 'spo2'], ['hrv', 'date_range', 'hrv'], ['training_readiness', 'date_range', 'training_readiness'],
+    ['training_status', 'date_range', 'training_status'], ['max_metrics', 'date_range', 'max_metric'], ['lactate_threshold', 'singleton', 'lactate_threshold'],
+    ['endurance_score', 'date_range', 'endurance_score'], ['running_tolerance', 'date_range', 'running_tolerance'], ['race_predictions', 'date_range', 'race_prediction'],
+    ['body_composition', 'date_range', 'body_composition'], ['weigh_ins', 'date_range', 'weigh_in'], ['blood_pressure', 'date_range', 'blood_pressure'],
+    ['hydration', 'date_range', 'hydration'], ['nutrition_food_log', 'date_range', 'nutrition_log'], ['nutrition_meals', 'date_range', 'nutrition_log'], ['nutrition_settings', 'date_range', 'nutrition_setting'],
+    ['menstrual', 'date_range', 'menstrual'], ['pregnancy_summary', 'singleton', 'pregnancy_summary'], ['activities', 'date_range', 'activity'],
+    ['activity_details', 'activity', 'activity_detail'], ['activity_splits', 'activity', 'activity_interval'], ['activity_typed_splits', 'activity', 'activity_interval'],
+    ['activity_split_summaries', 'activity', 'activity_interval'], ['activity_weather', 'activity', 'activity_weather'], ['activity_hr_zones', 'activity', 'activity_zone'],
+    ['activity_power_zones', 'activity', 'activity_zone'], ['activity_exercise_sets', 'activity', 'activity_exercise_set'], ['activity_gear', 'activity', 'activity_gear'],
+    ['activity_original', 'activity', 'activity_file'], ['activity_tcx', 'activity', 'activity_file'], ['activity_gpx', 'activity', 'activity_file'], ['activity_kml', 'activity', 'activity_file'],
+    ['activity_csv', 'activity', 'activity_file'], ['workouts', 'collection', 'workout'], ['scheduled_workouts', 'date_range', 'scheduled_workout'],
+    ['training_plans', 'collection', 'training_plan'], ['goals', 'collection', 'goal'], ['personal_records', 'singleton', 'personal_record'],
+    ['earned_badges', 'collection', 'badge'], ['available_badges', 'collection', 'badge'], ['challenges', 'collection', 'challenge'],
+    ['gear', 'collection', 'gear'], ['golf_summary', 'collection', 'golf_scorecard'], ['golf_user_stats', 'singleton', 'golf_user_stat'],
+]);
+export const stravaReadRegistry = registry('strava', [
+    ['athlete', 'singleton', 'athlete'], ['gear', 'child', 'gear'],
+    ['activity_candidates', 'date_range', 'activity'], ['activity_detail', 'activity', 'activity'],
+    ['segment', 'child', 'segment'], ['segment_efforts', 'child', 'segment_effort'],
+]);
+export const allReadOnlyEndpoints = [...intervalsReadRegistry, ...garminReadRegistry, ...stravaReadRegistry];
+export function assertReadOnlyRegistry() {
+    for (const endpoint of allReadOnlyEndpoints) {
+        if (endpoint.readOnly !== true)
+            throw new Error(`Unsafe endpoint registered: ${endpoint.provider}/${endpoint.name}`);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/elt/ingestion/providers/strava/service.d.ts

@@ -0,0 +1,42 @@
+import type { CatencePaths } from '../../../../contracts/runtime.js';
+type WorkerStatus = 'completed' | 'partial' | 'not_found' | 'ambiguous' | 'connected' | 'authorization_required' | 'error';
+type WorkerResult = {
+    status: WorkerStatus;
+    message?: string;
+    authorizationUrl?: string;
+    stravaActivityId?: string;
+    segmentId?: string;
+    gearCount?: number;
+    effortCount?: number;
+    continuationPage?: number;
+    lastCompletedPage?: number;
+    candidateCount?: number;
+    rawHash?: string;
+    matchEvidence?: Record<string, unknown>;
+    matchDiagnostics?: Record<string, unknown>;
+    rateHeaders?: Record<string, string>;
+};
+export declare class StravaRateLimitError extends Error {
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, retryAfterSeconds?: number | undefined);
+}
+export declare class StravaEnrichmentError extends Error {
+    constructor(message: string);
+}
+export declare function syncStravaGear(paths: CatencePaths, refresh?: boolean): Promise<WorkerResult | Record<string, unknown>>;
+/** Returns a Strava activity ID only for formats that identify one directly. */
+export declare function stravaActivityIdFromExternalId(value: string | null | undefined): string | null;
+export declare function stravaActivityIdFromSourcePayload(value: string | Record<string, unknown> | null): string | null;
+/** Prefer a persisted Strava source over a generic provider external ID. */
+export declare function resolveStravaActivityId(activityId: string, matches: Array<{
+    provider: string;
+    remote_activity_id: string;
+    external_id: string | null;
+}>): string | null;
+export declare function multisportChildActivitySourceIds(paths: CatencePaths, activityId: string): Promise<string[] | null>;
+export declare function hydrateStravaActivity(paths: CatencePaths, activityId: string, refresh?: boolean): Promise<WorkerResult | Record<string, unknown>>;
+export declare function hydrateStravaSegmentHistory(paths: CatencePaths, segmentId: string, refresh?: boolean): Promise<WorkerResult | Record<string, unknown>>;
+export declare function getStravaAuthorizationUrl(paths: CatencePaths, redirectUri: string): Promise<WorkerResult>;
+export declare function completeStravaAuthorization(paths: CatencePaths, code: string, redirectUri: string): Promise<WorkerResult>;
+export declare function disconnectStrava(paths: CatencePaths): Promise<void>;
+export {};