@murphai/murph 1.3.0 → 1.3.1

package/node_modules/@murphai/device-syncd/dist/providers/junction-client.js

@@ -1,18 +1,48 @@
+import { ActivityClient } from "@junction-api/sdk/activity";
+import { BodyClient } from "@junction-api/sdk/body";
+import { ElectrocardiogramClient } from "@junction-api/sdk/electrocardiogram";
+import { IntrospectClient, } from "@junction-api/sdk/introspect";
+import { LinkClient, } from "@junction-api/sdk/link";
+import { MealClient } from "@junction-api/sdk/meal";
+import { MenstrualCycleClient } from "@junction-api/sdk/menstrualCycle";
+import { ProfileClient } from "@junction-api/sdk/profile";
+import { SleepClient } from "@junction-api/sdk/sleep";
+import { SleepCycleClient } from "@junction-api/sdk/sleepCycle";
+import { UserClient, } from "@junction-api/sdk/user";
+import { VitalsClient } from "@junction-api/sdk/vitals";
+import { WorkoutsClient } from "@junction-api/sdk/workouts";
+import { resolveJunctionTimeseriesResourcePolicy } from "@murphai/contracts";
 import { resolveJunctionOrigin } from "@murphai/importers/device-providers/junction-origin";
-import { normalizeJunctionProviderSlug } from "../config/connect-routes.js";
+import { normalizeJunctionProviderSlug, resolveJunctionDeviceConnectRouteByProviderSlug, } from "../config/connect-routes.js";
 import { deviceSyncError, isDeviceSyncError } from "../errors.js";
 import { normalizeString } from "../shared.js";
 import { buildProviderApiError as buildProviderApiErrorBase } from "./shared-oauth.js";
 import { createProviderRequestAbortSignal, isProviderParentAbortError, isProviderTimeoutError, normalizeProviderAbortError, throwIfProviderRequestAborted, waitForProviderRetryDelay, } from "./request-abort.js";
-import { buildProviderRequestDiagnostics, extractProviderQueryParameterNames, } from "./provider-diagnostics.js";
+import { buildProviderRequestDiagnostics } from "./provider-diagnostics.js";
 import { assertValidJunctionClientConfig, resolveJunctionBaseUrl, } from "../config/junction-client-config.js";
 export { assertValidJunctionClientConfig, resolveJunctionBaseUrl, } from "../config/junction-client-config.js";
+const JUNCTION_SDK_PROVIDERS = Object.freeze([
+    "oura", "fitbit", "garmin", "whoop", "strava", "renpho", "peloton", "wahoo",
+    "zwift", "freestyle_libre", "abbott_libreview", "tandem_source", "freestyle_libre_ble",
+    "eight_sleep", "withings", "apple_health_kit", "manual", "ihealth", "google_fit",
+    "beurer_api", "beurer_ble", "omron", "omron_ble", "onetouch_ble", "accuchek_ble",
+    "contour_ble", "dexcom", "dexcom_v3", "hammerhead", "my_fitness_pal", "health_connect",
+    "samsung_health", "polar", "cronometer", "kardia", "whoop_v2", "ultrahuman",
+    "my_fitness_pal_v2", "map_my_fitness", "runkeeper",
+]);
+const JUNCTION_SDK_OAUTH_PROVIDERS = Object.freeze([
+    "oura", "fitbit", "garmin", "strava", "wahoo", "ihealth", "withings", "google_fit",
+    "dexcom_v3", "polar", "cronometer", "omron", "whoop_v2", "my_fitness_pal_v2",
+    "ultrahuman", "runkeeper",
+]);
 const DEFAULT_TIMEOUT_MS = 15_000;
 const MAX_GET_ATTEMPTS = 3;
 const DEFAULT_RETRY_DELAY_MS = 500;
 const MAX_RETRY_DELAY_MS = 5_000;
 const MAX_COLLECTION_PAGES = 100;
 const MAX_COLLECTION_RECORDS = 25_000;
+export const JUNCTION_MAX_USER_PROVIDERS = 64;
+const MAX_SDK_COMPAT_RESPONSE_BYTES = 32 * 1_024 * 1_024;
 // These summary endpoints declare `start_date`/`end_date` as YYYY-MM-DD dates
 // (not datetimes) in the Junction API reference.
 const JUNCTION_DATE_ONLY_SUMMARY_RESOURCES = new Set(["electrocardiogram", "menstrual_cycle", "sleep_cycle"]);
