@alliancemetric/sdk

v2.0.0

Published

8 days ago

Official TypeScript/JavaScript SDK for the Alliance Metrics API - PCOMS outcome measurement for mental health professionals

Alliance Metrics SDK

Official TypeScript/JavaScript SDK for the Alliance Metrics API.

Submit and analyze PCOMS (Partners for Change Outcome Management System) assessments including ORS, SRS, PHQ-9, and GAD-7 with built-in Expected Treatment Response (ETR) calculations.

Installation

npm install @alliancemetric/sdk
# or
yarn add @alliancemetric/sdk
# or
pnpm add @alliancemetric/sdk

Quick Start

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

Configuration

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
});

Assessments

Submit ORS (Outcome Rating Scale)

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)

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)

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)

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.

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

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

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 },
    },
  ],
});

Clients

// 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');

Account

// 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'],
});

API Keys

// 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:

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`);
  }
}

Clinical Reference

ORS Clinical Cutoffs

| Age Group | Clinical Cutoff | Interpretation | | ----------- | --------------- | ------------------------------------- | | Adult | 25.0 | ≥25 = Functional, <25 = Clinical | | Adolescent | 28.0 | ≥28 = Functional, <28 = Clinical | | Child | 28.0 | ≥28 = Functional, <28 = Clinical |

Reliable Change Index

ORS: 6.0 points (applies to all age groups)

SRS Alliance Cutoff

Score < 36 indicates potential alliance concern

PHQ-9 Severity Levels

| Score | Severity | | ----- | ----------------- | | 0-4 | Minimal | | 5-9 | Mild | | 10-14 | Moderate | | 15-19 | Moderately Severe | | 20-27 | Severe |

GAD-7 Severity Levels

| Score | Severity | | ----- | -------- | | 0-4 | Minimal | | 5-9 | Mild | | 10-14 | Moderate | | 15-21 | Severe |

Support

Documentation: docs.alliancemetric.com
Dashboard: dashboard.alliancemetric.com
Email: [email protected]
Issues: GitHub Issues

License

MIT