@timeback/sdk 0.1.7 → 0.1.8

package/dist/client/lib/user-cache.ts

@@ -0,0 +1,168 @@
+/**
+ * Shared User Cache
+ *
+ * Internal module for in-flight deduplication and short-lived caching of
+ * verify and profile requests. Used by Solid, Svelte, and Vue adapters.
+ */
+
+import type { TimebackProfile, TimebackVerifyResult } from '../../shared/types'
+import type { TimebackClient } from '../timeback-client.class'
+
+const VERIFY_CACHE_TTL_MS = 1500
+const PROFILE_CACHE_TTL_MS = 5000
+
+type VerifyCacheEntry = { atMs: number; result: TimebackVerifyResult }
+type ProfileCacheEntry = { atMs: number; profile: TimebackProfile }
+
+const verifyInFlight = new WeakMap<TimebackClient, Promise<TimebackVerifyResult>>()
+const verifyCache = new WeakMap<TimebackClient, VerifyCacheEntry>()
+
+const profileInFlight = new WeakMap<TimebackClient, Promise<TimebackProfile>>()
+const profileCache = new WeakMap<TimebackClient, ProfileCacheEntry>()
+
+/**
+ * Check whether a cached verification result is still fresh.
+ *
+ * @param entry - Cached entry (if any)
+ * @returns True if the cache entry exists and is within TTL
+ */
+function isVerifyCacheFresh(entry: VerifyCacheEntry | undefined): entry is VerifyCacheEntry {
+	return !!entry && Date.now() - entry.atMs < VERIFY_CACHE_TTL_MS
+}
+
+/**
+ * Check whether a cached profile result is still fresh.
+ *
+ * @param entry - Cached entry (if any)
+ * @returns True if the cache entry exists and is within TTL
+ */
+function isProfileCacheFresh(entry: ProfileCacheEntry | undefined): entry is ProfileCacheEntry {
+	return !!entry && Date.now() - entry.atMs < PROFILE_CACHE_TTL_MS
+}
+
+/**
+ * Verify the current user with in-flight dedupe and short-lived caching.
+ *
+ * @param timeback - Timeback client instance
+ * @param force - If true, bypass cache and in-flight reuse
+ * @returns Verify result
+ */
+export async function verifyOnce(
+	timeback: TimebackClient,
+	force: boolean,
+): Promise<TimebackVerifyResult> {
+	if (!force) {
+		const cached = verifyCache.get(timeback)
+
+		if (isVerifyCacheFresh(cached)) {
+			return cached.result
+		}
+
+		const existing = verifyInFlight.get(timeback)
+
+		if (existing) {
+			return await existing
+		}
+	}
+
+	const p = timeback.user.verify().then(result => {
+		/**
+		 * Guard against stale overwrites:
+		 *
+		 * If `force=true` triggers a newer request while an older one is still
+		 * in-flight, the older promise may resolve later. Only let the most
+		 * recent in-flight promise update the cache.
+		 */
+		if (verifyInFlight.get(timeback) === p) {
+			verifyCache.set(timeback, { atMs: Date.now(), result })
+		}
+		return result
+	})
+
+	verifyInFlight.set(timeback, p)
+	try {
+		return await p
+	} finally {
+		/**
+		 * Only remove the in-flight verification promise
+		 * if it is still the most recent for this client instance.
+		 */
+		if (verifyInFlight.get(timeback) === p) {
+			verifyInFlight.delete(timeback)
+		}
+	}
+}
+
+/**
+ * Get cached verification result if fresh.
+ *
+ * @param timeback - Timeback client instance
+ * @returns Cached result or undefined
+ */
+export function getVerifyCache(timeback: TimebackClient): TimebackVerifyResult | undefined {
+	const cached = verifyCache.get(timeback)
+	return isVerifyCacheFresh(cached) ? cached.result : undefined
+}
+
+/**
+ * Fetch the profile with in-flight dedupe and short-lived caching.
+ *
+ * @param timeback - Timeback client instance
+ * @param force - If true, bypass cache and in-flight reuse
+ * @returns The user's Timeback profile
+ */
+export async function fetchProfileOnce(
+	timeback: TimebackClient,
+	force: boolean,
+): Promise<TimebackProfile> {
+	if (!force) {
+		const cached = profileCache.get(timeback)
+
+		if (isProfileCacheFresh(cached)) {
+			return cached.profile
+		}
+
+		const existing = profileInFlight.get(timeback)
+
+		if (existing) {
+			return await existing
+		}
+	}
+
+	const p = timeback.user.fetch().then(profile => {
+		/**
+		 * Guard against stale overwrites:
+		 *
+		 * If `force=true` triggers a newer request while an older one is still
+		 * in-flight, the older promise may resolve later. Only let the most
+		 * recent in-flight promise update the cache.
+		 */
+		if (profileInFlight.get(timeback) === p) {
+			profileCache.set(timeback, { atMs: Date.now(), profile })
+		}
+		return profile
+	})
+
+	profileInFlight.set(timeback, p)
+	try {
+		return await p
+	} finally {
+		/**
+		 * Only remove the in-flight promise if it is still the most recent
+		 */
+		if (profileInFlight.get(timeback) === p) {
+			profileInFlight.delete(timeback)
+		}
+	}
+}
+
+/**
+ * Get cached profile result if fresh.
+ *
+ * @param timeback - Timeback client instance
+ * @returns Cached profile or undefined
+ */
+export function getProfileCache(timeback: TimebackClient): TimebackProfile | undefined {
+	const cached = profileCache.get(timeback)
+	return isProfileCacheFresh(cached) ? cached.profile : undefined
+}

