SDK Integration

Counslr SOS provides two TypeScript SDKs for browser integration. Both are zero-dependency packages that handle authentication, WebSocket communication, and error recovery.

Patient Web SDK

The Patient Web SDK (@counslr/patient-web-sdk) automates the patient-side flow: WebSocket connection, geolocation tracking, and location submission during SOS events.

Installation

npm install @counslr/patient-web-sdk

Usage

import { CounslrPatientSDK, RateLimitError } from '@counslr/patient-web-sdk';

const sdk = new CounslrPatientSDK({
  token: patientToken,       // JWT from POST /session/start
  apiBaseUrl: 'https://api.counslr-sos.example.com',
  wsUrl: 'wss://ws.counslr-sos.example.com',
  maxRetryAttempts: 3,       // Auto-retry on 429 (default: 3)
  onPSAPResults: (psaps) => {
    // Display PSAP contacts
  },
  onError: (err) => {
    if (err instanceof RateLimitError) {
      // All retries exhausted
    }
  },
});

sdk.init();   // Connects WebSocket + starts geolocation tracking
// ...
sdk.destroy(); // Closes WebSocket + clears location + removes session data

How It Works

1. init() decodes the JWT, saves session metadata to sessionStorage, connects the WebSocket, and starts navigator.geolocation.watchPosition
2. The SDK stores the latest GPS coordinates in a private variable (never persisted)
3. When a location_request message arrives via WebSocket, the SDK automatically submits the stored location via POST /v1/platforms/{platformId}/sessions/{sessionId}/sos/location
4. The server returns nearest PSAP contacts, which the SDK delivers via the onPSAPResults callback
5. destroy() nulls the location variable, closes the WebSocket, and clears sessionStorage

HIPAA Controls

• Location is stored in a private JavaScript variable only (never in localStorage, sessionStorage, or IndexedDB)
• sessionStorage contains only the JWT token and session IDs
• destroy() explicitly nulls the location and clears session data

Counselor SDK

The Counselor SDK (@counslr/counselor-sdk) provides session management, SOS triggering, and real-time PSAP result delivery via WebSocket.

Installation

npm install @counslr/counselor-sdk

Usage

The SDK supports two authentication modes: API key for server-side session management, and JWT for client-side SOS operations.

import { CounslrCounselorSDK, RateLimitError } from '@counslr/counselor-sdk';

// Server-side: create a session (using secret key)
const adminSDK = new CounslrCounselorSDK({ secretKey: 'sk_live_...' });
const session = await adminSDK.startSession({
  meetingId: 'room-123',
  counselorId: 'counselor-456',
  patientId: 'patient-789',
  expiresInMinutes: 60,
});

// Client-side: connect for real-time PSAP results (using counselor JWT)
const sessionSDK = new CounslrCounselorSDK({
  sessionToken: session.counselor_token,
  wsUrl: 'wss://ws.counslr-sos.example.com',
  maxRetryAttempts: 3,
  onPSAPResults: (results) => {
    console.log('Nearest PSAPs:', results.psaps);
  },
  onStateChange: (state) => {
    console.log('Connection:', state);
  },
  onError: (err) => {
    if (err instanceof RateLimitError) {
      // All retries exhausted
    }
  },
});
sessionSDK.connect();

// Trigger SOS (results arrive via onPSAPResults callback)
await sessionSDK.trigger({ sessionId: session.session_id });

// Clean up
sessionSDK.disconnect();
await adminSDK.endSession({ sessionId: session.session_id });

SDK ↔ API Endpoint Mapping

Rate Limit Handling

Both SDKs automatically retry on HTTP 429:

• Uses the Retry-After header value if present, otherwise exponential backoff (1s, 2s, 4s, …)
• Retries up to 3 times by default (configurable via maxRetryAttempts)
• After all retries are exhausted, throws RateLimitError
• Non-429 errors are never retried