@securecloudnetworks/epic-cli/README.md

Professional CLI tool for Epic EHR FHIR integration with JWT authentication and Railway backend

# Epic CLI - Professional Epic EHR Integration Tool

🏥 **The fastest way to integrate with Epic EHR FHIR APIs - 5 minutes setup, not 5 months!**

[![npm version](https://badge.fury.io/js/%40securecloudnetworks%2Fepic.svg)](https://badge.fury.io/js/%40securecloudnetworks%2Fepic)
[![License: Commercial](https://img.shields.io/badge/License-Commercial-blue.svg)](LICENSE.md)
[![Epic FHIR](https://img.shields.io/badge/Epic-FHIR%20R4-green.svg)](https://fhir.epic.com/)

**✅ FULLY FUNCTIONAL** - Version 1.0.9 with complete license activation, X.509 certificate generation, and seamless Epic integration!

## 🚀 Quick Start

```bash
# Install the latest version
npm install -g @securecloudnetworks/epic@latest

# Initialize with your license key (handles already-activated licenses gracefully)
epic init --license=YOUR-LICENSE-KEY

# Or run interactive setup with automatic X.509 certificate generation
epic setup

# Check status and start exploring
epic status
epic patients search --family Lopez
epic patient get PATIENT_ID
epic vitals PATIENT_ID --json
```

### 🎉 What's New in v1.0.9

- **✅ Seamless License Activation**: Gracefully handles Stripe-activated licenses
- **✅ Proper X.509 Certificates**: Generates RFC 5280 compliant certificates for Epic
- **✅ Complete JWT Authentication**: Full token lifecycle management
- **✅ Railway Backend Integration**: Production-ready at `https://api.ehrcli.com`
- **✅ Enhanced UX**: No more errors for already-activated licenses

## 💳 License Tiers

Epic CLI offers flexible licensing to match your needs:

### 🔓 Trial Mode (FREE)

- **10 API calls per day**
- **300 API calls per month** (30-day rolling)
- Sandbox environment only
- Community support via GitHub
- Perfect for evaluation and learning

### 👤 Starter ($199/year)

- **2,000 API calls per day**
- **60,000 API calls per month** (30-day rolling)
- Sandbox + Production environments
- JSON export capabilities
- Email support
- Perfect for solo developers and small projects

### 🏢 Professional ($499/year)

- **5,000 API calls per day**
- **150,000 API calls per month** (30-day rolling)
- CSV export and batch processing
- Advanced features
- Priority email support
- Perfect for growing teams and agencies

### 👥 Team License ($999/year)

- **10,000 API calls per day**
- **300,000 API calls per month** (30-day rolling)
- Up to 10 team members
- Team configuration sharing
- Advanced team features
- Priority email support
- Perfect for established teams

### 🏢 Enterprise License (Custom)

- **Unlimited API calls**
- Unlimited team members
- Advanced features: webhooks, custom queries, audit logs
- 24/7 phone support with SLA
- Custom integrations and on-premise deployment
- Perfect for large organizations and health systems

## 📋 Installation & Setup

### Prerequisites

- Node.js 16+
- Epic Developer Account ([Sign up free](https://fhir.epic.com/))
- 5 minutes of your time

### Installation

```bash
npm install -g @securecloudnetworks/epic
```

### Quick Setup Options

#### Option 1: Initialize with License

```bash
epic init --license=YOUR-LICENSE-KEY
```

#### Option 2: Environment Variables

```bash
# Create .env file or set environment variables
export EPIC_CLIENT_ID="your-client-id"
export EPIC_API_URL="https://fhir.epic.com/interconnect-fhir-oauth"
export EPIC_PRIVATE_KEY_PATH="./private-key.pem"
export EPIC_CLI_LICENSE="your-license-key"

epic init
```

#### Option 3: Interactive Setup (Recommended)

```bash
epic setup
```

The setup wizard will guide you through:

1. **Epic app configuration** (Client ID, environment)
2. **RSA key pair generation** (automatic 2048-bit keys)
3. **X.509 certificate creation** (RFC 5280 compliant for Epic)
4. **Certificate upload instructions** (step-by-step Epic Developer Portal guide)
5. **Integration testing** (verifies everything works end-to-end)

### 🔐 X.509 Certificate Generation (New in v1.0.8+)

Epic CLI now generates **proper X.509 certificates** instead of SPKI public keys:

```bash
# The setup wizard automatically creates:
# - epic-private.key (RSA-2048 private key)
# - epic-public.key (SPKI public key - for reference)
# - epic-cert.pem (X.509 certificate - upload this to Epic!)

# Certificate details:
# ✅ Format: X.509 Certificate (RFC 5280)
# ✅ Algorithm: RSA-2048 with SHA-256
# ✅ Type: Self-signed certificate
# ✅ Extensions: Proper certificate structure for Epic compatibility
```

**Important**: Upload the `epic-cert.pem` file (X.509 certificate) to Epic Developer Portal, not the public key file.

## 🔒 License Enforcement Update (v2.0.0)

**New in this version**: Strict license expiration and monthly quota enforcement

### Key Enhancements

- **Strict Expiration**: Licenses now expire exactly 1 year from `issuedAt` timestamp
- **Monthly Quotas**: 30-day rolling window quota tracking in addition to daily limits
- **Enhanced Validation**: Returns complete usage statistics including remaining calls and reset times
- **Environment Gating**: Trial users strictly limited to sandbox environment only

### License Timestamps

All licenses now include precise timestamps:

- `issuedAt`: When the license was first issued
- `expiresAt`: Exactly 1 year from issue date (strict enforcement)

### Usage Statistics

License validation now returns comprehensive usage information:

```json
{
  "valid": true,
  "tier": "starter",
  "status": "active",
  "issuedAt": "2024-08-29T05:00:00.000Z",
  "expiresAt": "2025-08-29T05:00:00.000Z",
  "usage": {
    "remainingCalls": 1995,
    "monthlyRemainingCalls": 59850,
    "resetAt": "2025-08-30T00:00:00.000Z",
    "monthlyResetAt": "2025-09-28T00:00:00.000Z"
  }
}
```

### Migration Notes

- Existing licenses will be automatically updated with `issuedAt` and `expiresAt` timestamps
- Monthly usage tracking starts from the update date
- All quota limits have been updated to match the new tier structure

## 🔑 License Management

### Activate Your License

```bash
# Purchase license at: https://ehrcli.com/pricing
# Note: Stripe automatically activates licenses upon purchase!

# Initialize with your license (handles already-activated licenses gracefully)
epic init --license=YOUR-LICENSE-KEY-HERE

# Or activate manually
epic license activate YOUR-LICENSE-KEY-HERE

# Check license status
epic status
epic license status

# View upgrade options
epic upgrade
```

### 🎉 Improved License Experience (v1.0.9)

**Seamless Stripe Integration**: No more errors for already-activated licenses!

```bash
# Before v1.0.9:
❌ License activation failed: License is already activated

# Now in v1.0.9:
ℹ️  License is already activated
✅ Proceeding with initialization...
```

### License Commands

```bash
epic status                        # Show overall CLI status and license info
epic license status               # Show detailed license and usage information
epic license activate <key>       # Activate a license key (handles already-activated)
epic license deactivate           # Return to trial mode
epic license test                  # Test license API connectivity
epic upgrade                       # View pricing and upgrade options
```

## 🛠️ Available Commands

### License Management

```bash
epic license status            # Show license tier and remaining calls
epic license activate <key>    # Activate your purchased license
epic upgrade                   # View pricing and purchase options
```

### Authentication & Status

```bash
epic auth test                 # Test Epic authentication
epic auth status               # Check token status
epic status                    # Overall system health
epic capabilities              # FHIR server capabilities
epic features                  # Show available features by license tier
```

### Patient Operations

```bash
# Search patients (all tiers)
epic patients search --family Smith --given John
epic patients search --gender female --count 10

# CSV export (Team+ only)
epic patients search --family Smith --csv

# Get patient details
epic patient PATIENT_ID
epic patient PATIENT_ID --json --include "vitals,labs,medications"
```

### Clinical Data (Starter+)

```bash
# Patient vitals
epic vitals PATIENT_ID
epic vitals PATIENT_ID --count 10 --since 2024-01-01

# Lab results
epic labs PATIENT_ID --json

# Medications
epic medications PATIENT_ID
epic medications PATIENT_ID --status active
```

### Configuration

```bash
epic config show              # Show current configuration
epic config validate          # Validate configuration
epic setup --force            # Re-run setup wizard
```

## 💻 Real-World Examples

### Trial Mode (Free)

```bash
# Perfect for learning and evaluation
epic patients search --family Lopez
epic patient erXuFYUfucBZaryVksYEcMg3

# 10 calls/day limit - upgrade when ready
epic upgrade
```

### Starter License

```bash
# Production environment access
epic patients search --family Smith --count 50 --json > patients.json

# 2000 calls/day for serious development
epic patient PATIENT_ID --include "vitals,labs,medications"
```

### Professional License

```bash
# CSV export for team analysis
epic patients search --gender female --count 100 --csv > female_patients.csv

# Batch processing capabilities
epic batch-process patient-ids.txt
```

### Team License

```bash
# Team configuration sharing
epic config share --team-id TEAM_ID

# Advanced team features with 10,000 calls/day
epic patients search --count 1000 --json
```

### Enterprise License

```bash
# Unlimited API calls for production systems
epic patients search --count 10000 --json

# Advanced webhook configuration
epic webhook setup --endpoint https://yourapp.com/epic-webhook
```

## 📊 Sample Output with License Info

### License Status Display

```bash
$ epic license status

📋 Epic CLI License Status

Tier: 👤 Starter
Status: Active
License Key: STR-****-7890
Expires: December 31, 2025 (342 days)

📊 Usage Information:
   Daily API Calls: 1,247 / 2,000
   Environments: sandbox, production
   Team Members: 1

✨ Available Features:
   ✅ basic search
   ✅ patient data
   ✅ export json
   ✅ vitals labs

📞 Support:
   Type: Email Support
   Contact: support@ehrcli.com
```

### Patient Search with License Display

```bash
$ epic patients search --family Lopez

🔓 Trial Mode - 8 calls remaining today
   Upgrade at: https://ehrcli.com/pricing

👥 Searching Epic patients...

✅ Found 1 patients:

1. [REDACTED] [REDACTED]
   ID: erXuFYUfucBZaryVksYEcMg3
   Birth Date: [REDACTED]
   Gender: female

🔓 Trial License - 7 calls remaining today
```

### Feature Gating Example

```bash
$ epic patients search --csv

❌ License Error: Feature 'export_csv' requires a higher license tier. Current: starter. Upgrade at: https://ehrcli.com/pricing
💡 Run: epic license activate <KEY> or epic upgrade
```

## 🔒 Usage Limits & Quotas

### Daily API Call Limits

| Tier         | Daily Limit | Reset Time   |
| ------------ | ----------- | ------------ |
| Trial        | 10          | Midnight UTC |
| Starter      | 2,000       | Midnight UTC |
| Professional | 5,000       | Midnight UTC |
| Team         | 10,000      | Midnight UTC |
| Enterprise   | Unlimited   | N/A          |

### Quota Exceeded Handling

```bash
$ epic patients search

❌ License Error: Daily API quota exceeded (10/10). Quota resets at 1/16/2024, 12:00:00 AM. Upgrade your license at https://ehrcli.com/pricing
💡 Run: epic license activate <KEY> or epic upgrade
```

## 🎯 Feature Matrix

| Feature                | Trial | Starter | Professional | Team | Enterprise |
| ---------------------- | ----- | ------- | ------------ | ---- | ---------- |
| Patient Search         | ✅    | ✅      | ✅           | ✅   | ✅         |
| Patient Details        | ✅    | ✅      | ✅           | ✅   | ✅         |
| JSON Export            | ✅    | ✅      | ✅           | ✅   | ✅         |
| Production Environment | ❌    | ✅      | ✅           | ✅   | ✅         |
| Vitals & Labs          | ❌    | ✅      | ✅           | ✅   | ✅         |
| CSV Export             | ❌    | ❌      | ✅           | ✅   | ✅         |
| Batch Processing       | ❌    | ❌      | ✅           | ✅   | ✅         |
| Team Sharing           | ❌    | ❌      | ❌           | ✅   | ✅         |
| Webhooks               | ❌    | ❌      | ❌           | ❌   | ✅         |
| Custom Queries         | ❌    | ❌      | ❌           | ❌   | ✅         |
| Audit Logs             | ❌    | ❌      | ❌           | ❌   | ✅         |

## 🧪 Testing License Features

Use mock licenses for testing without purchasing:

```bash
# Test starter license features
epic --mock-license starter license status
epic --mock-license starter patients search

# Test professional license features
epic --mock-license professional patients search --csv

# Test team license features
epic --mock-license team license status

# Test enterprise license
epic --mock-license enterprise license status

# Test expired license (falls back to trial)
epic --mock-license expired patients search
```

## 🛡️ Security & Compliance

### Data Security

- **JWT Authentication**: Complete RS384 algorithm with 2048-bit RSA keys
- **X.509 Certificates**: RFC 5280 compliant certificates for Epic integration
- **License Validation**: Real-time validation with Railway backend (`https://api.ehrcli.com`)
- **PHI Protection**: Automatic sanitization of sensitive healthcare data
- **HTTPS Only**: All Epic and backend communication encrypted
- **Secure Token Management**: Automatic token refresh and secure storage

### Epic Integration Security

```bash
# The CLI automatically handles:
# ✅ JWT token creation and refresh
# ✅ X.509 certificate generation and validation
# ✅ Secure API communication with Epic
# ✅ License validation with backend

# Check security status
epic status
```

### PHI Protection

```bash
# Enable PHI protection (default)
epic patients search --family Smith

# Disable local storage entirely
epic --no-store patients search --family Smith

# Environment variable for automation
export EPIC_CLI_NO_STORE=true
epic patients search --family Smith
```

### License Security

- **Key Validation**: Online license verification
- **Usage Limits**: Automatic quota enforcement
- **Feature Gating**: License-based feature access control
- **Audit Trail**: Complete usage logging (Enterprise)

## 🌐 Environment Variables

### Core Configuration

```bash
# Epic Integration
EPIC_CLIENT_ID=your-client-id
EPIC_API_URL=https://fhir.epic.com/interconnect-fhir-oauth
EPIC_TOKEN_URL=https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token
EPIC_PRIVATE_KEY_PATH=./private-key.pem
EPIC_ENVIRONMENT=sandbox  # or production
EPIC_SCOPE=system/*.read

# License Management
EPIC_CLI_LICENSE=your-license-key
EPIC_LICENSE_API_URL=https://api.ehrcli.com/v1/license/validate

# CLI Behavior
EPIC_CLI_NO_STORE=true    # Disable local storage
EPIC_DEFAULT_FORMAT=json  # or table
EPIC_DEFAULT_COUNT=10
```

### Configuration Files

```bash
# .env file in current directory
EPIC_CLIENT_ID=your-client-id
EPIC_CLI_LICENSE=your-license-key

# ~/.ehrclirc JSON configuration
{
  "EPIC_CLIENT_ID": "your-client-id",
  "EPIC_CLI_LICENSE": "your-license-key"
}
```

## 🏥 Epic Setup Guide

### 1. Create Epic App

- Go to [Epic on FHIR](https://fhir.epic.com/)
- Sign up for developer account
- Create new application

### 2. Configure App

- **Application Type**: Backend Service
- **FHIR Version**: R4
- **Scopes**:
  - `system/Patient.read`
  - `system/Observation.read`
  - `system/Appointment.read`
  - `system/MedicationRequest.read`

### 3. Run Epic CLI Setup

```bash
epic setup
```

The wizard will generate keys and show you exactly what to upload to Epic.

## 📈 Performance & Limits

- **Response Time**: <200ms average for most operations
- **Rate Limiting**: Respects Epic's 120 requests/minute limit
- **Concurrent Operations**: Supports batch processing (Team+)
- **Data Throughput**: 1000+ patient records/minute (Starter+)
- **Token Management**: Automatic refresh, 1-hour expiration

## 💰 Pricing & Upgrades

### Starter - $199/year

✅ 2,000 API calls/day
✅ Production environments
✅ JSON export capabilities
✅ Email support
✅ Perfect for solo developers

### Professional - $499/year

✅ 5,000 API calls/day
✅ CSV export & batch processing
✅ Advanced features
✅ Priority email support
✅ Perfect for growing teams

### Team License - $999/year

✅ 10,000 API calls/day
✅ Up to 10 team members
✅ Team configuration sharing
✅ Advanced team features
✅ Priority email support
✅ Perfect for established teams

### Enterprise License - Custom

✅ Unlimited API calls  
✅ Unlimited team members  
✅ Advanced features (webhooks, audit)  
✅ 24/7 phone support + SLA  
✅ Custom integrations  
✅ Perfect for health systems

**[Purchase License →](https://ehrcli.com/pricing)**

## 🎯 Use Cases by License Tier

### 🔓 Trial Mode Use Cases

- **Learning Epic FHIR**: Understand Epic's API structure
- **Proof of Concept**: Validate integration approach
- **Demo Preparation**: Show Epic data in presentations
- **Student Projects**: Academic research and learning

### 👤 Starter Use Cases

- **Rapid Prototyping**: Build Epic integrations quickly
- **Freelance Projects**: Deliver client solutions faster
- **Startup MVP**: Get to market with Epic integration
- **Personal Projects**: Side projects and experimentation

### 🏢 Professional Use Cases

- **Growing Teams**: CSV export and batch processing
- **Agency Work**: Serve multiple healthcare clients
- **Data Analysis**: Export and analyze Epic data at scale
- **Advanced Features**: Enhanced integration capabilities

### 👥 Team License Use Cases

- **Established Teams**: Up to 10 team members
- **Product Development**: Build Epic-integrated products
- **Team Collaboration**: Share configurations and workflows
- **Scalable Operations**: High-volume API usage

### 🏢 Enterprise Use Cases

- **Health System Integration**: Connect Epic to internal systems
- **Population Health**: Analyze large patient datasets
- **Clinical Decision Support**: Build real-time clinical tools
- **Compliance Reporting**: Automated regulatory reporting

## 🚨 Troubleshooting

### License Issues

| Issue                   | Solution                             |
| ----------------------- | ------------------------------------ |
| `Invalid license key`   | Check key format and contact support |
| `License expired`       | Renew at https://ehrcli.com/pricing  |
| `Daily quota exceeded`  | Upgrade tier or wait for reset       |
| `Feature not available` | Check license tier requirements      |

### Common Issues

| Issue            | Solution                                       |
| ---------------- | ---------------------------------------------- |
| `invalid_client` | Upload public key to Epic Developer Portal     |
| `scope_denied`   | Enable required FHIR scopes in Epic app        |
| `404 Not Found`  | Check Epic environment (sandbox vs production) |
| `Token expired`  | Run `epic auth refresh`                        |

### Debug Commands

```bash
# Enable verbose logging
epic --debug patients search --family Smith

# Check configuration and license
epic config validate
epic license status

# Test with mock license
epic --mock-license starter auth test
```

## 📞 Support

### Community Support (Trial)

- **Documentation**: [Complete CLI Guide](https://docs.ehrcli.com)
- **GitHub**: [Issues and Discussions](https://github.com/securecloudnetworks/epic)
- **Examples**: [Real-world use cases](https://github.com/securecloudnetworks/epic-examples)

### Commercial Support

- **Starter/Professional/Team**: support@ehrcli.com
- **Enterprise**: enterprise@ehrcli.com (24/7 phone available)
- **Training**: [Professional training available](https://ehrcli.com/training)

## 🎉 Success Stories

> "Epic CLI saved us 4 months of development time. The licensing is transparent and the trial mode let us evaluate everything before purchasing."
> **— Sarah Chen, CTO, HealthTech Startup**

> "We upgraded to Team license for CSV exports and batch processing. Perfect for our agency serving multiple clinics."
> **— Dr. Michael Rodriguez, Chief Medical Officer**

## 🔗 Related Projects

- **[Epic CLI Examples](https://github.com/securecloudnetworks/epic-examples)** - Real-world Epic CLI examples
- **[FHIR Utils](https://github.com/securecloudnetworks/fhir-utils)** - FHIR R4 utilities and validators
- **[Healthcare Integration Toolkit](https://github.com/securecloudnetworks/healthcare-toolkit)** - Multi-vendor EHR integration tools

## 📄 License

This project is licensed under a Commercial License. See [LICENSE.md](LICENSE.md) for details.

For commercial licensing inquiries, contact [sales@ehrcli.com](mailto:sales@ehrcli.com).

## 🚀 Get Started Today

```bash
# 1. Install Epic CLI
npm install -g @securecloudnetworks/epic

# 2. Initialize with license (or run setup wizard)
epic init --license=YOUR-LICENSE-KEY

# 3. Start with 10 free API calls per day
epic patients search --family Lopez

# 4. Upgrade when ready for production
epic upgrade
```

**Ready to integrate with Epic EHR in 5 minutes?**

[**Download Epic CLI →**](https://ehrcli.com) | [**Purchase License →**](https://ehrcli.com/pricing) | [**Documentation →**](https://docs.ehrcli.com)

---

**Made with ❤️ by [SecureCloudNetworks](https://securecloudnetworks.com)**

_Epic CLI - Turning months of Epic integration work into minutes. Now with flexible licensing for every need._