package/dist/client/namespaces/activity.d.ts

@@ -25,7 +25,7 @@ export declare class ActivityManager {
      * @param params - Activity parameters
      * @returns Started activity instance
      *
-     * @example
+     * @example Basic usage
      * ```typescript
      * const activity = timeback.activity.start({
      *   id: 'lesson-1',
@@ -36,8 +36,7 @@ export declare class ActivityManager {
      * await activity.end({
      *   totalQuestions: 10,
      *   correctQuestions: 8,
-     *   attemptNumber: 1,
-     *   pctCompleteApp: 67,
+     *   pctComplete: 67,
      * })
      * ```
      */

package/dist/client/namespaces/activity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../../src/client/namespaces/activity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAE5E;;GAEG;AACH,qBAAa,eAAe;IAMf,OAAO,CAAC,QAAQ,CAAC,YAAY;IALzC;;;;OAIG;IACH,YAA6B,YAAY,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,EAAI;IAE7F;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CAEtC;CACD"}
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../../src/client/namespaces/activity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAE5E;;GAEG;AACH,qBAAa,eAAe;IAMf,OAAO,CAAC,QAAQ,CAAC,YAAY;IALzC;;;;OAIG;IACH,YAA6B,YAAY,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,EAAI;IAE7F;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CAEtC;CACD"}

package/dist/client.d.ts

@@ -21,7 +21,7 @@
  * activity.resume()
  *
  * // End tracking with metrics
- * await activity.end({ totalQuestions: 10, correctQuestions: 8, attemptNumber: 1 })
+ * await activity.end({ totalQuestions: 10, correctQuestions: 8 })
  * ```
  */
 export { createClient, TimebackClient } from './client/index';

package/dist/client.js

@@ -1,257 +1 @@
-// src/shared/constants.ts
-var DEFAULT_BASE_PATH = "/api/timeback";
-var ROUTES = {
-  ACTIVITY: "/activity",
-  IDENTITY: {
-    SIGNIN: "/identity/signin",
-    SIGNOUT: "/identity/signout",
-    CALLBACK: "/identity/callback"
-  },
-  USER: {
-    ME: "/user/me",
-    VERIFY: "/user/verify"
-  }
-};
-
-// src/client/lib/utils.ts
-function isBrowser() {
-  return typeof window !== "undefined";
-}
-function getDefaultBaseURL() {
-  if (!isBrowser()) {
-    return;
-  }
-  return `${window.location.origin}${DEFAULT_BASE_PATH}`;
-}
-
-// src/client/lib/fetch.ts
-function getDefaultFetch() {
-  const globalFetch = typeof globalThis === "undefined" ? undefined : globalThis.fetch;
-  if (!globalFetch) {
-    return;
-  }
-  return (input, init) => globalThis.fetch(input, init);
-}
-
-// src/client/lib/activity/activity.class.ts
-class Activity {
-  params;
-  sendActivity;
-  _startedAt;
-  _isPaused = false;
-  _pausedAt;
-  _totalPausedMs = 0;
-  _ended = false;
-  constructor(params, sendActivity) {
-    this.params = params;
-    this.sendActivity = sendActivity;
-    this._startedAt = new Date;
-  }
-  get startedAt() {
-    return this._startedAt;
-  }
-  get isPaused() {
-    return this._isPaused;
-  }
-  get elapsedMs() {
-    if (this._ended) {
-      return 0;
-    }
-    const now = new Date;
-    let elapsed = now.getTime() - this._startedAt.getTime() - this._totalPausedMs;
-    if (this._isPaused && this._pausedAt) {
-      elapsed -= now.getTime() - this._pausedAt.getTime();
-    }
-    return Math.max(0, elapsed);
-  }
-  _buildPayload(data) {
-    const now = new Date;
-    const pausedMs = this._totalPausedMs + (this._isPaused && this._pausedAt ? now.getTime() - this._pausedAt.getTime() : 0);
-    const elapsedMs = now.getTime() - this._startedAt.getTime() - pausedMs;
-    return {
-      id: this.params.id,
-      name: this.params.name,
-      course: this.params.course,
-      startedAt: this._startedAt.toISOString(),
-      endedAt: now.toISOString(),
-      elapsedMs: Math.max(0, elapsedMs),
-      pausedMs,
-      metrics: {
-        totalQuestions: data.totalQuestions,
-        correctQuestions: data.correctQuestions,
-        ...data.xpEarned === undefined ? {} : { xpEarned: data.xpEarned },
-        ...data.masteredUnits === undefined ? {} : { masteredUnits: data.masteredUnits }
-      },
-      ...data.attemptNumber === undefined ? {} : { attemptNumber: data.attemptNumber },
-      ...data.pctCompleteApp === undefined ? {} : { pctCompleteApp: data.pctCompleteApp }
-    };
-  }
-  pause() {
-    if (this._isPaused || this._ended)
-      return;
-    this._isPaused = true;
-    this._pausedAt = new Date;
-  }
-  resume() {
-    if (!this._isPaused || this._ended || !this._pausedAt)
-      return;
-    this._totalPausedMs += new Date().getTime() - this._pausedAt.getTime();
-    this._isPaused = false;
-    this._pausedAt = undefined;
-  }
-  async end(data) {
-    if (this._ended)
-      return;
-    this._ended = true;
-    if (this._isPaused && this._pausedAt) {
-      this._totalPausedMs += new Date().getTime() - this._pausedAt.getTime();
-      this._isPaused = false;
-      this._pausedAt = undefined;
-    }
-    const payload = this._buildPayload(data);
-    await this.sendActivity(payload);
-  }
-}
-// src/client/namespaces/activity.ts
-class ActivityManager {
-  sendActivity;
-  constructor(sendActivity) {
-    this.sendActivity = sendActivity;
-  }
-  start(params) {
-    return new Activity(params, this.sendActivity);
-  }
-}
-// src/client/namespaces/auth.ts
-class Auth {
-  getBaseURL;
-  constructor(getBaseURL) {
-    this.getBaseURL = getBaseURL;
-  }
-  signIn() {
-    if (!isBrowser()) {
-      throw new Error("signIn() requires a browser environment");
-    }
-    window.location.href = `${this.getBaseURL()}${ROUTES.IDENTITY.SIGNIN}`;
-  }
-}
-// src/client/namespaces/user.ts
-class User {
-  getBaseURL;
-  fetchImpl;
-  constructor(getBaseURL, fetchImpl) {
-    this.getBaseURL = getBaseURL;
-    this.fetchImpl = fetchImpl;
-  }
-  async fetch() {
-    if (!isBrowser()) {
-      throw new Error("user.fetch() requires a browser environment");
-    }
-    const response = await this.fetchImpl(`${this.getBaseURL()}${ROUTES.USER.ME}`, {
-      method: "GET",
-      credentials: "include"
-    });
-    if (!response.ok) {
-      const errorResponse = await response.json().catch(() => ({ error: "Unknown error" }));
-      throw new Error(errorResponse.error ?? "Failed to fetch user profile");
-    }
-    return response.json();
-  }
-  async verify() {
-    if (!isBrowser()) {
-      throw new Error("user.verify() requires a browser environment");
-    }
-    const response = await this.fetchImpl(`${this.getBaseURL()}${ROUTES.USER.VERIFY}`, {
-      method: "GET",
-      credentials: "include"
-    });
-    if (!response.ok) {
-      const errorResponse = await response.json().catch(() => ({ error: "Unknown error" }));
-      throw new Error(errorResponse.error ?? "Failed to verify Timeback user");
-    }
-    const data = await response.json();
-    if (data.verified && data.timebackId) {
-      return { verified: true, timebackId: data.timebackId };
-    }
-    return { verified: false };
-  }
-}
-// src/client/timeback-client.class.ts
-class TimebackClient {
-  activity;
-  auth;
-  user;
-  _baseURL;
-  _fetch;
-  constructor(config = {}) {
-    this._baseURL = config.baseURL;
-    const baseFetch = config.fetch ?? getDefaultFetch();
-    if (!baseFetch) {
-      throw new Error("TimebackClient requires a fetch implementation. " + "Provide `fetch` in the constructor config for non-browser runtimes.");
-    }
-    const rawPlugins = config.plugins;
-    const plugins = Array.isArray(rawPlugins) ? rawPlugins : rawPlugins ? [rawPlugins] : [];
-    this._fetch = plugins.reduce((f, p) => p.wrapFetch(f), baseFetch);
-    this.activity = new ActivityManager((payload) => this.sendActivity(payload));
-    this.auth = new Auth(() => this.baseURL);
-    this.user = new User(() => this.baseURL, this._fetch);
-  }
-  get baseURL() {
-    if (!this._baseURL) {
-      const resolved = getDefaultBaseURL();
-      if (!resolved) {
-        throw new Error("Timeback client requires a browser environment for default baseURL. " + "Provide an explicit baseURL for server-side usage.");
-      }
-      this._baseURL = resolved;
-    }
-    return this._baseURL;
-  }
-  async sendActivity(payload) {
-    const response = await this._fetch(`${this.baseURL}${ROUTES.ACTIVITY}`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(payload),
-      credentials: "include"
-    });
-    if (!response.ok) {
-      const errorResponse = await response.json().catch(() => ({ error: "Unknown error" }));
-      throw new Error(errorResponse.error ?? "Failed to send activity");
-    }
-  }
-}
-
-// src/client/timeback-client.ts
-function createClient(config = {}) {
-  const baseURL = config.baseURL ?? getDefaultBaseURL();
-  return new TimebackClient({
-    baseURL,
-    fetch: config.fetch,
-    plugins: config.plugins
-  });
-}
-// src/client/auth/bearer.ts
-function bearer(options) {
-  const headerName = options.headerName ?? "Authorization";
-  const prefix = options.prefix ?? "Bearer ";
-  return {
-    wrapFetch(fetchImpl) {
-      return async (input, init) => {
-        const token = await options.getToken();
-        if (!token) {
-          throw new Error("Missing bearer token (are you authenticated yet?)");
-        }
-        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
-        if (!headers.has(headerName)) {
-          headers.set(headerName, `${prefix}${token}`);
-        }
-        return fetchImpl(input, { ...init, headers });
-      };
-    }
-  };
-}
-export {
-  createClient,
-  bearer,
-  TimebackClient,
-  Activity
-};
+import{a as o,b as y,c as b}from"./chunk-ahy54f2r.js";function r(e){let i=e.headerName??"Authorization",k=e.prefix??"Bearer ";return{wrapFetch(s){return async(t,m)=>{let a=await e.getToken();if(!a)throw Error("Missing bearer token (are you authenticated yet?)");let c=new Headers(m?.headers??(t instanceof Request?t.headers:void 0));if(!c.has(i))c.set(i,`${k}${a}`);return s(t,{...m,headers:c})}}}}export{b as createClient,r as bearer,y as TimebackClient,o as Activity};