Nextvisit API JavaScript/TypeScript SDK

Official JavaScript/TypeScript client library for the Nextvisit AI Clinical Documentation API.

Features

• Full TypeScript support with comprehensive type definitions
• Promise-based async/await API
• Automatic error handling with typed exceptions
• Support for both CommonJS and ES Modules
• Zero runtime dependencies
• Node.js 18+ support

Installation

npm install @yannelli/nextvisit-sdk

Or with yarn:

yarn add @yannelli/nextvisit-sdk

Quick Start

import { NextvisitClient } from "@yannelli/nextvisit-sdk";

// Create a client with an existing token
const client = new NextvisitClient({
  token: "nv-sk-your-token-here"
});

// Get the current user
const user = await client.users.getCurrentUser();
console.log(`Logged in as ${user.name}`);

// List patients
const patients = await client.patients.list();
console.log(`Found ${patients.meta.total} patients`);

Configuration

Client Options

interface NextvisitClientConfig {
  token?: string;         // Authentication token
  baseUrl?: string;       // API base URL (default: https://nextvisit.app/api)
  fetch?: typeof fetch;   // Custom fetch implementation
  timeout?: number;       // Request timeout in ms (default: 30000)
}

Examples

// Production client
const client = new NextvisitClient({
  token: "nv-sk-your-token"
});

// Local development
const client = new NextvisitClient({
  baseUrl: "http://localhost/api",
  token: "dev-token"
});

// Custom timeout
const client = new NextvisitClient({
  token: "nv-sk-your-token",
  timeout: 60000 // 60 seconds
});

Token Management

// Set token after initialization
client.setToken("nv-sk-new-token");

// Clear token
client.clearToken();

// Check if authenticated
if (client.hasToken()) {
  console.log("Client is authenticated");
}

API Reference

Authentication

// Login and get a token
const response = await client.auth.createToken({
  email: "[email protected]",
  password: "password",
  device_name: "My App"
});
client.setToken(response.token);

// List all tokens
const { tokens } = await client.auth.listTokens();
tokens.forEach(t => {
  console.log(`${t.name} - Created: ${t.created_at}`);
});

// Logout (revoke current token)
await client.auth.revokeCurrentToken();

// Revoke a specific token
await client.auth.revokeToken(tokenId);

Users

// Get current authenticated user
const user = await client.users.getCurrentUser();
console.log(user.id, user.name, user.email);

Patients

// List patients with pagination
const response = await client.patients.list({
  per_page: 25,
  sort: "-created_at" // Descending by creation date
});

// Filter patients
const filtered = await client.patients.list({
  "filter[last_name]": "Smith",
  "filter[trashed]": "with" // Include soft-deleted
});

// Get a single patient
const patient = await client.patients.get(patientId);

// Create a patient
const newPatient = await client.patients.create({
  first_name: "John",
  last_name: "Doe",
  date_of_birth: "1990-05-15",
  notes: "Referred for consultation",
  allergies: "Penicillin"
});

// Update a patient
const updated = await client.patients.update(patientId, {
  first_name: "Jonathan",
  notes: "Updated contact information"
});

// Delete a patient (soft delete)
await client.patients.delete(patientId);

// Search patients
const results = await client.patients.search(userId, {
  query: "John",
  per_page: 10,
  sort_by: "desc"
});

Progress Notes

// List progress notes
const notes = await client.progressNotes.list({
  patient_id: patientId,
  per_page: 25,
  sort_by: "latest" // or "oldest"
});

// Get a single progress note
const note = await client.progressNotes.get(noteId);

// Get audio URL for a note
const { url } = await client.progressNotes.getAudioUrl(noteId);

// Create a progress note with audio
const audioFile = new File([audioBlob], "recording.mp3", {
  type: "audio/mpeg"
});

const note = await client.progressNotes.create({
  name: "Follow-up Visit - John Doe",
  patient_id: patientId,
  file: audioFile,
  model_id: 1 // Optional template
});

// Create a text-only progress note
const textNote = await client.progressNotes.create({
  name: "Patient Consultation",
  note: "Patient presented with symptoms of...",
  model_id: 1,
  patient_id: patientId
});

