@nativesquare/soma 0.2.0 → 0.4.0

package/dist/garmin/auth.js

@@ -0,0 +1,155 @@
+// ─── 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`.
+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() {
+    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() {
+    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) {
+    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, url, params, consumerSecret, tokenSecret = "") {
+    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) {
+    const entries = Object.entries(params)
+        .map(([key, value]) => `${percentEncode(key)}="${percentEncode(value)}"`)
+        .join(", ");
+    return `OAuth ${entries}`;
+}
+/**
+ * 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) {
+    const url = `${OAUTH_BASE_URL}/oauth-service/oauth/request_token`;
+    const nonce = generateNonce();
+    const timestamp = getTimestamp();
+    const oauthParams = {
+        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,
+    };
+}
+/**
+ * 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) {
+    const url = `${OAUTH_BASE_URL}/oauth-service/oauth/access_token`;
+    const nonce = generateNonce();
+    const timestamp = getTimestamp();
+    const oauthParams = {
+        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 };
+}
+//# sourceMappingURL=auth.js.map

package/dist/garmin/auth.js.map

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

package/dist/garmin/body.d.ts

@@ -0,0 +1,26 @@
+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 declare function transformBody(body: GarminBodyComposition): {
+    metadata: {
+        start_time: string;
+        end_time: string;
+    };
+    measurements_data: {
+        measurements: {
+            measurement_time: string;
+            weight_kg: number | undefined;
+            BMI: number | undefined;
+            bodyfat_percentage: number | undefined;
+            muscle_mass_g: number | undefined;
+            bone_mass_g: number | undefined;
+            water_percentage: number | undefined;
+        }[];
+    } | undefined;
+};
+//# sourceMappingURL=body.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"body.d.ts","sourceRoot":"","sources":["../../src/garmin/body.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AAExD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,qBAAqB;;;;;;;;;;;;;;;;EAYxD"}

package/dist/garmin/body.js

@@ -0,0 +1,44 @@
+// ─── Body Transformer ────────────────────────────────────────────────────────
+// Transforms Garmin body composition data into the Soma Body schema shape.
+/**
+ * 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) {
+    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, timestamp) {
+    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,
+            },
+        ],
+    };
+}
+//# sourceMappingURL=body.js.map

package/dist/garmin/body.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body.js","sourceRoot":"","sources":["../../src/garmin/body.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,2EAA2E;AAM3E;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAA2B;IACvD,MAAM,aAAa,GAAG,IAAI,CAAC,wBAAwB,GAAG,IAAI,CAAC;IAC3D,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE,CAAC;IAExD,OAAO;QACL,QAAQ,EAAE;YACR,UAAU,EAAE,SAAS;YACrB,QAAQ,EAAE,SAAS;SACpB;QAED,iBAAiB,EAAE,qBAAqB,CAAC,IAAI,EAAE,SAAS,CAAC;KAC1D,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF,SAAS,qBAAqB,CAC5B,IAA2B,EAC3B,SAAiB;IAEjB,IACE,IAAI,CAAC,aAAa,IAAI,IAAI;QAC1B,IAAI,CAAC,gBAAgB,IAAI,IAAI;QAC7B,IAAI,CAAC,aAAa,IAAI,IAAI;QAC1B,IAAI,CAAC,iBAAiB,IAAI,IAAI;QAC9B,IAAI,CAAC,eAAe,IAAI,IAAI;QAC5B,IAAI,CAAC,kBAAkB,IAAI,IAAI,EAC/B,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO;QACL,YAAY,EAAE;YACZ;gBACE,gBAAgB,EAAE,SAAS;gBAC3B,SAAS,EACP,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS;gBACpE,GAAG,EAAE,IAAI,CAAC,aAAa;gBACvB,kBAAkB,EAAE,IAAI,CAAC,gBAAgB;gBACzC,aAAa,EAAE,IAAI,CAAC,iBAAiB;gBACrC,WAAW,EAAE,IAAI,CAAC,eAAe;gBACjC,gBAAgB,EAAE,IAAI,CAAC,kBAAkB;aAC1C;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/garmin/client.d.ts

@@ -0,0 +1,99 @@
+import type { GarminActivity, GarminDailySummary, GarminSleep, GarminBodyComposition, GarminMenstrualCycleData } from "./types.js";
+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 declare class GarminClient {
+    private readonly consumerKey;
+    private readonly consumerSecret;
+    private readonly accessToken;
+    private readonly tokenSecret;
+    private readonly baseUrl;
+    constructor(opts: GarminClientOptions);
+    /**
+     * Get daily wellness summaries.
+     *
+     * Garmin API: `GET /wellness-api/rest/dailies`
+     */
+    getDailies(params: TimeRangeParams): Promise<GarminDailySummary[]>;
+    /**
+     * Get activity summaries.
+     *
+     * Garmin API: `GET /wellness-api/rest/activities`
+     */
+    getActivities(params: TimeRangeParams): Promise<GarminActivity[]>;
+    /**
+     * Get sleep summaries.
+     *
+     * Garmin API: `GET /wellness-api/rest/sleeps`
+     */
+    getSleeps(params: TimeRangeParams): Promise<GarminSleep[]>;
+    /**
+     * Get body composition summaries.
+     *
+     * Garmin API: `GET /wellness-api/rest/bodyComps`
+     */
+    getBodyCompositions(params: TimeRangeParams): Promise<GarminBodyComposition[]>;
+    /**
+     * Get menstrual cycle data.
+     *
+     * Garmin API: `GET /wellness-api/rest/menstrualCycleData`
+     */
+    getMenstrualCycleData(params: TimeRangeParams): Promise<GarminMenstrualCycleData[]>;
+    /**
+     * 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
+     */
+    requestBackfill(summaryType: string, params: TimeRangeParams): Promise<void>;
+    private get;
+}
+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;
+}
+export declare class GarminApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/garmin/client.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAUpB,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,IAAI,EAAE,mBAAmB;IAUrC;;;;OAIG;IACG,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IASxE;;;;OAIG;IACG,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IASvE;;;;OAIG;IACG,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAShE;;;;OAIG;IACG,mBAAmB,CACvB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,qBAAqB,EAAE,CAAC;IASnC;;;;OAIG;IACG,qBAAqB,CACzB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,wBAAwB,EAAE,CAAC;IAStC;;;;;;;;OAQG;IACG,eAAe,CACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,IAAI,CAAC;YAUF,GAAG;CAoDlB;AAID,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,wBAAwB,EAAE,MAAM,CAAC;IACjC,mDAAmD;IACnD,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAWD,qBAAa,cAAe,SAAQ,KAAK;aAGrB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBAF5B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAK/B"}

