timeback 0.0.0-alpha.2 → 0.1.0

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

@@ -0,0 +1,37 @@
+/**
+ * Activity Namespace
+ *
+ * Activity creation and management.
+ */
+import { Activity } from '../lib/activity';
+import type { ActivityEndPayload, ActivityParams } from '../../shared/types';
+/**
+ * Activity namespace for creating and managing activities.
+ */
+export declare class ActivityManager {
+    private readonly sendActivity;
+    /**
+     * Create activity manager.
+     *
+     * @param sendActivity - Function to send activity to server
+     */
+    constructor(sendActivity: (payload: ActivityEndPayload) => Promise<void>);
+    /**
+     * Create a new activity.
+     *
+     * The activity is created but not started. Call `.start()` to begin tracking.
+     *
+     * @param params - Activity parameters
+     * @returns Activity instance
+     *
+     * @example
+     * ```typescript
+     * const activity = timeback.activity.new({ id: 'lesson-1', name: 'Intro', courseCode: 'MATH-1' })
+     * activity.start()
+     * // ... user completes lesson ...
+     * await activity.end({ totalQuestions: 10, correctQuestions: 8 })
+     * ```
+     */
+    new(params: ActivityParams): Activity;
+}
+//# sourceMappingURL=activity.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;OAeG;IACH,GAAG,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CAEpC;CACD"}

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

@@ -0,0 +1,33 @@
+/**
+ * Auth Namespace
+ *
+ * SSO redirect helpers for Timeback client.
+ * Note: User session state is managed by your own auth system.
+ */
+/**
+ * Auth interface.
+ */
+interface IAuth {
+    /** Sign in via Timeback SSO (redirects to IdP) */
+    signIn(): void;
+}
+/**
+ * SSO redirect helpers for Timeback client.
+ */
+export declare class Auth implements IAuth {
+    private readonly getBaseURL;
+    /**
+     * Create auth instance.
+     *
+     * @param getBaseURL - Function that returns the base URL for API routes
+     */
+    constructor(getBaseURL: () => string);
+    /**
+     * Sign in via Timeback SSO.
+     *
+     * Redirects the browser to the Timeback SSO login page.
+     */
+    signIn(): void;
+}
+export {};
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/client/namespaces/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;GAEG;AACH,UAAU,KAAK;IACd,kDAAkD;IAClD,MAAM,IAAI,IAAI,CAAA;CACd;AAED;;GAEG;AACH,qBAAa,IAAK,YAAW,KAAK;IAMrB,OAAO,CAAC,QAAQ,CAAC,UAAU;IALvC;;;;OAIG;IACH,YAA6B,UAAU,EAAE,MAAM,MAAM,EAAI;IAEzD;;;;OAIG;IACH,MAAM,IAAI,IAAI,CAKb;CACD"}

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

@@ -0,0 +1,7 @@
+/**
+ * Client Namespaces
+ */
+export { ActivityManager } from './activity';
+export { Auth } from './auth';
+export { User } from './user';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/namespaces/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA"}

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

@@ -0,0 +1,29 @@
+/**
+ * User Namespace
+ *
+ * User identity and profile data.
+ */
+import type { TimebackProfile } from '../../shared/types';
+/**
+ * User namespace for profile data.
+ */
+export declare class User {
+    private readonly getBaseURL;
+    /**
+     * Create user instance.
+     *
+     * @param getBaseURL - Function that returns the base URL for API routes
+     */
+    constructor(getBaseURL: () => string);
+    /**
+     * Fetch the full user profile from the Timeback API.
+     *
+     * This makes an API call to get enriched user data including XP, school,
+     * enrolled courses, and goals.
+     *
+     * @returns The user's Timeback profile
+     * @throws Error if not authenticated or API call fails
+     */
+    fetch(): Promise<TimebackProfile>;
+}
+//# sourceMappingURL=user.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/client/namespaces/user.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAEzD;;GAEG;AACH,qBAAa,IAAI;IAMJ,OAAO,CAAC,QAAQ,CAAC,UAAU;IALvC;;;;OAIG;IACH,YAA6B,UAAU,EAAE,MAAM,MAAM,EAAI;IAEzD;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,eAAe,CAAC,CAoBtC;CACD"}

