@rxbenefits/api

Version: 1.0.0
Status: 🚧 IN PROGRESS - TypeScript Migration Underway

Centralized API client library for RxBenefits applications with Auth0 authentication and comprehensive service integrations across multiple business domains.

🚧 Migration Status

Current State:

• ✅ Repository structure complete
• ✅ All 78 source files migrated
• ✅ Dependencies configured
• ⚠️ TypeScript strict mode compilation in progress (~300 type annotations remaining)
• ❌ Tests not yet implemented
• ❌ Documentation incomplete

Known Issues:

1. Missing notification icon exports from @rxbenefits/ui (Error, Success, Warning) - using console placeholders
2. ~150 parameter type annotations needed across Agent, Portal, Auth, DataMapper, and Keystone modules
3. ~8 exported types need explicit exports for public API
4. 2 missing module imports need resolution

Overview

The API library provides a unified interface to interact with all RxBenefits backend services, handling authentication, error management, notifications, and file operations automatically.

Key Features

• 🔐 Auth0 Integration: Automatic authentication token management
• 🎯 Type-Safe: Full TypeScript support with request/response types
• 🚨 Error Handling: Centralized error handling with user notifications
• 📁 File Operations: Built-in support for file uploads/downloads
• ⚙️ Configuration: Environment-based configuration
• 🔧 Multiple Domains: 8 business domain APIs (Auth, Portal, Keystone, Protect, Evaluate, Salesforce, Agent, DataMapper)

Installation

npm install @rxbenefits/api

# Peer dependencies
npm install @rxbenefits/constants @rxbenefits/types @rxbenefits/utils @rxbenefits/ui

Quick Start

Basic Usage

import { PortalAPI } from '@rxbenefits/api';

// Fetch organizations
const orgs = await PortalAPI.organizations.list({ queryParams: 'limit=10' });

// Get a specific organization
const org = await PortalAPI.organizations.get({ orgId: 123 });

Authentication Setup

import { BaseClient } from '@rxbenefits/api';
import { config } from '@rxbenefits/constants';

// BaseClient automatically handles Auth0 authentication
// using configuration from @rxbenefits/constants

API Domains

Portal API

Manages organizations, employees, dependents, invoices, and more.

import { PortalAPI } from '@rxbenefits/api';

// Organizations
await PortalAPI.organizations.list({ queryParams: 'limit=10' });
await PortalAPI.organizations.get({ orgId: 123 });

// Employees
await PortalAPI.employees.list({ orgId: 123, queryParams: 'status=active' });
await PortalAPI.employees.get({ orgId: 123, employeeId: 456 });

// Invoices
await PortalAPI.invoices.list({ orgId: 123, queryParams: '' });
await PortalAPI.invoices.download({ orgId: 123, invoiceId: 789, type: 'pdf', format: 'pdf' });

Auth API

User management, roles, and permissions.

import { AuthAPI } from '@rxbenefits/api';

// Users
await AuthAPI.users.list({ queryParams: 'limit=10' });
await AuthAPI.users.create(userData);

// Roles
await AuthAPI.roles.list({});
await AuthAPI.roles.create(roleData);

Keystone API

Drug lists, pharmacies, and clinical data.

import { KeystoneAPI } from '@rxbenefits/api';

// Drugs
await KeystoneAPI.drugs.list({ queryParams: 'search=aspirin' });

// Lists
await KeystoneAPI.lists.get({ id: 123, queryParams: '' });

Protect API

Clinical conditions and intervention drug lists.

import { ProtectAPI } from '@rxbenefits/api';

// Conditions
await ProtectAPI.conditions.listConditions();
await ProtectAPI.conditions.createCondition(conditionData);

// Interventions
await ProtectAPI.interventions.getInterventionDrugLists();

Agent API

Agent desktop functionality for member search and issue management.

import { MemberSearchAPI, MemberIssuesAPI } from '@rxbenefits/api';

