@flexpa/node-sdk

The NodeSDK simplifies the process of integrating Flexpa by providing a strongly-typed client for calling Flexpa APIs.

Installation

With yarn:

yarn add @flexpa/node-sdk

With npm:

npm install @flexpa/node-sdk

With pnpm:

pnpm install @flexpa/node-sdk

Usage

Initialize FlexpaClient (from Link Exchange)

import FlexpaClient, { IntrospectResponse } from '@flexpa/node-sdk';

const flexpaClient = await FlexpaClient.fromExchange(myPublicToken, mySecretKey, 'https://api.flexpa.com');
const tokenData: IntrospectResponse = await flexpaClient.introspect();

Initialize FlexpaClient (from Access Token)

import FlexpaClient from '@flexpa/node-sdk';

const flexpaClient = new FlexpaClient(myAccessToken);
// Or: const flexpaClient = new FlexpaClient(myAccessToken, "https://api.flexpa.com");

Initialize FlexpaClient (from Client Credentials)

The Client Credentials flow provides application access tokens for server-to-server authentication without a patient context. This is useful for:

• Making API calls on behalf of your application rather than a specific patient
• Accessing non-patient-specific endpoints
• Running backend services that need Flexpa API access

import FlexpaClient from '@flexpa/node-sdk';

// Get an application access token using OAuth 2.0 Client Credentials Grant Flow
const flexpaClient = await FlexpaClient.fromClientCredentials(
  myPublishableKey,
  mySecretKey,
  'https://api.flexpa.com', // optional
);

// The response includes:
// - access_token: JWT token for API requests
// - expires_in: 1800 seconds (30 minutes)
// - token_type: "Bearer"

// Application access tokens are valid for 30 minutes and use JWT format with ES256 signatures

Reading a FHIR Resource

import * as r4 from 'fhir/r4';
import { FlexpaClient } from '@flexpa/node-sdk';

const flexpaClient = new FlexpaClient(myAccessToken);
const patient: r4.Patient = await flepxaClient.read('Patient', '$PATIENT_ID');

Searching a FHIR Resource

import * as r4 from 'fhir/r4';
import { FlexpaClient } from '@flexpa/node-sdk';

const flexpaClient = new FlexpaClient(myAccessToken);
const bundle: r4.Bundle = await flepxaClient.search('Patient', { given: 'john', family: 'doe' });

Refreshing a Token

import FlexpaClient from '@flexpa/node-sdk';

// For multiple usage patient authorizations with refresh tokens
const flexpaClient = await FlexpaClient.fromExchange(myPublicToken, mySecretKey);

// When the access token is about to expire, refresh it
const refreshResponse = await flexpaClient.tokenRefresh(myPublishableKey, mySecretKey);
// The client's access token is automatically updated

buildAuthorizationUrl

Builds the OAuth 2.0 authorization URL for the PKCE flow. Open the returned URL in a browser to start patient authorization.

const authUrl = FlexpaClient.buildAuthorizationUrl({
  publishableKey,
  redirectUri,
  codeChallenge,
  externalId,
});

Options

| Option | Type | Description | | ---------------- | ------------------- | ------------------------------------------------------------------------------------ | | publishableKey | string | Your Flexpa publishable key (pk_test_… / pk_live_…). | | redirectUri | string | The URI to redirect to after the user completes authorization. | | codeChallenge | string | Base64url-encoded SHA256 of the code verifier (see generateCodeChallenge). | | externalId | string | Stable identifier for the user in your system. | | scope | string[] | OAuth scopes. Defaults to ['launch/patient']. | | state | string | Opaque CSRF token returned on the callback. | | endpointId | string | Pre-select a specific payer/provider endpoint by ID. | | apiBaseUrl | string | Override the API base URL. Defaults to https://api.flexpa.com. | | resume | boolean | Set to true to resume an in-progress consent workflow. Emits flexpa_resume=true. | | flow | AuthorizationFlow | Opt into a non-default flow. See Flow below. |

Flow

The flow option models non-default authorization flows as a discriminated union. Omit flow for the standard payer/provider flow.

TEFCA / IAL2 identity-verified flow

FlexpaClient.buildAuthorizationUrl({
  publishableKey,
  redirectUri,
  codeChallenge,
  externalId,
  flow: { type: 'ial2' },
});

Search-mode patient match (with optional demographic hints)

FlexpaClient.buildAuthorizationUrl({
  publishableKey,
  redirectUri,
  codeChallenge,
  externalId,
  flow: {
    type: 'search',
    hints: { firstName: 'Jane', lastName: 'Doe', dob: '1985-04-12' },
  },
});

The discriminated union enforces the server-side constraints at compile time: the two modes are mutually exclusive, and hints only apply to the search flow.

Publishing to NPM

• Update packages/node-sdk/package.json's version (or run yarn workspace @flexpa/node-sdk version patch | minor | major).
• Add a corresponding entry to packages/node-sdk/CHANGELOG.md.
• Open a PR to merge the version + changelog changes into the master branch.
• Once merged, run the Publish @flexpa/node-sdk github workflow to publish the new version to NPM.
• The NPM package will be available at https://www.npmjs.com/package/@flexpa/node-sdk

FAQ

| Topic | Answer | Comments | | ----------- | ------------ | ------------ | | Runtime | Node | | Build | Through yarn | yarn build |