@nativesquare/soma 0.2.0 → 0.4.0

package/src/garmin/auth.ts

@@ -0,0 +1,249 @@
+// ─── Garmin OAuth 1.0a Helpers ───────────────────────────────────────────────
+// Pure helper functions for the Garmin OAuth 1.0a three-legged flow.
+// Uses the Web Crypto API for HMAC-SHA1 signing and global `fetch`.
+
+import type {
+  GarminOAuthRequestTokenResponse,
+  GarminOAuthAccessTokenResponse,
+} from "./types.js";
+
+const OAUTH_BASE_URL = "https://connectapi.garmin.com";
+const AUTH_CONFIRM_URL = "https://connect.garmin.com/oauthConfirm";
+
+// ─── OAuth 1.0a Signature ───────────────────────────────────────────────────
+
+/**
+ * Generate a random nonce for OAuth 1.0a requests.
+ */
+export function generateNonce(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Get the current Unix timestamp in seconds.
+ */
+export function getTimestamp(): string {
+  return String(Math.floor(Date.now() / 1000));
+}
+
+/**
+ * Percent-encode a string per RFC 3986 (used by OAuth 1.0a).
+ * Unlike encodeURIComponent, this also encodes `!`, `*`, `'`, `(`, `)`.
+ */
+export function percentEncode(str: string): string {
+  return encodeURIComponent(str).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/**
+ * Build the OAuth 1.0a signature base string and compute the HMAC-SHA1 signature.
+ *
+ * @param method - HTTP method (e.g., "POST", "GET")
+ * @param url - The base URL (without query string)
+ * @param params - All OAuth + request parameters sorted alphabetically
+ * @param consumerSecret - The application's consumer secret
+ * @param tokenSecret - The token secret (empty string for request token step)
+ */
+export async function buildOAuthSignature(
+  method: string,
+  url: string,
+  params: Record<string, string>,
+  consumerSecret: string,
+  tokenSecret: string = "",
+): Promise<string> {
+  const sortedKeys = Object.keys(params).sort();
+  const paramString = sortedKeys
+    .map((key) => `${percentEncode(key)}=${percentEncode(params[key])}`)
+    .join("&");
+
+  const signatureBaseString = [
+    method.toUpperCase(),
+    percentEncode(url),
+    percentEncode(paramString),
+  ].join("&");
+
+  const signingKey = `${percentEncode(consumerSecret)}&${percentEncode(tokenSecret)}`;
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(signingKey),
+    { name: "HMAC", hash: "SHA-1" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(signatureBaseString),
+  );
+  return btoa(String.fromCharCode(...new Uint8Array(signature)));
+}
+
+/**
+ * Build the `Authorization: OAuth ...` header value from OAuth parameters.
+ */
+export function buildOAuthHeader(params: Record<string, string>): string {
+  const entries = Object.entries(params)
+    .map(([key, value]) => `${percentEncode(key)}="${percentEncode(value)}"`)
+    .join(", ");
+  return `OAuth ${entries}`;
+}
+
+// ─── Step 1: Get Request Token ──────────────────────────────────────────────
+
+export interface GetRequestTokenOptions {
+  consumerKey: string;
+  consumerSecret: string;
+  callbackUrl?: string;
+}
+
+/**
+ * Obtain an unauthorized request token from Garmin.
+ *
+ * This is Step 1 of the OAuth 1.0a three-legged flow:
+ * 1. Your server calls this function to get a temporary request token
+ * 2. Redirect the user to the returned `authUrl`
+ * 3. After the user authorizes, exchange the verifier for an access token
+ *
+ * @returns The request token, token secret, and the authorization URL
+ */
+export async function getRequestToken(
+  opts: GetRequestTokenOptions,
+): Promise<GarminOAuthRequestTokenResponse & { authUrl: string }> {
+  const url = `${OAUTH_BASE_URL}/oauth-service/oauth/request_token`;
+  const nonce = generateNonce();
+  const timestamp = getTimestamp();
+
+  const oauthParams: Record<string, string> = {
+    oauth_consumer_key: opts.consumerKey,
+    oauth_nonce: nonce,
+    oauth_signature_method: "HMAC-SHA1",
+    oauth_timestamp: timestamp,
+    oauth_version: "1.0",
+  };
+
+  if (opts.callbackUrl) {
+    oauthParams.oauth_callback = opts.callbackUrl;
+  }
+
+  const signature = await buildOAuthSignature(
+    "POST",
+    url,
+    oauthParams,
+    opts.consumerSecret,
+  );
+  oauthParams.oauth_signature = signature;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: buildOAuthHeader(oauthParams),
+    },
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `Garmin OAuth error (getRequestToken): ${response.status} ${response.statusText} — ${body}`,
+    );
+  }
+
+  const responseText = await response.text();
+  const parsed = new URLSearchParams(responseText);
+  const oauthToken = parsed.get("oauth_token");
+  const oauthTokenSecret = parsed.get("oauth_token_secret");
+
+  if (!oauthToken || !oauthTokenSecret) {
+    throw new Error(
+      `Garmin OAuth error: unexpected response format — ${responseText}`,
+    );
+  }
+
+  const authUrl = opts.callbackUrl
+    ? `${AUTH_CONFIRM_URL}?oauth_token=${encodeURIComponent(oauthToken)}&oauth_callback=${encodeURIComponent(opts.callbackUrl)}`
+    : `${AUTH_CONFIRM_URL}?oauth_token=${encodeURIComponent(oauthToken)}`;
+
+  return {
+    oauthToken,
+    oauthTokenSecret,
+    authUrl,
+  };
+}
+
+// ─── Step 3: Exchange for Access Token ──────────────────────────────────────
+
+export interface GetAccessTokenOptions {
+  consumerKey: string;
+  consumerSecret: string;
+  /** The request token from Step 1. */
+  token: string;
+  /** The request token secret from Step 1. */
+  tokenSecret: string;
+  /** The verifier from the OAuth callback (Step 2). */
+  verifier: string;
+}
+
+/**
+ * Exchange a request token + verifier for a permanent access token.
+ *
+ * This is Step 3 of the OAuth 1.0a three-legged flow.
+ * The returned access token and secret are permanent — Garmin tokens
+ * do not expire and there is no refresh flow.
+ */
+export async function getAccessToken(
+  opts: GetAccessTokenOptions,
+): Promise<GarminOAuthAccessTokenResponse> {
+  const url = `${OAUTH_BASE_URL}/oauth-service/oauth/access_token`;
+  const nonce = generateNonce();
+  const timestamp = getTimestamp();
+
+  const oauthParams: Record<string, string> = {
+    oauth_consumer_key: opts.consumerKey,
+    oauth_nonce: nonce,
+    oauth_signature_method: "HMAC-SHA1",
+    oauth_timestamp: timestamp,
+    oauth_token: opts.token,
+    oauth_verifier: opts.verifier,
+    oauth_version: "1.0",
+  };
+
+  const signature = await buildOAuthSignature(
+    "POST",
+    url,
+    oauthParams,
+    opts.consumerSecret,
+    opts.tokenSecret,
+  );
+  oauthParams.oauth_signature = signature;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: buildOAuthHeader(oauthParams),
+    },
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `Garmin OAuth error (getAccessToken): ${response.status} ${response.statusText} — ${body}`,
+    );
+  }
+
+  const responseText = await response.text();
+  const parsed = new URLSearchParams(responseText);
+  const oauthToken = parsed.get("oauth_token");
+  const oauthTokenSecret = parsed.get("oauth_token_secret");
+
+  if (!oauthToken || !oauthTokenSecret) {
+    throw new Error(
+      `Garmin OAuth error: unexpected access token response — ${responseText}`,
+    );
+  }
+
+  return { oauthToken, oauthTokenSecret };
+}

