@palamond/sdk

The official JavaScript/TypeScript SDK for the Palamond platform.

Palamond is an API-first healthcare platform built on FHIR. This package gives you everything you need to build an app against it:

• @palamond/sdk: the PalamondClient API client, plus the helpers you use alongside it.
• @palamond/sdk/fhir: TypeScript types for FHIR resources (Patient, Observation, Bundle, ...).
• @palamond/sdk/codes: the platform's code systems, identifier systems, tags, and extension URLs.

Install

npm install @palamond/sdk

Authentication

Palamond is an ordinary OAuth 2.0 / OpenID Connect authorization server. Your application runs the authorization_code flow with PKCE, and PalamondOAuth is a small, standards-only client for it.

Prefer the confidential profile. Your backend holds the client secret and the tokens; the browser only ever holds a session cookie for your own app.

import { PalamondOAuth } from '@palamond/sdk';

const auth = new PalamondOAuth({
  issuer: process.env.PALAMOND_ISSUER!, // from your application registration
  clientId: process.env.PALAMOND_CLIENT_ID!,
  clientSecret: process.env.PALAMOND_CLIENT_SECRET!,
  redirectUri: 'https://your.app/callback',
  scopes: ['openid', 'offline_access', 'patient:read'],
});

// 1. Start the flow. Store state, codeVerifier and nonce against the user's
//    session, then redirect them to request.url.
const request = await auth.createAuthorizationUrl();

// 2. On your callback route.
const tokens = await auth.callback(fullCallbackUrl, {
  codeVerifier: stored.codeVerifier,
  expectedState: stored.state,
  expectedNonce: stored.nonce,
});

A native app or an SPA with no backend opts in to the public profile explicitly with publicClient: true and no secret. That profile puts a real access token on the user's device: every check in your UI is decoration, and the server is the only authority. Read Authentication before choosing it.

Calling the API

PalamondClient takes a session — one patient's access, kept current — and never obtains a token itself. auth.session turns the tokens from the callback into one; it refreshes before expiry and reports each rotated token set through onTokens, which is where you persist it.

import { PalamondClient } from '@palamond/sdk';

const session = auth.session(tokens, { onTokens: (t) => saveTokens(userId, t) });
const palamond = new PalamondClient({ session });

// Workflow endpoints hang off resource namespaces that mirror the API paths.
const catalog = await palamond.protocols.list();
const started = await palamond.assessments.start({ healthcareService: catalog[0].healthcareService });

// The FHIR record is reached through flat helpers on the client itself.
const appointments = await palamond.searchResources('Appointment', { _count: '10' });

Every call acts as one patient and is scoped to their record by the platform. There is no client_credentials grant and no service account on this surface; the one non-interactive grant is delegated authentication (RFC 7523, for patients your application authenticates itself): new PalamondDelegatedAuth({ …, assertion: { issuer, key } }).session(userId) signs the assertions for you, needs the clinic's approval, and still yields a session for one named patient.

Platform constants

Every Palamond code system, identifier system, tag, and extension URL ships with the SDK, so you never hand-copy a URL out of the docs:

import { LATEST_VERSION_TAG, IDENTIFIER_SYSTEMS } from '@palamond/sdk/codes';

Documentation

Full guides, resource references, and worked examples live at docs.palamond.dev.