@testerpaykit/sdk 0.0.0-stage → 1.1.0

package/dist/index.mjs

@@ -0,0 +1,2063 @@
+// src/TesterPayKit.ts
+import { COLLECTIONS as COLLECTIONS6, BUG_REPORT_TYPES, BUG_REPORT_CATEGORIES, BUG_REPORT_SEVERITIES } from "@testerpaykit/core";
+
+// src/SessionManager.ts
+import { COLLECTIONS } from "@testerpaykit/core";
+import { v4 as uuidv4 } from "uuid";
+var SessionManager = class {
+  // non-null while clock is running
+  constructor(storage) {
+    this.currentSessionId = null;
+    this.sessionStartTime = 0;
+    // Foreground (paid-time) clock
+    this.foregroundAccumulatedMs = 0;
+    this.foregroundClockStartMs = null;
+    this.storage = storage;
+  }
+  /**
+   * Start a new testing session.
+   *
+   * Creates a new session with a unique ID and stores it in the database.
+   * If there's an active session, it will be ended before starting the new one.
+   *
+   * @returns Promise resolving to the new session ID
+   */
+  async startSession() {
+    if (this.hasActiveSession()) {
+      await this.endSession();
+    }
+    const sessionId = uuidv4();
+    this.currentSessionId = sessionId;
+    this.sessionStartTime = Date.now();
+    this.foregroundAccumulatedMs = 0;
+    this.foregroundClockStartMs = Date.now();
+    await this.storage.insert(COLLECTIONS.sessions, {
+      id: sessionId,
+      started_at: this.sessionStartTime,
+      screen_view_count: 0,
+      tap_count: 0,
+      ended_at: null,
+      end_reason: null,
+      duration_seconds: null,
+      foreground_seconds: null
+    });
+    return sessionId;
+  }
+  /**
+   * End the current testing session.
+   *
+   * Calculates session duration and updates the database.
+   * After ending, no session will be active.
+   *
+   * @param endReason - Reason for ending the session (default: 'completed')
+   */
+  async endSession(endReason = "completed") {
+    if (!this.currentSessionId) return;
+    this.pauseForegroundClock();
+    const endTime = Date.now();
+    const duration = Math.floor((endTime - this.sessionStartTime) / 1e3);
+    const foregroundSeconds = this.getForegroundSeconds();
+    await this.storage.update(
+      COLLECTIONS.sessions,
+      { id: this.currentSessionId },
+      {
+        ended_at: endTime,
+        duration_seconds: duration,
+        end_reason: endReason,
+        foreground_seconds: foregroundSeconds
+      }
+    );
+    this.currentSessionId = null;
+    this.sessionStartTime = 0;
+    this.foregroundAccumulatedMs = 0;
+    this.foregroundClockStartMs = null;
+  }
+  /**
+   * Pause the foreground (paid-time) clock.
+   * Call when the app moves to background. Has no effect if already paused.
+   */
+  pauseForegroundClock() {
+    if (this.foregroundClockStartMs !== null) {
+      this.foregroundAccumulatedMs += Date.now() - this.foregroundClockStartMs;
+      this.foregroundClockStartMs = null;
+    }
+  }
+  /**
+   * Resume the foreground (paid-time) clock.
+   * Call when the app returns to foreground. Has no effect if already running.
+   */
+  resumeForegroundClock() {
+    if (this.foregroundClockStartMs === null) {
+      this.foregroundClockStartMs = Date.now();
+    }
+  }
+  /**
+   * Get the accumulated foreground seconds for the current session.
+   *
+   * @returns Foreground time in whole seconds
+   */
+  getForegroundSeconds() {
+    let totalMs = this.foregroundAccumulatedMs;
+    if (this.foregroundClockStartMs !== null) {
+      totalMs += Date.now() - this.foregroundClockStartMs;
+    }
+    return Math.floor(totalMs / 1e3);
+  }
+  /**
+   * Get the current session ID.
+   *
+   * @returns Current session ID or null if no session is active
+   */
+  getCurrentSessionId() {
+    return this.currentSessionId;
+  }
+  /**
+   * Check if there's an active session.
+   *
+   * @returns true if a session is currently active
+   */
+  hasActiveSession() {
+    return this.currentSessionId !== null;
+  }
+  /**
+   * Get the current session duration in seconds.
+   *
+   * @returns Duration in seconds, or 0 if no session is active
+   */
+  getSessionDuration() {
+    if (!this.hasActiveSession()) return 0;
+    return Math.floor((Date.now() - this.sessionStartTime) / 1e3);
+  }
+  /**
+   * Get the epoch-ms timestamp when the current session started.
+   *
+   * @returns Epoch ms, or null when no session is active
+   */
+  getCurrentSessionStartedAt() {
+    if (!this.hasActiveSession()) return null;
+    return this.sessionStartTime;
+  }
+  /**
+   * Increment the screen view count for the current session.
+   * Internal method used by EventTracker.
+   */
+  async incrementScreenViews() {
+    if (!this.currentSessionId) return;
+    const row = await this.storage.findOne(
+      COLLECTIONS.sessions,
+      { id: this.currentSessionId }
+    );
+    if (!row) return;
+    await this.storage.update(
+      COLLECTIONS.sessions,
+      { id: this.currentSessionId },
+      { screen_view_count: (row.screen_view_count ?? 0) + 1 }
+    );
+  }
+  /**
+   * Increment the tap count for the current session.
+   * Internal method used by EventTracker.
+   */
+  async incrementTaps() {
+    if (!this.currentSessionId) return;
+    const row = await this.storage.findOne(
+      COLLECTIONS.sessions,
+      { id: this.currentSessionId }
+    );
+    if (!row) return;
+    await this.storage.update(
+      COLLECTIONS.sessions,
+      { id: this.currentSessionId },
+      { tap_count: (row.tap_count ?? 0) + 1 }
+    );
+  }
+};
+
+// src/EventTracker.ts
+import { COLLECTIONS as COLLECTIONS2 } from "@testerpaykit/core";
+import { v4 as uuidv42 } from "uuid";
+var EventTracker = class {
+  constructor(storage, captureFlags) {
+    this.sessionId = null;
+    this.storage = storage;
+    this.captureFlags = {
+      captureScreenViews: true,
+      captureTapEvents: true,
+      captureErrors: true,
+      captureCrashes: true,
+      ...captureFlags
+    };
+  }
+  /**
+   * Set the current session ID.
+   * Must be called before tracking events.
+   *
+   * @param sessionId - The active session ID
+   */
+  setSessionId(sessionId) {
+    this.sessionId = sessionId;
+  }
+  /**
+   * Track a screen view event.
+   * Gated by captureScreenViews flag.
+   *
+   * @param screenName - Name or route of the screen being viewed
+   * @param metadata - Optional additional metadata
+   */
+  async trackScreenView(screenName, metadata) {
+    if (!this.captureFlags.captureScreenViews) return;
+    await this.trackEvent("screen_view", {
+      screenName,
+      ...metadata
+    });
+  }
+  /**
+   * Track a tap/click event.
+   * Gated by captureTapEvents flag.
+   *
+   * @param screenName - Name of the screen where the tap occurred
+   * @param elementId - Optional ID of the tapped element
+   */
+  async trackTap(screenName, elementId) {
+    if (!this.captureFlags.captureTapEvents) return;
+    await this.trackEvent("tap", {
+      screenName,
+      elementId
+    });
+  }
+  /**
+   * Track a custom event.
+   *
+   * @param eventType - Type of the event
+   * @param metadata - Optional event metadata
+   */
+  async trackEvent(eventType, metadata) {
+    if (!this.sessionId) {
+      console.warn("No active session. Event not tracked:", eventType);
+      return;
+    }
+    await this.storage.insert(COLLECTIONS2.events, {
+      id: uuidv42(),
+      session_id: this.sessionId,
+      timestamp: Date.now(),
+      event_type: eventType,
+      screen_name: metadata?.screenName ?? null,
+      element_id: metadata?.elementId ?? null,
+      metadata: metadata ? JSON.stringify(metadata) : null
+    });
+  }
+  /**
+   * Track an error event.
+   * Gated by captureErrors flag.
+   *
+   * @param message - Error message
+   * @param stack - Optional stack trace
+   */
+  async trackError(message, stack) {
+    if (!this.captureFlags.captureErrors) return;
+    await this.storeBugReport("error", message, stack);
+  }
+  /**
+   * Track a crash event.
+   * Gated by captureCrashes flag.
+   *
+   * @param message - Crash message
+   * @param stack - Stack trace
+   */
+  async trackCrash(message, stack) {
+    if (!this.captureFlags.captureCrashes) return;
+    await this.storeBugReport("crash", message, stack);
+  }
+  /**
+   * Track a feedback submission.
+   *
+   * @param content - Feedback content
+   * @param rating - Optional numeric rating
+   */
+  async trackFeedback(content, rating) {
+    if (!this.sessionId) {
+      console.warn("No active session. Feedback not tracked.");
+      return;
+    }
+    const feedbackId = uuidv42();
+    await this.storage.insert(COLLECTIONS2.feedbacks, {
+      id: feedbackId,
+      session_id: this.sessionId,
+      content,
+      rating: rating ?? null,
+      created_at: Date.now()
+    });
+    await this.trackEvent("feedback_submit", {
+      feedbackId,
+      length: content.length,
+      hasRating: rating !== void 0
+    });
+  }
+  /**
+   * Track task start event.
+   *
+   * @param taskId - Unique task identifier
+   * @param title - Task title
+   */
+  async trackTaskStart(taskId, title) {
+    if (!this.sessionId) {
+      console.warn("No active session. Task start not tracked.");
+      return;
+    }
+    const now = Date.now();
+    const existing = await this.storage.findOne(
+      COLLECTIONS2.tasks,
+      { id: taskId }
+    );
+    if (existing) {
+      await this.storage.update(COLLECTIONS2.tasks, { id: taskId }, { started_at: now });
+    } else {
+      await this.storage.insert(COLLECTIONS2.tasks, {
+        id: taskId,
+        task_preset_id: taskId,
+        title,
+        started_at: now,
+        created_at: now,
+        is_completed: 0,
+        completed_at: null
+      });
+    }
+    await this.trackEvent("task_start", { taskId, title });
+  }
+  /**
+   * Track task completion event.
+   *
+   * @param taskId - Unique task identifier
+   */
+  async trackTaskComplete(taskId) {
+    if (!this.sessionId) {
+      console.warn("No active session. Task completion not tracked.");
+      return;
+    }
+    await this.storage.update(
+      COLLECTIONS2.tasks,
+      { id: taskId },
+      { completed_at: Date.now(), is_completed: 1 }
+    );
+    await this.trackEvent("task_complete", { taskId });
+  }
+  /**
+   * Store a bug report (error or crash).
+   *
+   * @param severity - Severity level ('error' or 'crash')
+   * @param message - Error/crash message
+   * @param stack - Optional stack trace
+   */
+  async storeBugReport(severity, message, stack) {
+    if (!this.sessionId) {
+      console.warn(`No active session. ${severity} not tracked.`);
+      return;
+    }
+    await this.storage.insert(COLLECTIONS2.bugReports, {
+      id: uuidv42(),
+      session_id: this.sessionId,
+      timestamp: Date.now(),
+      message,
+      stack: stack ?? null,
+      severity
+    });
+  }
+  /**
+   * Get event counts for a time period.
+   * Internal method for metrics aggregation.
+   *
+   * @param start - Start timestamp
+   * @param end - End timestamp
+   * @returns Map of event types to counts
+   */
+  async getEventCounts(start, end) {
+    const events = await this.storage.find(
+      COLLECTIONS2.events
+    );
+    const counts = {};
+    for (const event of events) {
+      if (event.timestamp >= start && event.timestamp <= end) {
+        counts[event.event_type] = (counts[event.event_type] ?? 0) + 1;
+      }
+    }
+    return counts;
+  }
+  /**
+   * Get unique screen names for a time period.
+   * Internal method for metrics aggregation.
+   *
+   * @param start - Start timestamp
+   * @param end - End timestamp
+   * @returns Array of unique screen names
+   */
+  async getUniqueScreens(start, end) {
+    const events = await this.storage.find(COLLECTIONS2.events);
+    const seen = /* @__PURE__ */ new Set();
+    for (const event of events) {
+      if (event.event_type === "screen_view" && event.screen_name !== null && event.screen_name !== void 0 && event.timestamp >= start && event.timestamp <= end) {
+        seen.add(event.screen_name);
+      }
+    }
+    return Array.from(seen);
+  }
+};
+
+// src/MetricsAggregator.ts
+import {
+  COLLECTIONS as COLLECTIONS3
+} from "@testerpaykit/core";
+import { v4 as uuidv43 } from "uuid";
+var ValidationConstants = {
+  minActiveMinutes: 10,
+  minUniqueScreens: 5,
+  maxTapsPerMinute: 100,
+  minSessions: 1
+};
+var MetricsAggregator = class {
+  constructor(storage, config) {
+    this.storage = storage;
+    this.config = config;
+  }
+  /**
+   * Aggregate a weekly summary for the past 7 days.
+   *
+   * @returns Promise resolving to the generated WeeklySummary
+   */
+  async aggregateWeeklySummary() {
+    const now = Date.now();
+    const weekAgo = now - 7 * 24 * 60 * 60 * 1e3;
+    return this.aggregateSummaryForPeriod(weekAgo, now);
+  }
+  /**
+   * Aggregate a summary for a specific time period.
+   *
+   * @param startTime - Start timestamp (milliseconds)
+   * @param endTime - End timestamp (milliseconds)
+   * @returns Promise resolving to the generated WeeklySummary
+   */
+  async aggregateSummaryForPeriod(startTime, endTime) {
+    const sessions = await this.getSessions(startTime, endTime);
+    const uniqueScreens = await this.getUniqueScreens(startTime, endTime);
+    const feedbackStats = await this.getFeedbackStats(startTime, endTime);
+    const taskStats = await this.getTaskStats(startTime, endTime);
+    const bugReportStats = await this.getBugReportStats(startTime, endTime);
+    const totalSessions = sessions.length;
+    const totalDuration = sessions.reduce((sum, s) => sum + (s.duration_seconds || 0), 0);
+    const activeMinutes = Math.floor(totalDuration / 60);
+    const totalScreenViews = sessions.reduce((sum, s) => sum + s.screen_view_count, 0);
+    const totalTaps = sessions.reduce((sum, s) => sum + s.tap_count, 0);
+    const avgTapsPerMinute = activeMinutes > 0 ? totalTaps / activeMinutes : 0;
+    const sessionMetrics = {
+      totalSessions,
+      activeMinutes,
+      uniqueScreens: uniqueScreens.length,
+      totalScreenViews,
+      avgTapsPerMinute,
+      tasksStarted: taskStats.started,
+      tasksCompleted: taskStats.completed,
+      crashes: bugReportStats.crashes,
+      errors: bugReportStats.errors,
+      feedbackCount: feedbackStats.count,
+      avgFeedbackLength: feedbackStats.avgLength,
+      qualityFlags: this.calculateQualityFlags(
+        totalSessions,
+        activeMinutes,
+        uniqueScreens.length,
+        avgTapsPerMinute
+      )
+    };
+    const integrityHash = this.generateIntegrityHash(sessionMetrics);
+    const summary = {
+      id: uuidv43(),
+      projectId: this.config.projectId,
+      testerId: this.config.testerId,
+      deviceId: this.config.deviceId,
+      periodStart: new Date(startTime).toISOString(),
+      periodEnd: new Date(endTime).toISOString(),
+      metrics: sessionMetrics,
+      integrityHash,
+      deviceMetadata: this.config.deviceMetadata,
+      appMetadata: this.config.appMetadata,
+      status: "pending",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      estimatedPayout: this.calculateEstimatedPayout(sessionMetrics)
+    };
+    return summary;
+  }
+  /**
+   * Store a weekly summary in the local database.
+   *
+   * @param summary - The summary to store
+   */
+  async storeSummary(summary) {
+    await this.storage.insert(COLLECTIONS3.weeklySummaries, {
+      id: summary.id,
+      data: JSON.stringify(summary),
+      status: summary.status,
+      created_at: Date.now()
+    });
+  }
+  /**
+   * Get pending summaries from the local database.
+   *
+   * @returns Array of pending WeeklySummary objects
+   */
+  async getPendingSummaries() {
+    const results = await this.storage.find(
+      COLLECTIONS3.weeklySummaries,
+      { status: "pending" }
+    );
+    return results.map((r) => JSON.parse(r.data));
+  }
+  /**
+   * Update summary status.
+   *
+   * @param summaryId - ID of the summary
+   * @param status - New status
+   */
+  async updateSummaryStatus(summaryId, status) {
+    await this.storage.update(
+      COLLECTIONS3.weeklySummaries,
+      { id: summaryId },
+      { status }
+    );
+  }
+  // Private helper methods
+  async getSessions(start, end) {
+    const all = await this.storage.find(COLLECTIONS3.sessions);
+    return all.filter((s) => s.started_at >= start && s.started_at <= end);
+  }
+  async getEventCounts(start, end) {
+    const all = await this.storage.find(
+      COLLECTIONS3.events
+    );
+    const counts = {};
+    for (const event of all) {
+      if (event.timestamp >= start && event.timestamp <= end) {
+        counts[event.event_type] = (counts[event.event_type] ?? 0) + 1;
+      }
+    }
+    return counts;
+  }
+  async getUniqueScreens(start, end) {
+    const all = await this.storage.find(COLLECTIONS3.events);
+    const seen = /* @__PURE__ */ new Set();
+    for (const event of all) {
+      if (event.event_type === "screen_view" && event.screen_name !== null && event.screen_name !== void 0 && event.timestamp >= start && event.timestamp <= end) {
+        seen.add(event.screen_name);
+      }
+    }
+    return Array.from(seen);
+  }
+  async getFeedbackStats(start, end) {
+    const all = await this.storage.find(COLLECTIONS3.feedbacks);
+    const feedbacks = all.filter((f) => f.created_at >= start && f.created_at <= end);
+    if (feedbacks.length === 0) {
+      return { count: 0, avgLength: 0 };
+    }
+    const totalLength = feedbacks.reduce((sum, f) => sum + f.content.length, 0);
+    return {
+      count: feedbacks.length,
+      avgLength: Math.round(totalLength / feedbacks.length)
+    };
+  }
+  async getTaskStats(start, end) {
+    const all = await this.storage.find(COLLECTIONS3.tasks);
+    const tasks = all.filter((t) => t.created_at >= start && t.created_at <= end);
+    const started = tasks.filter((t) => t.started_at !== null).length;
+    const completed = tasks.filter((t) => t.is_completed === 1).length;
+    return { started, completed };
+  }
+  async getBugReportStats(start, end) {
+    const all = await this.storage.find(COLLECTIONS3.bugReports);
+    const bugReports = all.filter((b) => b.timestamp >= start && b.timestamp <= end);
+    const errors = bugReports.filter((b) => b.severity === "error").length;
+    const crashes = bugReports.filter((b) => b.severity === "crash").length;
+    return { errors, crashes };
+  }
+  calculateQualityFlags(totalSessions, activeMinutes, uniqueScreens, avgTapsPerMinute) {
+    return {
+      minDwellOk: activeMinutes >= ValidationConstants.minActiveMinutes,
+      routeDepthOk: uniqueScreens >= ValidationConstants.minUniqueScreens,
+      tapSpam: avgTapsPerMinute > ValidationConstants.maxTapsPerMinute,
+      sufficientCoverage: totalSessions >= ValidationConstants.minSessions && uniqueScreens >= ValidationConstants.minUniqueScreens
+    };
+  }
+  generateIntegrityHash(metrics) {
+    const data = JSON.stringify(metrics);
+    let hash = 0;
+    for (let i = 0; i < data.length; i++) {
+      const char = data.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    return Math.abs(hash).toString(16).padStart(64, "0");
+  }
+  calculateEstimatedPayout(metrics) {
+    const baseRate = 0.1;
+    let payout = metrics.activeMinutes * baseRate;
+    if (metrics.qualityFlags.minDwellOk) payout *= 1.1;
+    if (metrics.qualityFlags.routeDepthOk) payout *= 1.1;
+    if (metrics.qualityFlags.sufficientCoverage) payout *= 1.2;
+    if (metrics.qualityFlags.tapSpam) payout *= 0.8;
+    if (metrics.feedbackCount > 0) payout += metrics.feedbackCount * 0.5;
+    if (metrics.tasksCompleted > 0) payout += metrics.tasksCompleted * 1;
+    return Math.round(payout * 100) / 100;
+  }
+};
+
+// src/Outbox.ts
+import { COLLECTIONS as COLLECTIONS4 } from "@testerpaykit/core";
+import { v4 as uuidv44 } from "uuid";
+var MAX_ATTEMPTS = 7;
+var Outbox = class {
+  constructor(storage, apiClient) {
+    this.draining = false;
+    this.storage = storage;
+    this.apiClient = apiClient;
+  }
+  // -------------------------------------------------------------------------
+  // Schema — no-op: schema is the adapter's responsibility
+  // -------------------------------------------------------------------------
+  async initSchema() {
+  }
+  // -------------------------------------------------------------------------
+  // Crash recovery — reset in_flight rows left over from a killed process
+  // -------------------------------------------------------------------------
+  async recoverInFlight() {
+    await this.storage.update(
+      COLLECTIONS4.outbox,
+      { state: "in_flight" },
+      { state: "pending" }
+    );
+  }
+  // -------------------------------------------------------------------------
+  // Enqueue helpers
+  // -------------------------------------------------------------------------
+  /** Enqueue a bug_report item; returns the local UUID immediately. */
+  enqueueSync(type, payload) {
+    const localId = uuidv44();
+    this._insertRow(localId, type, payload).catch(() => {
+    });
+    return localId;
+  }
+  /** Enqueue and wait for the DB insert to complete (for async callers). */
+  async enqueue(type, payload) {
+    const localId = uuidv44();
+    await this._insertRow(localId, type, payload);
+    return localId;
+  }
+  async _insertRow(localId, type, payload) {
+    await this.storage.insert(COLLECTIONS4.outbox, {
+      local_id: localId,
+      type,
+      payload: JSON.stringify(payload),
+      state: "pending",
+      attempts: 0,
+      last_error: null,
+      created_at: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Status query
+  // -------------------------------------------------------------------------
+  /**
+   * Map DB state → OutboxItemStatus.
+   * Returns null when the item is not found (means it was sent and deleted).
+   */
+  async getStatus(localId) {
+    const row = await this.storage.findOne(
+      COLLECTIONS4.outbox,
+      { local_id: localId }
+    );
+    if (!row) return null;
+    const state = row.state;
+    if (state === "pending") return "pending";
+    if (state === "in_flight") return "uploading";
+    if (state === "failed_permanent") return "failed";
+    return null;
+  }
+  // -------------------------------------------------------------------------
+  // Drainer — process pending items one by one
+  // -------------------------------------------------------------------------
+  /**
+   * Schedule a drain on the next microtask. Fire-and-forget.
+   * Callers (submitBugReport / createSubmission) call this after enqueue.
+   */
+  scheduleDrain() {
+    Promise.resolve().then(() => this.drain()).catch(() => {
+    });
+  }
+  /**
+   * Process all pending outbox items. Idempotent — safe to call concurrently
+   * (guarded by draining flag). No-ops when apiClient is absent.
+   */
+  async drain() {
+    if (this.draining) return;
+    if (!this.apiClient) return;
+    this.draining = true;
+    try {
+      await this._drainLoop();
+    } finally {
+      this.draining = false;
+    }
+  }
+  async _drainLoop() {
+    const rows = await this.storage.find(
+      COLLECTIONS4.outbox,
+      { state: "pending" }
+    );
+    if (rows.length === 0) return;
+    let serverIds;
+    const hasSubmissions = rows.some((r) => r.type === "submission");
+    if (hasSubmissions && this.apiClient?.fetchServerSubmissionIds) {
+      serverIds = await this.apiClient.fetchServerSubmissionIds();
+    }
+    for (const row of rows) {
+      await this._processRow(row, serverIds);
+    }
+  }
+  async _processRow(row, serverIds) {
+    await this.storage.update(
+      COLLECTIONS4.outbox,
+      { local_id: row.local_id },
+      { state: "in_flight" }
+    );
+    try {
+      const payload = JSON.parse(row.payload);
+      if (row.type === "bug_report") {
+        await this._uploadBugReport(row.local_id, payload);
+      } else if (row.type === "submission") {
+        await this._uploadSubmission(row.local_id, payload, serverIds);
+      }
+      await this.storage.delete(
+        COLLECTIONS4.outbox,
+        { local_id: row.local_id }
+      );
+    } catch (err) {
+      const statusCode = this._extractStatusCode(err);
+      if (statusCode !== null && statusCode >= 400 && statusCode < 500) {
+        await this.storage.update(
+          COLLECTIONS4.outbox,
+          { local_id: row.local_id },
+          {
+            state: "failed_permanent",
+            attempts: (row.attempts ?? 0) + 1,
+            last_error: String(err)
+          }
+        );
+      } else {
+        const nextAttempts = (row.attempts ?? 0) + 1;
+        await this.storage.update(
+          COLLECTIONS4.outbox,
+          { local_id: row.local_id },
+          {
+            state: nextAttempts >= MAX_ATTEMPTS ? "failed_permanent" : "pending",
+            attempts: nextAttempts,
+            last_error: String(err)
+          }
+        );
+      }
+    }
+  }
+  async _uploadBugReport(localId, payload) {
+    if (!this.apiClient?.submitBugReport) {
+      throw new Error("submitBugReport not available on apiClient");
+    }
+    await this.apiClient.submitBugReport(payload, { idempotencyKey: localId });
+  }
+  async _uploadSubmission(localId, payload, serverIds) {
+    if (serverIds?.has(localId)) return;
+    await this.apiClient.submitSummary(payload);
+  }
+  // -------------------------------------------------------------------------
+  // Connectivity hook (browser only)
+  // -------------------------------------------------------------------------
+  /** Register a window.online listener that triggers a drain. */
+  registerOnlineListener() {
+    if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+      window.addEventListener("online", () => {
+        this.drain().catch(() => {
+        });
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Helpers
+  // -------------------------------------------------------------------------
+  _extractStatusCode(err) {
+    if (err && typeof err === "object") {
+      const axiosErr = err;
+      if (axiosErr.response?.status != null) return axiosErr.response.status;
+      const genericErr = err;
+      if (genericErr.statusCode != null) return genericErr.statusCode;
+    }
+    return null;
+  }
+};
+
+// src/DeviceIdManager.ts
+import { COLLECTIONS as COLLECTIONS5 } from "@testerpaykit/core";
+import { v4 as uuidv45 } from "uuid";
+var DEVICE_ID_KEY = "device_id";
+var DEVICE_ID_CREATED_AT_KEY = "device_id_created_at";
+var THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1e3;
+var DeviceIdManager = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  /**
+   * Ensure the sdk_meta table exists. Schema is the adapter's responsibility;
+   * this is now a no-op kept for backwards-compatible call-sites.
+   */
+  async initSchema() {
+  }
+  /**
+   * Return the stored device id, creating or rotating it as needed.
+   *
+   * Rotation policy: if the id is older than 30 days, a new one is generated.
+   */
+  async getOrCreate() {
+    const rows = await this.storage.find(
+      COLLECTIONS5.sdkMeta,
+      { key: { in: [DEVICE_ID_KEY, DEVICE_ID_CREATED_AT_KEY] } }
+    );
+    const byKey = {};
+    for (const r of rows) {
+      byKey[r.key] = r.value;
+    }
+    const existingId = byKey[DEVICE_ID_KEY];
+    const createdAt = byKey[DEVICE_ID_CREATED_AT_KEY] ? parseInt(byKey[DEVICE_ID_CREATED_AT_KEY], 10) : null;
+    const now = Date.now();
+    const expired = createdAt === null || now - createdAt > THIRTY_DAYS_MS;
+    if (existingId && !expired) {
+      return existingId;
+    }
+    const newId = uuidv45();
+    await this._upsert(DEVICE_ID_KEY, newId);
+    await this._upsert(DEVICE_ID_CREATED_AT_KEY, String(now));
+    return newId;
+  }
+  async _upsert(key, value) {
+    const existing = await this.storage.findOne(
+      COLLECTIONS5.sdkMeta,
+      { key }
+    );
+    if (existing) {
+      await this.storage.update(COLLECTIONS5.sdkMeta, { key }, { value });
+    } else {
+      await this.storage.insert(COLLECTIONS5.sdkMeta, { key, value });
+    }
+  }
+};
+
+// src/TesterPayKit.ts
+import { v4 as uuidv46 } from "uuid";
+var LOCAL_PATTERNS = [
+  "localhost",
+  /^127\./,
+  /^10\./,
+  /^192\.168\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /\.local$/,
+  /\.lan$/
+];
+function deriveEnvironment(baseUrl) {
+  let host;
+  try {
+    host = new URL(baseUrl).hostname.toLowerCase();
+  } catch {
+    return "prod";
+  }
+  for (const p of LOCAL_PATTERNS) {
+    if (typeof p === "string" ? host === p : p.test(host)) {
+      return "local";
+    }
+  }
+  return "prod";
+}
+var LAST_SUBMISSION_AT_KEY = "last_submission_at";
+var SUBMISSION_PERIOD_MS = 7 * 24 * 60 * 60 * 1e3;
+var _TesterPayKit = class _TesterPayKit {
+  constructor(config) {
+    this.initialized = false;
+    // ── Resolved tester id (after anonymous login) ──────────────────────────────
+    // Populated by init() after a successful loginAnonymous. The server returns the
+    // real UUID for the tester row; submissions must use this, NOT the invite code.
+    this._resolvedTesterId = null;
+    // ── Auth token ──────────────────────────────────────────────────────────────
+    this._authToken = null;
+    // ── Server-side session sync ────────────────────────────────────────────────
+    // The local SessionManager only persists sessions in storage. To make a
+    // session appear in the coordinator dashboard we also create a SERVER session
+    // (once authed) and mirror screen-view events to it. Best-effort: never blocks
+    // or breaks the host app. Events that arrive before the server session exists
+    // are buffered, then flushed.
+    this._serverSessionId = null;
+    this._pendingSessionEvents = [];
+    this._logBuffer = [];
+    this._serverSessionInFlight = null;
+    this.config = {
+      autoStartSession: true,
+      debugMode: false,
+      weeklySubmissionDay: 7,
+      earningsBaseAmount: 1,
+      earningsPerMinuteRate: 0.1,
+      earningsCurrency: "EUR",
+      ...config
+    };
+    this.environment = config.apiBaseUrl ? deriveEnvironment(config.apiBaseUrl) : "prod";
+    this._resolvedDeviceId = config.deviceId ?? "";
+    this.deviceIdManager = new DeviceIdManager(config.storage);
+    this.sessionManager = new SessionManager(config.storage);
+    this.eventTracker = new EventTracker(config.storage, {
+      captureScreenViews: config.captureScreenViews ?? true,
+      captureTapEvents: config.captureTapEvents ?? true,
+      captureErrors: config.captureErrors ?? true,
+      captureCrashes: config.captureCrashes ?? true
+    });
+    const aggregatorConfig = {
+      projectId: config.projectId,
+      testerId: config.testerId,
+      deviceId: config.deviceId ?? "",
+      deviceMetadata: config.deviceMetadata,
+      appMetadata: config.appMetadata
+    };
+    this.metricsAggregator = new MetricsAggregator(config.storage, aggregatorConfig);
+    this.outbox = new Outbox(config.storage, config.apiClient);
+    this.anonymousAuthReady = new Promise((resolve) => {
+      this._resolveAnonymousAuth = resolve;
+    });
+  }
+  // ── Alias (contract: lifecycle.readiness.onTokenReady) ─────────────────────
+  get onTokenReady() {
+    return this.anonymousAuthReady;
+  }
+  // ── Auth state (contract: lifecycle.readiness.isAuthenticated) ─────────────
+  get isAuthenticated() {
+    return this._authToken !== null;
+  }
+  /**
+   * Initialize the SDK.
+   *
+   * Must be called before using any other SDK methods.
+   * Initializes storage and optionally starts a session.
+   */
+  async init() {
+    if (this.initialized) {
+      this.log("SDK already initialized");
+      return;
+    }
+    await this.config.storage.init();
+    await this.deviceIdManager.initSchema();
+    await this.outbox.initSchema();
+    await this.outbox.recoverInFlight();
+    if (!this.config.deviceId) {
+      this._resolvedDeviceId = await this.deviceIdManager.getOrCreate();
+      this.metricsAggregator.config = {
+        ...this.metricsAggregator.config,
+        deviceId: this._resolvedDeviceId
+      };
+    }
+    this.outbox.registerOnlineListener();
+    if (this.config.autoStartSession) {
+      const sessionId = await this.sessionManager.startSession();
+      this.eventTracker.setSessionId(sessionId);
+      this.log(`Session auto-started: ${sessionId}`);
+    }
+    this.initialized = true;
+    this.log("SDK initialized successfully");
+    const code = this.config.testerId;
+    const apiClient = this.config.apiClient;
+    if (code && apiClient?.loginAnonymous) {
+      void (async () => {
+        try {
+          const res = await apiClient.loginAnonymous(this.config.projectId, code);
+          if (res?.accessToken) {
+            this.setAuthToken(res.accessToken);
+            if (res.testerId) {
+              this._resolvedTesterId = res.testerId;
+              this.metricsAggregator.config = {
+                ...this.metricsAggregator.config,
+                testerId: res.testerId
+              };
+            }
+            this.log("anonymous tester token acquired");
+            void this._ensureServerSession();
+            void this.runDurabilitySweep().catch(() => void 0);
+          }
+        } catch (e) {
+          this.log(`anonymous token acquisition failed: ${String(e)}`);
+        } finally {
+          this._resolveAnonymousAuth();
+        }
+      })();
+    } else {
+      this._resolveAnonymousAuth();
+    }
+  }
+  /**
+   * Provide an auth token to the SDK (e.g. after anonymous login).
+   * Makes isAuthenticated return true and enables runDurabilitySweep.
+   */
+  setAuthToken(token) {
+    this._authToken = token;
+    this.config.apiClient?.setAccessToken(token);
+  }
+  // ── Registered-tester auth (for the tester-launcher widget) ──────────────────
+  /**
+   * Request a passwordless magic-link sign-in for a registered tester.
+   * TesterPayKit tester auth is magic-link (no passwords): the server emails a
+   * single-use link that returns to `returnUrl` (a first-party *.moinsen.dev
+   * page) carrying a token, which the host consumes via consumeTesterMagicLink.
+   * `country` (DE/AT/CH) lets an unknown email self-signup. Returns true if the
+   * request was accepted. Never throws.
+   */
+  async requestTesterMagicLink(email, returnUrl, country) {
+    const api = this.config.apiClient;
+    if (!api?.requestMagicLink) return false;
+    try {
+      await api.requestMagicLink({ email, returnUrl, country });
+      return true;
+    } catch (e) {
+      this.log(`magic-link request failed: ${String(e)}`);
+      return false;
+    }
+  }
+  /**
+   * Consume a magic-link token (from the returnUrl the tester landed on). On
+   * success the real tester token supersedes the anonymous one, the tester is
+   * enrolled in this project, and {accessToken, refreshToken} is returned so
+   * the host can persist the session. Returns null on failure. Never throws.
+   */
+  async consumeTesterMagicLink(token) {
+    const api = this.config.apiClient;
+    if (!api?.consumeMagicLink) return null;
+    try {
+      const res = await api.consumeMagicLink(token);
+      if (res?.accessToken) {
+        this.setAuthToken(res.accessToken);
+        await this.enrollSelf();
+        return {
+          accessToken: res.accessToken,
+          refreshToken: res.refreshToken ?? void 0
+        };
+      }
+      return null;
+    } catch (e) {
+      this.log(`magic-link consume failed: ${String(e)}`);
+      return null;
+    }
+  }
+  /**
+   * Enroll the current tester into THIS project (idempotent, best-effort).
+   * Used right after loginTester so the tester is a project participant.
+   * Returns true if enrolled (or already enrolled), false on hard failure.
+   */
+  async enrollSelf() {
+    const api = this.config.apiClient;
+    if (!api?.enrollInProject) return false;
+    try {
+      await api.enrollInProject(this.config.projectId);
+      return true;
+    } catch (e) {
+      const msg = String(e);
+      if (msg.includes("409") || msg.toLowerCase().includes("already")) {
+        return true;
+      }
+      this.log(`enrollSelf failed: ${msg}`);
+      return false;
+    }
+  }
+  // ── Server-side session sync (best-effort) ───────────────────────────────────
+  /** device_info payload for the server session, from configured metadata. */
+  _sessionDeviceInfo() {
+    const d = this.config.deviceMetadata;
+    return {
+      os: d.os,
+      os_version: d.osVersion,
+      device_model: d.deviceModel,
+      ...d.timezoneOffset != null && { timezone_offset: d.timezoneOffset },
+      // The local device id lives in the FK-free jsonb (not the device_id
+      // column, which references tester_devices) so grouping context is kept
+      // without a registration round-trip.
+      ...this._resolvedDeviceId && { device_id: this._resolvedDeviceId }
+    };
+  }
+  /**
+   * Lazily create the SERVER tester session once an anonymous token is in
+   * hand, then flush any buffered events. This is what makes the session
+   * show up in the coordinator dashboard. Best-effort: never throws.
+   */
+  _ensureServerSession() {
+    if (this._serverSessionId) return Promise.resolve();
+    this._serverSessionInFlight ?? (this._serverSessionInFlight = this._createServerSession().finally(() => {
+      this._serverSessionInFlight = null;
+    }));
+    return this._serverSessionInFlight;
+  }
+  async _createServerSession() {
+    if (!this._authToken) return;
+    const api = this.config.apiClient;
+    if (!api?.startTesterSession) return;
+    try {
+      const res = await api.startTesterSession({
+        projectId: this.config.projectId,
+        deviceInfo: this._sessionDeviceInfo(),
+        appVersion: this.config.appMetadata.version,
+        sdkVersion: this.config.deviceMetadata.sdkVersion
+        // NOTE: deliberately NOT sending device_id. On the server it's an FK
+        // into tester_devices, and the TS SDK has no device-registration flow
+        // yet, so an unregistered local UUID would 500 the session-create.
+        // The deviceId still rides along in deviceInfo for grouping context.
+      });
+      if (res?.sdkUpdate && !isProductionBuild()) {
+        const u = res.sdkUpdate;
+        console.warn(
+          `[testerpaykit] ${u.package} ${u.current} is outdated \u2014 ${u.latest} is out. Update: ${u.command}`
+        );
+      }
+      if (res?.id) {
+        this._serverSessionId = res.id;
+        this.log(`server session created: ${res.id}`);
+        await this._flushServerSessionEvents();
+      }
+    } catch (e) {
+      this.log(`server session create failed: ${String(e)}`);
+    }
+  }
+  /** Flush buffered session events to the server (best-effort, re-queues on fail). */
+  async _flushServerSessionEvents() {
+    const api = this.config.apiClient;
+    if (!this._serverSessionId || !api?.addSessionEvents) return;
+    if (this._pendingSessionEvents.length === 0) return;
+    const batch = this._pendingSessionEvents.splice(0);
+    try {
+      await api.addSessionEvents(this._serverSessionId, batch);
+    } catch (e) {
+      this._pendingSessionEvents.unshift(...batch);
+      this.log(`session events flush failed: ${String(e)}`);
+    }
+  }
+  /** End the server session (best-effort). Clears the id so it won't re-end. */
+  async _endServerSession(endReason) {
+    const api = this.config.apiClient;
+    const id = this._serverSessionId;
+    if (!id || !api?.endTesterSession) return;
+    this._serverSessionId = null;
+    try {
+      await this._flushServerSessionEvents();
+      const allowed = /* @__PURE__ */ new Set([
+        "completed",
+        "lifecycle_flush",
+        "timeout",
+        "abandoned"
+      ]);
+      await api.endTesterSession({
+        sessionId: id,
+        endReason: allowed.has(endReason) ? endReason : "completed"
+      });
+      this.log(`server session ended: ${id}`);
+    } catch (e) {
+      this.log(`server session end failed: ${String(e)}`);
+    }
+  }
+  // ── payout_durability — contract: invariants.payout_durability ──────────────
+  /**
+   * Run a durability sweep to ensure testing work is persisted and uploaded.
+   *
+   * No-op when no auth token is held. Otherwise, best-effort (each step is
+   * individually wrapped so one failure does not abort the rest):
+   *
+   * 1. Reconcile open sessions: find sessions in storage without an end_time
+   *    and close them with endReason='abandoned' so their duration counts.
+   * 2. Auto-create a period submission when overdue: tracks the last submission
+   *    timestamp in sdk_meta. "Due" = more than 7 days since last enqueue.
+   *    (Heuristic — uses wall-clock elapsed time, not calendar periods.)
+   * 3. Drain the outbox. The Outbox drain already skips server-known submission
+   *    ids (fetchServerSubmissionIds guard) so no double-pay occurs.
+   *
+   * Contract: api.submissions.runDurabilitySweep
+   */
+  async runDurabilitySweep() {
+    if (!this._authToken) {
+      this.log("runDurabilitySweep: no auth token \u2014 skipping");
+      return;
+    }
+    try {
+      await this._reconcileOpenSessions();
+    } catch (e) {
+      this.log(`runDurabilitySweep step 1 failed: ${e}`);
+    }
+    try {
+      await this._autoCreateSubmissionIfDue();
+    } catch (e) {
+      this.log(`runDurabilitySweep step 2 failed: ${e}`);
+    }
+    try {
+      await this.outbox.drain();
+    } catch (e) {
+      this.log(`runDurabilitySweep step 3 failed: ${e}`);
+    }
+  }
+  async _reconcileOpenSessions() {
+    const currentId = this.sessionManager.getCurrentSessionId() ?? "";
+    await this.config.storage.update(
+      COLLECTIONS6.sessions,
+      { ended_at: null, id: { ne: currentId } },
+      { ended_at: Date.now(), end_reason: "abandoned" }
+    );
+    this.log("runDurabilitySweep: open sessions reconciled");
+  }
+  async _autoCreateSubmissionIfDue() {
+    const row = await this.config.storage.findOne(
+      COLLECTIONS6.sdkMeta,
+      { key: LAST_SUBMISSION_AT_KEY }
+    );
+    const lastAt = row ? parseInt(row.value, 10) : null;
+    const now = Date.now();
+    if (lastAt === null) {
+      await this.config.storage.insert(COLLECTIONS6.sdkMeta, {
+        key: LAST_SUBMISSION_AT_KEY,
+        value: String(now)
+      });
+      this.log("runDurabilitySweep: first run \u2014 period clock started, no submission yet");
+      return;
+    }
+    if (now - lastAt < SUBMISSION_PERIOD_MS) {
+      this.log("runDurabilitySweep: submission not due yet");
+      return;
+    }
+    await this.config.storage.update(
+      COLLECTIONS6.sdkMeta,
+      { key: LAST_SUBMISSION_AT_KEY },
+      { value: String(now) }
+    );
+    await this.createSubmission();
+    this.log("runDurabilitySweep: auto-created period submission");
+  }
+  /**
+   * Start a new testing session.
+   *
+   * @returns Promise resolving to the new session ID
+   */
+  async startSession() {
+    this.ensureInitialized();
+    const sessionId = await this.sessionManager.startSession();
+    this.eventTracker.setSessionId(sessionId);
+    this.log(`Session started: ${sessionId}`);
+    void this._ensureServerSession();
+    return sessionId;
+  }
+  /**
+   * End the current testing session.
+   *
+   * @param endReason - Reason for ending (default: 'completed')
+   */
+  async endSession(endReason = "completed") {
+    this.ensureInitialized();
+    await this.sessionManager.endSession(endReason);
+    this.log("Session ended");
+    await this._endServerSession(endReason);
+  }
+  // ── App-lifecycle hooks (contract: lifecycle.app_lifecycle_hooks) ─────────
+  /**
+   * Call when the app moves to the foreground / resumes.
+   *
+   * Contract behaviour:
+   *   - If NO active session exists → start a new one.
+   *   - If a session IS active → resume the foreground clock only.
+   *     MUST NOT end and restart the active session.
+   */
+  async onAppResumed() {
+    this.ensureInitialized();
+    if (!this.sessionManager.hasActiveSession()) {
+      const sessionId = await this.sessionManager.startSession();
+      this.eventTracker.setSessionId(sessionId);
+      this.log("onAppResumed: new session started");
+      void this._ensureServerSession();
+    } else {
+      this.sessionManager.resumeForegroundClock();
+      this.log("onAppResumed: foreground clock resumed");
+    }
+  }
+  /**
+   * Call when the app moves to the background / is paused.
+   *
+   * Contract behaviour: freezes the foreground clock.
+   * MUST NOT end the session.
+   */
+  onAppPaused() {
+    this.ensureInitialized();
+    this.sessionManager.pauseForegroundClock();
+    this.log("onAppPaused: foreground clock paused");
+  }
+  /**
+   * Call when the app becomes inactive (e.g. phone call overlay, app-switcher).
+   *
+   * Contract behaviour: no-op for the session (may log only).
+   */
+  onAppInactive() {
+    this.ensureInitialized();
+    this.log("onAppInactive: no-op");
+  }
+  /**
+   * Call when the app process is about to be detached / destroyed.
+   *
+   * Contract behaviour: ends the active session with end_reason='lifecycle_flush'.
+   */
+  async onAppDetached() {
+    this.ensureInitialized();
+    if (this.sessionManager.hasActiveSession()) {
+      await this.sessionManager.endSession("lifecycle_flush");
+      this.log("onAppDetached: session flushed");
+    }
+    await this._endServerSession("lifecycle_flush");
+  }
+  /**
+   * Track a screen view event.
+   *
+   * @param screenName - Name or route of the screen
+   * @param metadata - Optional additional metadata
+   */
+  async trackScreenView(screenName, metadata) {
+    this.ensureInitialized();
+    await this.eventTracker.trackScreenView(screenName, metadata);
+    await this.sessionManager.incrementScreenViews();
+    this.log(`Screen view tracked: ${screenName}`);
+    this._pendingSessionEvents.push({
+      eventType: "screen_view",
+      screenRoute: screenName,
+      ...metadata && { eventData: metadata },
+      timestamp: /* @__PURE__ */ new Date()
+    });
+    if (this._serverSessionId) {
+      void this._flushServerSessionEvents();
+    } else {
+      void this._ensureServerSession();
+    }
+  }
+  /**
+   * Track a tap/click event.
+   *
+   * @param screenName - Name of the screen where the tap occurred
+   * @param elementId - Optional ID of the tapped element
+   */
+  async trackTap(screenName, elementId) {
+    this.ensureInitialized();
+    await this.eventTracker.trackTap(screenName, elementId);
+    await this.sessionManager.incrementTaps();
+    this.log(`Tap tracked: ${screenName}${elementId ? ` (${elementId})` : ""}`);
+  }
+  /**
+   * Track a custom event.
+   *
+   * @param eventType - Type of the event
+   * @param metadata - Optional event metadata
+   */
+  async trackEvent(eventType, metadata) {
+    this.ensureInitialized();
+    await this.eventTracker.trackEvent(eventType, metadata);
+    this.log(`Event tracked: ${eventType}`);
+  }
+  /**
+   * Track an error.
+   *
+   * @param message - Error message
+   * @param stack - Optional stack trace
+   */
+  async trackError(message, stack) {
+    this.ensureInitialized();
+    await this.eventTracker.trackError(message, stack);
+    this.log(`Error tracked: ${message}`);
+  }
+  /**
+   * Track a crash.
+   *
+   * @param message - Crash message
+   * @param stack - Stack trace
+   */
+  async trackCrash(message, stack) {
+    this.ensureInitialized();
+    await this.eventTracker.trackCrash(message, stack);
+    this.log(`Crash tracked: ${message}`);
+  }
+  /**
+   * Track feedback submission.
+   *
+   * @param content - Feedback content
+   * @param rating - Optional numeric rating
+   */
+  async trackFeedback(content, rating) {
+    this.ensureInitialized();
+    await this.eventTracker.trackFeedback(content, rating);
+    this.log(`Feedback tracked: ${content.length} characters`);
+  }
+  /**
+   * Track task start.
+   *
+   * @param taskId - Unique task identifier
+   * @param title - Task title
+   */
+  async trackTaskStart(taskId, title) {
+    this.ensureInitialized();
+    await this.eventTracker.trackTaskStart(taskId, title);
+    this.log(`Task started: ${title}`);
+  }
+  /**
+   * Track task completion.
+   *
+   * @param taskId - Unique task identifier
+   */
+  async trackTaskComplete(taskId) {
+    this.ensureInitialized();
+    await this.eventTracker.trackTaskComplete(taskId);
+    this.log(`Task completed: ${taskId}`);
+  }
+  /**
+   * Enqueue a bug report to the local outbox and return a local UUID
+   * immediately. The upload happens in the background — this method
+   * never awaits the network.
+   *
+   * Builds the full payload required by POST /v1/testers/me/bug-reports:
+   *   sessionId, type, severity, category, title, description,
+   *   currentScreen, deviceSnapshot, appSnapshot, projectId.
+   * testerId is intentionally omitted — the endpoint is tester-namespaced
+   * and derives the tester from the JWT.
+   *
+   * Contract: api.submissions.submitBugReport / invariants.local_first_outbox
+   *
+   * @param input - Structured bug report input
+   * @returns A local UUID that can be passed to getSubmissionStatus()
+   */
+  submitBugReport(input) {
+    this.ensureInitialized();
+    const sessionId = this.sessionManager.getCurrentSessionId() ?? uuidv46();
+    const rawType = input.type ?? "bug";
+    const type = BUG_REPORT_TYPES.includes(rawType) ? rawType : (() => {
+      this.log(`[WARN] submitBugReport: invalid type "${rawType}", coercing to "bug"`);
+      return "bug";
+    })();
+    const rawSeverity = input.severity ?? "medium";
+    const severity = BUG_REPORT_SEVERITIES.includes(rawSeverity) ? rawSeverity : (() => {
+      this.log(`[WARN] submitBugReport: invalid severity "${rawSeverity}", coercing to "medium"`);
+      return "medium";
+    })();
+    const rawCategory = input.category ?? "functional";
+    const category = BUG_REPORT_CATEGORIES.includes(rawCategory) ? rawCategory : (() => {
+      this.log(`[WARN] submitBugReport: invalid category "${rawCategory}", coercing to "functional"`);
+      return "functional";
+    })();
+    const payload = {
+      projectId: this.config.projectId,
+      sessionId,
+      type,
+      severity,
+      category,
+      title: input.title,
+      description: input.description,
+      currentScreen: input.currentScreen ?? "unknown",
+      deviceSnapshot: {
+        os: this.config.deviceMetadata.os,
+        osVersion: this.config.deviceMetadata.osVersion,
+        deviceModel: this.config.deviceMetadata.deviceModel
+      },
+      appSnapshot: {
+        bundleId: this.config.appMetadata.bundleId,
+        version: this.config.appMetadata.version,
+        buildNumber: this.config.appMetadata.buildNumber,
+        environment: this.environment
+      },
+      ...input.metadata
+    };
+    if (input.screenshotPath != null) {
+      payload.screenshotPath = input.screenshotPath;
+    }
+    if (input.expectedBehavior != null) {
+      payload.expectedBehavior = input.expectedBehavior;
+    }
+    if (input.actualBehavior != null) {
+      payload.actualBehavior = input.actualBehavior;
+    }
+    if (input.frequency != null) {
+      payload.frequency = input.frequency;
+    }
+    if (input.reproductionSteps != null) {
+      payload.reproductionSteps = input.reproductionSteps;
+    }
+    if (input.affectedFeature != null) {
+      payload.affectedFeature = input.affectedFeature;
+    }
+    const localId = this.outbox.enqueueSync("bug_report", payload);
+    this.outbox.scheduleDrain();
+    this.log(`Bug report enqueued: ${localId}`);
+    return localId;
+  }
+  /**
+   * Extract structured bug-report fields from a base64-encoded audio recording.
+   *
+   * Delegates to apiClient.voiceExtractBugFields. When `sourceLanguage` is
+   * explicitly provided (ISO-639-1, e.g. 'de'), it is forwarded as-is.
+   * When omitted, the language hint falls back to navigator.language
+   * (best-effort, browser-only). Soft-fails to null when the apiClient does
+   * not implement voiceExtractBugFields or the call throws.
+   *
+   * Contract: wire.bug_reports.voiceExtractBugFields
+   *
+   * @param audioBase64 - Raw base64 audio (no data: prefix)
+   * @param mimeType - MIME type of the audio (e.g. 'audio/webm')
+   * @param sourceLanguage - Optional explicit ISO-639-1 language code; when
+   *   omitted the SDK derives it from navigator.language
+   * @returns Extracted fields, or null on any failure
+   */
+  async extractBugFromVoice(audioBase64, mimeType, sourceLanguage) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.voiceExtractBugFields) {
+      this.log("extractBugFromVoice: apiClient does not implement voiceExtractBugFields \u2014 skipping");
+      return null;
+    }
+    let resolvedLanguage = sourceLanguage;
+    if (!resolvedLanguage) {
+      try {
+        if (typeof navigator !== "undefined" && navigator.language) {
+          resolvedLanguage = navigator.language.split("-")[0].toLowerCase();
+        }
+      } catch {
+      }
+    }
+    try {
+      const result = await apiClient.voiceExtractBugFields({
+        audioBase64,
+        mimeType,
+        projectId: this.config.projectId,
+        ...resolvedLanguage ? { sourceLanguage: resolvedLanguage } : {}
+      });
+      return result;
+    } catch (e) {
+      this.log(`extractBugFromVoice: failed \u2014 ${String(e)}`);
+      return null;
+    }
+  }
+  /**
+   * One-tap report draft from a screenshot of the current screen — the
+   * quick-action path next to voice. Returns null when the client does
+   * not support it; throws on a server error so the UI can show it.
+   *
+   * Contract: wire.bug_reports.quickDraftBug
+   *
+   * @param screenshotDataUrl - `data:image/...;base64,...` of the screen
+   */
+  async quickDraftBug(action, screenshotDataUrl, options = {}) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.quickDraftBug) return null;
+    const match = /^data:([^;]+);base64,(.*)$/.exec(screenshotDataUrl);
+    return apiClient.quickDraftBug({
+      action,
+      screenshotBase64: match ? match[2] : screenshotDataUrl,
+      mimeType: match ? match[1] : "image/png",
+      ...options.screenName ? { screenName: options.screenName } : {},
+      ...options.language ? { language: options.language } : {}
+    });
+  }
+  /**
+   * Upload an arbitrary attachment (screenshot, screen recording, voice note, etc.)
+   * to the standalone attachments endpoint (POST /v1/attachments).
+   *
+   * Returns the stored URL/path on success, null on any failure (best-effort,
+   * never throws).
+   *
+   * Contract: wire.bug_reports.uploadAttachment (standalone path)
+   *
+   * @param input - Attachment data with base64 content, MIME type, file type, and optional file name
+   * @returns The attachment url/path string, or null if upload failed or client unavailable
+   */
+  async uploadAttachment(input) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.uploadAttachment) {
+      this.log("uploadAttachment: no api client with uploadAttachment \u2014 skipping");
+      return null;
+    }
+    try {
+      const fileName = input.fileName ?? `${input.fileType}-${Date.now()}.${input.mimeType.split("/")[1]?.split(";")[0] ?? "bin"}`;
+      const fileSize = Math.ceil(input.base64.length * 3 / 4);
+      const response = await apiClient.uploadAttachment({
+        fileName,
+        fileType: input.fileType,
+        fileSize,
+        fileData: input.base64,
+        mimeType: input.mimeType
+      });
+      const path = response.url ?? response.id;
+      this.log(`uploadAttachment: uploaded as ${path}`);
+      return path ?? null;
+    } catch (e) {
+      this.log(`uploadAttachment: failed \u2014 ${String(e)}`);
+      return null;
+    }
+  }
+  /**
+   * Upload a screenshot dataURL to the standalone attachments endpoint.
+   *
+   * Converts the dataURL to a base64 payload and calls
+   * POST /v1/attachments via the api-client. Returns the attachment
+   * url/path on success, null on any failure (best-effort, never throws).
+   *
+   * Contract: wire.bug_reports.uploadAttachment (standalone path)
+   *
+   * @param dataUrl - A JPEG/PNG dataURL (e.g. from html2canvas or captureScreenshot)
+   * @returns The attachment url string, or null if upload failed or client unavailable
+   */
+  async uploadScreenshot(dataUrl) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.uploadAttachment) {
+      this.log("uploadScreenshot: no api client with uploadAttachment \u2014 skipping");
+      return null;
+    }
+    try {
+      const commaIdx = dataUrl.indexOf(",");
+      const fileData = commaIdx >= 0 ? dataUrl.slice(commaIdx + 1) : dataUrl;
+      const headerPart = commaIdx >= 0 ? dataUrl.slice(0, commaIdx) : "";
+      const mimeMatch = headerPart.match(/data:([^;]+)/);
+      const mimeType = mimeMatch ? mimeMatch[1] : "image/jpeg";
+      const fileName = `screenshot-${Date.now()}.jpg`;
+      const fileSize = Math.ceil(fileData.length * 3 / 4);
+      const response = await apiClient.uploadAttachment({
+        fileName,
+        fileType: "screenshot",
+        fileSize,
+        fileData,
+        mimeType
+      });
+      const path = response.filePath ?? response.id;
+      this.log(`uploadScreenshot: uploaded as ${path}`);
+      return path ?? null;
+    } catch (e) {
+      this.log(`uploadScreenshot: failed \u2014 ${String(e)}`);
+      return null;
+    }
+  }
+  /**
+   * Fetch the bug reports this tester has submitted (newest first).
+   * Delegates to apiClient.listMyBugReports. Soft-fails to an empty list
+   * when the client lacks the method or the call throws.
+   *
+   * Requires a tester auth token — if unauthenticated the server 401s and
+   * this returns the empty-list soft-fail result.
+   */
+  async getMyBugReports(params) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.listMyBugReports) {
+      this.log("getMyBugReports: apiClient does not implement listMyBugReports \u2014 returning empty list");
+      return { bugReports: [] };
+    }
+    try {
+      return await apiClient.listMyBugReports(params);
+    } catch (e) {
+      this.log(`getMyBugReports: failed \u2014 ${String(e)}`);
+      return { bugReports: [] };
+    }
+  }
+  /**
+   * Fetch tester notifications + unread count.
+   * Delegates to apiClient.getMyNotifications. Soft-fails to
+   * { notifications: [], unreadCount: 0 } on any error or missing method.
+   *
+   * Requires a tester auth token.
+   */
+  async getNotifications(params) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.getMyNotifications) {
+      this.log("getNotifications: apiClient does not implement getMyNotifications \u2014 returning empty");
+      return { notifications: [], unreadCount: 0 };
+    }
+    try {
+      return await apiClient.getMyNotifications(params);
+    } catch (e) {
+      this.log(`getNotifications: failed \u2014 ${String(e)}`);
+      return { notifications: [], unreadCount: 0 };
+    }
+  }
+  /**
+   * Mark notifications read. Pass an id to mark one; omit to mark all.
+   * Delegates to apiClient.markNotificationsRead. Soft-fails to null on
+   * any error or missing method (caller should treat null as "no change").
+   *
+   * Requires a tester auth token.
+   *
+   * @returns New unread count, or null on soft-fail.
+   */
+  async markNotificationsRead(id) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.markNotificationsRead) {
+      this.log("markNotificationsRead: apiClient does not implement markNotificationsRead \u2014 skipping");
+      return null;
+    }
+    try {
+      return await apiClient.markNotificationsRead(id ? { id } : void 0);
+    } catch (e) {
+      this.log(`markNotificationsRead: failed \u2014 ${String(e)}`);
+      return null;
+    }
+  }
+  /**
+   * Aggregate local metrics and enqueue a submission to the outbox.
+   * Returns a local UUID immediately — the upload happens in the background.
+   *
+   * Contract: api.submissions.createSubmissionAsync / invariants.local_first_outbox
+   *
+   * @returns A local UUID that can be passed to getSubmissionStatus()
+   */
+  async createSubmission() {
+    this.ensureInitialized();
+    const summary = await this.metricsAggregator.aggregateWeeklySummary();
+    const localId = await this.outbox.enqueue("submission", summary);
+    this.outbox.scheduleDrain();
+    this.log(`Submission enqueued: ${localId}`);
+    return localId;
+  }
+  /**
+   * Query the outbox state for a previously-enqueued item.
+   *
+   * Returns:
+   *   'pending'   — enqueued, not yet uploaded
+   *   'uploading' — upload in progress
+   *   'failed'    — permanently rejected (4xx); will not be retried
+   *   null        — item not found; treat as successfully sent (deleted on success)
+   *
+   * Contract: api.submissions.getSubmissionStatus / enums.OutboxItemStatus
+   *
+   * @param localId - The id returned by submitBugReport() or createSubmission()
+   */
+  async getSubmissionStatus(localId) {
+    this.ensureInitialized();
+    return this.outbox.getStatus(localId);
+  }
+  /**
+   * Generate and store a weekly summary.
+   *
+   * Aggregates all metrics from the past 7 days and stores the summary
+   * in the local database for later submission.
+   *
+   * @returns Promise resolving to the generated summary
+   */
+  async generateWeeklySummary() {
+    this.ensureInitialized();
+    const summary = await this.metricsAggregator.aggregateWeeklySummary();
+    await this.metricsAggregator.storeSummary(summary);
+    this.log(`Weekly summary generated: ${summary.id}`);
+    return summary;
+  }
+  /**
+   * Get all pending summaries.
+   *
+   * @returns Array of pending WeeklySummary objects
+   */
+  async getPendingSummaries() {
+    this.ensureInitialized();
+    return this.metricsAggregator.getPendingSummaries();
+  }
+  /**
+   * Submit pending summaries to the server.
+   * Requires apiClient to be configured.
+   *
+   * @returns Number of summaries successfully submitted
+   */
+  async submitPendingSummaries() {
+    this.ensureInitialized();
+    if (!this.config.apiClient) {
+      throw new Error("API client not configured. Cannot submit summaries.");
+    }
+    const pendingSummaries = await this.metricsAggregator.getPendingSummaries();
+    let successCount = 0;
+    for (const summary of pendingSummaries) {
+      try {
+        await this.config.apiClient.submitSummary(summary);
+        await this.metricsAggregator.updateSummaryStatus(summary.id, "submitted");
+        successCount++;
+        this.log(`Summary submitted: ${summary.id}`);
+      } catch (error) {
+        this.log(`Failed to submit summary ${summary.id}: ${error}`);
+      }
+    }
+    return successCount;
+  }
+  /**
+   * Get the current session ID.
+   *
+   * @returns Current session ID or null if no session is active
+   */
+  getCurrentSessionId() {
+    return this.sessionManager.getCurrentSessionId();
+  }
+  /**
+   * Check if there's an active session.
+   *
+   * @returns true if a session is currently active
+   */
+  hasActiveSession() {
+    return this.sessionManager.hasActiveSession();
+  }
+  /**
+   * Get the current session duration in seconds.
+   *
+   * @returns Duration in seconds, or 0 if no session is active
+   */
+  getSessionDuration() {
+    return this.sessionManager.getSessionDuration();
+  }
+  /**
+   * Close the SDK and clean up resources.
+   */
+  async close() {
+    if (this.sessionManager.hasActiveSession()) {
+      await this.sessionManager.endSession();
+    }
+    await this.config.storage.close();
+    this.initialized = false;
+    this.log("SDK closed");
+  }
+  /**
+   * Ensure the SDK is initialized before use.
+   * @throws Error if SDK is not initialized
+   */
+  ensureInitialized() {
+    if (!this.initialized) {
+      throw new Error("TesterPayKit not initialized. Call init() first.");
+    }
+  }
+  /**
+   * Log debug messages. Always pushes to the ring buffer (regardless of
+   * debugMode) so TpkDebugLogsScreen has content. Console output stays
+   * gated by debugMode.
+   */
+  log(message) {
+    this._logBuffer.push({ ts: Date.now(), message });
+    if (this._logBuffer.length > _TesterPayKit.LOG_BUFFER_MAX) {
+      this._logBuffer.shift();
+    }
+    if (this.config.debugMode) {
+      console.log(`[TesterPayKit] ${message}`);
+    }
+  }
+  /**
+   * Get a copy of the debug log buffer, newest entry first.
+   * The buffer accumulates up to 200 entries regardless of debugMode.
+   */
+  getDebugLogs() {
+    return this._logBuffer.slice().reverse();
+  }
+  /**
+   * Clear the debug log buffer.
+   */
+  clearDebugLogs() {
+    this._logBuffer = [];
+  }
+  /**
+   * Get the epoch-ms timestamp when the current session started.
+   * Delegates to SessionManager.
+   *
+   * @returns Epoch ms, or null when no session is active
+   */
+  getCurrentSessionStartedAt() {
+    return this.sessionManager.getCurrentSessionStartedAt();
+  }
+  /**
+   * Compute estimated session earnings.
+   *
+   * engagedMinutes = floor(elapsed since session start in minutes).
+   * amount = earningsBaseAmount + engagedMinutes * earningsPerMinuteRate.
+   * currency = earningsCurrency from config.
+   *
+   * Soft-safe: never throws; returns base/0/currency when no session.
+   * Max cap: 480 minutes (8 hours) to keep amounts sane.
+   */
+  getSessionEarnings() {
+    try {
+      const base = this.config.earningsBaseAmount ?? 1;
+      const rate = this.config.earningsPerMinuteRate ?? 0.1;
+      const currency = this.config.earningsCurrency ?? "EUR";
+      const startedAt = this.sessionManager.getCurrentSessionStartedAt();
+      if (startedAt === null) {
+        return { engagedMinutes: 0, amount: base, currency };
+      }
+      const elapsedMs = Date.now() - startedAt;
+      const engagedMinutes = Math.min(Math.floor(elapsedMs / 6e4), 480);
+      const amount = base + engagedMinutes * rate;
+      return { engagedMinutes, amount, currency };
+    } catch {
+      return {
+        engagedMinutes: 0,
+        amount: this.config.earningsBaseAmount ?? 1,
+        currency: this.config.earningsCurrency ?? "EUR"
+      };
+    }
+  }
+  /**
+   * Return the configured app metadata (bundleId, version, buildNumber, etc.).
+   * Used by TpkWorkboardScreen to show the current build info block.
+   */
+  getAppInfo() {
+    return this.config.appMetadata;
+  }
+  /**
+   * Fetch the tester's assigned tasks.
+   * Delegates to apiClient.getMyTasks. Soft-fails to an empty TaskListResponse
+   * when the client lacks the method or the call throws.
+   */
+  async getMyTasks(params) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.getMyTasks) {
+      this.log("getMyTasks: apiClient does not implement getMyTasks \u2014 returning empty list");
+      return { tasks: [], total: 0, summary: { pending: 0, inProgress: 0, completed: 0 } };
+    }
+    try {
+      return await apiClient.getMyTasks(params);
+    } catch (e) {
+      this.log(`getMyTasks: failed \u2014 ${String(e)}`);
+      return { tasks: [], total: 0, summary: { pending: 0, inProgress: 0, completed: 0 } };
+    }
+  }
+  /**
+   * Mark a task assignment in-progress.
+   * Delegates to apiClient.startTaskAssignment. Soft-fails silently on error.
+   */
+  async startTask(assignmentId) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.startTaskAssignment) {
+      this.log("startTask: apiClient does not implement startTaskAssignment \u2014 skipping");
+      return;
+    }
+    try {
+      await apiClient.startTaskAssignment(assignmentId);
+    } catch (e) {
+      this.log(`startTask: failed \u2014 ${String(e)}`);
+    }
+  }
+  /**
+   * Complete a task assignment.
+   * Delegates to apiClient.completeTaskAssignment. Soft-fails silently on error.
+   */
+  async completeTask(assignmentId) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.completeTaskAssignment) {
+      this.log("completeTask: apiClient does not implement completeTaskAssignment \u2014 skipping");
+      return;
+    }
+    try {
+      await apiClient.completeTaskAssignment(assignmentId);
+    } catch (e) {
+      this.log(`completeTask: failed \u2014 ${String(e)}`);
+    }
+  }
+  /**
+   * Fetch the tester's retest queue.
+   * Delegates to apiClient.getMyRetests. Soft-fails to an empty array.
+   */
+  async getMyRetests(params) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.getMyRetests) {
+      this.log("getMyRetests: apiClient does not implement getMyRetests \u2014 returning empty list");
+      return [];
+    }
+    try {
+      return await apiClient.getMyRetests(params);
+    } catch (e) {
+      this.log(`getMyRetests: failed \u2014 ${String(e)}`);
+      return [];
+    }
+  }
+  /**
+   * Mark a retest as verified (bug is fixed).
+   * Delegates to apiClient.verifyRetest. Soft-fails silently on error.
+   */
+  async verifyRetest(bugId, stepVerdicts) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.verifyRetest) {
+      this.log("verifyRetest: apiClient does not implement verifyRetest \u2014 skipping");
+      return;
+    }
+    try {
+      await apiClient.verifyRetest(bugId, stepVerdicts);
+    } catch (e) {
+      this.log(`verifyRetest: failed \u2014 ${String(e)}`);
+    }
+  }
+  /**
+   * Reopen a retest (bug still present), optionally with a reason.
+   * Delegates to apiClient.reopenRetest. Soft-fails silently on error.
+   */
+  async reopenRetest(bugId, reason, stepVerdicts) {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.reopenRetest) {
+      this.log("reopenRetest: apiClient does not implement reopenRetest \u2014 skipping");
+      return;
+    }
+    try {
+      await apiClient.reopenRetest(bugId, reason, stepVerdicts);
+    } catch (e) {
+      this.log(`reopenRetest: failed \u2014 ${String(e)}`);
+    }
+  }
+  /**
+   * Fetch the tester's profile.
+   * Delegates to apiClient.getMyProfile. Soft-fails to null on error.
+   */
+  async getMyProfile() {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.getMyProfile) {
+      this.log("getMyProfile: apiClient does not implement getMyProfile \u2014 returning null");
+      return null;
+    }
+    try {
+      return await apiClient.getMyProfile();
+    } catch (e) {
+      this.log(`getMyProfile: failed \u2014 ${String(e)}`);
+      return null;
+    }
+  }
+  /**
+   * Fetch the tester's points balance.
+   * Delegates to apiClient.getMyPoints. Soft-fails to null on error.
+   */
+  async getMyPoints() {
+    const apiClient = this.config.apiClient;
+    if (!apiClient?.getMyPoints) {
+      this.log("getMyPoints: apiClient does not implement getMyPoints \u2014 returning null");
+      return null;
+    }
+    try {
+      return await apiClient.getMyPoints();
+    } catch (e) {
+      this.log(`getMyPoints: failed \u2014 ${String(e)}`);
+      return null;
+    }
+  }
+};
+// ── Debug log ring buffer ────────────────────────────────────────────────────
+// Holds the most recent LOG_BUFFER_MAX entries regardless of debugMode.
+// Console output stays gated by debugMode.
+_TesterPayKit.LOG_BUFFER_MAX = 200;
+var TesterPayKit = _TesterPayKit;
+function isProductionBuild() {
+  try {
+    return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+  } catch {
+    return false;
+  }
+}
+
+// src/index.ts
+import { BUG_REPORT_TYPES as BUG_REPORT_TYPES2, BUG_REPORT_CATEGORIES as BUG_REPORT_CATEGORIES2, BUG_REPORT_SEVERITIES as BUG_REPORT_SEVERITIES2 } from "@testerpaykit/core";
+export {
+  BUG_REPORT_CATEGORIES2 as BUG_REPORT_CATEGORIES,
+  BUG_REPORT_SEVERITIES2 as BUG_REPORT_SEVERITIES,
+  BUG_REPORT_TYPES2 as BUG_REPORT_TYPES,
+  DeviceIdManager,
+  EventTracker,
+  MetricsAggregator,
+  Outbox,
+  SessionManager,
+  TesterPayKit,
+  ValidationConstants
+};