@nativesquare/soma 0.3.0 → 0.4.0

package/src/garmin/activity.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from "vitest";
+import { transformActivity } from "./activity.js";
+import type { GarminActivity } from "./types.js";
+
+const baseActivity: GarminActivity = {
+  userId: "garmin_user_1",
+  userAccessToken: "token",
+  summaryId: "summary_12345",
+  activityId: 12345,
+  activityName: "Morning Run",
+  activityType: "RUNNING",
+  durationInSeconds: 3600,
+  startTimeInSeconds: 1700000000,
+  startTimeOffsetInSeconds: -18000,
+};
+
+describe("transformActivity", () => {
+  it("maps metadata correctly", () => {
+    const result = transformActivity(baseActivity);
+
+    expect(result.metadata.summary_id).toBe("summary_12345");
+    expect(result.metadata.start_time).toBe("2023-11-14T22:13:20.000Z");
+    expect(result.metadata.end_time).toBe("2023-11-14T23:13:20.000Z");
+    expect(result.metadata.type).toBe(8); // RUNNING → Terra Running
+    expect(result.metadata.upload_type).toBe(1); // Automatic
+    expect(result.metadata.name).toBe("Morning Run");
+  });
+
+  it("maps manual upload type", () => {
+    const manual = { ...baseActivity, manual: true };
+    const result = transformActivity(manual);
+    expect(result.metadata.upload_type).toBe(2);
+  });
+
+  it("maps duration data", () => {
+    const result = transformActivity(baseActivity);
+    expect(result.active_durations_data.activity_seconds).toBe(3600);
+  });
+
+  it("maps calories data", () => {
+    const withCalories: GarminActivity = {
+      ...baseActivity,
+      activeKilocalories: 450,
+      bmrKilocalories: 75,
+    };
+    const result = transformActivity(withCalories);
+
+    expect(result.calories_data).toBeDefined();
+    expect(result.calories_data!.net_activity_calories).toBe(450);
+    expect(result.calories_data!.BMR_calories).toBe(75);
+    expect(result.calories_data!.total_burned_calories).toBe(525);
+  });
+
+  it("returns undefined calories_data when no calorie fields present", () => {
+    const result = transformActivity(baseActivity);
+    expect(result.calories_data).toBeUndefined();
+  });
+
+  it("maps distance data", () => {
+    const withDistance: GarminActivity = {
+      ...baseActivity,
+      distanceInMeters: 10000,
+      elevationGainInMeters: 150,
+      elevationLossInMeters: 120,
+      steps: 12000,
+    };
+    const result = transformActivity(withDistance);
+
+    expect(result.distance_data).toBeDefined();
+    expect(result.distance_data!.summary!.distance_meters).toBe(10000);
+    expect(result.distance_data!.summary!.steps).toBe(12000);
+    expect(result.distance_data!.summary!.elevation!.gain_actual_meters).toBe(150);
+  });
+
+  it("maps heart rate summary", () => {
+    const withHR: GarminActivity = {
+      ...baseActivity,
+      averageHeartRateInBeatsPerMinute: 155,
+      maxHeartRateInBeatsPerMinute: 185,
+    };
+    const result = transformActivity(withHR);
+
+    expect(result.heart_rate_data).toBeDefined();
+    expect(result.heart_rate_data!.summary!.avg_hr_bpm).toBe(155);
+    expect(result.heart_rate_data!.summary!.max_hr_bpm).toBe(185);
+  });
+
+  it("maps movement data with speed and cadence", () => {
+    const withMovement: GarminActivity = {
+      ...baseActivity,
+      averageSpeedInMetersPerSecond: 3.5,
+      maxSpeedInMetersPerSecond: 5.2,
+      averageRunCadenceInStepsPerMinute: 170,
+      maxRunCadenceInStepsPerMinute: 190,
+    };
+    const result = transformActivity(withMovement);
+
+    expect(result.movement_data).toBeDefined();
+    expect(result.movement_data!.avg_speed_meters_per_second).toBe(3.5);
+    expect(result.movement_data!.max_speed_meters_per_second).toBe(5.2);
+    expect(result.movement_data!.avg_cadence_rpm).toBe(170);
+    expect(result.movement_data!.max_cadence_rpm).toBe(190);
+  });
+
+  it("maps device data", () => {
+    const withDevice: GarminActivity = {
+      ...baseActivity,
+      deviceName: "Garmin Forerunner 265",
+    };
+    const result = transformActivity(withDevice);
+
+    expect(result.device_data).toBeDefined();
+    expect(result.device_data!.name).toBe("Garmin Forerunner 265");
+  });
+
+  it("maps position data", () => {
+    const withPosition: GarminActivity = {
+      ...baseActivity,
+      startingLatitudeInDegree: 37.7749,
+      startingLongitudeInDegree: -122.4194,
+    };
+    const result = transformActivity(withPosition);
+
+    expect(result.position_data).toBeDefined();
+    expect(result.position_data!.start_pos_lat_lng_deg).toEqual([37.7749, -122.4194]);
+  });
+
+  it("maps power data", () => {
+    const withPower: GarminActivity = {
+      ...baseActivity,
+      activityType: "CYCLING",
+      averagePowerInWatts: 200,
+      maxPowerInWatts: 450,
+    };
+    const result = transformActivity(withPower);
+
+    expect(result.power_data).toBeDefined();
+    expect(result.power_data!.avg_watts).toBe(200);
+    expect(result.power_data!.max_watts).toBe(450);
+  });
+
+  it("maps lap data", () => {
+    const withLaps: GarminActivity = {
+      ...baseActivity,
+      laps: [
+        {
+          startTimeInSeconds: 1700000000,
+          timerDurationInSeconds: 600,
+          totalDistanceInMeters: 1600,
+          heartRate: 150,
+          maxSpeed: 4.5,
+        },
+        {
+          startTimeInSeconds: 1700000600,
+          timerDurationInSeconds: 600,
+          totalDistanceInMeters: 1650,
+          heartRate: 158,
+          maxSpeed: 4.8,
+        },
+      ],
+    };
+    const result = transformActivity(withLaps);
+
+    expect(result.lap_data).toBeDefined();
+    expect(result.lap_data!.laps).toHaveLength(2);
+    expect(result.lap_data!.laps![0].distance_meters).toBe(1600);
+    expect(result.lap_data!.laps![0].avg_hr_bpm).toBe(150);
+  });
+
+  it("uses summaryId as summary_id and falls back to activityId", () => {
+    const withoutSummaryId = {
+      ...baseActivity,
+      summaryId: undefined as unknown as string,
+    };
+    const result = transformActivity(withoutSummaryId);
+    expect(result.metadata.summary_id).toBe("12345");
+  });
+});