package/dist/garmin/client.js

@@ -0,0 +1,153 @@
+// ─── 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 { generateNonce, getTimestamp, buildOAuthSignature, buildOAuthHeader, } from "./auth.js";
+const DEFAULT_BASE_URL = "https://apis.garmin.com";
+/**
+ * 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 {
+    consumerKey;
+    consumerSecret;
+    accessToken;
+    tokenSecret;
+    baseUrl;
+    constructor(opts) {
+        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) {
+        return this.get("/wellness-api/rest/dailies", timeRangeQuery(params));
+    }
+    // ─── Activities ─────────────────────────────────────────────────────────
+    /**
+     * Get activity summaries.
+     *
+     * Garmin API: `GET /wellness-api/rest/activities`
+     */
+    async getActivities(params) {
+        return this.get("/wellness-api/rest/activities", timeRangeQuery(params));
+    }
+    // ─── Sleep ──────────────────────────────────────────────────────────────
+    /**
+     * Get sleep summaries.
+     *
+     * Garmin API: `GET /wellness-api/rest/sleeps`
+     */
+    async getSleeps(params) {
+        return this.get("/wellness-api/rest/sleeps", timeRangeQuery(params));
+    }
+    // ─── Body Composition ─────────────────────────────────────────────────
+    /**
+     * Get body composition summaries.
+     *
+     * Garmin API: `GET /wellness-api/rest/bodyComps`
+     */
+    async getBodyCompositions(params) {
+        return this.get("/wellness-api/rest/bodyComps", timeRangeQuery(params));
+    }
+    // ─── Menstrual Cycle ──────────────────────────────────────────────────
+    /**
+     * Get menstrual cycle data.
+     *
+     * Garmin API: `GET /wellness-api/rest/menstrualCycleData`
+     */
+    async getMenstrualCycleData(params) {
+        return this.get("/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, params) {
+        const query = timeRangeQuery(params);
+        await this.get(`/wellness-api/rest/backfill/${summaryType}`, query);
+    }
+    // ─── Internal ─────────────────────────────────────────────────────────
+    async get(path, queryParams) {
+        const fullUrl = `${this.baseUrl}${path}`;
+        const qs = queryParams
+            ? `?${new URLSearchParams(queryParams).toString()}`
+            : "";
+        const requestUrl = `${fullUrl}${qs}`;
+        const nonce = generateNonce();
+        const timestamp = getTimestamp();
+        const oauthParams = {
+            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());
+    }
+}
+function timeRangeQuery(params) {
+    return {
+        uploadStartTimeInSeconds: String(params.uploadStartTimeInSeconds),
+        uploadEndTimeInSeconds: String(params.uploadEndTimeInSeconds),
+    };
+}
+// ─── Error ────────────────────────────────────────────────────────────────────
+export class GarminApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "GarminApiError";
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/garmin/client.js.map

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

