@epic-web/workshop-utils 6.85.5 → 6.86.0

package/dist/db.server.d.ts

@@ -20,6 +20,20 @@ export declare const PlayerPreferencesSchema: z.ZodDefault<z.ZodOptional<z.ZodOb
     defaultView: z.ZodOptional<z.ZodString>;
     activeSidebarTab: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>>>;
+declare const PendingProgressMutationSchema: z.ZodObject<{
+    lessonSlug: z.ZodString;
+    complete: z.ZodBoolean;
+    queuedAt: z.ZodString;
+    host: z.ZodOptional<z.ZodString>;
+    workshopSlug: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PendingProgressMutation = z.infer<typeof PendingProgressMutationSchema>;
+export type PendingProgressMutationScope = {
+    host: string;
+    workshopSlug: string;
+    userId: string;
+};
 declare const DataSchema: z.ZodObject<{
     preferences: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         player: z.ZodDefault<z.ZodOptional<z.ZodObject<{
@@ -79,6 +93,14 @@ declare const DataSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     clientId: z.ZodOptional<z.ZodString>;
     mutedNotifications: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+    pendingProgressMutations: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        lessonSlug: z.ZodString;
+        complete: z.ZodBoolean;
+        queuedAt: z.ZodString;
+        host: z.ZodOptional<z.ZodString>;
+        workshopSlug: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export declare function getClientId(): Promise<string>;
 export declare function logout({ productHost }?: {
@@ -117,6 +139,14 @@ export declare function readDb(): Promise<{
         } | undefined;
         fontSize?: number | undefined;
     };
+    pendingProgressMutations: {
+        lessonSlug: string;
+        complete: boolean;
+        queuedAt: string;
+        host?: string | undefined;
+        workshopSlug?: string | undefined;
+        userId?: string | undefined;
+    }[];
     authInfo?: {
         id: string;
         tokenSet: {
@@ -248,6 +278,65 @@ export declare function setPreferences(preferences: z.input<typeof DataSchema>['
     fontSize?: number | undefined;
     onboardingComplete?: string[] | undefined;
 }>;
+export declare function hasPendingProgressMutationScope(mutation: PendingProgressMutation): mutation is PendingProgressMutation & PendingProgressMutationScope;
+export declare function isPendingProgressMutationInScope(mutation: PendingProgressMutation, scope: PendingProgressMutationScope): boolean;
+export declare function mutatePendingProgressMutations(updater: (pendingProgressMutations: Array<PendingProgressMutation>) => Array<PendingProgressMutation>): Promise<{
+    lessonSlug: string;
+    complete: boolean;
+    queuedAt: string;
+    host?: string | undefined;
+    workshopSlug?: string | undefined;
+    userId?: string | undefined;
+}[]>;
+export declare function getPendingProgressMutations({ scope, }?: {
+    scope?: PendingProgressMutationScope;
+}): Promise<{
+    lessonSlug: string;
+    complete: boolean;
+    queuedAt: string;
+    host?: string | undefined;
+    workshopSlug?: string | undefined;
+    userId?: string | undefined;
+}[]>;
+export declare function queuePendingProgressMutation({ scope, lessonSlug, complete, queuedAt, }: {
+    scope: PendingProgressMutationScope;
+    lessonSlug: string;
+    complete: boolean;
+    queuedAt?: string;
+}): Promise<{
+    lessonSlug: string;
+    complete: boolean;
+    queuedAt: string;
+    host?: string | undefined;
+    workshopSlug?: string | undefined;
+    userId?: string | undefined;
+}[]>;
+export declare function reconcileQueuedProgressMutation({ pendingProgressMutations, scope, lessonSlug, complete, queuedAt, }: {
+    pendingProgressMutations: Array<PendingProgressMutation>;
+    scope: PendingProgressMutationScope;
+    lessonSlug: string;
+    complete: boolean;
+    queuedAt?: string;
+}): {
+    lessonSlug: string;
+    complete: boolean;
+    queuedAt: string;
+    host?: string | undefined;
+    workshopSlug?: string | undefined;
+    userId?: string | undefined;
+}[];
+export declare function replacePendingProgressMutationsForScope({ scope, basePendingProgressMutations, nextPendingProgressMutations, }: {
+    scope: PendingProgressMutationScope;
+    basePendingProgressMutations: Array<PendingProgressMutation>;
+    nextPendingProgressMutations: Array<PendingProgressMutation>;
+}): Promise<{
+    lessonSlug: string;
+    complete: boolean;
+    queuedAt: string;
+    host?: string | undefined;
+    workshopSlug?: string | undefined;
+    userId?: string | undefined;
+}[]>;
 /**
  * Mark an onboarding feature as complete.
  * This is used to track which tips/indicators have been dismissed.

package/dist/db.server.js

@@ -1,6 +1,7 @@
 import "./init-env.js";
 import { randomUUID as cuid } from 'crypto';
 import fsExtra from 'fs-extra';
+import PQueue from 'p-queue';
 import { redirect } from 'react-router';
 import { z } from 'zod';
 import { getWorkshopConfig } from "./config.server.js";
@@ -78,6 +79,14 @@ const AuthInfoSchema = z.object({
     name: z.string().nullable().optional(),
 });
 const MutedNotificationSchema = z.array(z.string()).default([]);
+const PendingProgressMutationSchema = z.object({
+    lessonSlug: z.string(),
+    complete: z.boolean(),
+    queuedAt: z.string(),
+    host: z.string().optional(),
+    workshopSlug: z.string().optional(),
+    userId: z.string().optional(),
+});
 const DataSchema = z.object({
     preferences: z
         .object({
@@ -107,6 +116,10 @@ const DataSchema = z.object({
     authInfos: z.record(z.string(), AuthInfoSchema).optional(),
     clientId: z.string().optional(),
     mutedNotifications: MutedNotificationSchema.optional(),
+    pendingProgressMutations: z
+        .array(PendingProgressMutationSchema)
+        .optional()
+        .default([]),
 });
 export async function getClientId() {
     const data = await readDb();
@@ -336,6 +349,109 @@ export async function setPreferences(preferences) {
     await saveJSON(updatedData);
     return updatedData.preferences;
 }
+const pendingProgressMutationWriteQueue = new PQueue({ concurrency: 1 });
+export function hasPendingProgressMutationScope(mutation) {
+    return Boolean(mutation.host && mutation.workshopSlug && mutation.userId);
+}
+export function isPendingProgressMutationInScope(mutation, scope) {
+    return (hasPendingProgressMutationScope(mutation) &&
+        mutation.host === scope.host &&
+        mutation.workshopSlug === scope.workshopSlug &&
+        mutation.userId === scope.userId);
+}
+function getPendingProgressMutationKey(mutation) {
+    return [
+        mutation.host ?? '',
+        mutation.workshopSlug ?? '',
+        mutation.userId ?? '',
+        mutation.lessonSlug,
+        mutation.complete ? '1' : '0',
+        mutation.queuedAt,
+    ].join('|');
+}
+function mergePendingProgressMutationsByLesson(mutations) {
+    const mergedByLessonSlug = new Map();
+    for (const mutation of mutations) {
+        const existingMutation = mergedByLessonSlug.get(mutation.lessonSlug);
+        if (!existingMutation) {
+            mergedByLessonSlug.set(mutation.lessonSlug, mutation);
+            continue;
+        }
+        const existingQueuedAt = Date.parse(existingMutation.queuedAt);
+        const nextQueuedAt = Date.parse(mutation.queuedAt);
+        if (nextQueuedAt >= existingQueuedAt) {
+            mergedByLessonSlug.set(mutation.lessonSlug, mutation);
+        }
+    }
+    return Array.from(mergedByLessonSlug.values());
+}
+export async function mutatePendingProgressMutations(updater) {
+    return pendingProgressMutationWriteQueue.add(async () => {
+        const data = await readDb();
+        const pendingProgressMutations = data?.pendingProgressMutations ?? [];
+        const nextPendingProgressMutations = updater(pendingProgressMutations);
+        const updatedData = {
+            ...data,
+            pendingProgressMutations: nextPendingProgressMutations,
+        };
+        await saveJSON(updatedData);
+        return updatedData.pendingProgressMutations;
+    });
+}
+export async function getPendingProgressMutations({ scope, } = {}) {
+    const data = await readDb();
+    const pendingProgressMutations = data?.pendingProgressMutations ?? [];
+    if (!scope)
+        return pendingProgressMutations;
+    return pendingProgressMutations.filter((mutation) => isPendingProgressMutationInScope(mutation, scope));
+}
+export async function queuePendingProgressMutation({ scope, lessonSlug, complete, queuedAt = new Date().toISOString(), }) {
+    return mutatePendingProgressMutations((pendingProgressMutations) => reconcileQueuedProgressMutation({
+        pendingProgressMutations,
+        scope,
+        lessonSlug,
+        complete,
+        queuedAt,
+    }));
+}
+export function reconcileQueuedProgressMutation({ pendingProgressMutations, scope, lessonSlug, complete, queuedAt = new Date().toISOString(), }) {
+    const existingMutation = pendingProgressMutations.find((mutation) => isPendingProgressMutationInScope(mutation, scope) &&
+        mutation.lessonSlug === lessonSlug);
+    const pendingWithoutLessonMutation = pendingProgressMutations.filter((mutation) => !(isPendingProgressMutationInScope(mutation, scope) &&
+        mutation.lessonSlug === lessonSlug));
+    // If the new mutation undoes the queued one for this lesson, drop both so
+    // the queue reflects the net effect.
+    if (existingMutation && existingMutation.complete !== complete) {
+        return pendingWithoutLessonMutation;
+    }
+    return [
+        ...pendingWithoutLessonMutation,
+        {
+            host: scope.host,
+            workshopSlug: scope.workshopSlug,
+            userId: scope.userId,
+            lessonSlug,
+            complete,
+            queuedAt,
+        },
+    ];
+}
+export async function replacePendingProgressMutationsForScope({ scope, basePendingProgressMutations, nextPendingProgressMutations, }) {
+    return mutatePendingProgressMutations((pendingProgressMutations) => {
+        const outOfScopePendingProgressMutations = pendingProgressMutations.filter((mutation) => !isPendingProgressMutationInScope(mutation, scope));
+        const currentScopedPendingProgressMutations = pendingProgressMutations.filter((mutation) => isPendingProgressMutationInScope(mutation, scope));
+        const basePendingProgressMutationKeys = new Set(basePendingProgressMutations.map(getPendingProgressMutationKey));
+        const newScopedPendingProgressMutations = currentScopedPendingProgressMutations.filter((mutation) => !basePendingProgressMutationKeys.has(getPendingProgressMutationKey(mutation)));
+        const mergedScopedPendingProgressMutations = mergePendingProgressMutationsByLesson([
+            ...nextPendingProgressMutations,
+            ...newScopedPendingProgressMutations,
+        ]);
+        return [
+            ...outOfScopePendingProgressMutations,
+            ...mergedScopedPendingProgressMutations,
+        ];
+    });
+}
 /**
  * Mark an onboarding feature as complete.
  * This is used to track which tips/indicators have been dismissed.

package/dist/epic-api.server.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { getExercises, getWorkshopFinished, getWorkshopInstructions } from "./apps.server.js";
+import { type PendingProgressMutation } from "./db.server.js";
 import { type Timings } from "./timing.server.js";
 declare const EpicVideoMetadataSchema: z.ZodObject<{
     playbackId: z.ZodString;
@@ -74,6 +75,41 @@ declare function getEpicVideoInfo({ epicVideoEmbed, accessToken, request, timing
     requestCountry: string;
     restrictedCountry: string;
 } | null>;
+export declare function shouldQueueProgressMutationForStatus(status: number): boolean;
+export declare function resolveProgressSyncState({ epicCompletedAt, pendingProgressMutation, }: {
+    epicCompletedAt: string | null;
+    pendingProgressMutation?: PendingProgressMutation;
+}): {
+    epicCompletedAt: string | null;
+    syncStatus: "synced";
+} | {
+    epicCompletedAt: string | null;
+    syncStatus: "pending";
+};
+type DroppedProgressMutation = {
+    lessonSlug: string;
+    complete: boolean;
+    reason: string;
+};
+export declare function resolveProgressMutationOutcome({ lessonSlug, syncResult, }: {
+    lessonSlug: string;
+    syncResult: {
+        pendingProgressMutations: Array<PendingProgressMutation>;
+        droppedProgressMutations: Array<DroppedProgressMutation>;
+    };
+}): {
+    readonly status: "error";
+    readonly error: string;
+    readonly queuedCount?: undefined;
+} | {
+    readonly status: "queued";
+    readonly queuedCount: number;
+    readonly error?: undefined;
+} | {
+    readonly status: "success";
+    readonly error?: undefined;
+    readonly queuedCount?: undefined;
+};
 export type Progress = Awaited<ReturnType<typeof getProgress>>[number];
 export declare function getProgress({ timings, request, }?: {
     timings?: Timings;
@@ -82,6 +118,7 @@ export declare function getProgress({ timings, request, }?: {
     epicLessonUrl: string;
     epicLessonSlug: string;
     epicCompletedAt: string | null;
+    syncStatus: "synced" | "pending";
 } & (LocalProgressForEpicLesson | {
     type: "unknown";
 }))[]>;
@@ -144,16 +181,16 @@ export declare function updateProgress({ lessonSlug, complete }: {
     request?: Request;
 }): Promise<{
     readonly status: "error";
-    readonly error: "cannot update progress when deployed";
-} | {
-    readonly status: "error";
-    readonly error: "not authenticated";
+    readonly error: string;
+    readonly queuedCount?: undefined;
 } | {
-    readonly status: "error";
-    readonly error: `${number} ${string}`;
+    readonly status: "queued";
+    readonly queuedCount: number;
+    readonly error?: undefined;
 } | {
     readonly status: "success";
     readonly error?: undefined;
+    readonly queuedCount?: undefined;
 }>;
 export declare function getWorkshopData(slug: string, { timings, request, forceFresh, }?: {
     timings?: Timings;

package/dist/epic-api.server.js

@@ -6,10 +6,11 @@ import { z } from 'zod';
 import { getExerciseApp, getExercises, getWorkshopFinished, getWorkshopInstructions, } from "./apps.server.js";
 import { cachified, epicApiCache } from "./cache.server.js";
 import { getWorkshopConfig } from "./config.server.js";
-import { getAuthInfo, setAuthInfo } from "./db.server.js";
+import { getAuthInfo, getPendingProgressMutations, isPendingProgressMutationInScope, queuePendingProgressMutation, replacePendingProgressMutationsForScope, setAuthInfo, } from "./db.server.js";
 import { getEnv } from "./init-env.js";
 import { logger } from "./logger.js";
 import { getErrorMessage } from "./utils.js";
+import { checkConnection } from "./utils.server.js";
 // Module-level logger for epic-api operations
 const log = logger('epic:api');
 const Transcript = z
@@ -131,7 +132,7 @@ export async function getEpicVideoMetadata({ playbackId, host, accessToken, requ
         swr: 1000 * 60 * 60 * 24 * 365 * 10,
         offlineFallbackValue: null,
         checkValue: EpicVideoMetadataSchema.nullable(),
-        async getFreshValue(context) {
+        async getFreshValue() {
             const apiUrl = `https://${normalizedHost}/api/video/${encodeURIComponent(playbackId)}`;
             videoMetadataLog(`making video metadata request to: ${apiUrl}`);
             const response = await fetch(apiUrl, accessToken
@@ -139,23 +140,19 @@ export async function getEpicVideoMetadata({ playbackId, host, accessToken, requ
                 : undefined).catch((e) => new Response(getErrorMessage(e), { status: 500 }));
             videoMetadataLog(`video metadata response: ${response.status} ${response.statusText}`);
             if (!response.ok) {
-                context.metadata.ttl = 1000 * 2;
-                context.metadata.swr = 0;
-                return null;
+                throw new Error(`Failed to fetch video metadata: ${response.status} ${response.statusText}`);
             }
             const rawInfo = await response.json();
             const parsedInfo = EpicVideoMetadataSchema.safeParse(rawInfo);
             if (parsedInfo.success) {
                 return parsedInfo.data;
             }
-            context.metadata.ttl = 1000 * 2;
-            context.metadata.swr = 0;
             videoMetadataLog.error(`video metadata parsing failed for ${playbackId}`, {
                 host: normalizedHost,
                 rawInfo,
                 parseError: parsedInfo.error,
             });
-            return null;
+            throw new Error(`Failed to parse video metadata for ${playbackId}`);
         },
     }).catch((e) => {
         videoMetadataLog.error(`failed to fetch video metadata for ${playbackId}:`, e);
@@ -384,7 +381,7 @@ async function getEpicProgress({ timings, request, forceFresh, } = {}) {
         swr: 1000 * 60 * 60 * 24 * 365 * 10,
         offlineFallbackValue: [],
         checkValue: EpicProgressSchema,
-        async getFreshValue(context) {
+        async getFreshValue() {
             const progressUrl = `https://${host}/api/progress`;
             log(`making progress API request to: ${progressUrl}`);
             const response = await fetch(progressUrl, {
@@ -396,17 +393,172 @@ async function getEpicProgress({ timings, request, forceFresh, } = {}) {
             if (response.status < 200 || response.status >= 300) {
                 log.error(`failed to fetch progress from EpicWeb: ${response.status} ${response.statusText}`);
                 console.error(`Failed to fetch progress from EpicWeb: ${response.status} ${response.statusText}`);
-                // don't cache errors for long...
-                context.metadata.ttl = 1000 * 2;
-                context.metadata.swr = 0;
-                return [];
+                throw new Error(`Failed to fetch progress from EpicWeb: ${response.status} ${response.statusText}`);
             }
             const progressData = await response.json();
             const parsedProgress = EpicProgressSchema.parse(progressData);
             log(`successfully fetched ${parsedProgress.length} progress entries`);
             return parsedProgress;
         },
+    }).catch((error) => {
+        log.error('failed to get progress via cache/api and no cache fallback is available', error);
+        return [];
+    });
+}
+export function shouldQueueProgressMutationForStatus(status) {
+    // Retry-worthy statuses and auth failures should remain queued so they can
+    // be replayed later once connectivity/auth recovers.
+    return (status === 401 ||
+        status === 403 ||
+        status === 408 ||
+        status === 425 ||
+        status === 429 ||
+        status >= 500);
+}
+export function resolveProgressSyncState({ epicCompletedAt, pendingProgressMutation, }) {
+    if (!pendingProgressMutation) {
+        return { epicCompletedAt, syncStatus: 'synced' };
+    }
+    return {
+        epicCompletedAt: pendingProgressMutation.complete
+            ? pendingProgressMutation.queuedAt
+            : null,
+        syncStatus: 'pending',
+    };
+}
+function createPendingProgressMutationScope({ host, workshopSlug, userId, }) {
+    return {
+        host,
+        workshopSlug: workshopSlug ?? '__unknown-workshop__',
+        userId,
+    };
+}
+function pendingProgressQueuesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((entry, index) => {
+        const other = b[index];
+        if (!other)
+            return false;
+        return (entry.lessonSlug === other.lessonSlug &&
+            entry.complete === other.complete &&
+            entry.queuedAt === other.queuedAt);
+    });
+}
+async function postProgressMutation({ host, accessToken, lessonSlug, complete, }) {
+    const progressUrl = `https://${host}/api/progress`;
+    const payload = complete
+        ? { lessonSlug }
+        : { lessonSlug, remove: true };
+    log(`making POST request to: ${progressUrl} with payload: ${JSON.stringify(payload)}`);
+    try {
+        const response = await fetch(progressUrl, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${accessToken}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify(payload),
+        });
+        return { status: 'success', response, payload };
+    }
+    catch (error) {
+        return { status: 'error', error: getErrorMessage(error), payload };
+    }
+}
+async function syncPendingProgressMutations({ scope, host, accessToken, request, timings, }) {
+    const pendingProgressMutations = await getPendingProgressMutations({ scope });
+    if (!pendingProgressMutations.length) {
+        return {
+            pendingProgressMutations,
+            syncedCount: 0,
+            droppedProgressMutations: [],
+        };
+    }
+    const isOnline = await checkConnection({ request, timings }).catch(() => false);
+    if (!isOnline) {
+        log(`connection offline, skipping replay of ${pendingProgressMutations.length} queued progress mutation${pendingProgressMutations.length === 1 ? '' : 's'}`);
+        return {
+            pendingProgressMutations,
+            syncedCount: 0,
+            droppedProgressMutations: [],
+        };
+    }
+    let syncedCount = 0;
+    let queueChanged = false;
+    const droppedProgressMutations = [];
+    let remainingProgressMutations = [];
+    for (let index = 0; index < pendingProgressMutations.length; index++) {
+        const pendingMutation = pendingProgressMutations[index];
+        if (!pendingMutation)
+            continue;
+        log(`replaying queued progress mutation (${index + 1}/${pendingProgressMutations.length}) for lesson: ${pendingMutation.lessonSlug} (complete: ${pendingMutation.complete})`);
+        const response = await postProgressMutation({
+            host,
+            accessToken,
+            lessonSlug: pendingMutation.lessonSlug,
+            complete: pendingMutation.complete,
+        });
+        if (response.status === 'error') {
+            log.error(`failed replaying queued progress mutation for ${pendingMutation.lessonSlug}: ${response.error}`);
+            remainingProgressMutations = pendingProgressMutations.slice(index);
+            break;
+        }
+        log(`queued progress replay response: ${response.response.status} ${response.response.statusText}`);
+        if (response.response.ok) {
+            syncedCount++;
+            queueChanged = true;
+            continue;
+        }
+        if (shouldQueueProgressMutationForStatus(response.response.status)) {
+            log(`queued progress mutation for ${pendingMutation.lessonSlug} still not syncable (${response.response.status}), keeping in queue`);
+            remainingProgressMutations = pendingProgressMutations.slice(index);
+            break;
+        }
+        log.error(`dropping queued progress mutation for ${pendingMutation.lessonSlug}: ${response.response.status} ${response.response.statusText}`);
+        droppedProgressMutations.push({
+            lessonSlug: pendingMutation.lessonSlug,
+            complete: pendingMutation.complete,
+            reason: `${response.response.status} ${response.response.statusText}`,
+        });
+        queueChanged = true;
+    }
+    if (!queueChanged &&
+        pendingProgressQueuesEqual(remainingProgressMutations, pendingProgressMutations)) {
+        return {
+            pendingProgressMutations,
+            syncedCount,
+            droppedProgressMutations,
+        };
+    }
+    await replacePendingProgressMutationsForScope({
+        scope,
+        basePendingProgressMutations: pendingProgressMutations,
+        nextPendingProgressMutations: remainingProgressMutations,
     });
+    log(`queued progress replay complete. synced: ${syncedCount}, remaining: ${remainingProgressMutations.length}`);
+    return {
+        pendingProgressMutations: remainingProgressMutations,
+        syncedCount,
+        droppedProgressMutations,
+    };
+}
+export function resolveProgressMutationOutcome({ lessonSlug, syncResult, }) {
+    const droppedProgressMutation = syncResult.droppedProgressMutations.find((mutation) => mutation.lessonSlug === lessonSlug);
+    if (droppedProgressMutation) {
+        return {
+            status: 'error',
+            error: droppedProgressMutation.reason,
+        };
+    }
+    const isStillPending = syncResult.pendingProgressMutations.some((mutation) => mutation.lessonSlug === lessonSlug);
+    if (isStillPending) {
+        return {
+            status: 'queued',
+            queuedCount: syncResult.pendingProgressMutations.length,
+        };
+    }
+    return { status: 'success' };
 }
 export async function getProgress({ timings, request, } = {}) {
     if (getEnv().EPICSHOP_DEPLOYED)
@@ -417,10 +569,30 @@ export async function getProgress({ timings, request, } = {}) {
     const { product: { slug, host }, } = getWorkshopConfig();
     if (!slug)
         return [];
+    const progressMutationScope = createPendingProgressMutationScope({
+        host,
+        workshopSlug: slug,
+        userId: authInfo.id,
+    });
+    const syncResult = await syncPendingProgressMutations({
+        scope: progressMutationScope,
+        host,
+        accessToken: authInfo.tokenSet.access_token,
+        request,
+        timings,
+    });
+    const pendingProgressByLessonSlug = new Map(syncResult.pendingProgressMutations.map((mutation) => [
+        mutation.lessonSlug,
+        mutation,
+    ]));
     log(`aggregating progress data for workshop: ${slug}`);
     const [workshopData, epicProgress, workshopInstructions, workshopFinished, exercises,] = await Promise.all([
         getWorkshopData(slug, { request, timings }),
-        getEpicProgress({ request, timings }),
+        getEpicProgress({
+            request,
+            timings,
+            forceFresh: syncResult.syncedCount > 0,
+        }),
         getWorkshopInstructions({ request }),
         getWorkshopFinished({ request }),
         getExercises({ request, timings }),
@@ -431,7 +603,11 @@ export async function getProgress({ timings, request, } = {}) {
         for (const lesson of lessons) {
             const epicLessonSlug = lesson.slug;
             const lessonProgress = epicProgress.find(({ lessonId }) => lessonId === lesson._id);
-            const epicCompletedAt = lessonProgress ? lessonProgress.completedAt : null;
+            const pendingProgressMutation = pendingProgressByLessonSlug.get(epicLessonSlug);
+            const progressSyncState = resolveProgressSyncState({
+                epicCompletedAt: lessonProgress ? lessonProgress.completedAt : null,
+                pendingProgressMutation,
+            });
             const progressForLesson = resolveLocalProgressForEpicLesson(epicLessonSlug, {
                 workshopInstructions,
                 workshopFinished,
@@ -443,7 +619,8 @@ export async function getProgress({ timings, request, } = {}) {
                     ...progressForLesson,
                     epicLessonUrl,
                     epicLessonSlug,
-                    epicCompletedAt,
+                    epicCompletedAt: progressSyncState.epicCompletedAt,
+                    syncStatus: progressSyncState.syncStatus,
                 });
             }
             else {
@@ -451,7 +628,8 @@ export async function getProgress({ timings, request, } = {}) {
                     type: 'unknown',
                     epicLessonUrl,
                     epicLessonSlug,
-                    epicCompletedAt,
+                    epicCompletedAt: progressSyncState.epicCompletedAt,
+                    syncStatus: progressSyncState.syncStatus,
                 });
             }
         }
@@ -565,31 +743,43 @@ export async function updateProgress({ lessonSlug, complete }, { timings, reques
     if (!authInfo) {
         return { status: 'error', error: 'not authenticated' };
     }
-    const { product: { host }, } = getWorkshopConfig();
-    const progressUrl = `https://${host}/api/progress`;
-    const payload = complete ? { lessonSlug } : { lessonSlug, remove: true };
-    log(`updating progress for lesson: ${lessonSlug} (complete: ${complete})`);
-    log(`making POST request to: ${progressUrl} with payload: ${JSON.stringify(payload)}`);
-    const response = await fetch(progressUrl, {
-        method: 'POST',
-        headers: {
-            authorization: `Bearer ${authInfo.tokenSet.access_token}`,
-            'content-type': 'application/json',
-        },
-        body: JSON.stringify(payload),
-    }).catch((e) => new Response(getErrorMessage(e), { status: 500 }));
-    log(`progress update response: ${response.status} ${response.statusText}`);
-    // force the progress to be fresh whether or not we're successful
-    await getEpicProgress({ forceFresh: true, request, timings });
-    if (response.status < 200 || response.status >= 300) {
-        log(`progress update failed: ${response.status} ${response.statusText}`);
-        return {
-            status: 'error',
-            error: `${response.status} ${response.statusText}`,
-        };
+    const { product: { host, slug }, } = getWorkshopConfig();
+    const progressMutationScope = createPendingProgressMutationScope({
+        host,
+        workshopSlug: slug,
+        userId: authInfo.id,
+    });
+    const normalizedComplete = Boolean(complete);
+    log(`updating progress for lesson: ${lessonSlug} (complete: ${normalizedComplete})`);
+    const pendingProgressMutations = await queuePendingProgressMutation({
+        scope: progressMutationScope,
+        lessonSlug,
+        complete: normalizedComplete,
+    });
+    const scopedPendingProgressMutations = pendingProgressMutations.filter((mutation) => isPendingProgressMutationInScope(mutation, progressMutationScope));
+    log(`queued progress mutation for lesson: ${lessonSlug}. pending count: ${scopedPendingProgressMutations.length}`);
+    const syncResult = await syncPendingProgressMutations({
+        scope: progressMutationScope,
+        host,
+        accessToken: authInfo.tokenSet.access_token,
+        request,
+        timings,
+    });
+    if (syncResult.syncedCount > 0) {
+        // Force a fresh pull so loaders and CLIs see synchronized progress.
+        await getEpicProgress({ forceFresh: true, request, timings });
     }
-    log(`progress update successful for lesson: ${lessonSlug}`);
-    return { status: 'success' };
+    const outcome = resolveProgressMutationOutcome({ lessonSlug, syncResult });
+    if (outcome.status === 'success') {
+        log(`progress update successful for lesson: ${lessonSlug}`);
+    }
+    else if (outcome.status === 'queued') {
+        log(`progress update queued for lesson: ${lessonSlug}. pending count: ${outcome.queuedCount}`);
+    }
+    else {
+        log(`progress update failed for lesson: ${lessonSlug}: ${outcome.error}`);
+    }
+    return outcome;
 }
 const ModuleSchema = z.object({
     resources: z
@@ -632,15 +822,20 @@ export async function getWorkshopData(slug, { timings, request, forceFresh, } =
             const response = await fetch(workshopUrl).catch((e) => new Response(getErrorMessage(e), { status: 500 }));
             log(`workshop data response: ${response.status} ${response.statusText}`);
             if (response.status < 200 || response.status >= 300) {
-                log.error(`failed to fetch workshop data from EpicWeb for ${slug}: ${response.status} ${response.statusText}`);
-                console.error(`Failed to fetch workshop data from EpicWeb for ${slug}: ${response.status} ${response.statusText}`);
-                return { resources: [] };
+                const errorMessage = `Failed to fetch workshop data from EpicWeb for ${slug}: ${response.status} ${response.statusText}`;
+                log.error(errorMessage);
+                if (!log.enabled)
+                    console.error(errorMessage);
+                throw new Error(errorMessage);
             }
             const jsonResponse = await response.json();
             const parsedData = ModuleSchema.parse(jsonResponse);
             log(`successfully fetched workshop data for ${slug} with ${parsedData.resources?.length ?? 0} resources`);
             return parsedData;
         },
+    }).catch((error) => {
+        log.error(`failed to get workshop data for ${slug} via cache/api`, error);
+        return { resources: [] };
     });
 }
 export async function userHasAccessToExerciseStep({ exerciseNumber, stepNumber, timings, request, forceFresh, }) {

package/dist/utils.server.d.ts

@@ -1,7 +1,8 @@
 import "./init-env.js";
 import { type Timings } from "./timing.server.js";
 export { dayjs } from "./utils.js";
-export declare function checkConnection({ request, timings, }?: {
+export declare function checkConnection({ request, timings, forceFresh, }?: {
     request?: Request;
     timings?: Timings;
+    forceFresh?: boolean;
 }): Promise<boolean>;

package/dist/utils.server.js

@@ -35,7 +35,7 @@ async function raceConnectivity() {
         return false;
     }
 }
-export async function checkConnection({ request, timings, } = {}) {
+export async function checkConnection({ request, timings, forceFresh, } = {}) {
     connectionLog('calling cachified to check connection');
     const isOnline = await cachified({
         cache: connectionCache,
@@ -43,6 +43,7 @@ export async function checkConnection({ request, timings, } = {}) {
         timings,
         key: 'connected',
         ttl: 1000 * 10,
+        forceFresh,
         checkValue: z.boolean(),
         async getFreshValue(context) {
             connectionLog('getting fresh connection value');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epic-web/workshop-utils",
-  "version": "6.85.5",
+  "version": "6.86.0",
   "publishConfig": {
     "access": "public"
   },