package/src/garmin/activity.ts

@@ -0,0 +1,272 @@
+// ─── Activity Transformer ────────────────────────────────────────────────────
+// Transforms a Garmin activity into the Soma Activity schema shape.
+
+import type { GarminActivity } from "./types.js";
+import { mapActivityType } from "./maps/activity-type.js";
+
+export type ActivityData = ReturnType<typeof transformActivity>;
+
+/**
+ * Transform a Garmin activity into a Soma Activity document shape.
+ *
+ * The returned object is ready to be spread into an `ingestActivity` call
+ * alongside `connectionId` and `userId`.
+ *
+ * @param activity - The Garmin activity from the Health API
+ * @returns Soma Activity fields (without connectionId/userId)
+ *
+ * @example
+ * ```ts
+ * const data = transformActivity(garminActivity);
+ * await soma.ingestActivity(ctx, { connectionId, userId, ...data });
+ * ```
+ */
+export function transformActivity(activity: GarminActivity) {
+  const startMs = activity.startTimeInSeconds * 1000;
+  const endMs = startMs + activity.durationInSeconds * 1000;
+  const startDate = new Date(startMs).toISOString();
+  const endDate = new Date(endMs).toISOString();
+
+  return {
+    metadata: {
+      summary_id: activity.summaryId ?? String(activity.activityId),
+      start_time: startDate,
+      end_time: endDate,
+      type: mapActivityType(activity.activityType),
+      upload_type: activity.manual ? 2 : 1,
+      name: activity.activityName,
+    },
+
+    active_durations_data: {
+      activity_seconds: activity.durationInSeconds,
+    },
+
+    calories_data: buildCaloriesData(activity),
+
+    device_data: activity.deviceName
+      ? { name: activity.deviceName }
+      : undefined,
+
+    distance_data: buildDistanceData(activity),
+
+    heart_rate_data: buildHeartRateData(activity),
+
+    movement_data: buildMovementData(activity),
+
+    position_data: buildPositionData(activity),
+
+    power_data: buildPowerData(activity),
+
+    lap_data: buildLapData(activity),
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildCaloriesData(activity: GarminActivity) {
+  if (
+    activity.activeKilocalories == null &&
+    activity.bmrKilocalories == null
+  ) {
+    return undefined;
+  }
+
+  const total =
+    (activity.activeKilocalories ?? 0) + (activity.bmrKilocalories ?? 0);
+
+  return {
+    net_activity_calories: activity.activeKilocalories,
+    BMR_calories: activity.bmrKilocalories,
+    total_burned_calories: total || undefined,
+  };
+}
+
+function buildDistanceData(activity: GarminActivity) {
+  if (activity.distanceInMeters == null && activity.elevationGainInMeters == null) {
+    return undefined;
+  }
+
+  return {
+    summary: {
+      distance_meters: activity.distanceInMeters,
+      steps: activity.steps,
+      elevation:
+        activity.elevationGainInMeters != null
+          ? {
+              gain_actual_meters: activity.elevationGainInMeters,
+              loss_actual_meters: activity.elevationLossInMeters,
+            }
+          : undefined,
+    },
+  };
+}
+
+function buildHeartRateData(activity: GarminActivity) {
+  const hasHrSummary =
+    activity.averageHeartRateInBeatsPerMinute != null ||
+    activity.maxHeartRateInBeatsPerMinute != null;
+  const hasSamples = activity.samples && activity.samples.length > 0;
+
+  if (!hasHrSummary && !hasSamples) return undefined;
+
+  const hrSamples = hasSamples
+    ? activity.samples!
+        .filter((s) => s.heartRate != null && s.startTimeInSeconds != null)
+        .map((s) => ({
+          timestamp: new Date(s.startTimeInSeconds! * 1000).toISOString(),
+          bpm: s.heartRate!,
+        }))
+    : undefined;
+
+  return {
+    summary: hasHrSummary
+      ? {
+          avg_hr_bpm: activity.averageHeartRateInBeatsPerMinute,
+          max_hr_bpm: activity.maxHeartRateInBeatsPerMinute,
+        }
+      : undefined,
+    detailed:
+      hrSamples && hrSamples.length > 0
+        ? { hr_samples: hrSamples }
+        : undefined,
+  };
+}
+
+function buildMovementData(activity: GarminActivity) {
+  const avgCadence =
+    activity.averageRunCadenceInStepsPerMinute ??
+    activity.averageBikeCadenceInRoundsPerMinute;
+  const maxCadence =
+    activity.maxRunCadenceInStepsPerMinute ??
+    activity.maxBikeCadenceInRoundsPerMinute;
+
+  const hasMovement =
+    activity.averageSpeedInMetersPerSecond != null ||
+    activity.maxSpeedInMetersPerSecond != null ||
+    avgCadence != null;
+
+  const hasSamples = activity.samples && activity.samples.length > 0;
+
+  if (!hasMovement && !hasSamples) return undefined;
+
+  const speedSamples = hasSamples
+    ? activity.samples!
+        .filter(
+          (s) =>
+            s.speedMetersPerSecond != null && s.startTimeInSeconds != null,
+        )
+        .map((s) => ({
+          timestamp: new Date(s.startTimeInSeconds! * 1000).toISOString(),
+          speed_meters_per_second: s.speedMetersPerSecond!,
+        }))
+    : undefined;
+
+  const cadenceSamples = hasSamples
+    ? activity.samples!
+        .filter(
+          (s) =>
+            (s.runCadenceInStepsPerMinute != null ||
+              s.bikeCadenceInRPM != null) &&
+            s.startTimeInSeconds != null,
+        )
+        .map((s) => ({
+          timestamp: new Date(s.startTimeInSeconds! * 1000).toISOString(),
+          cadence_rpm:
+            s.runCadenceInStepsPerMinute ?? s.bikeCadenceInRPM ?? 0,
+        }))
+    : undefined;
+
+  return {
+    avg_speed_meters_per_second: activity.averageSpeedInMetersPerSecond,
+    max_speed_meters_per_second: activity.maxSpeedInMetersPerSecond,
+    avg_pace_minutes_per_kilometer: activity.averagePaceInMinutesPerKilometer,
+    max_pace_minutes_per_kilometer: activity.maxPaceInMinutesPerKilometer,
+    avg_cadence_rpm: avgCadence,
+    max_cadence_rpm: maxCadence,
+    speed_samples:
+      speedSamples && speedSamples.length > 0 ? speedSamples : undefined,
+    cadence_samples:
+      cadenceSamples && cadenceSamples.length > 0
+        ? cadenceSamples
+        : undefined,
+  };
+}
+
+function buildPositionData(activity: GarminActivity) {
+  const hasStartPos =
+    activity.startingLatitudeInDegree != null &&
+    activity.startingLongitudeInDegree != null;
+  const hasSamples = activity.samples && activity.samples.length > 0;
+
+  if (!hasStartPos && !hasSamples) return undefined;
+
+  const positionSamples = hasSamples
+    ? activity.samples!
+        .filter(
+          (s) =>
+            s.latitudeInDegree != null &&
+            s.longitudeInDegree != null &&
+            s.startTimeInSeconds != null,
+        )
+        .map((s) => ({
+          timestamp: new Date(s.startTimeInSeconds! * 1000).toISOString(),
+          coords_lat_lng_deg: [s.latitudeInDegree!, s.longitudeInDegree!],
+        }))
+    : undefined;
+
+  return {
+    start_pos_lat_lng_deg: hasStartPos
+      ? [
+          activity.startingLatitudeInDegree!,
+          activity.startingLongitudeInDegree!,
+        ]
+      : undefined,
+    position_samples:
+      positionSamples && positionSamples.length > 0
+        ? positionSamples
+        : undefined,
+  };
+}
+
+function buildPowerData(activity: GarminActivity) {
+  const hasPowerSummary =
+    activity.averagePowerInWatts != null ||
+    activity.maxPowerInWatts != null;
+  const hasSamples = activity.samples && activity.samples.length > 0;
+
+  if (!hasPowerSummary && !hasSamples) return undefined;
+
+  const powerSamples = hasSamples
+    ? activity.samples!
+        .filter(
+          (s) => s.powerInWatts != null && s.startTimeInSeconds != null,
+        )
+        .map((s) => ({
+          timestamp: new Date(s.startTimeInSeconds! * 1000).toISOString(),
+          watts: s.powerInWatts!,
+        }))
+    : undefined;
+
+  return {
+    avg_watts: activity.averagePowerInWatts,
+    max_watts: activity.maxPowerInWatts,
+    power_samples:
+      powerSamples && powerSamples.length > 0 ? powerSamples : undefined,
+  };
+}
+
+function buildLapData(activity: GarminActivity) {
+  if (!activity.laps || activity.laps.length === 0) return undefined;
+
+  return {
+    laps: activity.laps.map((lap) => ({
+      start_time: new Date(lap.startTimeInSeconds * 1000).toISOString(),
+      end_time: new Date(
+        (lap.startTimeInSeconds + lap.timerDurationInSeconds) * 1000,
+      ).toISOString(),
+      distance_meters: lap.totalDistanceInMeters,
+      avg_hr_bpm: lap.heartRate,
+      avg_speed_meters_per_second: lap.maxSpeed,
+    })),
+  };
+}

package/src/garmin/auth.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildOAuthSignature,
+  buildOAuthHeader,
+  percentEncode,
+  generateNonce,
+  getTimestamp,
+} from "./auth.js";
+
+describe("percentEncode", () => {
+  it("encodes special characters per RFC 3986", () => {
+    expect(percentEncode("hello world")).toBe("hello%20world");
+    expect(percentEncode("a=b&c=d")).toBe("a%3Db%26c%3Dd");
+    expect(percentEncode("test!")).toBe("test%21");
+    expect(percentEncode("100%")).toBe("100%25");
+  });
+
+  it("encodes characters that encodeURIComponent misses", () => {
+    expect(percentEncode("a'b")).toBe("a%27b");
+    expect(percentEncode("a(b)")).toBe("a%28b%29");
+    expect(percentEncode("a*b")).toBe("a%2Ab");
+  });
+
+  it("does not encode unreserved characters", () => {
+    expect(percentEncode("abcXYZ123")).toBe("abcXYZ123");
+    expect(percentEncode("-._~")).toBe("-._~");
+  });
+});
+
+describe("generateNonce", () => {
+  it("returns a 32-character hex string", () => {
+    const nonce = generateNonce();
+    expect(nonce).toHaveLength(32);
+    expect(nonce).toMatch(/^[0-9a-f]+$/);
+  });
+
+  it("generates unique values", () => {
+    const nonce1 = generateNonce();
+    const nonce2 = generateNonce();
+    expect(nonce1).not.toBe(nonce2);
+  });
+});
+
+describe("getTimestamp", () => {
+  it("returns a Unix timestamp string", () => {
+    const ts = getTimestamp();
+    const parsed = parseInt(ts, 10);
+    expect(parsed).toBeGreaterThan(1700000000);
+    expect(String(parsed)).toBe(ts);
+  });
+});
+
+describe("buildOAuthSignature", () => {
+  it("produces a valid HMAC-SHA1 signature", async () => {
+    const signature = await buildOAuthSignature(
+      "GET",
+      "https://api.example.com/resource",
+      {
+        oauth_consumer_key: "consumer_key",
+        oauth_nonce: "kllo9940pd9333jh",
+        oauth_signature_method: "HMAC-SHA1",
+        oauth_timestamp: "1191242096",
+        oauth_version: "1.0",
+      },
+      "consumer_secret",
+      "",
+    );
+
+    expect(signature).toBeTruthy();
+    expect(typeof signature).toBe("string");
+    expect(signature).toMatch(/^[A-Za-z0-9+/]+=*$/);
+  });
+
+  it("includes token secret in signing key when provided", async () => {
+    const sig1 = await buildOAuthSignature(
+      "POST",
+      "https://api.example.com/resource",
+      { oauth_consumer_key: "key", oauth_nonce: "abc", oauth_timestamp: "123" },
+      "consumer_secret",
+      "",
+    );
+
+    const sig2 = await buildOAuthSignature(
+      "POST",
+      "https://api.example.com/resource",
+      { oauth_consumer_key: "key", oauth_nonce: "abc", oauth_timestamp: "123" },
+      "consumer_secret",
+      "token_secret",
+    );
+
+    expect(sig1).not.toBe(sig2);
+  });
+
+  it("sorts parameters alphabetically", async () => {
+    const sig1 = await buildOAuthSignature(
+      "GET",
+      "https://api.example.com/resource",
+      { z_param: "last", a_param: "first", m_param: "middle" },
+      "secret",
+    );
+    const sig2 = await buildOAuthSignature(
+      "GET",
+      "https://api.example.com/resource",
+      { a_param: "first", m_param: "middle", z_param: "last" },
+      "secret",
+    );
+
+    expect(sig1).toBe(sig2);
+  });
+});
+
+describe("buildOAuthHeader", () => {
+  it("builds a valid OAuth Authorization header", () => {
+    const header = buildOAuthHeader({
+      oauth_consumer_key: "my_key",
+      oauth_nonce: "abc123",
+      oauth_signature: "sig%3D",
+      oauth_signature_method: "HMAC-SHA1",
+      oauth_timestamp: "1234567890",
+      oauth_version: "1.0",
+    });
+
+    expect(header).toMatch(/^OAuth /);
+    expect(header).toContain('oauth_consumer_key="my_key"');
+    expect(header).toContain('oauth_nonce="abc123"');
+    expect(header).toContain('oauth_version="1.0"');
+  });
+});