@@ -35,13 +65,21 @@ export class JunctionClient {
         this.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
     }
     async resolveUser(clientUserId, options = {}) {
-        const payload = await this.requestJson("GET", `/v2/user/resolve/${encodeURIComponent(clientUserId)}`, undefined, { endpointKind: "junction_user_resolve", optional404: true, signal: options.signal ?? null });
+        const payload = await this.requestSdkResource("GET", {
+            endpointKind: "junction_user_resolve",
+            optional404: true,
+            signal: options.signal ?? null,
+        }, (clientOptions, requestOptions) => new UserClient(clientOptions)
+            .getByClientUserId({ clientUserId }, requestOptions));
         return payload ? parseJunctionUser(payload, "Junction resolve user response") : null;
     }
     async createUser(clientUserId, options = {}) {
-        const payload = await this.requestJson("POST", "/v2/user/", {
-            client_user_id: clientUserId,
-        }, { endpointKind: "junction_user_create", signal: options.signal ?? null });
+        const payload = await this.requestSdkResource("POST", {
+            bodyFieldNames: ["client_user_id"],
+            endpointKind: "junction_user_create",
+            signal: options.signal ?? null,
+        }, (clientOptions, requestOptions) => new UserClient(clientOptions)
+            .create({ clientUserId }, requestOptions));
         return parseJunctionUser(payload, "Junction create user response");
     }
     async createOrResolveUser(clientUserId, options = {}) {
@@ -61,18 +99,33 @@ export class JunctionClient {
         }
     }
     async createLinkToken(input) {
-        const body = {
-            user_id: input.userId,
-            redirect_url: input.callbackUrl,
-        };
         const provider = normalizeJunctionProviderSlug(input.provider);
-        if (provider) {
-            body.provider = provider;
+        const sdkProvider = provider ? requireJunctionSdkProvider(provider) : undefined;
+        const providerFilter = input.providerFilter?.map((candidate) => requireJunctionSdkProvider(normalizeRequiredProviderSlug(candidate)));
+        const bodyFieldNames = ["user_id", "redirect_url"];
+        if (sdkProvider) {
+            bodyFieldNames.push("provider");
         }
-        else if (input.providerFilter && input.providerFilter.length > 0) {
-            body.filter_on_providers = [...input.providerFilter];
+        else if (providerFilter && providerFilter.length > 0) {
+            bodyFieldNames.push("filter_on_providers");
         }
-        const payload = await this.requestJson("POST", "/v2/link/token", body, { endpointKind: "junction_link_token_create", signal: input.signal ?? null });
+        const payload = await this.requestSdkResource("POST", {
+            bodyFieldNames,
+            endpointKind: "junction_link_token_create",
+            signal: input.signal ?? null,
+        }, (clientOptions, requestOptions) => {
+            const request = {
+                userId: input.userId,
+                redirectUrl: input.callbackUrl,
+            };
+            if (sdkProvider) {
+                request.provider = sdkProvider;
+            }
+            else if (providerFilter && providerFilter.length > 0) {
+                request.filterOnProviders = providerFilter;
+            }
+            return new LinkClient(clientOptions).token(request, requestOptions);
+        });
         const linkWebUrl = normalizeString(payload.link_web_url) ?? normalizeString(payload.linkWebUrl);
         if (!linkWebUrl) {
             throw deviceSyncError({
@@ -95,8 +148,11 @@ export class JunctionClient {
         if (!normalizedUserId) {
             throw new TypeError("Junction sign-in token creation requires a Junction user id.");
         }
-        const payload = await this.requestJson("POST", `/v2/user/${encodeURIComponent(normalizedUserId)}/sign_in_token`, undefined, { endpointKind: "junction_user_sign_in_token", signal: options.signal ?? null });
-        const signInToken = normalizeString(payload?.sign_in_token) ?? normalizeString(payload?.signInToken);
+        const payload = await this.requestSdkResource("POST", {
+            endpointKind: "junction_user_sign_in_token",
+            signal: options.signal ?? null,
+        }, (clientOptions, requestOptions) => new UserClient(clientOptions).getUserSignInToken({ userId: normalizedUserId }, requestOptions));
+        const signInToken = normalizeString(payload.sign_in_token) ?? normalizeString(payload.signInToken);
         if (!signInToken) {
             throw deviceSyncError({
                 code: "JUNCTION_SIGN_IN_TOKEN_INVALID",
@@ -108,7 +164,17 @@ export class JunctionClient {
         return { signInToken };
     }
     async listUserProviders(userId, options = {}) {
-        const payload = await this.requestJson("GET", `/v2/user/providers/${encodeURIComponent(userId)}`, undefined, { endpointKind: "junction_user_providers", signal: options.signal ?? null });
+        const payload = await this.requestSdkResource("GET", {
+            endpointKind: "junction_user_providers",
+            signal: options.signal ?? null,
+            ...(options.collectionWorkLimit
+                ? {
+                    maxAttempts: options.collectionWorkLimit.maxAttemptsPerPage,
+                    timeoutMs: options.collectionWorkLimit.requestTimeoutMs,
+                }
+                : {}),
+        }, (clientOptions, requestOptions) => new UserClient(clientOptions)
+            .getConnectedProviders({ userId }, requestOptions));
         return parseJunctionProviders(payload);
     }
     async deregisterProvider(input) {
@@ -120,43 +186,107 @@ export class JunctionClient {
         if (!userId) {
             throw new TypeError("Junction provider deregistration requires a Junction user id.");
         }
-        await this.requestJson("DELETE", `/v2/user/${encodeURIComponent(userId)}/${encodeURIComponent(providerSlug)}`, undefined, { endpointKind: "junction_user_provider_deregister", signal: input.signal ?? null });
+        await this.requestSdkResource("DELETE", { endpointKind: "junction_user_provider_deregister", signal: input.signal ?? null }, (clientOptions, requestOptions) => new UserClient(clientOptions).deregisterProvider({
+            provider: requireJunctionSdkProvider(providerSlug),
+            userId,
+        }, requestOptions));
     }
     async listUserDevices(userId, options = {}) {
-        const payload = await this.requestJson("GET", `/v2/user/${encodeURIComponent(userId)}/device`, undefined, { endpointKind: "junction_user_devices", signal: options.signal ?? null });
+        const payload = await this.requestSdkResource("GET", { endpointKind: "junction_user_devices", signal: options.signal ?? null }, (clientOptions, requestOptions) => new UserClient(clientOptions)
+            .getDevices({ userId }, requestOptions));
         return extractCollectionRecords(payload);
     }
     async listSummary(input) {
         if (input.resource === "profile") {
             return this.listProfileSummary(input);
         }
-        return this.fetchWindowedCollection(`/v2/summary/${encodeURIComponent(input.resource)}/${encodeURIComponent(input.userId)}`, {
-            ...input,
-            dateQueryFormat: resolveJunctionSummaryDateQueryFormat(input),
-        }, { endpointKind: "junction_summary_collection" });
+        return this.fetchWindowedCollection({ ...input, dateQueryFormat: resolveJunctionSummaryDateQueryFormat(input) }, extractCollectionRecords, (cursor) => this.requestSummaryPage(input, cursor));
     }
     async listProfileSummary(input) {
-        const search = new URLSearchParams();
-        const sourceProviderSlug = normalizeSourceSlug(input.sourceProviderSlug);
-        if (sourceProviderSlug) {
-            search.set("provider", sourceProviderSlug);
-        }
-        const suffix = search.size > 0 ? `?${search.toString()}` : "";
-        const payload = await this.requestJson("GET", `/v2/summary/profile/${encodeURIComponent(input.userId)}${suffix}`, undefined, { endpointKind: "junction_summary_collection", signal: input.signal ?? null });
+        const provider = optionalJunctionSdkProvider(input.sourceProviderSlug);
+        const payload = await this.requestSdkResource("GET", {
+            endpointKind: "junction_summary_collection",
+            queryParameterNames: provider ? ["provider"] : [],
+            signal: input.signal ?? null,
+            ...(input.collectionWorkLimit
+                ? {
+                    maxAttempts: input.collectionWorkLimit.maxAttemptsPerPage,
+                    timeoutMs: input.collectionWorkLimit.requestTimeoutMs,
+                }
+                : {}),
+        }, (clientOptions, requestOptions) => {
+            const request = { userId: input.userId };
+            if (provider) {
+                request.provider = provider;
+            }
+            return new ProfileClient(clientOptions).get(request, requestOptions);
+        });
         return extractCollectionRecords(payload, "profile");
     }
     async listTimeseries(input) {
-        const apiResource = resolveJunctionTimeseriesApiResource(input.resource);
-        return this.fetchWindowedCollection(`/v2/timeseries/${encodeURIComponent(input.userId)}/${encodeURIComponent(apiResource)}/grouped`, input, {
-            endpointKind: "junction_timeseries_collection",
-            extractRecords: extractTimeseriesRecords,
-        });
+        const policy = resolveJunctionTimeseriesResourcePolicy(input.resource);
+        if (policy?.fetchMode === "workout_stream") {
+            throw new TypeError("Junction workout_stream uses the dedicated workout stream endpoint.");
+        }
+        return this.fetchWindowedCollection({
+            ...input,
+            maxRecords: policy?.maxSamplesPerWindow === undefined
+                ? input.maxRecords
+                : Math.min(input.maxRecords ?? policy.maxSamplesPerWindow, policy.maxSamplesPerWindow),
+        }, input.requireStructurallyCompleteCollection
+            ? (payload, resource) => extractStructurallyCompleteTimeseriesRecords(payload, resource, normalizeSourceSlug(input.sourceProviderSlug))
+            : extractTimeseriesRecords, (cursor) => this.requestTimeseriesPage(input, cursor));
+    }
+    async getWorkoutStream(input) {
+        const workoutId = normalizeString(input.workoutId);
+        if (!workoutId) {
+            throw new TypeError("Junction workout stream requires a workout id.");
+        }
+        return this.requestSdkResource("GET", {
+            endpointKind: "junction_workout_stream",
+            signal: input.signal ?? null,
+            ...(input.collectionWorkLimit
+                ? {
+                    maxAttempts: input.collectionWorkLimit.maxAttemptsPerPage,
+                    timeoutMs: input.collectionWorkLimit.requestTimeoutMs,
+                }
+                : {}),
+        }, (clientOptions, requestOptions) => new WorkoutsClient(clientOptions)
+            .getByWorkoutId({ workoutId }, requestOptions));
     }
     async introspectResources(input) {
-        return this.requestJson("GET", `/v2/introspect/resources?${buildJunctionIntrospectionSearch(input).toString()}`, undefined, { endpointKind: "junction_introspect_resources", signal: input.signal ?? null });
+        const provider = optionalJunctionSdkProvider(input.sourceProviderSlug);
+        return this.requestSdkResource("GET", {
+            endpointKind: "junction_introspect_resources",
+            queryParameterNames: ["user_id", "user_limit", ...(provider ? ["provider"] : [])],
+            signal: input.signal ?? null,
+        }, (clientOptions, requestOptions) => {
+            const request = {
+                userId: input.userId,
+                userLimit: input.userLimit ?? 1,
+            };
+            if (provider) {
+                request.provider = provider;
+            }
+            return new IntrospectClient(clientOptions).getUserResources(request, requestOptions);
+        });
     }
     async introspectHistoricalPull(input) {
-        const payload = await this.requestJson("GET", `/v2/introspect/historical_pull?${buildJunctionIntrospectionSearch(input).toString()}`, undefined, { endpointKind: "junction_introspect_historical_pull", signal: input.signal ?? null });
+        const provider = optionalJunctionSdkProvider(input.sourceProviderSlug);
+        const payload = await this.requestSdkResource("GET", {
+            endpointKind: "junction_introspect_historical_pull",
+            queryParameterNames: ["user_id", "user_limit", ...(provider ? ["provider"] : [])],
+            signal: input.signal ?? null,
+        }, (clientOptions, requestOptions) => {
+            const request = {
+                userId: input.userId,
+                userLimit: input.userLimit ?? 1,
+            };
+            if (provider) {
+                request.provider = provider;
+            }
+            return new IntrospectClient(clientOptions).getUserHistoricalPulls(request, requestOptions);
+        });
         return parseJunctionHistoricalPullSnapshot(payload, input.userId, input.sourceProviderSlug ?? null);
     }
     /**
@@ -175,22 +305,21 @@ export class JunctionClient {
         if (!sourceProviderSlug) {
             throw new TypeError("Junction historical pull triggers require a provider slug.");
         }
-        const userIds = [
-            ...new Set(input.userIds
+        const userIds = [...new Set(input.userIds
                 .map((userId) => normalizeString(userId))
-                .filter((userId) => typeof userId === "string")),
-        ];
+                .filter((userId) => typeof userId === "string"))];
         if (userIds.length === 0) {
             throw new TypeError("Junction historical pull triggers require at least one user id.");
         }
         try {
-            await this.requestJson("POST", "/v2/link/bulk_trigger_historical_pull", {
-                provider: sourceProviderSlug,
-                user_ids: userIds,
-            }, {
+            await this.requestSdkResource("POST", {
+                bodyFieldNames: ["provider", "user_ids"],
                 endpointKind: "junction_bulk_trigger_historical_pull",
                 signal: input.signal ?? null,
-            });
+            }, (clientOptions, requestOptions) => new LinkClient(clientOptions).bulkTriggerHistoricalPull({
+                provider: requireJunctionSdkOAuthProvider(sourceProviderSlug),
+                userIds,
+            }, requestOptions));
             return { accepted: true, endpointUnavailable: false };
         }
         catch (error) {
@@ -201,127 +330,322 @@ export class JunctionClient {
         }
     }
     async refreshUserData(input) {
-        const search = new URLSearchParams();
-        const timeoutSeconds = normalizeJunctionRefreshTimeoutSeconds(input.timeoutSeconds);
-        if (timeoutSeconds !== null) {
-            search.set("timeout", String(timeoutSeconds));
-        }
-        const suffix = search.size > 0 ? `?${search.toString()}` : "";
-        return this.requestJson("POST", `/v2/user/refresh/${encodeURIComponent(input.userId)}${suffix}`, undefined, { endpointKind: "junction_user_refresh", signal: input.signal ?? null });
+        const timeout = normalizeJunctionRefreshTimeoutSeconds(input.timeoutSeconds);
+        return this.requestSdkResource("POST", {
+            endpointKind: "junction_user_refresh",
+            queryParameterNames: timeout === null ? [] : ["timeout"],
+            signal: input.signal ?? null,
+        }, (clientOptions, requestOptions) => {
+            const request = { userId: input.userId };
+            if (timeout !== null) {
+                request.timeout = timeout;
+            }
+            return new UserClient(clientOptions).refresh(request, requestOptions);
+        });
     }
-    async fetchWindowedCollection(path, input, options = {}) {
+    async fetchWindowedCollection(input, extractRecords, requestPage) {
         const records = [];
         let cursor = null;
         let pages = 0;
-        const extractRecords = options.extractRecords ?? extractCollectionRecords;
+        const pageLimit = input.collectionWorkLimit?.maxPages ?? MAX_COLLECTION_PAGES;
         do {
-            if (pages >= MAX_COLLECTION_PAGES) {
+            if (pages >= pageLimit) {
                 throw deviceSyncError({
-                    code: "JUNCTION_API_PAGINATION_LIMIT",
-                    message: `Junction ${input.resource} response exceeded the configured page limit.`,
+                    code: input.collectionWorkLimit
+                        ? "JUNCTION_API_WINDOW_TOO_LARGE"
+                        : "JUNCTION_API_PAGINATION_LIMIT",
+                    message: `Junction ${input.resource} response exceeded the page budget for one complete window.`,
                     retryable: true,
                     httpStatus: 502,
                 });
             }
-            const dateQueryFormat = input.dateQueryFormat ?? "datetime";
-            const search = new URLSearchParams({
-                start_date: toDateParameter(input.windowStart, dateQueryFormat, "start"),
-                end_date: toDateParameter(input.windowEnd, dateQueryFormat, "end"),
-            });
-            const sourceProviderSlug = normalizeSourceSlug(input.sourceProviderSlug);
-            if (sourceProviderSlug) {
-                search.set("provider", sourceProviderSlug);
+            const payload = await requestPage(cursor);
+            const maxRecords = input.maxRecords ?? MAX_COLLECTION_RECORDS;
+            if (!Number.isSafeInteger(maxRecords) || maxRecords < 1) {
+                throw new TypeError("Junction collection record limit must be a positive integer.");
             }
-            if (cursor) {
-                search.set("next_cursor", cursor);
+            for (const record of extractRecords(payload, input.resource)) {
+                if (records.length >= maxRecords) {
+                    throw deviceSyncError({
+                        code: "JUNCTION_API_RECORD_LIMIT",
+                        message: `Junction ${input.resource} response exceeded the configured record limit.`,
+                        retryable: true,
+                        httpStatus: 502,
+                    });
+                }
+                records.push(record);
             }
-            const payload = await this.requestJson("GET", `${path}?${search.toString()}`, undefined, { endpointKind: options.endpointKind, signal: input.signal ?? null });
-            records.push(...extractRecords(payload, input.resource));
             pages += 1;
-            if (records.length > MAX_COLLECTION_RECORDS) {
-                throw deviceSyncError({
-                    code: "JUNCTION_API_RECORD_LIMIT",
-                    message: `Junction ${input.resource} response exceeded the configured record limit.`,
-                    retryable: true,
-                    httpStatus: 502,
-                });
-            }
             cursor = extractNextCursor(payload);
         } while (cursor);
         return records;
     }
-    async requestJson(method, path, body, options = {}) {
-        const attempts = method === "GET" ? MAX_GET_ATTEMPTS : 1;
+    requestSummaryPage(input, cursor) {
+        const format = resolveJunctionSummaryDateQueryFormat(input);
+        const provider = optionalJunctionSdkProvider(input.sourceProviderSlug);
+        const request = {
+            userId: input.userId,
+            startDate: toDateParameter(input.windowStart, format, "start"),
+            endDate: toDateParameter(input.windowEnd, format, "end"),
+        };
+        if (provider) {
+            request.provider = provider;
+        }
+        const queryParameterNames = [
+            "start_date",
+            "end_date",
+            ...(provider ? ["provider"] : []),
+            ...(cursor ? ["next_cursor"] : []),
+        ];
+        return this.requestSdkResource("GET", {
+            endpointKind: "junction_summary_collection",
+            queryParameterNames,
+            signal: input.signal ?? null,
+            ...(input.collectionWorkLimit
+                ? {
+                    maxAttempts: input.collectionWorkLimit.maxAttemptsPerPage,
+                    timeoutMs: input.collectionWorkLimit.requestTimeoutMs,
+                }
+                : {}),
+        }, (clientOptions, requestOptions) => {
+            if (cursor) {
+                requestOptions.queryParams = { next_cursor: cursor };
+            }
+            switch (input.resource) {
+                case "activity": return new ActivityClient(clientOptions).get(request, requestOptions);
+                case "sleep": return new SleepClient(clientOptions).get(request, requestOptions);
+                case "sleep_cycle": return new SleepCycleClient(clientOptions).get(request, requestOptions);
+                case "workouts": return new WorkoutsClient(clientOptions).get(request, requestOptions);
+                case "body": return new BodyClient(clientOptions).get(request, requestOptions);
+                case "meal": return new MealClient(clientOptions).get(request, requestOptions);
+                case "menstrual_cycle": return new MenstrualCycleClient(clientOptions).get(request, requestOptions);
+                case "electrocardiogram": return new ElectrocardiogramClient(clientOptions).get(request, requestOptions);
+                default: throw new TypeError(`Unsupported Junction summary resource: ${input.resource}`);
+            }
+        });
+    }
+    requestTimeseriesPage(input, cursor) {
+        const provider = optionalJunctionSdkProvider(input.sourceProviderSlug);
+        const request = {
+            userId: input.userId,
+            startDate: toDateParameter(input.windowStart, input.dateQueryFormat ?? "datetime", "start"),
+            endDate: toDateParameter(input.windowEnd, input.dateQueryFormat ?? "datetime", "end"),
+        };
+        if (cursor) {
+            request.nextCursor = cursor;
+        }
+        if (provider) {
+            request.provider = provider;
+        }
+        const queryParameterNames = [
+            "start_date",
+            "end_date",
+            ...(provider ? ["provider"] : []),
+            ...(cursor ? ["next_cursor"] : []),
+        ];
+        return this.requestSdkResource("GET", {
+            endpointKind: "junction_timeseries_collection",
+            queryParameterNames,
+            signal: input.signal ?? null,
+        }, (clientOptions, requestOptions) => {
+            const client = new VitalsClient(clientOptions);
+            switch (input.resource) {
+                case "steps": return client.stepsGrouped(request, requestOptions);
+                case "distance": return client.distanceGrouped(request, requestOptions);
+                case "calories_active": return client.caloriesActiveGrouped(request, requestOptions);
+                case "heartrate": return client.heartrateGrouped(request, requestOptions);
+                case "hrv": return client.hrvGrouped(request, requestOptions);
+                case "respiratory_rate": return client.respiratoryRateGrouped(request, requestOptions);
+                case "blood_oxygen": return client.bloodOxygenGrouped(request, requestOptions);
+                case "stress_level": return client.stressLevelGrouped(request, requestOptions);
+                case "vo2_max": return client.vo2MaxGrouped(request, requestOptions);
+                case "weight": return client.bodyWeightGrouped(request, requestOptions);
+                case "body_temperature_delta": return client.bodyTemperatureDeltaGrouped(request, requestOptions);
+                case "body_temperature": return client.bodyTemperatureGrouped(request, requestOptions);
+                case "basal_body_temperature": return client.basalBodyTemperatureGrouped(request, requestOptions);
+                case "caffeine": return client.caffeineGrouped(request, requestOptions);
+                case "water": return client.waterGrouped(request, requestOptions);
+                case "mindfulness_minutes": return client.mindfulnessMinutesGrouped(request, requestOptions);
+                case "heart_rate_recovery_one_minute": return client.heartRateRecoveryOneMinuteGrouped(request, requestOptions);
+                case "sleep_breathing_disturbance": return client.sleepBreathingDisturbanceGrouped(request, requestOptions);
+                case "afib_burden": return client.afibBurdenGrouped(request, requestOptions);
+                case "glucose": return client.glucoseGrouped(request, requestOptions);
+                case "blood_pressure": return client.bloodPressureGrouped(request, requestOptions);
+                case "note": return client.noteGrouped(request, requestOptions);
+                case "body_mass_index": return client.bodyMassIndexGrouped(request, requestOptions);
+                case "carbohydrates": return client.carbohydratesGrouped(request, requestOptions);
+                case "fat": return client.bodyFatGrouped(request, requestOptions);
+                case "forced_expiratory_volume_1": return client.forcedExpiratoryVolume1Grouped(request, requestOptions);
+                case "forced_vital_capacity": return client.forcedVitalCapacityGrouped(request, requestOptions);
+                case "heart_rate_alert": return client.heartRateAlertGrouped(request, requestOptions);
+                case "inhaler_usage": return client.inhalerUsageGrouped(request, requestOptions);
+                case "insulin_injection": return client.insulinInjectionGrouped(request, requestOptions);
+                case "lean_body_mass": return client.leanBodyMassGrouped(request, requestOptions);
+                case "peak_expiratory_flow_rate": return client.peakExpiratoryFlowRateGrouped(request, requestOptions);
+                case "sleep_apnea_alert": return client.sleepApneaAlertGrouped(request, requestOptions);
+                case "waist_circumference": return client.waistCircumferenceGrouped(request, requestOptions);
+                case "calories_basal": return client.caloriesBasalGrouped(request, requestOptions);
+                case "daylight_exposure": return client.daylightExposureGrouped(request, requestOptions);
+                case "fall": return client.fallGrouped(request, requestOptions);
+                case "floors_climbed": return client.floorsClimbedGrouped(request, requestOptions);
+                case "handwashing": return client.handwashingGrouped(request, requestOptions);
+                case "stand_duration": return client.standDurationGrouped(request, requestOptions);
+                case "stand_hour": return client.standHourGrouped(request, requestOptions);
+                case "uv_exposure": return client.uvExposureGrouped(request, requestOptions);
+                case "wheelchair_push": return client.wheelchairPushGrouped(request, requestOptions);
+                case "workout_distance": return client.workoutDistanceGrouped(request, requestOptions);
+                case "workout_duration": return client.workoutDurationGrouped(request, requestOptions);
+                case "workout_swimming_stroke": return client.workoutSwimmingStrokeGrouped(request, requestOptions);
+                case "electrocardiogram_voltage": return client.electrocardiogramVoltageGrouped(request, requestOptions);
+                default: throw new TypeError(`Unsupported Junction timeseries resource: ${input.resource}`);
+            }
+        });
+    }
+    async requestSdkResource(method, options, invoke) {
+        const attempts = method === "GET"
+            ? options.maxAttempts ?? MAX_GET_ATTEMPTS
+            : 1;
         let lastError;
-        const endpointKind = options.endpointKind ?? resolveJunctionEndpointKind(path);
+        const hasJsonBody = (options.bodyFieldNames?.length ?? 0) > 0;
         const requestDiagnostics = buildProviderRequestDiagnostics({
             method,
-            endpointKind,
+            endpointKind: options.endpointKind,
             authKind: "provider_config_api_key_header",
             authPlacement: "headers",
             credentialPresent: Boolean(this.apiKey),
-            contentType: body ? "application_json" : "none",
-            bodyKind: body ? "json_object" : "none",
-            bodyFieldNames: body ? Object.keys(body) : [],
-            queryParameterNames: extractProviderQueryParameterNames(path),
+            contentType: hasJsonBody ? "application_json" : "none",
+            bodyKind: hasJsonBody ? "json_object" : "none",
+            bodyFieldNames: options.bodyFieldNames ?? [],
+            queryParameterNames: options.queryParameterNames ?? [],
         });
         for (let attempt = 1; attempt <= attempts; attempt += 1) {
             throwIfProviderRequestAborted(options.signal);
             const requestAbort = createProviderRequestAbortSignal({
                 signal: options.signal ?? null,
-                timeoutMs: this.requestTimeoutMs,
+                timeoutMs: options.timeoutMs ?? this.requestTimeoutMs,
             });
-            try {
-                const response = await this.fetchImpl(new URL(path.replace(/^\/+/u, ""), this.baseUrl), {
-                    method,
-                    headers: {
-                        "Content-Type": "application/json",
-                        "x-vital-api-key": this.apiKey,
-                    },
-                    body: body ? JSON.stringify(body) : undefined,
+            let capturedResponse = null;
+            let observedOptionalNotFound = false;
+            const sdkFetch = async (input, init) => {
+                const response = await this.fetchImpl(input, {
+                    ...init,
                     signal: requestAbort.signal,
                 });
-                throwIfProviderRequestAborted(requestAbort.signal);
                 if (options.optional404 && response.status === 404) {
+                    observedOptionalNotFound = true;
                     await response.body?.cancel().catch(() => undefined);
+                    return new Response(null, {
+                        headers: response.headers,
+                        status: response.status,
+                        statusText: response.statusText,
+                    });
+                }
+                if (!response.body) {
+                    return response;
+                }
+                if (junctionSdkResponseExceedsDeclaredLimit(response)) {
+                    await response.body.cancel().catch(() => undefined);
+                    throw junctionSdkResponseTooLargeError();
+                }
+                const capture = createJunctionSdkResponseCapture(response);
+                capturedResponse = capture;
+                return new Response(createJunctionSdkBoundedBodyStream(response.body, capture), {
+                    headers: response.headers,
+                    status: response.status,
+                    statusText: response.statusText,
+                });
+            };
+            const timeoutInSeconds = (options.timeoutMs ?? this.requestTimeoutMs) / 1_000;
+            const clientOptions = {
+                apiKey: this.apiKey,
+                baseUrl: this.baseUrl,
+                fetch: sdkFetch,
+                headers: { "Content-Type": "application/json" },
+                maxRetries: 0,
+                timeoutInSeconds,
+            };
+            try {
+                const payload = await invoke(clientOptions, {
+                    abortSignal: requestAbort.signal,
+                    maxRetries: 0,
+                    timeoutInSeconds,
+                });
+                throwIfProviderRequestAborted(requestAbort.signal);
+                return payload;
+            }
+            catch (error) {
+                const providerError = unwrapJunctionSdkErrorCause(error);
+                lastError = providerError;
+                if (isProviderParentAbortError(providerError, requestAbort.signal)) {
+                    throw normalizeProviderAbortError(providerError, requestAbort.signal);
+                }
+                if (!requestAbort.signal.aborted
+                    && options.signal
+                    && isProviderParentAbortError(providerError, options.signal)) {
+                    throw normalizeProviderAbortError(providerError, options.signal);
+                }
+                if (requestAbort.signal.aborted
+                    && isProviderTimeoutError(providerError, requestAbort.signal)) {
+                    break;
+                }
+                if (observedOptionalNotFound) {
                     throwIfProviderRequestAborted(requestAbort.signal);
                     return null;
                 }
-                const text = await response.text();
-                if (!response.ok) {
-                    const retryable = method === "GET" && (response.status === 429 || response.status >= 500);
+                const sdkFailure = readJunctionSdkHttpFailure(error)
+                    ?? (error instanceof Error && error.name === "ParseError"
+                        ? readCapturedJunctionSdkHttpFailure(capturedResponse)
+                        : null);
+                if (options.optional404 && sdkFailure?.response.status === 404) {
+                    throwIfProviderRequestAborted(requestAbort.signal);
+                    return null;
+                }
+                if (sdkFailure && !sdkFailure.response.ok) {
+                    const retryable = method === "GET"
+                        && (sdkFailure.response.status === 429 || sdkFailure.response.status >= 500);
                     if (retryable && attempt < attempts) {
-                        await waitForProviderRetryDelay(resolveRetryDelayMs(response, attempt), options.signal);
+                        await waitForProviderRetryDelay(resolveRetryDelayMs(sdkFailure.response, attempt), options.signal);
                         continue;
                     }
                     throw buildProviderApiError({
                         code: "JUNCTION_API_REQUEST_FAILED",
-                        message: `Junction API request failed for ${endpointKind}.`,
-                        response,
-                        body: text,
+                        message: `Junction API request failed for ${options.endpointKind}.`,
+                        response: sdkFailure.response,
+                        body: sdkFailure.body,
                         retryable,
-                        httpStatus: response.status >= 400 && response.status < 600 ? 502 : undefined,
+                        httpStatus: 502,
                         diagnostics: requestDiagnostics,
                     });
                 }
-                return parseJsonResponse(text);
-            }
-            catch (error) {
-                lastError = error;
-                if (isProviderParentAbortError(error, requestAbort.signal)) {
-                    throw normalizeProviderAbortError(error, requestAbort.signal);
+                if (sdkFailure?.response.ok) {
+                    throw invalidJunctionSdkResponseError(sdkFailure.body);
                 }
-                if (!requestAbort.signal.aborted
-                    && options.signal
-                    && isProviderParentAbortError(error, options.signal)) {
-                    throw normalizeProviderAbortError(error, options.signal);
+                if (error instanceof Error && error.name === "ParseError") {
+                    const legacyPayload = readCapturedJunctionSdkSuccess(capturedResponse);
+                    if (legacyPayload.present) {
+                        return legacyPayload.payload;
+                    }
+                    throw invalidJunctionSdkResponseError(legacyPayload.body);
+                }
+                if (error instanceof TypeError
+                    || (error instanceof Error && error.name === "JsonError")) {
+                    throw deviceSyncError({
+                        code: "JUNCTION_SDK_REQUEST_INVALID",
+                        message: `Junction SDK could not construct ${options.endpointKind}.`,
+                        retryable: false,
+                        httpStatus: 502,
+                        details: requestDiagnostics,
+                        cause: error,
+                    });
                 }
-                if (isDeviceSyncError(error)) {
-                    if (!error.retryable || attempt >= attempts) {
-                        throw error;
+                if (isDeviceSyncError(providerError)) {
+                    if (!providerError.retryable || attempt >= attempts) {
+                        throw providerError;
                     }
                 }
-                else if (attempt >= attempts || isProviderTimeoutError(error, requestAbort.signal)) {
+                else if (attempt >= attempts
+                    || isJunctionSdkTimeoutError(error)
+                    || isProviderTimeoutError(providerError, requestAbort.signal)) {
                     break;
                 }
                 await waitForProviderRetryDelay(resolveRetryDelayMs(null, attempt), options.signal);
@@ -332,7 +656,7 @@ export class JunctionClient {
         }
         throw deviceSyncError({
             code: "JUNCTION_API_REQUEST_FAILED",
-            message: `Junction API request failed for ${endpointKind}.`,
+            message: `Junction API request failed for ${options.endpointKind}.`,
             retryable: method === "GET",
             httpStatus: 502,
             details: requestDiagnostics,
@@ -347,45 +671,195 @@ function buildProviderApiError(input) {
         diagnostics: input.diagnostics,
     });
 }
-function resolveJunctionEndpointKind(path) {
-    const pathname = safeProviderPathname(path);
-    if (pathname.startsWith("/v2/user/resolve/")) {
-        return "junction_user_resolve";
+function unwrapJunctionSdkErrorCause(error) {
+    let current = error;
+    const visited = new Set();
+    while (isJunctionSdkErrorWithCause(current)
+        && !visited.has(current)) {
+        visited.add(current);
+        current = current.cause;
+    }
+    return current;
+}
+function createJunctionSdkResponseCapture(response) {
+    return {
+        chunks: [],
+        complete: false,
+        exceededLimit: false,
+        // Preserve the runtime's complete Response metadata. Cloudflare extends
+        // the standard Response surface (for example with `webSocket`), and the
+        // SDK's RawResponse mapped type follows the active runtime definition.
+        rawResponse: response,
+        totalBytes: 0,
+    };
+}
+function createJunctionSdkBoundedBodyStream(body, capture) {
+    const reader = body.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            const { done, value } = await reader.read();
+            if (done) {
+                capture.complete = true;
+                controller.close();
+                reader.releaseLock();
+                return;
+            }
+            const chunk = value;
+            capture.totalBytes += chunk.byteLength;
+            if (capture.totalBytes > MAX_SDK_COMPAT_RESPONSE_BYTES) {
+                capture.exceededLimit = true;
+                capture.chunks = [];
+                const error = junctionSdkResponseTooLargeError();
+                await reader.cancel(error).catch(() => undefined);
+                controller.error(error);
+                reader.releaseLock();
+                return;
+            }
+            capture.chunks.push(Uint8Array.from(chunk));
+            controller.enqueue(chunk);
+        },
+        async cancel(reason) {
+            await reader.cancel(reason).catch(() => undefined);
+            reader.releaseLock();
+        },
+    });
+}
+function junctionSdkResponseExceedsDeclaredLimit(response) {
+    const contentLength = response.headers.get("content-length");
+    if (contentLength === null || !/^\d+$/u.test(contentLength.trim())) {
+        return false;
+    }
+    const parsedLength = Number(contentLength);
+    return Number.isSafeInteger(parsedLength) && parsedLength > MAX_SDK_COMPAT_RESPONSE_BYTES;
+}
+function junctionSdkResponseTooLargeError() {
+    return deviceSyncError({
+        code: "JUNCTION_API_RESPONSE_TOO_LARGE",
+        message: "Junction API response exceeded the configured size limit.",
+        retryable: false,
+        httpStatus: 502,
+    });
+}
+function readCapturedJunctionSdkSuccess(capture) {
+    if (!capture || capture.rawResponse.status < 200 || capture.rawResponse.status >= 300) {
+        return { body: "", payload: null, present: false };
     }
-    if (pathname === "/v2/user/") {
-        return "junction_user_create";
+    return readCapturedJunctionSdkBody(capture);
+}
+function readCapturedJunctionSdkHttpFailure(capture) {
+    if (!capture || capture.rawResponse.status < 300) {
+        return null;
     }
-    if (pathname === "/v2/link/token") {
-        return "junction_link_token_create";
+    const body = readCapturedJunctionSdkText(capture);
+    if (body === null) {
+        return null;
     }
-    if (pathname.startsWith("/v2/user/refresh/")) {
-        return "junction_user_refresh";
+    return {
+        body,
+        response: new Response(null, {
+            headers: capture.rawResponse.headers,
+            status: capture.rawResponse.status,
+            statusText: capture.rawResponse.statusText,
+        }),
+    };
+}
+function readCapturedJunctionSdkBody(capture) {
+    const body = readCapturedJunctionSdkText(capture);
+    if (body === null) {
+        return { body: "", payload: null, present: false };
+    }
+    if (!body.trim()) {
+        return { body, payload: null, present: true };
+    }
+    try {
+        return { body, payload: JSON.parse(body), present: true };
+    }
+    catch {
+        return { body, payload: null, present: false };
+    }
+}
+function readCapturedJunctionSdkText(capture) {
+    if (!capture.complete || capture.exceededLimit) {
+        return null;
     }
-    if (pathname.startsWith("/v2/user/providers/")) {
-        return "junction_user_providers";
+    const bodyBytes = new Uint8Array(capture.totalBytes);
+    let offset = 0;
+    for (const chunk of capture.chunks) {
+        bodyBytes.set(chunk, offset);
+        offset += chunk.byteLength;
     }
-    if (/^\/v2\/user\/[^/]+\/device$/u.test(pathname)) {
-        return "junction_user_devices";
+    return new TextDecoder().decode(bodyBytes);
+}
+function readJunctionSdkHttpFailure(error) {
+    const sdkError = readPlainObject(error);
+    if (!sdkError || !isJunctionSdkErrorName(error)) {
+        return null;
     }
-    if (/^\/v2\/user\/[^/]+\/[^/]+$/u.test(pathname)) {
-        return "junction_user_provider_deregister";
+    const rawResponse = readPlainObject(sdkError.rawResponse);
+    const status = sdkError.statusCode ?? rawResponse?.status;
+    if (typeof status !== "number" || !Number.isInteger(status) || status < 200 || status > 599) {
+        return null;
     }
-    if (pathname.startsWith("/v2/summary/")) {
-        return "junction_summary_collection";
+    return {
+        body: serializeJunctionSdkErrorBody(sdkError.body),
+        response: new Response(null, {
+            headers: readHeaders(rawResponse?.headers),
+            status,
+            statusText: normalizeString(rawResponse?.statusText) ?? undefined,
+        }),
+    };
+}
+function isJunctionSdkErrorWithCause(error) {
+    return (isJunctionSdkErrorName(error) || isJunctionSdkTimeoutError(error))
+        && error.cause !== undefined;
+}
+function isJunctionSdkErrorName(error) {
+    return error instanceof Error && (error.name === "JunctionError"
+        || error.name === "BadRequestError"
+        || error.name === "NotFoundError"
+        || error.name === "UnprocessableEntityError");
+}
+function isJunctionSdkTimeoutError(error) {
+    return error instanceof Error && error.name === "JunctionTimeoutError";
+}
+function readHeaders(value) {
+    return value instanceof Headers ? value : undefined;
+}
+function serializeJunctionSdkErrorBody(body) {
+    if (typeof body === "string") {
+        return body;
     }
-    if (pathname.startsWith("/v2/timeseries/")) {
-        return "junction_timeseries_collection";
+    if (body === null || body === undefined) {
+        return "";
     }
-    if (pathname === "/v2/introspect/resources") {
-        return "junction_introspect_resources";
+    try {
+        return JSON.stringify(body);
     }
-    if (pathname === "/v2/introspect/historical_pull") {
-        return "junction_introspect_historical_pull";
+    catch {
+        return "";
     }
-    if (pathname === "/v2/link/bulk_trigger_historical_pull") {
-        return "junction_bulk_trigger_historical_pull";
+}
+function invalidJunctionSdkResponseError(body) {
+    if (body.trim()) {
+        try {
+            JSON.parse(body);
+        }
+        catch (error) {
+            return deviceSyncError({
+                code: "JUNCTION_API_INVALID_JSON",
+                message: "Junction API response was not valid JSON.",
+                retryable: false,
+                httpStatus: 502,
+                cause: error,
+            });
+        }
     }
-    return "junction_api";
+    return deviceSyncError({
+        code: "JUNCTION_API_RESPONSE_INVALID",
+        message: "Junction API response did not match the documented response shape.",
+        retryable: false,
+        httpStatus: 502,
+    });
 }
 /**
  * A gated Junction endpoint answers 403 (not entitled) or 404 (not routed for
@@ -399,19 +873,15 @@ function isJunctionDisabledEndpointError(error) {
     const status = error.details?.status;
     return status === 403 || status === 404;
 }
-function buildJunctionIntrospectionSearch(input) {
-    const search = new URLSearchParams({
-        user_id: input.userId,
-        user_limit: String(input.userLimit ?? 1),
-    });
-    const sourceProviderSlug = normalizeSourceSlug(input.sourceProviderSlug);
-    if (sourceProviderSlug) {
-        search.set("provider", sourceProviderSlug);
+export function resolveJunctionTimeseriesApiResource(resource) {
+    switch (resource) {
+        case "fat":
+            return "body_fat";
+        case "weight":
+            return "body_weight";
+        default:
+            return resource;
     }
-    return search;
-}
-function resolveJunctionTimeseriesApiResource(resource) {
-    return resource === "weight" ? "body_weight" : resource;
 }
 function resolveJunctionSummaryDateQueryFormat(input) {
     return JUNCTION_DATE_ONLY_SUMMARY_RESOURCES.has(input.resource)
@@ -424,13 +894,34 @@ function normalizeJunctionRefreshTimeoutSeconds(value) {
     }
     return Math.max(5, Math.min(60, Math.trunc(value)));
 }
-function safeProviderPathname(path) {
-    try {
-        return new URL(path, "https://provider.invalid").pathname;
+function normalizeRequiredProviderSlug(value) {
+    const provider = normalizeJunctionProviderSlug(value);
+    if (!provider) {
+        throw new TypeError("Junction provider value is invalid.");
     }
-    catch {
-        return path.split("?")[0] ?? "";
+    return provider;
+}
+function optionalJunctionSdkProvider(value) {
+    const normalized = normalizeJunctionProviderSlug(value);
+    return normalized ? requireJunctionSdkProvider(normalized) : undefined;
+}
+function requireJunctionSdkProvider(value) {
+    const route = resolveJunctionDeviceConnectRouteByProviderSlug(value);
+    const canonicalValue = route?.route.sourceProviderSlug ?? value;
+    const provider = JUNCTION_SDK_PROVIDERS.find((candidate) => candidate === canonicalValue);
+    if (provider) {
+        return provider;
+    }
+    throw new TypeError(`Unsupported Junction provider slug: ${value}`);
+}
+function requireJunctionSdkOAuthProvider(value) {
+    const route = resolveJunctionDeviceConnectRouteByProviderSlug(value);
+    const canonicalValue = route?.route.sourceProviderSlug ?? value;
+    const provider = JUNCTION_SDK_OAUTH_PROVIDERS.find((candidate) => candidate === canonicalValue);
+    if (provider) {
+        return provider;
     }
+    throw new TypeError(`Unsupported Junction OAuth provider slug: ${value}`);
 }
 export function isAllowedJunctionLinkHost(hostname, allowedLinkHosts = JUNCTION_DEFAULT_ALLOWED_LINK_HOSTS) {
     const normalizedHostname = normalizeJunctionLinkHostname(hostname);
@@ -500,7 +991,8 @@ function parseJunctionUser(payload, label) {
     return { userId };
 }
 function parseJunctionProviders(payload) {
-    return extractCollectionRecords(payload)
+    const records = extractCollectionRecords(payload);
+    return records
         .map(parseJunctionProviderConnection)
         .filter((provider) => Boolean(provider));
 }
@@ -537,8 +1029,9 @@ export function parseJunctionHistoricalPullSnapshot(payload, expectedUserId, req
                 || (requestedProvider && sourceProviderSlug !== requestedProvider)) {
                 continue;
             }
-            const notPulledResources = Array.isArray(details.not_pulled)
-                ? [...new Set(details.not_pulled.flatMap((resource) => {
+            const rawNotPulled = details.not_pulled ?? details.notPulled;
+            const notPulledResources = Array.isArray(rawNotPulled)
+                ? [...new Set(rawNotPulled.flatMap((resource) => {
                         const normalized = normalizeJunctionProviderSlug(resource);
                         return normalized ? [normalized] : [];
                     }))].sort((left, right) => left.localeCompare(right))
@@ -563,11 +1056,11 @@ export function parseJunctionHistoricalPullSnapshot(payload, expectedUserId, req
                             errorDetails: normalizeString(statistics.error_details)
                                 ?? normalizeString(statistics.errorDetails)
                                 ?? null,
-                            rangeEnd: normalizeString(statistics.range_end)
-                                ?? normalizeString(statistics.rangeEnd)
+                            rangeEnd: normalizeJunctionDateString(statistics.range_end)
+                                ?? normalizeJunctionDateString(statistics.rangeEnd)
                                 ?? null,
-                            rangeStart: normalizeString(statistics.range_start)
-                                ?? normalizeString(statistics.rangeStart)
+                            rangeStart: normalizeJunctionDateString(statistics.range_start)
+                                ?? normalizeJunctionDateString(statistics.rangeStart)
                                 ?? null,
                             resource,
                             status,
@@ -626,12 +1119,18 @@ function readJunctionProviderConnectionErrorDetails(record) {
     }
     const errorType = normalizeString(details.error_type) ?? normalizeString(details.errorType) ?? null;
     const errorMessage = normalizeString(details.error_message) ?? normalizeString(details.errorMessage) ?? null;
-    const erroredAt = normalizeString(details.errored_at) ?? normalizeString(details.erroredAt) ?? null;
+    const erroredAt = normalizeJunctionDateString(details.errored_at ?? details.erroredAt);
     if (!errorType && !errorMessage && !erroredAt) {
         return null;
     }
     return { errorType, errorMessage, erroredAt };
 }
+function normalizeJunctionDateString(value) {
+    if (value instanceof Date) {
+        return Number.isFinite(value.getTime()) ? value.toISOString() : null;
+    }
+    return normalizeString(value) ?? null;
+}
 function readJunctionProviderConnectionId(record) {
     return (normalizeString(record.id)
         ?? normalizeString(record.provider_connection_id)
@@ -708,6 +1207,12 @@ function extractCollectionRecords(payload, resource) {
             return candidate;
         }
     }
+    if (!resource) {
+        const providerCollections = Object.values(record).filter((candidate) => Array.isArray(candidate));
+        if (providerCollections.length > 0) {
+            return providerCollections.flat();
+        }
+    }
     return resource ? [record] : [];
 }
 function resolveCollectionEnvelopeKeys(resource) {
@@ -717,31 +1222,97 @@ function extractTimeseriesRecords(payload, resource) {
     const groupedRecords = flattenGroupedTimeseries(resource, payload);
     return groupedRecords ?? extractCollectionRecords(payload, resource);
 }
-function flattenGroupedTimeseries(resource, payload) {
+function extractStructurallyCompleteTimeseriesRecords(payload, resource, requestedSourceProviderSlug) {
+    const groupedRecords = flattenGroupedTimeseries(resource, payload, {
+        strict: true,
+    });
+    const records = groupedRecords ?? extractCollectionRecords(payload, resource);
+    if (groupedRecords === null
+        && (!payload || typeof payload !== "object")) {
+        throw incompleteJunctionCalendarCollectionError();
+    }
+    for (const record of records) {
+        const entry = readPlainObject(record);
+        const sourceProviderSlug = entry
+            ? normalizeSourceSlug(resolveJunctionOrigin(entry).sourceProviderSlug)
+            : null;
+        if (!entry || (requestedSourceProviderSlug && !sourceProviderSlug)) {
+            throw incompleteJunctionCalendarCollectionError();
+        }
+    }
+    return records;
+}
+function flattenGroupedTimeseries(resource, payload, options = {}) {
     const envelope = readPlainObject(payload);
+    if (options.strict && envelope && "groups" in envelope && !readPlainObject(envelope.groups)) {
+        throw incompleteJunctionCalendarCollectionError();
+    }
     const groups = readPlainObject(envelope?.groups);
     if (!groups) {
         return null;
     }
     const records = [];
     for (const [sourceSlug, rawGroups] of Object.entries(groups)) {
+        const normalizedGroupedSourceSlug = normalizeSourceSlug(sourceSlug);
+        if (options.strict && !normalizedGroupedSourceSlug) {
+            throw incompleteJunctionCalendarCollectionError();
+        }
+        if (options.strict && (rawGroups === undefined || rawGroups === null)) {
+            throw incompleteJunctionCalendarCollectionError();
+        }
         for (const rawGroup of asArray(rawGroups)) {
             const group = readPlainObject(rawGroup);
             if (!group) {
+                if (options.strict) {
+                    throw incompleteJunctionCalendarCollectionError();
+                }
+                if (resource === "electrocardiogram_voltage") {
+                    throw new TypeError("Junction ECG group must be an object.");
+                }
                 continue;
             }
+            if (options.strict
+                && (!("data" in group) || group.data === undefined || group.data === null)) {
+                throw incompleteJunctionCalendarCollectionError();
+            }
+            const groupId = firstDefinedString(group, ["id", "recordingId", "recording_id"]);
+            if (resource === "electrocardiogram_voltage" && !groupId) {
+                throw new TypeError("Junction ECG group lacked a stable recording id.");
+            }
+            if (resource === "electrocardiogram_voltage" && !Array.isArray(group.data)) {
+                throw new TypeError("Junction ECG group data must be an array.");
+            }
             for (const rawSample of asArray(group.data)) {
                 const sample = readPlainObject(rawSample);
                 if (!sample) {
+                    if (options.strict) {
+                        throw incompleteJunctionCalendarCollectionError();
+                    }
+                    if (resource === "electrocardiogram_voltage") {
+                        throw new TypeError("Junction ECG sample must be an object.");
+                    }
                     continue;
                 }
+                const sampleId = firstDefinedString(sample, ["recordingId", "recording_id"]);
+                if (resource === "electrocardiogram_voltage"
+                    && sampleId
+                    && sampleId !== groupId) {
+                    throw new TypeError("Junction ECG sample conflicted with its group recording id.");
+                }
                 const origin = resolveJunctionOrigin(sample, {
                     ...group,
-                    groupedSourceSlug: sourceSlug,
+                    groupedSourceSlug: normalizedGroupedSourceSlug ?? sourceSlug,
                 });
+                const sourceProviderSlug = normalizeSourceSlug(origin.sourceProviderSlug);
+                if (options.strict && !sourceProviderSlug) {
+                    throw incompleteJunctionCalendarCollectionError();
+                }
                 records.push(stripUndefinedRecord({
                     ...sample,
-                    sourceProviderSlug: normalizeSourceSlug(origin.sourceProviderSlug) ?? undefined,
+                    sourceProviderSlug: sourceProviderSlug ?? undefined,
+                    junctionGroupId: resource === "electrocardiogram_voltage"
+                        ? groupId
+                        : undefined,
                     sourceType: origin.sourceType,
                     sourceInstanceId: origin.sourceInstanceId,
                     junctionResource: resource,
@@ -751,6 +1322,25 @@ function flattenGroupedTimeseries(resource, payload) {
     }
     return records;
 }
+function incompleteJunctionCalendarCollectionError() {
+    return deviceSyncError({
+        code: "JUNCTION_CALENDAR_REFRESH_INCOMPLETE_NORMALIZATION",
+        message: "Junction calendar refresh response was not structurally complete.",
+        retryable: true,
+        httpStatus: 502,
+    });
+}
+function firstDefinedValue(record, keys) {
+    for (const key of keys) {
+        if (record[key] !== undefined && record[key] !== null) {
+            return record[key];
+        }
+    }
+    return undefined;
+}
+function firstDefinedString(record, keys) {
+    return normalizeString(firstDefinedValue(record, keys));
+}
 function asArray(value) {
     if (Array.isArray(value)) {
         return value;
@@ -779,23 +1369,6 @@ function toDateParameter(timestamp, format, boundary) {
     const isoTimestamp = date.toISOString();
     return format === "date" ? isoTimestamp.slice(0, 10) : isoTimestamp;
 }
-function parseJsonResponse(text) {
-    if (!text.trim()) {
-        return null;
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch (error) {
-        throw deviceSyncError({
-            code: "JUNCTION_API_INVALID_JSON",
-            message: "Junction API response was not valid JSON.",
-            retryable: false,
-            httpStatus: 502,
-            cause: error,
-        });
-    }
-}
 function resolveRetryDelayMs(response, attempt) {
     const retryAfter = response?.headers.get("retry-after");
     const retryAfterMs = retryAfter ? parseRetryAfterMs(retryAfter) : null;