package/src/garmin/body.ts

@@ -0,0 +1,59 @@
+// ─── Body Transformer ────────────────────────────────────────────────────────
+// Transforms Garmin body composition data into the Soma Body schema shape.
+
+import type { GarminBodyComposition } from "./types.js";
+
+export type BodyData = ReturnType<typeof transformBody>;
+
+/**
+ * Transform a Garmin body composition record into a Soma Body document shape.
+ *
+ * @param body - The Garmin body composition data from the Health API
+ * @returns Soma Body fields (without connectionId/userId)
+ */
+export function transformBody(body: GarminBodyComposition) {
+  const measurementMs = body.measurementTimeInSeconds * 1000;
+  const timestamp = new Date(measurementMs).toISOString();
+
+  return {
+    metadata: {
+      start_time: timestamp,
+      end_time: timestamp,
+    },
+
+    measurements_data: buildMeasurementsData(body, timestamp),
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildMeasurementsData(
+  body: GarminBodyComposition,
+  timestamp: string,
+) {
+  if (
+    body.weightInGrams == null &&
+    body.bodyFatInPercent == null &&
+    body.bodyMassIndex == null &&
+    body.muscleMassInGrams == null &&
+    body.boneMassInGrams == null &&
+    body.bodyWaterInPercent == null
+  ) {
+    return undefined;
+  }
+
+  return {
+    measurements: [
+      {
+        measurement_time: timestamp,
+        weight_kg:
+          body.weightInGrams != null ? body.weightInGrams / 1000 : undefined,
+        BMI: body.bodyMassIndex,
+        bodyfat_percentage: body.bodyFatInPercent,
+        muscle_mass_g: body.muscleMassInGrams,
+        bone_mass_g: body.boneMassInGrams,
+        water_percentage: body.bodyWaterInPercent,
+      },
+    ],
+  };
+}

package/src/garmin/client.ts

@@ -0,0 +1,254 @@
+// ─── Garmin Health API Client ────────────────────────────────────────────────
+// Lightweight, fetch-based client for the Garmin Health API.
+// Every request is signed with OAuth 1.0a using the consumer and user tokens.
+// Uses the Web Crypto API for HMAC-SHA1 signing and global `fetch`.
+
+import type {
+  GarminActivity,
+  GarminDailySummary,
+  GarminSleep,
+  GarminBodyComposition,
+  GarminMenstrualCycleData,
+} from "./types.js";
+import {
+  generateNonce,
+  getTimestamp,
+  buildOAuthSignature,
+  buildOAuthHeader,
+} from "./auth.js";
+
+const DEFAULT_BASE_URL = "https://apis.garmin.com";
+
+export interface GarminClientOptions {
+  /** Your application's consumer key (from Garmin Developer Portal). */
+  consumerKey: string;
+  /** Your application's consumer secret. */
+  consumerSecret: string;
+  /** The user's permanent OAuth access token. */
+  accessToken: string;
+  /** The user's permanent OAuth token secret. */
+  tokenSecret: string;
+  /**
+   * Base URL of the Garmin Health API.
+   * Defaults to `https://apis.garmin.com`.
+   */
+  baseUrl?: string;
+}
+
+/**
+ * A lightweight client for the Garmin Health API.
+ *
+ * All requests are signed with OAuth 1.0a. Time-range parameters
+ * use Unix epoch seconds for `uploadStartTimeInSeconds` and
+ * `uploadEndTimeInSeconds`.
+ *
+ * @example
+ * ```ts
+ * const client = new GarminClient({
+ *   consumerKey: "your_key",
+ *   consumerSecret: "your_secret",
+ *   accessToken: "user_token",
+ *   tokenSecret: "user_secret",
+ * });
+ *
+ * const dailies = await client.getDailies({
+ *   uploadStartTimeInSeconds: startEpoch,
+ *   uploadEndTimeInSeconds: endEpoch,
+ * });
+ * ```
+ */
+export class GarminClient {
+  private readonly consumerKey: string;
+  private readonly consumerSecret: string;
+  private readonly accessToken: string;
+  private readonly tokenSecret: string;
+  private readonly baseUrl: string;
+
+  constructor(opts: GarminClientOptions) {
+    this.consumerKey = opts.consumerKey;
+    this.consumerSecret = opts.consumerSecret;
+    this.accessToken = opts.accessToken;
+    this.tokenSecret = opts.tokenSecret;
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  }
+
+  // ─── Daily Summaries ────────────────────────────────────────────────────
+
+  /**
+   * Get daily wellness summaries.
+   *
+   * Garmin API: `GET /wellness-api/rest/dailies`
+   */
+  async getDailies(params: TimeRangeParams): Promise<GarminDailySummary[]> {
+    return this.get<GarminDailySummary[]>(
+      "/wellness-api/rest/dailies",
+      timeRangeQuery(params),
+    );
+  }
+
+  // ─── Activities ─────────────────────────────────────────────────────────
+
+  /**
+   * Get activity summaries.
+   *
+   * Garmin API: `GET /wellness-api/rest/activities`
+   */
+  async getActivities(params: TimeRangeParams): Promise<GarminActivity[]> {
+    return this.get<GarminActivity[]>(
+      "/wellness-api/rest/activities",
+      timeRangeQuery(params),
+    );
+  }
+
+  // ─── Sleep ──────────────────────────────────────────────────────────────
+
+  /**
+   * Get sleep summaries.
+   *
+   * Garmin API: `GET /wellness-api/rest/sleeps`
+   */
+  async getSleeps(params: TimeRangeParams): Promise<GarminSleep[]> {
+    return this.get<GarminSleep[]>(
+      "/wellness-api/rest/sleeps",
+      timeRangeQuery(params),
+    );
+  }
+
+  // ─── Body Composition ─────────────────────────────────────────────────
+
+  /**
+   * Get body composition summaries.
+   *
+   * Garmin API: `GET /wellness-api/rest/bodyComps`
+   */
+  async getBodyCompositions(
+    params: TimeRangeParams,
+  ): Promise<GarminBodyComposition[]> {
+    return this.get<GarminBodyComposition[]>(
+      "/wellness-api/rest/bodyComps",
+      timeRangeQuery(params),
+    );
+  }
+
+  // ─── Menstrual Cycle ──────────────────────────────────────────────────
+
+  /**
+   * Get menstrual cycle data.
+   *
+   * Garmin API: `GET /wellness-api/rest/menstrualCycleData`
+   */
+  async getMenstrualCycleData(
+    params: TimeRangeParams,
+  ): Promise<GarminMenstrualCycleData[]> {
+    return this.get<GarminMenstrualCycleData[]>(
+      "/wellness-api/rest/menstrualCycleData",
+      timeRangeQuery(params),
+    );
+  }
+
+  // ─── Backfill ─────────────────────────────────────────────────────────
+
+  /**
+   * Request historical data backfill from Garmin.
+   *
+   * Garmin processes backfill requests asynchronously and delivers data
+   * via the configured webhook endpoint. Maximum range: 90 days per request.
+   *
+   * @param summaryType - The data type to backfill (e.g., "dailies", "activities", "sleeps", "bodyComps")
+   * @param params - Time range for the backfill
+   */
+  async requestBackfill(
+    summaryType: string,
+    params: TimeRangeParams,
+  ): Promise<void> {
+    const query = timeRangeQuery(params);
+    await this.get(
+      `/wellness-api/rest/backfill/${summaryType}`,
+      query,
+    );
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────
+
+  private async get<T>(
+    path: string,
+    queryParams?: Record<string, string>,
+  ): Promise<T> {
+    const fullUrl = `${this.baseUrl}${path}`;
+    const qs = queryParams
+      ? `?${new URLSearchParams(queryParams).toString()}`
+      : "";
+    const requestUrl = `${fullUrl}${qs}`;
+
+    const nonce = generateNonce();
+    const timestamp = getTimestamp();
+
+    const oauthParams: Record<string, string> = {
+      oauth_consumer_key: this.consumerKey,
+      oauth_nonce: nonce,
+      oauth_signature_method: "HMAC-SHA1",
+      oauth_timestamp: timestamp,
+      oauth_token: this.accessToken,
+      oauth_version: "1.0",
+    };
+
+    // OAuth signature must include both OAuth params and query params
+    const allParams = { ...oauthParams, ...(queryParams ?? {}) };
+    const signature = await buildOAuthSignature(
+      "GET",
+      fullUrl,
+      allParams,
+      this.consumerSecret,
+      this.tokenSecret,
+    );
+    oauthParams.oauth_signature = signature;
+
+    const response = await fetch(requestUrl, {
+      method: "GET",
+      headers: {
+        Authorization: buildOAuthHeader(oauthParams),
+        Accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new GarminApiError(
+        `Garmin API error: ${response.status} ${response.statusText}`,
+        response.status,
+        body,
+      );
+    }
+
+    return (await response.json()) as T;
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+export interface TimeRangeParams {
+  /** Start of the time range as Unix epoch seconds. */
+  uploadStartTimeInSeconds: number;
+  /** End of the time range as Unix epoch seconds. */
+  uploadEndTimeInSeconds: number;
+}
+
+function timeRangeQuery(params: TimeRangeParams): Record<string, string> {
+  return {
+    uploadStartTimeInSeconds: String(params.uploadStartTimeInSeconds),
+    uploadEndTimeInSeconds: String(params.uploadEndTimeInSeconds),
+  };
+}
+
+// ─── Error ────────────────────────────────────────────────────────────────────
+
+export class GarminApiError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly body: string,
+  ) {
+    super(message);
+    this.name = "GarminApiError";
+  }
+}