package/dist/client/timeback-client.class.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Timeback Client Class
+ *
+ * Client-side SDK for activity tracking and identity.
+ */
+import { ActivityManager, Auth, User } from './namespaces';
+/**
+ * Timeback client configuration.
+ */
+interface TimebackClientConfig {
+    /** Base URL for Timeback API routes. Defaults to window.location.origin + '/api/timeback' */
+    baseURL?: string;
+}
+/**
+ * Timeback client for activity tracking and identity.
+ */
+export declare class TimebackClient {
+    readonly activity: ActivityManager;
+    readonly auth: Auth;
+    readonly user: User;
+    private _baseURL;
+    /**
+     * Create a new Timeback client.
+     *
+     * @param config - Client configuration
+     */
+    constructor(config?: TimebackClientConfig);
+    /**
+     * Get the base URL, resolving lazily if needed.
+     *
+     * @returns The base URL
+     */
+    private get baseURL();
+    private sendActivity;
+}
+export {};
+//# sourceMappingURL=timeback-client.class.d.ts.map

package/dist/client/timeback-client.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeback-client.class.d.ts","sourceRoot":"","sources":["../../src/client/timeback-client.class.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAI1D;;GAEG;AACH,UAAU,oBAAoB;IAC7B,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,qBAAa,cAAc;IAC1B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,OAAO,CAAC,QAAQ,CAAoB;IAEpC;;;;OAIG;IACH,YAAY,MAAM,GAAE,oBAAyB,EAK5C;IAED;;;;OAIG;IACH,OAAO,KAAK,OAAO,GAYlB;YAOa,YAAY;CAiB1B"}

package/dist/client/timeback-client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Timeback Client Factory
+ *
+ * Factory function for creating Timeback client instances.
+ */
+import { TimebackClient } from './timeback-client.class';
+/**
+ * Create a Timeback client instance.
+ *
+ * @param config - Client configuration (baseURL is optional, defaults to window.location.origin + '/api/timeback')
+ * @returns Timeback client
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'timeback/client'
+ *
+ * // Zero config - uses window.location.origin + '/api/timeback'
+ * const client = createClient()
+ *
+ * // With explicit URL
+ * const client = createClient({
+ *   baseURL: 'https://myapp.com/api/timeback',
+ * })
+ * ```
+ */
+export declare function createClient(config?: {
+    baseURL?: string;
+}): TimebackClient;
+//# sourceMappingURL=timeback-client.d.ts.map

