@fincuratech/curve-sdk-js

TypeScript SDK for the Curve Dental (CurveHero) tenant APIs. It owns the authenticated HTTP client and a thin, typed wrapper around the Curve endpoints used for insurance-payment write-back: clinics, contact search, billing accounts, coverage, transactions, notes, and claim closing.

Curve does not expose a programmatic login. The caller is responsible for obtaining a valid curve_hero_session cookie (e.g. via browser automation) and passing it to the client. The SDK is a pure HTTP layer — it does no browser automation, ERA/claim mapping, scoring, or posting orchestration.

Installation

pnpm add @fincuratech/curve-sdk-js
# or
npm install @fincuratech/curve-sdk-js

Quick start

import { createCurveClient } from '@fincuratech/curve-sdk-js';

const curve = createCurveClient({
  subdomain: 'yourtenant',
  sessionCookieValue: 'the-curve_hero_session-cookie-value',
});

// Enumerate the tenant's clinics (also doubles as an auth probe).
const clinics = await curve.clinics.list();

// Enumerate the tenant's credit/debit adjustment types.
const adjustmentTypes = await curve.adjustmentTypes.list();

// Search patients by free-text filter (name, client number, …).
const contacts = await curve.contacts.search('Jane Smith');

// Fetch the responsible-party billing account for a patient.
const account = await curve.billing.getAccount('33546');

// Subscriber/member identifiers from the patient's coverage.
const subscriberIds = await curve.coverage.getSubscriberIdentifiers('33546');

// Post an insurance payment (retries automatically on `causes_overpayment`).
const { id } = await curve.transactions.post(transactionBody);

// Attach a billing note and close the claim.
await curve.notes.post({ description, invoiceId, patientId });
await curve.claims.close(claimId, { previousTag: 'Open' });

Configuration

type CurveApiConfig = {
  /** Tenant subdomain — the `{subdomain}` in `https://{subdomain}.curvehero.com`. */
  subdomain: string;
  /** Value of the `curve_hero_session` cookie from an authenticated session. */
  sessionCookieValue: string;
  /** Cookie name override (defaults to `curve_hero_session`). */
  sessionCookieName?: string;
  /** Request timeout in milliseconds (defaults to 60000). */
  timeoutMs?: number;
  /** User-Agent override (defaults to a Firefox-shaped UA). */
  userAgent?: string;
};

API reference

| Namespace | Method | Curve endpoint | | -------------------------------------- | ----------------------------------- | --------------------------------------- | | clinics | list() | GET /cheetah/clinic | | adjustmentTypes | list() | GET /cheetah/adjustment_type | | contacts | search(filter) | GET /cheetah/contacts/search | | billing | getAccount(patientId) | GET /cheetah/billing/{id}/account | | coverage | getSubscriberIdentifiers(id) | GET /patient/getCoverageJson/{id} | | transactions | post(body) | POST /cheetah/transaction | | notes | post({ description, … }) | POST /note | | claims | close(claimId, { previousTag }) | PATCH /cheetah/claim/{id} |

Helpers resolveConfiguredClinic and assertAuthenticatedClinics are exported for callers that scope a client to a single clinic and want a fatal auth gate.

Logging

The SDK is silent by default. Plug in a logger for debugging:

import { setLogger, createConsoleLogger } from '@fincuratech/curve-sdk-js';

setLogger(createConsoleLogger('debug'));

License

MIT