Official TypeScript/JavaScript SDK for the Alliance Metrics API - PCOMS outcome measurement for mental health professionals
npm install @alliancemetric/sdkbash
npm install @alliancemetric/sdk
or
yarn add @alliancemetric/sdk
or
pnpm add @alliancemetric/sdk
`
Quick Start
`typescript
import { AllianceMetric } from '@alliancemetric/sdk';
const client = new AllianceMetric({
apiKey: 'your-api-key', // Get from https://dashboard.alliancemetric.com
});
// Submit an ORS assessment
const result = await client.assessments.submitOrs({
clientId: 'client-123',
sessionNumber: 1,
ageGroup: 'adult',
scores: {
individual: 5.5,
interpersonal: 6.0,
social: 4.5,
overall: 5.0,
},
});
console.log(Total Score: ${result.data.totalScore});
console.log(Status: ${result.data.interpretation.status});
`
Features
- Full TypeScript Support: Comprehensive type definitions for all API operations
- All Assessment Types: ORS, SRS, PHQ-9, GAD-7
- ETR Calculations: Built-in Expected Treatment Response trajectory analysis
- Client Management: Track clients and their assessment history
- Automatic Retries: Configurable retry logic with exponential backoff
- Error Handling: Typed error classes for different error scenarios
API Reference
$3
`typescript
const client = new AllianceMetric({
apiKey: 'your-api-key', // Required
baseUrl: 'https://api.alliancemetric.com', // Optional
timeout: 30000, // Optional: Request timeout in ms
retries: 3, // Optional: Number of retry attempts
});
`
$3
#### Submit ORS (Outcome Rating Scale)
`typescript
const result = await client.assessments.submitOrs({
clientId: 'client-123',
sessionNumber: 1,
ageGroup: 'adult', // 'adult' | 'adolescent' | 'child'
scores: {
individual: 5.5, // 0-10
interpersonal: 6.0, // 0-10
social: 4.5, // 0-10
overall: 5.0, // 0-10
},
clinicianId: 'therapist-001', // Optional
sessionDate: '2024-01-15', // Optional
});
// Response includes:
// - totalScore: Combined score (0-40)
// - interpretation: Clinical status and recommendations
// - change: Change from intake if applicable
// - creditsUsed/remainingCredits
`
#### Submit SRS (Session Rating Scale)
`typescript
const result = await client.assessments.submitSrs({
clientId: 'client-123',
sessionNumber: 1,
scores: {
relationship: 9.0, // 0-10
goalsTopics: 8.5, // 0-10
approachMethod: 9.0, // 0-10
overall: 9.5, // 0-10
},
});
// Response includes alliance status and flagged items
`
#### Submit PHQ-9 (Depression Screening)
`typescript
const result = await client.assessments.submitPhq9({
clientId: 'client-123',
sessionNumber: 1,
scores: {
item1: 2, item2: 1, item3: 2, item4: 1,
item5: 1, item6: 2, item7: 1, item8: 0,
item9: 0, // Suicidal ideation - triggers alert if > 0
},
});
// Response includes severity level and suicidal ideation alerts
`
#### Submit GAD-7 (Anxiety Screening)
`typescript
const result = await client.assessments.submitGad7({
clientId: 'client-123',
sessionNumber: 1,
scores: {
item1: 2, item2: 1, item3: 2, item4: 1,
item5: 0, item6: 1, item7: 1,
},
});
// Response includes anxiety severity level
`
#### Calculate ETR (Expected Treatment Response)
ETR calculations use proprietary algorithms performed server-side. The SDK returns trajectory predictions without exposing algorithm internals.
`typescript
const result = await client.assessments.calculateEtr({
intakeScore: 18.5,
ageGroup: 'adult',
sessions: 12, // Optional, defaults to 12
});
// Returns expected score trajectory for treatment planning
`
#### Calculate Progress
`typescript
const result = await client.assessments.calculateProgress({
ageGroup: 'adult',
scores: [
{ score: 18.5, date: '2024-01-15' },
{ score: 22.0, date: '2024-01-22' },
{ score: 25.5, date: '2024-01-29' },
],
});
// Returns comprehensive progress analysis including:
// - Reliable Change indicator
// - Clinically Significant Change
// - ETR comparison
// - Validity indicators (sawtooth, ceiling effects)
`
#### Batch Submit
`typescript
const result = await client.assessments.submitBatch({
assessments: [
{
type: 'ors',
clientId: 'client-123',
sessionNumber: 1,
ageGroup: 'adult',
scores: { individual: 5, interpersonal: 6, social: 5, overall: 5 },
},
{
type: 'srs',
clientId: 'client-123',
sessionNumber: 1,
scores: { relationship: 9, goalsTopics: 8, approachMethod: 9, overall: 9 },
},
],
});
`
$3
`typescript
// List clients
const clients = await client.clients.list({
page: 1,
limit: 20,
status: 'active',
sortBy: 'lastSession',
});
// Get client details
const detail = await client.clients.get('client-123');
// Get treatment trajectory
const trajectory = await client.clients.getTrajectory('client-123');
// Get comprehensive report
const report = await client.clients.getReport('client-123');
// Get assessment history
const orsHistory = await client.clients.getOrsHistory('client-123');
const srsHistory = await client.clients.getSrsHistory('client-123');
const phq9History = await client.clients.getPhq9History('client-123');
const gad7History = await client.clients.getGad7History('client-123');
`
$3
`typescript
// Get account info
const account = await client.account.get();
// Check credit balance
const balance = await client.account.getBalance();
// Get usage statistics
const usage = await client.account.getUsage({
startDate: '2024-01-01',
endDate: '2024-01-31',
});
// Manage webhooks
const webhooks = await client.account.listWebhooks();
await client.account.createWebhook({
url: 'https://your-app.com/webhooks',
events: ['assessment.submitted', 'alert.created'],
});
`
$3
`typescript
// List keys
const keys = await client.apiKeys.list();
// Create a new key (store the returned key securely!)
const newKey = await client.apiKeys.create({
name: 'Production Integration',
permissions: ['assessments:write', 'clients:read'],
});
// Rotate a key
const rotatedKey = await client.apiKeys.rotate('old-key-id', {
name: 'Rotated Production Key',
});
`
Error Handling
The SDK provides typed error classes for different scenarios:
`typescript
import {
AllianceMetric,
AuthenticationError,
ValidationError,
InsufficientCreditsError,
RateLimitError,
} from '@alliancemetric/sdk';
try {
await client.assessments.submitOrs({ ... });
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key');
} else if (error instanceof ValidationError) {
console.error('Invalid data:', error.errors);
} else if (error instanceof InsufficientCreditsError) {
console.error(Need ${error.required} credits, have ${error.available});
} else if (error instanceof RateLimitError) {
console.error(Rate limited. Retry after ${error.retryAfter}s);
}
}
``