package/dist/client/timeback-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeback-client.d.ts","sourceRoot":"","sources":["../../src/client/timeback-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAExD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,cAAc,CAG9E"}

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Timeback Client
+ *
+ * Framework-agnostic client exports.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'timeback/client'
+ *
+ * const client = createClient()
+ *
+ * // Start tracking
+ * const activity = client.startActivity({
+ *   id: 'lesson-123',
+ *   name: 'Algebra Basics',
+ *   courseCode: 'FASTMATH-1',
+ * })
+ *
+ * // Pause/resume
+ * activity.pause()
+ * activity.resume()
+ *
+ * // End tracking with metrics
+ * await activity.end({ totalQuestions: 10, correctQuestions: 8 })
+ * ```
+ */
+export { createClient, TimebackClient } from './client/index';
+export { createActivity, Activity } from './client/index';
+export type { TimebackUser, TimebackIdentity, TimebackProfile, ActivityParams, ActivityMetrics, } from './shared/types';
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzD,YAAY,EACX,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,eAAe,GACf,MAAM,gBAAgB,CAAA"}

package/dist/client.js

@@ -0,0 +1,198 @@
+// 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"
+  }
+};
+
+// 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/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;
+  }
+  get isStarted() {
+    return this._startedAt !== undefined;
+  }
+  get startedAt() {
+    return this._startedAt;
+  }
+  start() {
+    if (this._startedAt)
+      return this;
+    this._startedAt = new Date;
+    return this;
+  }
+  get isPaused() {
+    return this._isPaused;
+  }
+  get elapsedMs() {
+    if (!this._startedAt || 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);
+  }
+  pause() {
+    if (!this._startedAt || 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(metrics) {
+    if (!this._startedAt) {
+      throw new Error("Cannot end activity that was never started");
+    }
+    if (this._ended)
+      return;
+    this._ended = true;
+    if (this._isPaused && this._pausedAt) {
+      this._totalPausedMs += new Date().getTime() - this._pausedAt.getTime();
+    }
+    const endedAt = new Date;
+    const elapsedMs = endedAt.getTime() - this._startedAt.getTime() - this._totalPausedMs;
+    const payload = {
+      id: this.params.id,
+      name: this.params.name,
+      courseCode: this.params.courseCode,
+      startedAt: this._startedAt.toISOString(),
+      endedAt: endedAt.toISOString(),
+      elapsedMs: Math.max(0, elapsedMs),
+      pausedMs: this._totalPausedMs,
+      metrics
+    };
+    await this.sendActivity(payload);
+  }
+}
+
+// src/client/lib/activity/activity.ts
+function createActivity(params, sendActivity) {
+  return new Activity(params, sendActivity);
+}
+// src/client/namespaces/activity.ts
+class ActivityManager {
+  sendActivity;
+  constructor(sendActivity) {
+    this.sendActivity = sendActivity;
+  }
+  new(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;
+  constructor(getBaseURL) {
+    this.getBaseURL = getBaseURL;
+  }
+  async fetch() {
+    if (!isBrowser()) {
+      throw new Error("user.fetch() requires a browser environment");
+    }
+    const response = await fetch(`${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();
+  }
+}
+// src/client/timeback-client.class.ts
+class TimebackClient {
+  activity;
+  auth;
+  user;
+  _baseURL;
+  constructor(config = {}) {
+    this._baseURL = config.baseURL;
+    this.activity = new ActivityManager((payload) => this.sendActivity(payload));
+    this.auth = new Auth(() => this.baseURL);
+    this.user = new User(() => this.baseURL);
+  }
+  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 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 });
+}
+export {
+  createClient,
+  createActivity,
+  TimebackClient,
+  Activity
+};

package/dist/index.d.ts

@@ -1,17 +1,30 @@
 /**
- * A simple identity function that returns the input unchanged.
+ * Timeback SDK
+ *
+ * Server-side exports for the Timeback SDK.
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from 'timeback'
+ *
+ * export const timeback = await createServer({
+ *   env: 'production',
+ *   api: {
+ *     clientId: process.env.TIMEBACK_API_CLIENT_ID!,
+ *     clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
+ *   },
+ *   identity: {
+ *     mode: 'custom',
+ *     getUser: async (req) => ({
+ *       id: session.userId,
+ *       email: session.user.email,
+ *       name: session.user.name,
+ *     }),
+ *   },
+ * })
+ * ```
  */
-export declare function identity<T>(value: T): T;
-/**
- * A no-op function that does nothing.
- */
-export declare function noop(): void;
-/**
- * Returns true. Useful as a placeholder predicate.
- */
-export declare function yes(): boolean;
-/**
- * Returns false. Useful as a placeholder predicate.
- */
-export declare function no(): boolean;
+export { createServer } from './server';
+export type { ApiCredentials, CustomIdentityConfig, Environment, IdentityConfig, SsoIdentityConfig, TimebackConfig, TimebackInstance, BuildStateContext, CallbackSuccessContext, CallbackErrorContext, OIDCTokens, OIDCUserInfo, } from './server';
+export type { TimebackUser, ActivityParams, ActivityMetrics } from './shared/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEvC;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAAG;AAE/B;;GAEG;AACH,wBAAgB,GAAG,IAAI,OAAO,CAE7B;AAED;;GAEG;AACH,wBAAgB,EAAE,IAAI,OAAO,CAE5B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,YAAY,EACX,cAAc,EACd,oBAAoB,EACpB,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAEhB,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,UAAU,EACV,YAAY,GACZ,MAAM,UAAU,CAAA;AAEjB,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA"}