catence 0.0.0 → 0.2.0-beta.1

package/dist/elt/application/management.js

@@ -0,0 +1,285 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { buildRetrievalIndex } from '../../core/retrieval/index.js';
+import { defaultFromDate, ensurePaths, requireIntervalsConfig } from '../../core/runtime/configuration.js';
+import { athleteProviderEnvironment } from '../../core/runtime/secrets.js';
+import { importJsonl } from '../ingestion/importer.js';
+import { IntervalsExtractor } from '../ingestion/providers/intervals.js';
+import { completeStravaAuthorization, disconnectStrava, getStravaAuthorizationUrl, syncStravaGear } from '../ingestion/providers/strava/service.js';
+import { setManualActivityLink, unlinkActivitySource } from '../normalization/activities/linking.js';
+import { CatenceDatabase } from '../storage/database.js';
+import { withDataWriteLock } from '../storage/write-lock.js';
+const execFileAsync = promisify(execFile);
+function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+}
+async function syncProvider(database, paths, provider, options) {
+    const explicitWindow = options.explicitFrom ? { fromDate: options.explicitFrom, toDate: options.toDate, source: 'explicit' } : null;
+    const uncoveredExplicitWindow = async (cursorName) => {
+        if (!explicitWindow)
+            return null;
+        if (!options.backfill)
+            return explicitWindow;
+        const window = await database.resolveBackfillWindow(provider, cursorName, explicitWindow.fromDate, explicitWindow.toDate, options.refreshActivities);
+        return window ? { ...window, source: 'explicit' } : null;
+    };
+    const dailyWindow = explicitWindow ? await uncoveredExplicitWindow('daily') : await database.resolveIncrementalWindow(provider, 'daily', options.toDate, defaultFromDate(), 3);
+    const activityWindow = explicitWindow ? await uncoveredExplicitWindow('activities') : await database.resolveIncrementalWindow(provider, 'activities', options.toDate, defaultFromDate(), 14);
+    const hasProviderWork = provider === 'intervals' ? activityWindow !== null : dailyWindow !== null || activityWindow !== null;
+    if (!hasProviderWork) {
+        return {
+            runId: null, provider, fromDate: null,
+            dailyFromDate: dailyWindow?.fromDate ?? null, dailyToDate: dailyWindow?.toDate ?? null,
+            activityFromDate: activityWindow?.fromDate ?? null, activityToDate: activityWindow?.toDate ?? null,
+            toDate: options.toDate, dailyCursorSource: dailyWindow?.source ?? null, activityCursorSource: activityWindow?.source ?? null,
+            refreshedActivities: provider === 'garmin' && options.refreshActivities, skipped: true,
+        };
+    }
+    const fromDate = [dailyWindow?.fromDate, activityWindow?.fromDate].filter((date) => Boolean(date)).sort()[0];
+    const runId = await database.beginRun(provider, fromDate);
+    let extractionStarted = false;
+    try {
+        if (provider === 'intervals') {
+            const environment = await athleteProviderEnvironment(paths);
+            const config = requireIntervalsConfig(environment);
+            extractionStarted = true;
+            await new IntervalsExtractor(database, paths, config.apiKey, config.athleteId).sync(runId, activityWindow, !options.backfill || options.refreshActivities);
+        }
+        else {
+            const output = path.join(paths.staging, 'garmin', `${runId}.jsonl`);
+            const knownActivities = path.join(paths.staging, 'garmin', `${runId}.known-activities.json`);
+            await mkdir(path.dirname(knownActivities), { recursive: true });
+            // An explicit refresh intentionally provides no known hashes, causing
+            // the staging worker to re-fetch Garmin activity details, files, and
+            // streams even when the list-summary hash is unchanged.
+            await writeFile(knownActivities, JSON.stringify(options.refreshActivities ? {} : await database.knownActivitySummaryHashes('garmin')));
+            extractionStarted = true;
+            const arguments_ = ['run', 'python', '-m', 'python.catence.providers.garmin.cli', '--from', fromDate, '--to', options.toDate, '--data-dir', paths.root, '--output', output, '--run-id', runId, '--known-activities', knownActivities];
+            if (dailyWindow)
+                arguments_.push('--daily-from', dailyWindow.fromDate, '--daily-to', dailyWindow.toDate);
+            else
+                arguments_.push('--skip-daily');
+            if (activityWindow)
+                arguments_.push('--activity-from', activityWindow.fromDate, '--activity-to', activityWindow.toDate);
+            else
+                arguments_.push('--skip-activities');
+            if (options.backfill && !options.refreshActivities)
+                arguments_.push('--historical-only');
+            await execFileAsync('uv', arguments_, {
+                cwd: packageRoot(),
+                env: { ...(await athleteProviderEnvironment(paths)), UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
+            });
+            if (!existsSync(output))
+                throw new Error('Garmin staging worker completed without writing a JSONL manifest.');
+            await importJsonl(database, runId, output);
+        }
+    }
+    catch (error) {
+        await database.addError(runId, provider, 'sync', null, error instanceof Error ? error.message : String(error), true);
+    }
+    finally {
+        await database.finishRun(runId);
+    }
+    if (options.advanceCursor && !options.explicitFrom && extractionStarted) {
+        await database.advanceIncrementalCursor(provider, 'daily', runId, options.toDate, 3);
+        await database.advanceIncrementalCursor(provider, 'activities', runId, options.toDate, 14);
+    }
+    return {
+        runId, provider, fromDate,
+        dailyFromDate: dailyWindow?.fromDate ?? null, dailyToDate: dailyWindow?.toDate ?? null,
+        activityFromDate: activityWindow?.fromDate ?? null, activityToDate: activityWindow?.toDate ?? null,
+        toDate: options.toDate, dailyCursorSource: dailyWindow?.source ?? null, activityCursorSource: activityWindow?.source ?? null,
+        refreshedActivities: provider === 'garmin' && options.refreshActivities, skipped: false,
+    };
+}
+export async function initializeDataStore(paths) {
+    await ensurePaths(paths);
+    const database = await CatenceDatabase.open(paths);
+    await database.close();
+    return { dataDir: paths.root, database: paths.database, message: 'Catence data store is ready. Run sync to import provider data.' };
+}
+export async function syncData(paths, provider, explicitFrom, advanceCursor = true, refreshActivities = false, backfill = false) {
+    await ensurePaths(paths);
+    if (provider === 'strava')
+        return { provider, result: await syncStravaGear(paths) };
+    const database = await CatenceDatabase.open(paths);
+    try {
+        const providers = provider === 'all' ? ['intervals', 'garmin'] : [provider];
+        const toDate = new Date().toISOString().slice(0, 10);
+        const runs = [];
+        for (const source of providers)
+            runs.push(await syncProvider(database, paths, source, { explicitFrom, toDate, advanceCursor, refreshActivities, backfill }));
+        return { runIds: runs.flatMap((run) => run.runId ? [run.runId] : []), runs };
+    }
+    finally {
+        await database.close();
+    }
+}
+export async function retryDataSync(paths, previousRunId) {
+    await ensurePaths(paths);
+    const database = await CatenceDatabase.open(paths);
+    try {
+        const previous = await database.getRun(previousRunId);
+        if (!previous)
+            throw new Error(`No sync run found for ${previousRunId}.`);
+        if (previous.provider === 'strava')
+            throw new Error('Retry Strava gear sync with `catence-data sync --provider strava`.');
+        const run = await syncProvider(database, paths, previous.provider, { explicitFrom: previous.from_date, toDate: new Date().toISOString().slice(0, 10), advanceCursor: false, refreshActivities: false, backfill: false });
+        return { retriedRun: previousRunId, runId: run.runId, run };
+    }
+    finally {
+        await database.close();
+    }
+}
+export async function connectStrava(paths, code, redirectUri) {
+    return code ? completeStravaAuthorization(paths, code, redirectUri) : getStravaAuthorizationUrl(paths, redirectUri);
+}
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+/** Validate a local OAuth return address before opening a callback listener. */
+export function loopbackStravaRedirect(redirectUri) {
+    let parsed;
+    try {
+        parsed = new URL(redirectUri);
+    }
+    catch {
+        throw new Error('--redirect-uri must be an absolute URL.');
+    }
+    if (parsed.protocol !== 'http:' || !LOOPBACK_HOSTS.has(parsed.hostname) || !parsed.port) {
+        throw new Error('--callback requires an http loopback --redirect-uri with an explicit port.');
+    }
+    return parsed;
+}
+function readStravaCallback(requestUrl, callback) {
+    const received = new URL(requestUrl ?? '/', callback);
+    if (received.pathname !== callback.pathname)
+        throw new Error('Strava returned to an unexpected callback path.');
+    const error = received.searchParams.get('error');
+    if (error)
+        throw new Error(`Strava authorization was declined or failed: ${error}.`);
+    const code = received.searchParams.get('code');
+    if (!code)
+        throw new Error('Strava callback did not include an authorization code.');
+    return { code, state: received.searchParams.get('state') };
+}
+function callbackPage(response, success) {
+    response.writeHead(success ? 200 : 400, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+    response.end(success
+        ? '<!doctype html><title>Catence connected</title><p>Strava is connected to Catence. You can close this tab.</p>'
+        : '<!doctype html><title>Catence authorization failed</title><p>Strava authorization did not complete. Return to the terminal for details.</p>');
+}
+/**
+ * Complete Strava OAuth through a short-lived loopback callback listener.
+ *
+ * The authorization URL is emitted through the caller so the CLI can keep
+ * stdout machine-readable for the final connection result.
+ */
+export async function connectStravaWithCallback(paths, redirectUri, onAuthorizationUrl, timeoutMs = 300_000) {
+    const callback = loopbackStravaRedirect(redirectUri);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1_000)
+        throw new Error('OAuth callback timeout must be at least one second.');
+    const expectedState = randomUUID();
+    const listener = createServer();
+    const callbackResult = new Promise((resolve, reject) => {
+        listener.once('error', reject);
+        listener.on('request', (request, response) => {
+            if (request.method !== 'GET') {
+                response.writeHead(405, { allow: 'GET' }).end();
+                return;
+            }
+            try {
+                const result = readStravaCallback(request.url, callback);
+                if (result.state !== expectedState)
+                    throw new Error('Strava callback state did not match this authorization request.');
+                callbackPage(response, true);
+                resolve(result);
+            }
+            catch (error) {
+                callbackPage(response, false);
+                reject(error);
+            }
+        });
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            listener.once('error', reject);
+            listener.listen(Number(callback.port), callback.hostname.replace(/^\[|\]$/g, ''), () => {
+                listener.off('error', reject);
+                resolve();
+            });
+        });
+        const authorization = await getStravaAuthorizationUrl(paths, callback.toString());
+        if (!authorization.authorizationUrl)
+            throw new Error('Strava did not return an authorization URL.');
+        const authorizationUrl = new URL(authorization.authorizationUrl);
+        authorizationUrl.searchParams.set('state', expectedState);
+        onAuthorizationUrl(authorizationUrl.toString());
+        const timed = Promise.race([
+            callbackResult,
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Timed out waiting for the Strava callback.')), timeoutMs)),
+        ]);
+        const { code } = await timed;
+        return completeStravaAuthorization(paths, code, callback.toString());
+    }
+    finally {
+        if (listener.listening)
+            await new Promise((resolve) => listener.close(() => resolve()));
+    }
+}
+export async function disconnectStravaAccount(paths) {
+    await disconnectStrava(paths);
+    return { provider: 'strava', disconnected: true };
+}
+export async function linkActivity(paths, source, activity) {
+    await ensurePaths(paths);
+    await withDataWriteLock(paths, async () => {
+        const database = await CatenceDatabase.open(paths);
+        try {
+            await setManualActivityLink(database, source, activity);
+        }
+        finally {
+            await database.close();
+        }
+    });
+    return { source, activity, method: 'manual' };
+}
+export async function unlinkActivity(paths, source) {
+    await ensurePaths(paths);
+    await withDataWriteLock(paths, async () => {
+        const database = await CatenceDatabase.open(paths);
+        try {
+            await unlinkActivitySource(database, source);
+        }
+        finally {
+            await database.close();
+        }
+    });
+    return { source, method: 'source' };
+}
+export async function dataStatus(paths) {
+    await ensurePaths(paths);
+    const database = await CatenceDatabase.open(paths);
+    try {
+        return await database.status();
+    }
+    finally {
+        await database.close();
+    }
+}
+export async function rebuildRetrievalIndex(paths) {
+    if (!existsSync(paths.database))
+        throw new Error('No Catence database exists yet. Complete a sync before building the retrieval index.');
+    const database = await CatenceDatabase.open(paths);
+    try {
+        return await buildRetrievalIndex(database);
+    }
+    finally {
+        await database.close();
+    }
+}
+//# sourceMappingURL=management.js.map

package/dist/elt/ingestion/importer.d.ts

@@ -0,0 +1,8 @@
+import type { CatenceDatabase } from '../storage/database.js';
+import { type StagingRecord } from '../../contracts/staging.js';
+export declare function importRecord(database: CatenceDatabase, runId: string, record: StagingRecord): Promise<void>;
+export declare function importJsonl(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
+export declare function importSingleStagingFile(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
+export declare function queueWorkItem(database: CatenceDatabase, runId: string, provider: 'intervals' | 'garmin' | 'strava', endpoint: string, remoteId: string | null, scope: unknown): Promise<string>;
+export declare function completeWorkItem(database: CatenceDatabase, itemId: string): Promise<void>;
+export declare function failWorkItem(database: CatenceDatabase, itemId: string, message: string): Promise<void>;

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;