@securecloudnetworks/epic-cli

v1.0.14

Published

2 months ago

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

0High
0Medium
0Low

ehradapter

epic ehr fhir healthcare cli jwt authentication medical integration

Epic CLI - Professional Epic EHR Integration Tool

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

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

🚀 Quick Start

# 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)
5 minutes of your time

Installation

npm install -g @securecloudnetworks/epic

Quick Setup Options

Option 1: Initialize with License

epic init --license=YOUR-LICENSE-KEY

Option 2: Environment Variables

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

epic setup

The setup wizard will guide you through:

Epic app configuration (Client ID, environment)
RSA key pair generation (automatic 2048-bit keys)
X.509 certificate creation (RFC 5280 compliant for Epic)
Certificate upload instructions (step-by-step Epic Developer Portal guide)
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:

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

{
  "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

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

# 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

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

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

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

# 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+)

# 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

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

💻 Real-World Examples

Trial Mode (Free)

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

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

Starter License

# 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

# 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

# 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

# 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

$ 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: [email protected]

Patient Search with License Display

$ 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

$ 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

$ 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:

# 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

# 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

# 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

# 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

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

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 →

🎯 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

# 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
GitHub: Issues and Discussions
Examples: Real-world use cases

Commercial Support

Starter/Professional/Team: [email protected]
Enterprise: [email protected] (24/7 phone available)
Training: Professional training available

🎉 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 - Real-world Epic CLI examples
FHIR Utils - FHIR R4 utilities and validators
Healthcare Integration Toolkit - Multi-vendor EHR integration tools

📄 License

This project is licensed under a Commercial License. See LICENSE.md for details.

For commercial licensing inquiries, contact [email protected].

🚀 Get Started Today

# 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 → | Purchase License → | Documentation →

Made with ❤️ by SecureCloudNetworks

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