npm package: @flexpa/node-sdk
Description: The NodeSDK simplifies the process of integrating Flexpa by providing a strongly-typed client for calling Flexpa APIs.
Latest version: 1.0.0

# @flexpa/node-sdk

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

## Installation

With yarn:

```bash
yarn add @flexpa/node-sdk
```

With npm:

```bash
npm install @flexpa/node-sdk
```

With pnpm:

```bash
pnpm install @flexpa/node-sdk
```

## Usage

**Initialize FlexpaClient (from Link Exchange)**

```typescript
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)**

```typescript
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

```typescript
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**

```typescript
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**

```typescript
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**

```typescript
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
```

## Publishing to NPM

- Run `yarn workspace @flexpa/node-sdk version patch | minor | major` to update the package's version.
- Open a PR to merge the version changes into the `master` branch.
- Once merged, run the [Publish @flexpa/node-sdk](https://github.com/flexpa/flexpa/actions/workflows/node-sdk-npm-registry.yml) 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` |