@nativesquare/soma 0.11.0 → 0.13.0

package/dist/client/garmin.d.ts

@@ -0,0 +1,291 @@
+import type { SomaComponent } from "./index.js";
+import type { ActionCtx, SomaGarminConfig, RegisterRoutesOptions } from "./types.js";
+import { type HttpRouter } from "convex/server";
+export declare const GARMIN_OAUTH_CALLBACK_PATH = "/api/garmin/callback";
+export declare const GARMIN_WEBHOOK_BASE_PATH = "/api/garmin/webhook";
+export declare class SomaGarmin {
+    private component;
+    private requireConfig;
+    constructor(component: SomaComponent, requireConfig: () => SomaGarminConfig);
+    /**
+     * Generate a Garmin OAuth 2.0 authorization URL with PKCE.
+     *
+     * The state and code verifier are stored inside the component automatically,
+     * and the callback handler registered by `registerRoutes` completes
+     * the flow without further host-app intervention.
+     *
+     * @param ctx - Action context from the host app
+     * @param opts.userId - The host app's user identifier
+     * @param opts.redirectUri - Optional override for the OAuth callback URL
+     * @returns `{ authUrl, state }`
+     *
+     * @example
+     * ```ts
+     * const { authUrl } = await soma.garmin.getAuthUrl(ctx, {
+     *   userId: "user_123",
+     *   redirectUri: "https://your-app.convex.site/api/garmin/callback",
+     * });
+     * // Redirect user to authUrl — the callback is handled automatically
+     * ```
+     */
+    getAuthUrl(ctx: ActionCtx, opts: {
+        userId: string;
+        redirectUri?: string;
+    }): Promise<any>;
+    /**
+     * Disconnect a user from Garmin.
+     *
+     * Deregisters the user at Garmin (best-effort), deletes stored tokens,
+     * and sets the connection to inactive.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     *
+     * @example
+     * ```ts
+     * await soma.garmin.disconnect(ctx, { userId: "user_123" });
+     * ```
+     */
+    disconnect(ctx: ActionCtx, args: {
+        userId: string;
+    }): Promise<any>;
+    /**
+     * Pull activity summaries from Garmin.
+     *
+     * Fetches activities, transforms them into the normalized Soma schema,
+     * and ingests them with automatic deduplication.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullActivities(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull daily wellness summaries from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullDailies(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull sleep summaries from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullSleep(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull body composition data from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullBody(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull menstrual cycle tracking data from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullMenstruation(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull blood pressure readings from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullBloodPressures(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull skin temperature data from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullSkinTemperature(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull user metrics (VO2 max, fitness age, etc.) from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullUserMetrics(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull heart rate variability (HRV) summaries from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullHRV(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull stress detail data from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullStressDetails(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull pulse oximetry (SpO2) data from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullPulseOx(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull respiration (breathing rate) data from Garmin.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     */
+    pullRespiration(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Pull all supported data types from Garmin in a single call.
+     *
+     * Equivalent to calling every individual `pull*` method. Automatically
+     * refreshes the access token if expired.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+     * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+     *
+     * @example
+     * ```ts
+     * await soma.garmin.pullAll(ctx, { userId: "user_123" });
+     * ```
+     */
+    pullAll(ctx: ActionCtx, args: {
+        userId: string;
+        startTimeInSeconds?: number;
+        endTimeInSeconds?: number;
+    }): Promise<any>;
+    /**
+     * Push a planned workout to Garmin Connect.
+     *
+     * Creates the workout on the user's Garmin account from a planned
+     * workout stored in Soma.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.plannedWorkoutId - The Soma planned workout document ID
+     * @param args.workoutProvider - Optional provider identifier for the workout source
+     */
+    pushWorkout(ctx: ActionCtx, args: {
+        userId: string;
+        plannedWorkoutId: string;
+        workoutProvider?: string;
+    }): Promise<any>;
+    /**
+     * Schedule a planned workout on the user's Garmin calendar.
+     *
+     * The workout must already exist on Garmin (via `pushWorkout`).
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.plannedWorkoutId - The Soma planned workout document ID
+     * @param args.date - Optional target date (YYYY-MM-DD); defaults to the workout's planned_date
+     */
+    pushSchedule(ctx: ActionCtx, args: {
+        userId: string;
+        plannedWorkoutId: string;
+        date?: string;
+    }): Promise<any>;
+    /**
+     * Delete a planned workout from Garmin Connect.
+     *
+     * Removes the workout from the user's Garmin account.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.plannedWorkoutId - The Soma planned workout document ID
+     */
+    deleteWorkout(ctx: ActionCtx, args: {
+        userId: string;
+        plannedWorkoutId: string;
+    }): Promise<any>;
+    /**
+     * Remove a scheduled workout from the user's Garmin calendar.
+     *
+     * Unschedules the workout without deleting the workout itself.
+     *
+     * @param ctx - Action context from the host app
+     * @param args.userId - The host app's user identifier
+     * @param args.plannedWorkoutId - The Soma planned workout document ID
+     */
+    deleteSchedule(ctx: ActionCtx, args: {
+        userId: string;
+        plannedWorkoutId: string;
+    }): Promise<any>;
+    static registerRoutes(http: HttpRouter, component: SomaComponent, opts?: RegisterRoutesOptions["garmin"]): void;
+}
+//# sourceMappingURL=garmin.d.ts.map

package/dist/client/garmin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"garmin.d.ts","sourceRoot":"","sources":["../../src/client/garmin.ts"],"names":[],"mappings":"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"}