package/dist/garmin/daily.d.ts

@@ -0,0 +1,74 @@
+import type { GarminDailySummary } from "./types.js";
+export type DailyData = ReturnType<typeof transformDaily>;
+/**
+ * Transform a Garmin daily summary into a Soma Daily document shape.
+ *
+ * @param daily - The Garmin daily summary from the Health API
+ * @returns Soma Daily fields (without connectionId/userId)
+ */
+export declare function transformDaily(daily: GarminDailySummary): {
+    metadata: {
+        start_time: string;
+        end_time: string;
+        upload_type: number;
+    };
+    active_durations_data: {
+        activity_seconds: number | undefined;
+        moderate_intensity_seconds: number | undefined;
+        vigorous_intensity_seconds: number | undefined;
+    } | undefined;
+    calories_data: {
+        net_activity_calories: number | undefined;
+        BMR_calories: number | undefined;
+        total_burned_calories: number | undefined;
+    } | undefined;
+    distance_data: {
+        distance_meters: number | undefined;
+        steps: number | undefined;
+        floors_climbed: number | undefined;
+    } | undefined;
+    heart_rate_data: {
+        summary: {
+            avg_hr_bpm: number | undefined;
+            max_hr_bpm: number | undefined;
+            min_hr_bpm: number | undefined;
+            resting_hr_bpm: number | undefined;
+        } | undefined;
+        detailed: {
+            hr_samples: ({
+                timestamp: string;
+            } & {
+                bpm: number;
+            })[];
+        } | undefined;
+    } | undefined;
+    oxygen_data: {
+        avg_saturation_percentage: number | undefined;
+        saturation_samples: ({
+            timestamp: string;
+        } & {
+            percentage: number;
+        })[] | undefined;
+    } | undefined;
+    stress_data: {
+        avg_stress_level: number | undefined;
+        max_stress_level: number | undefined;
+        stress_duration_seconds: number | undefined;
+        rest_stress_duration_seconds: number | undefined;
+        activity_stress_duration_seconds: number | undefined;
+        low_stress_duration_seconds: number | undefined;
+        medium_stress_duration_seconds: number | undefined;
+        high_stress_duration_seconds: number | undefined;
+        samples: ({
+            timestamp: string;
+        } & {
+            level: number;
+        })[] | undefined;
+        body_battery_samples: ({
+            timestamp: string;
+        } & {
+            level: number;
+        })[] | undefined;
+    } | undefined;
+};
+//# sourceMappingURL=daily.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"daily.d.ts","sourceRoot":"","sources":["../../src/garmin/daily.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BA8LlC,MAAM;;;;;;;;;uBAAN,MAAM;;;;;;;;;;;;;;;uBAAN,MAAM;;;;;uBAAN,MAAM;;;;;EAvK3B"}