@eddydesk/core

Core client and utilities for EddyDesk QA platform.

Note: Most users should install @eddydesk/react or @eddydesk/react-native instead, which include this package automatically.

Installation

npm install @eddydesk/core

Usage

import { createEddyDesk } from '@eddydesk/core';

const eddydesk = createEddyDesk({
  projectId: 'your-project-id',
  getCurrentUser: async () => ({
    id: 'user-123',
    email: '[email protected]',
    name: 'Jane Doe', // Optional, used for reporter identity
  }),
});

// Submit a report
await eddydesk.submitReport({
  type: 'bug',
  description: 'Button does not work',
  severity: 'high',
  appContext: { currentRoute: '/dashboard' },
});

// Check if user is a tester
const isTester = await eddydesk.isTester();

// Get assigned test cases
const assignments = await eddydesk.getAssignedTests();

Configuration

interface EddyDeskConfig {
  // Required
  projectId: string;
  getCurrentUser: () => Promise<{ id: string; email: string; name?: string } | null>;

  // Optional — context
  getAppContext?: () => AppContext;          // Rich app context (userRole, etc.)
  getNavigationHistory?: () => string[];    // Custom navigation tracking

  // Optional — callbacks
  onReportSubmitted?: (report: EddyDeskReport) => void;
  onNavigate?: (route: string) => void;     // Deep linking from test cases

  // Optional — self-hosted
  supabaseUrl?: string;
  supabaseAnonKey?: string;
}

AppContext

Provide getAppContext to attach rich context to every bug report. This helps the developer fixing the bug understand the user's state:

const eddydesk = createEddyDesk({
  projectId: 'your-project-id',
  getCurrentUser: async () => ({ id: user.id, email: user.email }),
  getAppContext: () => ({
    currentRoute: window.location.pathname,
    userRole: currentUser?.role,       // e.g. 'owner', 'manager', 'guest'
    propertyId: currentProperty?.id,   // App-specific context
    custom: {                          // Any additional context
      theme: 'dark',
      locale: 'en-US',
    },
  }),
});

Automatic Context Capture

EddyDesk automatically captures debugging context when initialized via EddyDeskProvider (React or React Native). No manual setup required.

What's captured automatically:

This data is attached to every bug report as enhanced_context and is available to the MCP server's get_report_context tool.

Manual Capture (framework authors)

If you're not using EddyDeskProvider, start capture manually:

import { contextCapture } from '@eddydesk/core';

// Start capturing (call once at app init)
contextCapture.startCapture();

// For React Native: manually track screen changes
contextCapture.trackNavigation('/home');
contextCapture.trackNavigation('/settings');

// Get captured data (automatically included in submitReport)
const context = contextCapture.getEnhancedContext();

Client Methods

Types

interface EddyDeskReport {
  type: 'bug' | 'feedback' | 'suggestion' | 'test_pass' | 'test_fail';
  description: string;
  title?: string;
  severity?: 'critical' | 'high' | 'medium' | 'low';
  screenshots?: string[];
  appContext?: AppContext;
  enhancedContext?: EnhancedBugContext;
}

interface AppContext {
  currentRoute: string;
  screenName?: string;
  userRole?: string;
  propertyId?: string;
  custom?: Record<string, unknown>;
}

interface TesterInfo {
  id: string;
  name: string;
  email: string;
  assignedTests: number;
  completedTests: number;
}

interface TestAssignment {
  id: string;
  status: string;
  testCase: {
    id: string;
    title: string;
    description: string;
    steps: TestStep[];
    expectedResult: string;
    priority: string;
  };
}

type IssueCategory = 'open' | 'done' | 'reopened';

interface IssueCounts {
  open: number;
  done: number;
  reopened: number;
}

interface TesterIssue {
  id: string;
  title: string;
  description: string;
  reportType: ReportType;
  severity: Severity | null;
  status: ReportStatus;
  screenshotUrls: string[];
  route?: string;
  reporterName?: string;
  createdAt: string;
  updatedAt: string;
  verifiedByName?: string;   // Who retested (done issues)
  verifiedAt?: string;       // When verification passed (done issues)
  originalBugId?: string;    // Original report ID (reopened issues)
  originalBugTitle?: string; // Original bug title (reopened issues)
}

Issue Tracking

The SDK provides methods for testers to track their bug lifecycle:

// Get counts for issue cards (open, done, reopened)
const counts = await eddydesk.getIssueCounts();
// { open: 3, done: 12, reopened: 1 }

// Get enriched issue list by category
const openIssues = await eddydesk.getIssues('open');
const doneIssues = await eddydesk.getIssues('done');
const reopenedIssues = await eddydesk.getIssues('reopened');

// Done issues include verification proof
doneIssues[0].verifiedByName;  // "Jane Doe"
doneIssues[0].verifiedAt;      // "2026-02-05T12:00:00Z"

// Reopened issues include original bug context
reopenedIssues[0].originalBugTitle;  // "Login button unresponsive"
reopenedIssues[0].originalBugId;     // "uuid-of-original-report"

For Framework Authors

If you're building a EddyDesk integration for a different framework (Vue, Svelte, etc.), use this package as the foundation:

import { EddyDeskClient, createEddyDesk, contextCapture, EddyDeskConfig } from '@eddydesk/core';

// Start context capture at app init
contextCapture.startCapture();

// Create your framework-specific wrapper around the client
const client = createEddyDesk(config);