@testerpaykit/sdk 0.0.0-stage → 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,908 @@
+import { ISessionManager, IStorage, IApiClient, DeviceMetadata, AppMetadata, BugReportInput, VoiceBugExtractResponse, QuickActionKind, MyBugReportsResponse, NotificationsResult, OutboxItemStatus, WeeklySummary, TaskListFilter, TaskListResponse, RetestItem, RetestStepVerdicts, TesterProfile, TesterPoints, IEventTracker } from '@testerpaykit/core';
+export { AppMetadata, BUG_REPORT_CATEGORIES, BUG_REPORT_SEVERITIES, BUG_REPORT_TYPES, BugReportCategory, BugReportInput, BugReportSeverity, BugReportType, DeviceMetadata, IApiClient, IEventTracker, ISessionManager, IStorage, OutboxItemStatus, QualityFlags, SessionMetrics, WeeklySummary } from '@testerpaykit/core';
+
+type SessionEndReason = 'completed' | 'lifecycle_flush' | 'timeout' | 'abandoned';
+/**
+ * Session manager implementation for tracking user testing sessions.
+ *
+ * Implements ISessionManager interface and manages the lifecycle of testing sessions,
+ * including session creation, duration tracking, foreground/paid-time clock,
+ * and database persistence.
+ */
+declare class SessionManager implements ISessionManager {
+    private currentSessionId;
+    private sessionStartTime;
+    private storage;
+    private foregroundAccumulatedMs;
+    private foregroundClockStartMs;
+    constructor(storage: IStorage);
+    /**
+     * 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
+     */
+    startSession(): Promise<string>;
+    /**
+     * 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')
+     */
+    endSession(endReason?: SessionEndReason): Promise<void>;
+    /**
+     * Pause the foreground (paid-time) clock.
+     * Call when the app moves to background. Has no effect if already paused.
+     */
+    pauseForegroundClock(): void;
+    /**
+     * Resume the foreground (paid-time) clock.
+     * Call when the app returns to foreground. Has no effect if already running.
+     */
+    resumeForegroundClock(): void;
+    /**
+     * Get the accumulated foreground seconds for the current session.
+     *
+     * @returns Foreground time in whole seconds
+     */
+    getForegroundSeconds(): number;
+    /**
+     * Get the current session ID.
+     *
+     * @returns Current session ID or null if no session is active
+     */
+    getCurrentSessionId(): string | null;
+    /**
+     * Check if there's an active session.
+     *
+     * @returns true if a session is currently active
+     */
+    hasActiveSession(): boolean;
+    /**
+     * Get the current session duration in seconds.
+     *
+     * @returns Duration in seconds, or 0 if no session is active
+     */
+    getSessionDuration(): number;
+    /**
+     * Get the epoch-ms timestamp when the current session started.
+     *
+     * @returns Epoch ms, or null when no session is active
+     */
+    getCurrentSessionStartedAt(): number | null;
+    /**
+     * Increment the screen view count for the current session.
+     * Internal method used by EventTracker.
+     */
+    incrementScreenViews(): Promise<void>;
+    /**
+     * Increment the tap count for the current session.
+     * Internal method used by EventTracker.
+     */
+    incrementTaps(): Promise<void>;
+}
+
+/**
+ * Configuration for TesterPayKit SDK.
+ */
+interface TesterPayKitConfig {
+    /**
+     * API key for authentication
+     */
+    apiKey: string;
+    /**
+     * API base URL (required). Used to derive `environment`.
+     * e.g. "https://api.testerpaykit.com" or "http://localhost:18080"
+     */
+    apiBaseUrl?: string;
+    /**
+     * Project identifier
+     */
+    projectId: string;
+    /**
+     * Tester pseudonymous identifier
+     */
+    testerId: string;
+    /**
+     * Device pseudonymous identifier override.
+     * When omitted, a UUIDv4 is generated and persisted by DeviceIdManager
+     * with a 30-day rotation policy (contract: invariants.device_id).
+     */
+    deviceId?: string;
+    /**
+     * Storage adapter instance
+     */
+    storage: IStorage;
+    /**
+     * API client instance (optional, for Agent 4 integration)
+     */
+    apiClient?: IApiClient;
+    /**
+     * Device metadata
+     */
+    deviceMetadata: DeviceMetadata;
+    /**
+     * App metadata
+     */
+    appMetadata: AppMetadata;
+    /**
+     * Automatically start a session on init (default: true)
+     */
+    autoStartSession?: boolean;
+    /**
+     * Enable debug logging (default: false)
+     */
+    debugMode?: boolean;
+    /**
+     * Base payout amount awarded at session start (default: 1.0).
+     */
+    earningsBaseAmount?: number;
+    /**
+     * Additional payout per engaged minute (default: 0.10).
+     */
+    earningsPerMinuteRate?: number;
+    /**
+     * Currency for earnings display (default: 'EUR').
+     */
+    earningsCurrency?: string;
+    /**
+     * Capture screen view events (default: true)
+     */
+    captureScreenViews?: boolean;
+    /**
+     * Capture tap/click events (default: true)
+     */
+    captureTapEvents?: boolean;
+    /**
+     * Capture error events (default: true)
+     */
+    captureErrors?: boolean;
+    /**
+     * Capture crash events (default: true)
+     */
+    captureCrashes?: boolean;
+    /**
+     * Day of week for the weekly period submission (1=Mon … 7=Sun, default: 7).
+     * Contract: configuration.weeklySubmissionDay
+     */
+    weeklySubmissionDay?: number;
+}
+/**
+ * Main TesterPayKit SDK class.
+ *
+ * Orchestrates session management, event tracking, and metrics aggregation
+ * for the TesterPayKit testing platform.
+ *
+ * @example
+ * ```typescript
+ * import { TesterPayKit } from '@testerpaykit/sdk';
+ * import { IndexedDBAdapter } from '@testerpaykit/storage-browser';
+ *
+ * const storage = new IndexedDBAdapter();
+ * const sdk = new TesterPayKit({
+ *   apiKey: 'your-api-key',
+ *   apiBaseUrl: 'https://api.testerpaykit.com',
+ *   projectId: 'project-123',
+ *   testerId: 'tester-456',
+ *   storage,
+ *   deviceMetadata: { os: 'Web', osVersion: '1.0', ... },
+ *   appMetadata: { bundleId: 'com.example.app', version: '1.0.0', ... },
+ * });
+ *
+ * await sdk.init();
+ * await sdk.anonymousAuthReady;          // wait for auth before first authed call
+ * await sdk.trackScreenView('HomeScreen');
+ * ```
+ */
+declare class TesterPayKit {
+    private config;
+    private sessionManager;
+    private eventTracker;
+    private metricsAggregator;
+    private outbox;
+    private deviceIdManager;
+    private initialized;
+    private _resolvedDeviceId;
+    private _resolvedTesterId;
+    private _authToken;
+    private _serverSessionId;
+    private _pendingSessionEvents;
+    readonly anonymousAuthReady: Promise<void>;
+    private _resolveAnonymousAuth;
+    readonly environment: 'local' | 'prod';
+    private static readonly LOG_BUFFER_MAX;
+    private _logBuffer;
+    constructor(config: TesterPayKitConfig);
+    get onTokenReady(): Promise<void>;
+    get isAuthenticated(): boolean;
+    /**
+     * Initialize the SDK.
+     *
+     * Must be called before using any other SDK methods.
+     * Initializes storage and optionally starts a session.
+     */
+    init(): Promise<void>;
+    /**
+     * Provide an auth token to the SDK (e.g. after anonymous login).
+     * Makes isAuthenticated return true and enables runDurabilitySweep.
+     */
+    setAuthToken(token: string): void;
+    /**
+     * 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.
+     */
+    requestTesterMagicLink(email: string, returnUrl: string, country?: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    consumeTesterMagicLink(token: string): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+    } | 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.
+     */
+    enrollSelf(): Promise<boolean>;
+    /** device_info payload for the server session, from configured metadata. */
+    private _sessionDeviceInfo;
+    /**
+     * 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.
+     */
+    private _ensureServerSession;
+    private _serverSessionInFlight;
+    private _createServerSession;
+    /** Flush buffered session events to the server (best-effort, re-queues on fail). */
+    private _flushServerSessionEvents;
+    /** End the server session (best-effort). Clears the id so it won't re-end. */
+    private _endServerSession;
+    /**
+     * 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
+     */
+    runDurabilitySweep(): Promise<void>;
+    private _reconcileOpenSessions;
+    private _autoCreateSubmissionIfDue;
+    /**
+     * Start a new testing session.
+     *
+     * @returns Promise resolving to the new session ID
+     */
+    startSession(): Promise<string>;
+    /**
+     * End the current testing session.
+     *
+     * @param endReason - Reason for ending (default: 'completed')
+     */
+    endSession(endReason?: SessionEndReason): Promise<void>;
+    /**
+     * 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.
+     */
+    onAppResumed(): Promise<void>;
+    /**
+     * Call when the app moves to the background / is paused.
+     *
+     * Contract behaviour: freezes the foreground clock.
+     * MUST NOT end the session.
+     */
+    onAppPaused(): void;
+    /**
+     * Call when the app becomes inactive (e.g. phone call overlay, app-switcher).
+     *
+     * Contract behaviour: no-op for the session (may log only).
+     */
+    onAppInactive(): void;
+    /**
+     * Call when the app process is about to be detached / destroyed.
+     *
+     * Contract behaviour: ends the active session with end_reason='lifecycle_flush'.
+     */
+    onAppDetached(): Promise<void>;
+    /**
+     * Track a screen view event.
+     *
+     * @param screenName - Name or route of the screen
+     * @param metadata - Optional additional metadata
+     */
+    trackScreenView(screenName: string, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Track a tap/click event.
+     *
+     * @param screenName - Name of the screen where the tap occurred
+     * @param elementId - Optional ID of the tapped element
+     */
+    trackTap(screenName: string, elementId?: string): Promise<void>;
+    /**
+     * Track a custom event.
+     *
+     * @param eventType - Type of the event
+     * @param metadata - Optional event metadata
+     */
+    trackEvent(eventType: string, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Track an error.
+     *
+     * @param message - Error message
+     * @param stack - Optional stack trace
+     */
+    trackError(message: string, stack?: string): Promise<void>;
+    /**
+     * Track a crash.
+     *
+     * @param message - Crash message
+     * @param stack - Stack trace
+     */
+    trackCrash(message: string, stack: string): Promise<void>;
+    /**
+     * Track feedback submission.
+     *
+     * @param content - Feedback content
+     * @param rating - Optional numeric rating
+     */
+    trackFeedback(content: string, rating?: number): Promise<void>;
+    /**
+     * Track task start.
+     *
+     * @param taskId - Unique task identifier
+     * @param title - Task title
+     */
+    trackTaskStart(taskId: string, title: string): Promise<void>;
+    /**
+     * Track task completion.
+     *
+     * @param taskId - Unique task identifier
+     */
+    trackTaskComplete(taskId: string): Promise<void>;
+    /**
+     * 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: BugReportInput): string;
+    /**
+     * 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
+     */
+    extractBugFromVoice(audioBase64: string, mimeType: string, sourceLanguage?: string): Promise<VoiceBugExtractResponse | 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
+     */
+    quickDraftBug(action: QuickActionKind, screenshotDataUrl: string, options?: {
+        screenName?: string;
+        language?: string;
+    }): Promise<VoiceBugExtractResponse | null>;
+    /**
+     * 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
+     */
+    uploadAttachment(input: {
+        base64: string;
+        mimeType: string;
+        fileType: 'screen_recording' | 'voice_note' | 'image' | 'screenshot' | 'video' | 'audio' | 'log' | 'document' | 'other';
+        fileName?: string;
+    }): Promise<string | 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
+     */
+    uploadScreenshot(dataUrl: string): Promise<string | 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.
+     */
+    getMyBugReports(params?: {
+        status?: string;
+        limit?: number;
+        page?: number;
+    }): Promise<MyBugReportsResponse>;
+    /**
+     * 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.
+     */
+    getNotifications(params?: {
+        limit?: number;
+        unreadOnly?: boolean;
+    }): Promise<NotificationsResult>;
+    /**
+     * 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.
+     */
+    markNotificationsRead(id?: string): Promise<number | 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()
+     */
+    createSubmission(): Promise<string>;
+    /**
+     * 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()
+     */
+    getSubmissionStatus(localId: string): Promise<OutboxItemStatus | null>;
+    /**
+     * 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
+     */
+    generateWeeklySummary(): Promise<WeeklySummary>;
+    /**
+     * Get all pending summaries.
+     *
+     * @returns Array of pending WeeklySummary objects
+     */
+    getPendingSummaries(): Promise<WeeklySummary[]>;
+    /**
+     * Submit pending summaries to the server.
+     * Requires apiClient to be configured.
+     *
+     * @returns Number of summaries successfully submitted
+     */
+    submitPendingSummaries(): Promise<number>;
+    /**
+     * Get the current session ID.
+     *
+     * @returns Current session ID or null if no session is active
+     */
+    getCurrentSessionId(): string | null;
+    /**
+     * Check if there's an active session.
+     *
+     * @returns true if a session is currently active
+     */
+    hasActiveSession(): boolean;
+    /**
+     * Get the current session duration in seconds.
+     *
+     * @returns Duration in seconds, or 0 if no session is active
+     */
+    getSessionDuration(): number;
+    /**
+     * Close the SDK and clean up resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Ensure the SDK is initialized before use.
+     * @throws Error if SDK is not initialized
+     */
+    private ensureInitialized;
+    /**
+     * Log debug messages. Always pushes to the ring buffer (regardless of
+     * debugMode) so TpkDebugLogsScreen has content. Console output stays
+     * gated by debugMode.
+     */
+    private log;
+    /**
+     * Get a copy of the debug log buffer, newest entry first.
+     * The buffer accumulates up to 200 entries regardless of debugMode.
+     */
+    getDebugLogs(): Array<{
+        ts: number;
+        message: string;
+    }>;
+    /**
+     * Clear the debug log buffer.
+     */
+    clearDebugLogs(): void;
+    /**
+     * Get the epoch-ms timestamp when the current session started.
+     * Delegates to SessionManager.
+     *
+     * @returns Epoch ms, or null when no session is active
+     */
+    getCurrentSessionStartedAt(): number | null;
+    /**
+     * 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(): {
+        engagedMinutes: number;
+        amount: number;
+        currency: string;
+    };
+    /**
+     * Return the configured app metadata (bundleId, version, buildNumber, etc.).
+     * Used by TpkWorkboardScreen to show the current build info block.
+     */
+    getAppInfo(): 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.
+     */
+    getMyTasks(params?: TaskListFilter): Promise<TaskListResponse>;
+    /**
+     * Mark a task assignment in-progress.
+     * Delegates to apiClient.startTaskAssignment. Soft-fails silently on error.
+     */
+    startTask(assignmentId: string): Promise<void>;
+    /**
+     * Complete a task assignment.
+     * Delegates to apiClient.completeTaskAssignment. Soft-fails silently on error.
+     */
+    completeTask(assignmentId: string): Promise<void>;
+    /**
+     * Fetch the tester's retest queue.
+     * Delegates to apiClient.getMyRetests. Soft-fails to an empty array.
+     */
+    getMyRetests(params?: {
+        status?: string;
+    }): Promise<RetestItem[]>;
+    /**
+     * Mark a retest as verified (bug is fixed).
+     * Delegates to apiClient.verifyRetest. Soft-fails silently on error.
+     */
+    verifyRetest(bugId: string, stepVerdicts?: RetestStepVerdicts): Promise<void>;
+    /**
+     * Reopen a retest (bug still present), optionally with a reason.
+     * Delegates to apiClient.reopenRetest. Soft-fails silently on error.
+     */
+    reopenRetest(bugId: string, reason?: string, stepVerdicts?: RetestStepVerdicts): Promise<void>;
+    /**
+     * Fetch the tester's profile.
+     * Delegates to apiClient.getMyProfile. Soft-fails to null on error.
+     */
+    getMyProfile(): Promise<TesterProfile | null>;
+    /**
+     * Fetch the tester's points balance.
+     * Delegates to apiClient.getMyPoints. Soft-fails to null on error.
+     */
+    getMyPoints(): Promise<TesterPoints | null>;
+}
+
+interface CaptureFlags {
+    captureScreenViews: boolean;
+    captureTapEvents: boolean;
+    captureErrors: boolean;
+    captureCrashes: boolean;
+}
+/**
+ * Event tracker implementation for capturing user interactions and app events.
+ *
+ * Implements IEventTracker interface and tracks various event types including
+ * screen views, taps, errors, crashes, feedback, and task progress.
+ */
+declare class EventTracker implements IEventTracker {
+    private storage;
+    private sessionId;
+    private captureFlags;
+    constructor(storage: IStorage, captureFlags?: Partial<CaptureFlags>);
+    /**
+     * Set the current session ID.
+     * Must be called before tracking events.
+     *
+     * @param sessionId - The active session ID
+     */
+    setSessionId(sessionId: string): void;
+    /**
+     * Track a screen view event.
+     * Gated by captureScreenViews flag.
+     *
+     * @param screenName - Name or route of the screen being viewed
+     * @param metadata - Optional additional metadata
+     */
+    trackScreenView(screenName: string, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * 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
+     */
+    trackTap(screenName: string, elementId?: string): Promise<void>;
+    /**
+     * Track a custom event.
+     *
+     * @param eventType - Type of the event
+     * @param metadata - Optional event metadata
+     */
+    trackEvent(eventType: string, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Track an error event.
+     * Gated by captureErrors flag.
+     *
+     * @param message - Error message
+     * @param stack - Optional stack trace
+     */
+    trackError(message: string, stack?: string): Promise<void>;
+    /**
+     * Track a crash event.
+     * Gated by captureCrashes flag.
+     *
+     * @param message - Crash message
+     * @param stack - Stack trace
+     */
+    trackCrash(message: string, stack: string): Promise<void>;
+    /**
+     * Track a feedback submission.
+     *
+     * @param content - Feedback content
+     * @param rating - Optional numeric rating
+     */
+    trackFeedback(content: string, rating?: number): Promise<void>;
+    /**
+     * Track task start event.
+     *
+     * @param taskId - Unique task identifier
+     * @param title - Task title
+     */
+    trackTaskStart(taskId: string, title: string): Promise<void>;
+    /**
+     * Track task completion event.
+     *
+     * @param taskId - Unique task identifier
+     */
+    trackTaskComplete(taskId: string): Promise<void>;
+    /**
+     * Store a bug report (error or crash).
+     *
+     * @param severity - Severity level ('error' or 'crash')
+     * @param message - Error/crash message
+     * @param stack - Optional stack trace
+     */
+    private storeBugReport;
+    /**
+     * 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
+     */
+    getEventCounts(start: number, end: number): Promise<Record<string, number>>;
+    /**
+     * 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
+     */
+    getUniqueScreens(start: number, end: number): Promise<string[]>;
+}
+
+/**
+ * Validation constants for quality assessment.
+ */
+declare const ValidationConstants: {
+    minActiveMinutes: number;
+    minUniqueScreens: number;
+    maxTapsPerMinute: number;
+    minSessions: number;
+};
+/**
+ * Configuration for MetricsAggregator.
+ */
+interface MetricsAggregatorConfig {
+    projectId: string;
+    testerId: string;
+    deviceId: string;
+    deviceMetadata: DeviceMetadata;
+    appMetadata: AppMetadata;
+}
+/**
+ * Metrics aggregator for generating weekly summaries.
+ *
+ * Aggregates session data, events, feedback, tasks, and bug reports
+ * into a comprehensive weekly summary for submission.
+ */
+declare class MetricsAggregator {
+    private storage;
+    private config;
+    constructor(storage: IStorage, config: MetricsAggregatorConfig);
+    /**
+     * Aggregate a weekly summary for the past 7 days.
+     *
+     * @returns Promise resolving to the generated WeeklySummary
+     */
+    aggregateWeeklySummary(): Promise<WeeklySummary>;
+    /**
+     * 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
+     */
+    aggregateSummaryForPeriod(startTime: number, endTime: number): Promise<WeeklySummary>;
+    /**
+     * Store a weekly summary in the local database.
+     *
+     * @param summary - The summary to store
+     */
+    storeSummary(summary: WeeklySummary): Promise<void>;
+    /**
+     * Get pending summaries from the local database.
+     *
+     * @returns Array of pending WeeklySummary objects
+     */
+    getPendingSummaries(): Promise<WeeklySummary[]>;
+    /**
+     * Update summary status.
+     *
+     * @param summaryId - ID of the summary
+     * @param status - New status
+     */
+    updateSummaryStatus(summaryId: string, status: string): Promise<void>;
+    private getSessions;
+    private getEventCounts;
+    private getUniqueScreens;
+    private getFeedbackStats;
+    private getTaskStats;
+    private getBugReportStats;
+    private calculateQualityFlags;
+    private generateIntegrityHash;
+    private calculateEstimatedPayout;
+}
+
+declare class Outbox {
+    private storage;
+    private apiClient;
+    private draining;
+    constructor(storage: IStorage, apiClient?: IApiClient);
+    initSchema(): Promise<void>;
+    recoverInFlight(): Promise<void>;
+    /** Enqueue a bug_report item; returns the local UUID immediately. */
+    enqueueSync(type: 'bug_report' | 'submission', payload: unknown): string;
+    /** Enqueue and wait for the DB insert to complete (for async callers). */
+    enqueue(type: 'bug_report' | 'submission', payload: unknown): Promise<string>;
+    private _insertRow;
+    /**
+     * Map DB state → OutboxItemStatus.
+     * Returns null when the item is not found (means it was sent and deleted).
+     */
+    getStatus(localId: string): Promise<OutboxItemStatus | null>;
+    /**
+     * Schedule a drain on the next microtask. Fire-and-forget.
+     * Callers (submitBugReport / createSubmission) call this after enqueue.
+     */
+    scheduleDrain(): void;
+    /**
+     * Process all pending outbox items. Idempotent — safe to call concurrently
+     * (guarded by draining flag). No-ops when apiClient is absent.
+     */
+    drain(): Promise<void>;
+    private _drainLoop;
+    private _processRow;
+    private _uploadBugReport;
+    private _uploadSubmission;
+    /** Register a window.online listener that triggers a drain. */
+    registerOnlineListener(): void;
+    private _extractStatusCode;
+}
+
+/**
+ * Manages a locally-generated UUIDv4 device id persisted in storage.
+ *
+ * Contract: invariants.device_id
+ * - Generates a new id on first use.
+ * - Rotates (new id) after 30 days.
+ * - config.deviceId overrides this (passed through, not persisted here).
+ */
+declare class DeviceIdManager {
+    private storage;
+    constructor(storage: IStorage);
+    /**
+     * Ensure the sdk_meta table exists. Schema is the adapter's responsibility;
+     * this is now a no-op kept for backwards-compatible call-sites.
+     */
+    initSchema(): Promise<void>;
+    /**
+     * 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.
+     */
+    getOrCreate(): Promise<string>;
+    private _upsert;
+}
+
+export { DeviceIdManager, EventTracker, MetricsAggregator, Outbox, SessionManager, TesterPayKit, ValidationConstants };
+export type { CaptureFlags, MetricsAggregatorConfig, SessionEndReason, TesterPayKitConfig };