@clipin/convex-wearables 0.0.3 → 0.1.1

package/src/client/index.test.ts

@@ -3,6 +3,7 @@ import {
   getSdkSyncPath,
   getSdkSyncUrl,
   oauthCallback,
+  registerRoutes,
   stravaWebhookEvent,
   stravaWebhookVerify,
   WearablesClient,
@@ -49,4 +50,182 @@ describe("package exports", () => {
     expect(typeof stravaWebhookVerify).toBe("function");
     expect(typeof stravaWebhookEvent).toBe("function");
   });
+
+  it("exposes time-series storage policy helpers on the client", async () => {
+    const component = {
+      dataPoints: {
+        getTimeSeriesPolicyConfiguration: "getPolicyConfiguration",
+        getUserTimeSeriesPolicyPreset: "getUserPreset",
+        getEffectiveTimeSeriesPolicy: "getEffectivePolicy",
+        replaceTimeSeriesPolicyConfiguration: "replacePolicyConfiguration",
+        setUserTimeSeriesPolicyPreset: "setUserPreset",
+      },
+    } as unknown as WearablesComponent;
+
+    const client = new WearablesClient(component, { providers: {} });
+
+    const queryCalls: Array<{ ref: unknown; args: unknown }> = [];
+    const mutationCalls: Array<{ ref: unknown; args: unknown }> = [];
+
+    const queryCtx: Parameters<WearablesClient["getTimeSeriesPolicyConfiguration"]>[0] = {
+      runQuery: async (...args: unknown[]) => {
+        const [ref, queryArgs] = args as unknown as [unknown, unknown?];
+        queryCalls.push({ ref, args: queryArgs });
+        return null as never;
+      },
+    };
+    const mutationCtx: Parameters<WearablesClient["replaceTimeSeriesPolicyConfiguration"]>[0] = {
+      runMutation: async (...args: unknown[]) => {
+        const [ref, mutationArgs] = args as unknown as [unknown, unknown?];
+        mutationCalls.push({ ref, args: mutationArgs });
+        return null as never;
+      },
+    };
+
+    await client.getTimeSeriesPolicyConfiguration(queryCtx);
+    await client.getUserTimeSeriesPolicyPreset(queryCtx, {
+      userId: "user-1",
+    });
+    await client.getEffectiveTimeSeriesPolicy(queryCtx, {
+      userId: "user-1",
+      provider: "garmin",
+      seriesType: "heart_rate",
+    });
+    await client.replaceTimeSeriesPolicyConfiguration(mutationCtx, {
+      defaultRules: [
+        {
+          provider: "garmin",
+          seriesType: "heart_rate",
+          tiers: [
+            { kind: "raw", fromAge: "0m", toAge: "24h" },
+            { kind: "rollup", fromAge: "24h", toAge: "7d", bucket: "30m" },
+            { kind: "rollup", fromAge: "7d", toAge: null, bucket: "3h" },
+          ],
+        },
+      ],
+    });
+    await client.setUserTimeSeriesPolicyPreset(mutationCtx, {
+      userId: "user-1",
+      presetKey: "pro",
+    });
+
+    expect(queryCalls).toEqual([
+      { ref: "getPolicyConfiguration", args: {} },
+      { ref: "getUserPreset", args: { userId: "user-1" } },
+      {
+        ref: "getEffectivePolicy",
+        args: {
+          userId: "user-1",
+          provider: "garmin",
+          seriesType: "heart_rate",
+        },
+      },
+    ]);
+    expect(mutationCalls).toEqual([
+      {
+        ref: "replacePolicyConfiguration",
+        args: {
+          defaultRules: [
+            {
+              provider: "garmin",
+              seriesType: "heart_rate",
+              tiers: [
+                { kind: "raw", fromAge: "0m", toAge: "24h" },
+                { kind: "rollup", fromAge: "24h", toAge: "7d", bucket: "30m" },
+                { kind: "rollup", fromAge: "7d", toAge: null, bucket: "3h" },
+              ],
+            },
+          ],
+        },
+      },
+      {
+        ref: "setUserPreset",
+        args: {
+          userId: "user-1",
+          presetKey: "pro",
+        },
+      },
+    ]);
+  });
+});
+
+describe("registerRoutes", () => {
+  it("schedules Garmin push ingestion and acknowledges the webhook immediately", async () => {
+    const routes: Array<{
+      handler: { _handler: (ctx: unknown, request: Request) => Promise<Response> };
+      method: string;
+      path: string;
+    }> = [];
+    const http = {
+      route: (route: (typeof routes)[number]) => {
+        routes.push(route);
+      },
+    };
+    const processPushPayload = "wearables.garminWebhooks.processPushPayload";
+    const component = {
+      garminWebhooks: {
+        processPushPayload,
+      },
+    } as unknown as WearablesComponent;
+
+    registerRoutes(http as never, component, {
+      garmin: {
+        clientId: "garmin-client-id",
+        oauthCallbackPath: false,
+        webhookPath: "/webhooks/garmin/push",
+        healthPath: false,
+      },
+    });
+
+    const pushRoute = routes.find(
+      (route) => route.path === "/webhooks/garmin/push" && route.method === "POST",
+    );
+    expect(pushRoute).toBeDefined();
+
+    const scheduled: Array<{ delayMs: number; functionRef: unknown; args: unknown }> = [];
+    const ctx = {
+      scheduler: {
+        runAfter: async (delayMs: number, functionRef: unknown, args: unknown) => {
+          scheduled.push({ delayMs, functionRef, args });
+          return "scheduled-garmin-push";
+        },
+      },
+    };
+
+    const response = await pushRoute!.handler._handler(
+      ctx,
+      new Request("https://example.com/webhooks/garmin/push", {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "garmin-client-id": "garmin-client-id",
+        },
+        body: JSON.stringify({
+          dailies: [
+            {
+              userId: "garmin-user-1",
+              summaryId: "daily-1",
+              startTimeInSeconds: 1_776_988_800,
+              durationInSeconds: 86_400,
+              steps: 12_345,
+            },
+          ],
+        }),
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe("OK");
+    expect(scheduled).toHaveLength(1);
+    expect(scheduled[0]).toMatchObject({
+      delayMs: 0,
+      functionRef: processPushPayload,
+    });
+    expect(scheduled[0]?.args).toMatchObject({
+      garminClientId: "garmin-client-id",
+    });
+    expect(JSON.parse((scheduled[0]?.args as { payloadJson: string }).payloadJson)).toMatchObject({
+      dailies: [{ summaryId: "daily-1" }],
+    });
+  });
 });

package/src/client/index.ts

@@ -21,6 +21,7 @@ import type {
   Connection,
   DailySummary,
   DataPoint,
+  EffectiveTimeSeriesPolicy,
   EventCategory,
   EventsPage,
   GarminRoutesConfig,
@@ -36,7 +37,12 @@ import type {
   SdkSyncPayload,
   SyncJob,
   SyncStatus,
+  TimeSeriesMaintenanceInput,
   TimeSeriesPage,
+  TimeSeriesPolicyConfiguration,
+  TimeSeriesPolicyPresetInput,
+  TimeSeriesPolicyRuleInput,
+  UserTimeSeriesPolicyPreset,
   WearablesConfig,
 } from "./types.js";
 
@@ -54,6 +60,7 @@ export type {
   Connection,
   DailySummary,
   DataPoint,
+  EffectiveTimeSeriesPolicy,
   EventCategory,
   EventsPage,
   GarminRoutesConfig,
@@ -69,7 +76,12 @@ export type {
   SdkSyncPayload,
   SyncJob,
   SyncStatus,
+  TimeSeriesMaintenanceInput,
   TimeSeriesPage,
+  TimeSeriesPolicyConfiguration,
+  TimeSeriesPolicyPresetInput,
+  TimeSeriesPolicyRuleInput,
+  UserTimeSeriesPolicyPreset,
   WearablesConfig,
 };
 
@@ -234,6 +246,69 @@ export class WearablesClient {
     return await ctx.runQuery(this.component.dataPoints.getAvailableSeriesTypes, args);
   }
 
+  /**
+   * Get persisted time-series policy configuration.
+   */
+  async getTimeSeriesPolicyConfiguration(ctx: QueryRunner): Promise<TimeSeriesPolicyConfiguration> {
+    return (await ctx.runQuery(
+      this.component.dataPoints.getTimeSeriesPolicyConfiguration,
+      {},
+    )) as TimeSeriesPolicyConfiguration;
+  }
+
+  /**
+   * Get the preset assigned to a user, if any.
+   */
+  async getUserTimeSeriesPolicyPreset(
+    ctx: QueryRunner,
+    args: { userId: string },
+  ): Promise<UserTimeSeriesPolicyPreset | null> {
+    return (await ctx.runQuery(
+      this.component.dataPoints.getUserTimeSeriesPolicyPreset,
+      args,
+    )) as UserTimeSeriesPolicyPreset | null;
+  }
+
+  /**
+   * Resolve the effective time-series policy for a user/provider/series triple.
+   */
+  async getEffectiveTimeSeriesPolicy(
+    ctx: QueryRunner,
+    args: { userId: string; provider: ProviderName; seriesType: string },
+  ): Promise<EffectiveTimeSeriesPolicy> {
+    return (await ctx.runQuery(
+      this.component.dataPoints.getEffectiveTimeSeriesPolicy,
+      args,
+    )) as EffectiveTimeSeriesPolicy;
+  }
+
+  /**
+   * Replace the persisted time-series policy configuration.
+   */
+  async replaceTimeSeriesPolicyConfiguration(
+    ctx: MutationRunner,
+    args: {
+      defaultRules: TimeSeriesPolicyRuleInput[];
+      presets?: TimeSeriesPolicyPresetInput[];
+      maintenance?: TimeSeriesMaintenanceInput;
+    },
+  ): Promise<{ defaultRulesStored: number; presetsStored: number }> {
+    return await ctx.runMutation(
+      this.component.dataPoints.replaceTimeSeriesPolicyConfiguration,
+      args,
+    );
+  }
+
+  /**
+   * Assign or clear a user-specific policy preset.
+   */
+  async setUserTimeSeriesPolicyPreset(
+    ctx: MutationRunner,
+    args: { userId: string; presetKey: string | null },
+  ): Promise<null> {
+    return await ctx.runMutation(this.component.dataPoints.setUserTimeSeriesPolicyPreset, args);
+  }
+
   // -----------------------------------------------------------------------
   // Data Access — Summaries
   // -----------------------------------------------------------------------
@@ -506,13 +581,18 @@ export function registerRoutes(
         });
 
         try {
-          await ctx.runAction(component.garminWebhooks.processPushPayload, {
-            payloadJson: JSON.stringify(payload),
-            garminClientId: garminClientId ?? "",
-          });
-
-          console.info("Garmin webhook processed successfully", {
+          const scheduledFunctionId = await ctx.scheduler.runAfter(
+            0,
+            component.garminWebhooks.processPushPayload,
+            {
+              payloadJson: JSON.stringify(payload),
+              garminClientId: garminClientId ?? "",
+            },
+          );
+
+          console.info("Garmin webhook ingestion scheduled", {
             componentFunction: GARMIN_PUSH_COMPONENT_FUNCTION,
+            scheduledFunctionId,
             payloadSummary,
           });
 
@@ -523,7 +603,7 @@ export function registerRoutes(
             serializedError.message.includes("Couldn't resolve") &&
             serializedError.message.includes(GARMIN_PUSH_COMPONENT_FUNCTION);
 
-          console.error("Garmin webhook processing failed", {
+          console.error("Garmin webhook scheduling failed", {
             componentFunction: GARMIN_PUSH_COMPONENT_FUNCTION,
             payloadSummary,
             error: serializedError,

package/src/client/types.ts

@@ -26,6 +26,10 @@ export type SyncJobStatus = "queued" | "running" | "completed" | "failed" | "can
 
 export type BackfillJobStatus = "queued" | "running" | "completed" | "failed" | "canceled";
 
+export type DurationInput = string | number;
+
+export type TimeSeriesRollupAggregation = "avg" | "min" | "max" | "last" | "count";
+
 // ---------------------------------------------------------------------------
 // Provider configuration (passed by app)
 // ---------------------------------------------------------------------------
@@ -287,6 +291,13 @@ export type HealthEvent = WorkoutEvent | SleepEvent;
 export interface DataPoint {
   timestamp: number;
   value: number;
+  resolution?: "raw" | "rollup";
+  bucketMinutes?: number;
+  avg?: number;
+  min?: number;
+  max?: number;
+  last?: number;
+  count?: number;
 }
 
 export interface TimeSeriesPage {
@@ -295,6 +306,94 @@ export interface TimeSeriesPage {
   hasMore: boolean;
 }
 
+export interface TimeSeriesRawTierInput {
+  kind: "raw";
+  fromAge: DurationInput;
+  toAge: DurationInput | null;
+}
+
+export interface TimeSeriesRollupTierInput {
+  kind: "rollup";
+  fromAge: DurationInput;
+  toAge: DurationInput | null;
+  bucket: DurationInput;
+  aggregations?: TimeSeriesRollupAggregation[];
+}
+
+export type TimeSeriesTierInput = TimeSeriesRawTierInput | TimeSeriesRollupTierInput;
+
+export interface TimeSeriesPolicyRuleInput {
+  provider?: ProviderName;
+  seriesType?: string;
+  tiers: TimeSeriesTierInput[];
+}
+
+export interface TimeSeriesPolicyPresetInput {
+  key: string;
+  rules: TimeSeriesPolicyRuleInput[];
+}
+
+export interface TimeSeriesMaintenanceInput {
+  enabled?: boolean;
+  interval?: DurationInput;
+}
+
+export interface TimeSeriesRawTier {
+  kind: "raw";
+  fromAgeMs: number;
+  toAgeMs: number | null;
+}
+
+export interface TimeSeriesRollupTier {
+  kind: "rollup";
+  fromAgeMs: number;
+  toAgeMs: number | null;
+  bucketMs: number;
+  aggregations: TimeSeriesRollupAggregation[];
+}
+
+export type TimeSeriesTier = TimeSeriesRawTier | TimeSeriesRollupTier;
+
+export interface TimeSeriesPolicyRule {
+  _id: string;
+  policySetKind: "default" | "preset";
+  policySetKey: string;
+  updatedAt: number;
+  scope: "global" | "provider" | "series" | "provider_series";
+  provider?: ProviderName;
+  seriesType?: string;
+  tiers: TimeSeriesTier[];
+}
+
+export interface TimeSeriesPolicyPreset {
+  key: string;
+  rules: TimeSeriesPolicyRule[];
+}
+
+export interface TimeSeriesPolicyConfiguration {
+  maintenance: {
+    enabled: boolean;
+    intervalMs: number;
+  };
+  defaultRules: TimeSeriesPolicyRule[];
+  presets: TimeSeriesPolicyPreset[];
+}
+
+export interface UserTimeSeriesPolicyPreset {
+  userId: string;
+  presetKey: string;
+  updatedAt: number;
+}
+
+export interface EffectiveTimeSeriesPolicy {
+  provider: ProviderName;
+  seriesType: string;
+  sourceKind: "preset" | "default" | "builtin";
+  sourceKey: string | null;
+  matchedScope: "default" | "global" | "provider" | "series" | "provider_series";
+  tiers: TimeSeriesTier[];
+}
+
 // ---------------------------------------------------------------------------
 // Events page
 // ---------------------------------------------------------------------------