// Member Search
await MemberSearchAPI.searchByAlternateId({
  alternateId: '123',
  firstName: 'John',
  lastName: 'Doe',
  dateOfBirth: '1990-01-01',
});

// Issues
await MemberIssuesAPI.list({ userNo: 1, queryParams: 'status=open' });

DataMapper API

Eligibility imports and data mapping.

import { DataMapperAPI } from '@rxbenefits/api';

// Templates
await DataMapperAPI.templates.getAll();
await DataMapperAPI.templates.create(templateData);

// Imports
await DataMapperAPI.eligibilityImport.getImports({
  eligibilityImportSchemaNo: 123,
  queryParams: '',
});

Evaluate API

Prospect opportunity management.

import { EvaluateAPI } from '@rxbenefits/api';

await EvaluateAPI.prospectOpps.getAll();
await EvaluateAPI.prospectOpps.get({ opportunityId: 123 });

Salesforce API

Salesforce CRM integration.

import { SalesforceAPI } from '@rxbenefits/api';

await SalesforceAPI.opportunities.query({ queryParams: 'status=open' });
await SalesforceAPI.opportunities.get({ id: '0061234567890ABC' });

Advanced Usage

Error Handling

Errors are automatically handled and displayed to users via notifications:

try {
  await PortalAPI.employees.get({ orgId: 123, employeeId: 456 });
} catch (error) {
  // Error is already displayed to user via notification
  console.error('Additional handling if needed', error);
}

File Downloads

// Download invoice
await PortalAPI.invoices.download({
  orgId: 123,
  invoiceId: 789,
  type: 'invoice',
  format: 'pdf',
});
// File is automatically downloaded to user's browser

Custom Configuration

import { BaseClient } from '@rxbenefits/api';

// BaseClient configuration is managed via @rxbenefits/constants
// See config.apiBaseUrls for endpoint configuration

API Reference

Exported APIs

• PortalAPI - Portal service APIs
• AuthAPI - Authentication and user management
• KeystoneAPI - Drug and pharmacy data
• ProtectAPI - Clinical conditions and interventions
• EvaluateAPI - Prospect opportunities
• SalesforceAPI - Salesforce CRM
• MemberSearchAPI - Agent desktop member search
• MemberIssuesAPI - Agent desktop issue management
• MembersHubAPI - Member hub services
• DataMapperAPI - Data mapping and imports
• BaseClient - Low-level HTTP client

Development

# Install dependencies
npm install

# Type check
npm run typecheck

# Lint
npm run lint

# Format
npm run format

# Build
npm run build

# Run tests (once implemented)
npm test

Migration Notes

This library was migrated from the @optimize/api monorepo library. Key changes:

1. Dependencies Updated: All @optimize/* imports changed to @rxbenefits/*
2. Peer Dependencies: Constants, types, utils, and UI libraries are peer dependencies
3. Notification Icons: Temporarily using console placeholders until UI library exports Error/Success/Warning icons
4. TypeScript Strict Mode: In progress - ~300 type annotations being added

Known Issues & TODOs

High Priority

• [ ] Complete TypeScript type annotations (~150 parameters across 8 modules)
• [ ] Export internal types used in public API (DependentRequest, OrgsRequest, etc.)
• [ ] Resolve missing module imports (Agent/membersHubService, DataMapper/ImportSchema)
• [ ] Replace placeholder notification functions with actual UI library exports

Medium Priority

• [ ] Implement comprehensive test suite (target 70% coverage)
• [ ] Add JSDoc comments to all public APIs
• [ ] Create usage examples for each domain
• [ ] Document breaking changes (if any)

Low Priority

• [ ] Performance optimization
• [ ] Bundle size optimization
• [ ] Storybook for API examples

Contributing

Please ensure all TypeScript types are properly annotated and tests pass before submitting PRs.

License

MIT

Support

For issues or questions, contact the RxBenefits development team.

Migration Started: October 24, 2025
Last Updated: October 25, 2025
Status: 🚧 Active Migration - Phase 3 (Dependency Resolution) In Progress