// Update a progress note
const updated = await client.progressNotes.update(noteId, {
  name: "Updated Visit Name",
  transcription: "Corrected transcription..."
});

// Sign/approve a progress note
const signedNote = await client.progressNotes.sign(noteId);

// Delete a progress note
await client.progressNotes.delete(noteId);

Supported audio formats: mp3, mp4, m4a, wav, ogg, webm, flac, aac, pcm, opus Maximum file size: 200MB

Billing

// List available plans
const { plans } = await client.billing.listPlans();
plans.forEach(plan => {
  console.log(`${plan.name}: ${plan.price_prefix}${plan.price}${plan.price_suffix}`);
});

// Get billing estimate
const estimate = await client.billing.getEstimate();
console.log(`Users: ${estimate.users}`);
console.log(`Total: ${estimate.total_formatted}`);
console.log(`Renewal: ${estimate.renewal_date}`);

// Get usage statistics
const usage = await client.billing.getUsage("notes");
console.log(`Plan: ${usage.plan.name} (${usage.plan.status})`);
console.log(`Usage: ${usage.usage.used} / ${usage.usage.limit}`);

Transcription

// Transcribe an audio file
const response = await client.transcription.transcribeFile({
  file: audioFile // File or Blob
});

if (response.success) {
  console.log(response.text);
}

// Get temporary token for client-side transcription
const tokenResponse = await client.transcription.getToken();
if (tokenResponse.success && tokenResponse.token) {
  // Use with Deepgram SDK for real-time transcription
  const deepgram = createClient(tokenResponse.token);
}

Error Handling

The SDK provides typed error classes for different failure scenarios:

import {
  NextvisitError,
  NextvisitApiError,
  UnauthorizedError,
  ForbiddenError,
  NotFoundError,
  ValidationError,
  NetworkError
} from "@yannelli/nextvisit-sdk";

try {
  const user = await client.users.getCurrentUser();
} catch (error) {
  if (error instanceof UnauthorizedError) {
    // 401 - Authentication failed
    console.error("Please log in again");
  } else if (error instanceof ForbiddenError) {
    // 403 - Access denied
    console.error("You don't have permission");
  } else if (error instanceof NotFoundError) {
    // 404 - Resource not found
    console.error("Resource not found");
  } else if (error instanceof ValidationError) {
    // 422 - Validation failed
    console.error("Validation errors:", error.errors);
  } else if (error instanceof NetworkError) {
    // Network request failed
    console.error("Network error:", error.message);
  } else if (error instanceof NextvisitApiError) {
    // Other API error
    console.error(`API error (${error.status}): ${error.message}`);
  }
}

Error Classes

| Class | Status Code | Description | |-------|-------------|-------------| | NextvisitError | - | Base error class | | NextvisitApiError | Any | API error with status code | | UnauthorizedError | 401 | Authentication required | | ForbiddenError | 403 | Access denied | | NotFoundError | 404 | Resource not found | | ValidationError | 422 | Validation failed (includes errors field) | | NetworkError | - | Network request failure |

TypeScript Support

All API responses are fully typed. Import types directly from the package:

import type {
  User,
  PatientFull,
  ProgressNote,
  PaginatedResponse,
  TokenResponse,
  BillingPlan,
  BillingUsage
} from "@yannelli/nextvisit-sdk";

// Types are inferred from API calls
const patient = await client.patients.get(123);
// patient is typed as PatientFull

const notes = await client.progressNotes.list();
// notes is typed as PaginatedResponse<ProgressNote>

Development

Prerequisites

• Node.js 18.0.0 or higher

Setup

# Clone the repository
git clone https://github.com/yannelli/nextvisit-sdk.git
cd nextvisit-sdk

# Install dependencies
npm install

Scripts

# Build the package
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Type checking
npm run typecheck

# Lint code
npm run lint

Building

The package is built using tsup and outputs:

• dist/index.js - CommonJS bundle
• dist/index.mjs - ES Module bundle
• dist/index.d.ts - TypeScript declarations

License

MIT License - see LICENSE for details.

Links

• Documentation
• Nextvisit AI
• npm Package
• GitHub Repository