Quick Start

Get started with the TypeScript SDK in minutes.

Installation

First, install the SDK:

npm install syntheticusers
# or
yarn add syntheticusers

Initialize the Client

import { createConfiguration, Configuration } from '@syntheticusers/sdk'

// Configure authentication
const configuration: Configuration = createConfiguration({
  baseServer: 'https://api.syntheticusers.com',
  authMethods: {
    HTTPBearer: {
      tokenProvider: {
        getToken: () => 'your-access-token'
      }
    }
  }
})

JavaScript (CommonJS)

const { createConfiguration } = require('syntheticusers')

const configuration = createConfiguration({
  baseServer: 'https://api.syntheticusers.com',
  authMethods: {
    HTTPBearer: {
      tokenProvider: {
        getToken: () => 'your-access-token'
      }
    }
  }
})

Complete Workflow Example

Here's a complete example showing the core workflow: create an audience, generate synthetic users, run interviews, and analyze results.

import {
  createConfiguration,
  AudiencesApi,
  StudiesApi,
  SummariesApi
} from 'syntheticusers'

// Configure client
const configuration = createConfiguration({
  baseServer: 'https://api.syntheticusers.com',
  authMethods: {
    HTTPBearer: {
      tokenProvider: {
        getToken: () => 'your-access-token'
      }
    }
  }
})

async function conductResearch() {
  // Initialize API instances
  const audiencesApi = new AudiencesApi(configuration)
  const studiesApi = new StudiesApi(configuration)
  const summariesApi = new SummariesApi(configuration)
  
  const projectId = 'your-project-id'
  
  try {
    // Step 1: Generate an audience with synthetic users
    console.log('Generating audience...')
    const audience = await audiencesApi.generateAudienceV1({
      projectId,
      audienceGenerate: {
        name: 'Mobile App Users',
        description: 'Tech-savvy users aged 25-40 who frequently use mobile apps',
        size: 10
      }
    })
    console.log(`✓ Created audience: ${audience.id}`)
    
    // Step 2: Create a research study
    console.log('Creating study...')
    const study = await studiesApi.createStudyV1({
      projectId,
      studyCreate: {
        description: 'Validate new app navigation design',
        audienceIds: [audience.id]
      }
    })
    console.log(`✓ Created study: ${study.id}`)
    
    // Step 3: Conduct interviews
    console.log('Running interviews...')
    await studiesApi.interviewV1({
      projectId,
      studyId: study.id,
      interviewRequest: {
        message: 'How do you typically navigate mobile apps? What frustrates you most?'
      }
    })
    console.log('✓ Interviews started')
    
    // Step 4: Generate insights summary
    console.log('Generating insights...')
    const summary = await studiesApi.generateSummaryV1({
      projectId,
      studyId: study.id,
      summaryCreate: {
        title: 'Navigation Research Findings',
        description: 'Key insights from user interviews'
      }
    })
    console.log(`✓ Generated summary: ${summary.id}`)
    
    // Step 5: Ask follow-up questions
    console.log('Asking follow-up questions...')
    const response = await summariesApi.summaryFollowUpV1({
      projectId,
      summaryId: summary.id,
      summaryFollowUpRequest: {
        message: 'What were the top 3 pain points users mentioned?'
      }
    })
    console.log(`\nInsights: ${response.answer}`)
    
  } catch (error) {
    console.error('Error:', error)
  }
}

// Run the workflow
conductResearch()

Configuration Options

Using Environment Variables

import { createConfiguration } from 'syntheticusers'

const configuration = createConfiguration({
  baseServer: 'https://api.syntheticusers.com',
  authMethods: {
    HTTPBearer: {
      tokenProvider: {
        getToken: () => process.env.SYNTHETICUSERS_API_TOKEN || ''
      }
    }
  }
})

Custom Headers and Timeout

import { createConfiguration } from 'syntheticusers'

const configuration = createConfiguration({
  baseServer: 'https://api.syntheticusers.com',
  authMethods: {
    HTTPBearer: {
      tokenProvider: {
        getToken: () => 'your-access-token'
      }
    }
  },
  headers: {
    'X-Custom-Header': 'value'
  },
  timeout: 30000  // 30 seconds
})

Error Handling

import { createConfiguration, StudiesApi, ResponseError } from '@syntheticusers/sdk'

const configuration = createConfiguration({
  baseServer: 'https://api.syntheticusers.com',
  authMethods: {
    HTTPBearer: {
      tokenProvider: {
        getToken: () => 'your-access-token'
      }
    }
  }
})

async function createStudyWithErrorHandling() {
  const studiesApi = new StudiesApi(configuration)
  
  try {
    const study = await studiesApi.createStudyV1({
      projectId: 'your-project-id',
      studyCreate: {
        description: 'My study'
      }
    })
    
    console.log('Study created:', study.id)
    
  } catch (error) {
    if (error instanceof ResponseError) {
      console.error(`API Error: ${error.response.status}`)
      const body = await error.response.json()
      console.error('Error details:', body)
    } else {
      console.error('Unexpected error:', error)
    }
  }
}

Common Operations

List Resources

import { ProjectsApi, StudiesApi } from '@syntheticusers/sdk'

const projectsApi = new ProjectsApi(configuration)
const studiesApi = new StudiesApi(configuration)

// List all projects
const projects = await projectsApi.listProjectsV1({
  workspaceId: 'your-workspace-id'
})

// List studies in a project
const studies = await studiesApi.listStudiesV1({
  projectId: 'your-project-id'
})

Export Data

import { StudiesApi, SummariesApi } from '@syntheticusers/sdk'
import fs from 'fs/promises'

const studiesApi = new StudiesApi(configuration)
const summariesApi = new SummariesApi(configuration)

// Download study as PDF
const pdfContent = await studiesApi.getStudyPdfV1({
  projectId: 'your-project-id',
  studyId: 'your-study-id'
})

await fs.writeFile('study.pdf', pdfContent)

// Export summary
const summaryPdf = await summariesApi.exportSummaryV1({
  projectId: 'your-project-id',
  summaryId: 'your-summary-id',
  format: 'pdf'
})

await fs.writeFile('summary.pdf', summaryPdf)

TypeScript Configuration

For optimal TypeScript support, ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  }
}

Next Steps

• Core Concepts - Understand the data model
• Complete Guide - Step-by-step walkthrough
• API Reference - Full method documentation
• Common Tasks - Quick links to key methods