npm package: @rxbenefits/api
Description: Centralized API client library for RxBenefits applications with Auth0 authentication and comprehensive service integrations
Author: RxBenefits
Latest version: 1.0.0

# @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

```bash
npm install @rxbenefits/api

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

## Quick Start

### Basic Usage

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

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

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

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

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

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

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

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

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

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

### Salesforce API

Salesforce CRM integration.

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

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

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

### Custom Configuration

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

```bash
# 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