@yannelli/nextvisit-sdk 1.0.1

package/README.md

@@ -0,0 +1,399 @@
+# Nextvisit API JavaScript/TypeScript SDK
+
+Official JavaScript/TypeScript client library for the [Nextvisit AI Clinical Documentation API](https://developers.nextvisit.app).
+
+[![npm version](https://img.shields.io/npm/v/@yannelli/nextvisit-sdk.svg)](https://www.npmjs.com/package/@yannelli/nextvisit-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
+
+```bash
+npm install @yannelli/nextvisit-sdk
+```
+
+Or with yarn:
+
+```bash
+yarn add @yannelli/nextvisit-sdk
+```
+
+## Quick Start
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// Login and get a token
+const response = await client.auth.createToken({
+  email: "user@example.com",
+  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
+
+```typescript
+// Get current authenticated user
+const user = await client.users.getCurrentUser();
+console.log(user.id, user.name, user.email);
+```
+
+### Patients
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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:
+
+```typescript
+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:
+
+```typescript
+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
+
+```bash
+# Clone the repository
+git clone https://github.com/yannelli/nextvisit-sdk.git
+cd nextvisit-sdk
+
+# Install dependencies
+npm install
+```
+
+### Scripts
+
+```bash
+# 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](https://tsup.egoist.dev/) and outputs:
+
+- `dist/index.js` - CommonJS bundle
+- `dist/index.mjs` - ES Module bundle
+- `dist/index.d.ts` - TypeScript declarations
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Documentation](https://docs.nextvisitai.com)
+- [Nextvisit AI](https://nextvisitai.com)
+- [npm Package](https://www.npmjs.com/package/@yannelli/nextvisit-sdk)
+- [GitHub Repository](https://github.com/yannelli/nextvisit-sdk)