Scout AI Client SDK Reference

import { ScoutAIClient } from '@userlens/scout-ai';

new ScoutAIClient(config: ScoutAIClientConfig)

const client = new ScoutAIClient({
  baseUrl: 'https://your-app.azurestaticapps.net/api/scout-ai',
  headers: {
    Authorization: 'Bearer eyJhbG...',
  },
});

health(): Promise<HealthResponse>

const status = await client.health();
console.log(status.anthropicConfigured); // true

complete(params: CompleteParams): Promise<string>

const response = await client.complete({
  systemPrompt: 'You are a UX research expert.',
  userPrompt: 'What are the key principles of usability testing?',
  temperature: 0.5,
});

chat(params: ChatParams): Promise<string>

const reply = await client.chat({
  systemPrompt: 'You are Scout AI, a UX research assistant.',
  userPrompt: 'What patterns do you see across these sessions?',
  messages: [
    { role: 'user', content: 'Here are my session notes for 5 participants...' },
    { role: 'assistant', content: 'I can see several emerging themes...' },
  ],
});

rewrite(params: RewriteParams): Promise<string>

const improved = await client.rewrite({
  text: 'The user was not able to find the button easily and had trouble.',
  focus: 'Make this more concise and suitable for a stakeholder report',
});
// "The user struggled to locate the button."

analyzeHypotheses(params: HypothesisAnalysisParams): Promise<string>

const analysis = await client.analyzeHypotheses({
  projectName: 'Mobile App Redesign',
  hypotheses: [
    { statement: 'Users prefer bottom navigation over hamburger menus', status: 'untested' },
    { statement: 'Onboarding reduces churn for new users', status: 'testing' },
  ],
  researchData: [
    { title: 'Session P1', content: 'Participant immediately looked to the bottom...' },
    { title: 'Session P2', content: 'User skipped the onboarding tutorial...' },
  ],
});

generateReport(params: ReportParams): Promise<string>

const report = await client.generateReport({
  projectName: 'Checkout Redesign',
  reportType: 'executive',
  synthesisNotes: [
    { content: '3 of 5 users abandoned at the payment step', theme: 'drop-off' },
    { content: 'Users praised the progress indicator', theme: 'positive' },
  ],
  hypotheses: [
    { statement: 'Simplifying the form reduces abandonment', status: 'validated' },
  ],
});

summarizeSessions(params: SummaryParams): Promise<string>

const summary = await client.summarizeSessions({
  projectName: 'Dashboard UX Study',
  summaryType: 'themes',
  sessionNotes: [
    { title: 'P1 - Sarah (Product Manager)', content: 'Found the dashboard overwhelming...' },
    { title: 'P2 - James (Developer)', content: 'Wanted more customization options...' },
    { title: 'P3 - Maria (Designer)', content: 'Appreciated the visual hierarchy...' },
  ],
});

generatePersonas(params: PersonaParams): Promise<string>

const personas = await client.generatePersonas({
  projectName: 'E-commerce Platform',
  count: 4,
  researchData: [
    { title: 'Interview - Power User', content: 'Shops daily, price-sensitive...' },
    { title: 'Interview - Casual Browser', content: 'Visits weekly, discovery-driven...' },
  ],
});

createJourneyMap(params: JourneyMapParams): Promise<string>

const journeyMap = await client.createJourneyMap({
  projectName: 'Support Ticket Flow',
  researchData: [
    { title: 'Session 1', content: 'User started by searching the FAQ, then...' },
    { title: 'Session 2', content: 'User went directly to live chat...' },
  ],
});

extractThemes(params: ThemeParams): Promise<string>

const themes = await client.extractThemes({
  projectName: 'Dashboard Redesign',
  researchData: [
    { title: 'Interview 1', content: 'Participant mentioned information overload...' },
    { title: 'Interview 2', content: 'Wanted to customize which widgets appear...' },
  ],
});

generateInterviewGuide(params: InterviewGuideParams): Promise<string>

