Connecting

Everything goes through one client. @palamond/sdk ships it, together with the FHIR types and the platform's code systems, so this is the only package you install.

npm install @palamond/sdk

Import	What you get
`@palamond/sdk`	`PalamondClient`, request and response types, and helpers (`getApiError`, `createReference`, ...).
`@palamond/sdk/fhir`	FHIR resource types (`Patient`, `Observation`, `Task`, ...).
`@palamond/sdk/codes`	The platform's code systems, tags, and extension URLs.

The client's shape mirrors the API's two planes. The workflow endpoints hang off resource namespaces that follow the URL structure: /v1/assessments is palamond.assessments.start(...), /v1/tasks/{id}/complete is palamond.tasks.complete(...), /v1/appointments/{id}/reschedule is palamond.appointments.reschedule(...). The FHIR record is reached through flat helpers directly on the client (searchResources, readResource, createResource, ...). Every call is typed, so your app never builds URLs or request bodies by hand, and you can tell at a glance which plane a line of code talks to.

Create a client

client.ts

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

export const palamond = new PalamondClient({
  clientId: 'your-public-client-id',
});

The client targets the production API (https://api.prd.palamond.dev/) by default. Pass baseUrl to point at another environment; keep it in configuration so each build targets the right host.

client.ts (per environment)

export const palamond = new PalamondClient({
  clientId: process.env.NEXT_PUBLIC_PALAMOND_CLIENT_ID,
  baseUrl: process.env.NEXT_PUBLIC_PALAMOND_API_URL, // e.g. https://api.lab.palamond.dev/
});

Create one client per app and reuse it. The client keeps an in-memory cache and the active session, so a single shared instance is both faster and correct.

Common options

const palamond = new PalamondClient({
  clientId: 'your-public-client-id',
  cacheTime: 60_000,
  onUnauthenticated: () => {
    // Session expired or missing: send the user to sign-in.
    window.location.href = '/signin';
  },
});

clientId: the OAuth client your app authenticates as.
baseUrl: the API host, when not production.
cacheTime: how long, in milliseconds, to serve reads from the client cache.
onUnauthenticated: called when a request fails because there is no valid session.
storage: where tokens persist. Defaults to localStorage in the browser.

Patient sessions only

The API serves signed-in patients. Every call acts as the patient who signed in and sees exactly their record; there are no service accounts or privileged clients on this surface. That is what makes a browser app safe by construction: the token in the client can never see more than its own patient.

If you run a backend for your frontend, it holds the patient's session server-side and calls the API the same way, as that patient.

Make your first authenticated call

Once a session exists (next page), confirm it works:

const me = await palamond.patient.profile();
console.log(me.id, me.name?.[0]?.family);

Continue with Authentication for the sign-in flows.

Create a client

Common options

Patient sessions only

Make your first authenticated call

On this page