const guide = await client.generateInterviewGuide({
  projectName: 'Navigation Redesign',
  objectives: [
    'Understand how users discover features',
    'Identify navigation pain points',
    'Evaluate mental models for information architecture',
  ],
  duration: 45,
});

interface ScoutAIClientConfig {
  baseUrl: string;
  headers?: Record<string, string>;
  fetch?: typeof globalThis.fetch;
}

interface HealthResponse {
  status: string;
  service: string;
  anthropicConfigured: boolean;
}

interface CompleteParams {
  systemPrompt: string;
  userPrompt: string;
  maxTokens?: number;    // default: 4096
  temperature?: number;  // default: 0.7
}

interface ChatParams {
  userPrompt: string;
  systemPrompt?: string;
  messages?: ChatMessage[];
  maxTokens?: number;       // default: 4096
  temperature?: number;     // default: 0.7
  includeCitations?: boolean; // default: true
}

interface RewriteParams {
  text: string;
  focus?: string;
}

interface HypothesisAnalysisParams {
  projectName?: string;          // default: "Research Project"
  hypotheses: HypothesisInput[];
  researchData: ResearchDataItem[];
}

interface ReportParams {
  projectName: string;
  synthesisNotes?: SynthesisNote[];
  hypotheses?: HypothesisInput[];
  reportType?: ReportType;  // default: "detailed"
}

interface SummaryParams {
  projectName: string;
  sessionNotes: SessionNote[];
  summaryType?: SummaryType;  // default: "overview"
}

interface PersonaParams {
  projectName: string;
  researchData?: (string | ResearchDataItem)[];
  count?: number;  // default: 3
}

interface JourneyMapParams {
  projectName: string;
  researchData?: (string | ResearchDataItem)[];
}

interface ThemeParams {
  projectName: string;
  researchData?: (string | ResearchDataItem)[];
}

interface InterviewGuideParams {
  projectName: string;
  objectives?: string[];
  duration?: number;  // default: 60
}

interface ChatMessage {
  role: 'user' | 'assistant';
  content: string;
}

interface HypothesisInput {
  statement: string;
  status: 'validated' | 'invalidated' | 'partial' | 'untested'
        | 'testing' | 'supported' | 'partially_supported';
}

interface ResearchDataItem {
  title?: string;
  content: string;
}

interface SynthesisNote {
  content: string;
  theme?: string;
}

interface SessionNote {
  title: string;
  content: string;
}

type ReportType = 'executive' | 'detailed' | 'presentation';

type SummaryType = 'overview' | 'findings-report' | 'detailed' | 'themes' | 'quotes';

import {
  ScoutAIError,
  ScoutAIValidationError,
  ScoutAIContentTooLargeError,
  ScoutAIRateLimitError,
  ScoutAIServerError,
} from '@userlens/scout-ai';

Error
 └── ScoutAIError
      ├── ScoutAIValidationError      (400)
      ├── ScoutAIContentTooLargeError  (413)
      ├── ScoutAIRateLimitError        (429)
      └── ScoutAIServerError           (5xx)

class ScoutAIError extends Error {
  readonly status: number;
  readonly code: string;
}

ScoutAIError.fromResponse(status: number, body: { error?: string }): ScoutAIError

try {
  const summary = await client.summarizeSessions({
    projectName: 'My Study',
    sessionNotes: notes,
  });
} catch (err) {
  if (err instanceof ScoutAIContentTooLargeError) {
    // Reduce content and retry
    const fewerNotes = notes.slice(0, 5);
    const summary = await client.summarizeSessions({
      projectName: 'My Study',
      sessionNotes: fewerNotes,
    });
  } else if (err instanceof ScoutAIRateLimitError) {
    // Wait and retry
    await new Promise(r => setTimeout(r, 5000));
    // retry...
  } else if (err instanceof ScoutAIError) {
    // Any other API error
    console.error(`Scout AI error (${err.code}): ${err.message}`);
  } else {
    // Network error, etc.
    throw err;
  }
}