hipaa-agent

Node.js/TypeScript SDK for HIPAA Agent — the autonomous AI HIPAA compliance officer for healthcare practices.

30 fully typed async methods covering scanning, grading, breach intelligence, compliance tracking, document generation, and more. Zero runtime dependencies (uses native fetch). Built-in retries with exponential backoff.

Installation

npm install hipaa-agent

Quick Start

import { HIPAAAgent } from 'hipaa-agent';

const agent = new HIPAAAgent({ apiKey: 'ha_live_...' });

// Get compliance grade
const score = await agent.getComplianceScore({ npi: '1234567890' });
console.log(`Grade: ${score.grade}, Score: ${score.numerical_score}`);

// Check breach history
const breach = await agent.getBreach({ npi: '1234567890' });
console.log(`Matched: ${breach.matched}, Breaches: ${breach.breaches.length}`);

// Look up a practice
const practice = await agent.lookupPractice({ npi: '1234567890' });
console.log(`Practice: ${practice.practice_name}`);

Authentication

Get your API key at hipaaagent.ai/developers. Keys use the format ha_live_* (production) or ha_test_* (sandbox).

const agent = new HIPAAAgent({
  apiKey: 'ha_live_...',
  baseUrl: 'https://hipaaagent.ai', // default
  timeout: 60_000,                   // ms, default 60000
  maxRetries: 3,                     // default 3
});

Methods

Scanning (4 methods)

// Launch a 73-tool HIPAA compliance scan (150 credits)
const scan = await agent.scan({ npi: '1234567890' });

// Check scan status (25 credits)
const status = await agent.getScanStatus({ npi: '1234567890' });

// Get HIPAA Agent Compliance Score across 10 categories (25 credits)
const score = await agent.getComplianceScore({ npi: '1234567890' });

// Batch scan multiple practices, max 50 (150 credits each)
const batch = await agent.batchScan({
  practices: [
    { npi: '1234567890' },
    { npi: '0987654321', domain: 'example.com' },
  ]
});

Reports & Evidence (3 methods)

// Full findings report with HIPAA citations (25 credits)
const report = await agent.getReport({ npi: '1234567890' });

// SHA-256 hash chain audit trail (25 credits)
const auditLog = await agent.getAuditLog({ npi: '1234567890' });

// 10-component evidence package (25 credits)
const evidence = await agent.getEvidencePackage({ npi: '1234567890' });

Documents (3 methods)

// Generate a Business Associate Agreement (25 credits)
const baa = await agent.generateBaa({
  npi: '1234567890',
  vendor_name: 'Cloud EHR Inc',
  services_description: 'Cloud-hosted EHR platform',
});

// Get HIPAA policy documents (25 credits)
const policies = await agent.getPolicies({ npi: '1234567890' });

// Generate Security Risk Assessment (500 credits)
const sra = await agent.generateSra({
  npi: '1234567890',
  respondent_email: '[email protected]',
  respondent_name: 'Jane Smith',
});

Breach Intelligence (3 methods)

// HHS breach history lookup (25 credits)
const breach = await agent.getBreach({ npi: '1234567890' });

// Breach risk score (25 credits)
const breachScore = await agent.getBreachScore({ npi: '1234567890' });

// 12-month breach probability forecast (25 credits)
const probability = await agent.getBreachProbability({ npi: '1234567890' });

Internal Network (3 methods)

// Deploy internal network scanner (25 credits)
const internal = await agent.triggerInternalScan({ npi: '1234567890' });

// Check agent deployment status (25 credits)
const agentStatus = await agent.getInternalScanStatus({ npi: '1234567890' });

// Get internal scan findings (25 credits)
const findings = await agent.getInternalFindings({ npi: '1234567890' });

Practice Info (3 methods)

// NPPES lookup + scan data (25 credits)
const practice = await agent.lookupPractice({ npi: '1234567890' });

// Outreach/drip campaign status (25 credits)
const outreach = await agent.getOutreachStatus({ npi: '1234567890' });

// Comprehensive practice summary (25 credits)
const summary = await agent.getPracticeSummary({ npi: '1234567890' });

Platform (4 methods)

// Staff training status (25 credits)
const training = await agent.getTrainingStatus({ npi: '1234567890' });

// Vendor BAA records (25 credits)
const baas = await agent.getVendorBaaList({ npi: '1234567890' });

// Log a security incident (25 credits)
const incident = await agent.logIncident({
  npi: '1234567890',
  incident_type: 'phishing',
  description: 'Staff member received phishing email',
  severity: 'medium',
});

// Incident history (25 credits)
const incidents = await agent.getIncidents({ npi: '1234567890' });

Controls & Compliance (4 methods)

// 13 HIPAA/NIST control signals (25 credits)
const controls = await agent.getControls({ npi: '1234567890' });
console.log(`${controls.passed}/${controls.total_controls} controls passing`);

// Validate a data transfer workflow (25 credits)
const validation = await agent.validateWorkflow({
  workflow_type: 'data_transfer',
  data_type: 'phi',
  destination: 'cloud_us',
  controls_applied: ['encryption_in_transit', 'baa'],
});

// Compliance state machine — May 2026 deadline (25 credits)
const state = await agent.getComplianceState({ npi: '1234567890' });
console.log(`State: ${state.state}, ${state.completed}/${state.total} complete`);

// Compliance change detection (25 credits)
const delta = await agent.getComplianceDelta({
  npi: '1234567890',
  since: '2026-01-01',
});

Vendor Risk (1 method)

// Vendor risk graph — breach history + BAA coverage (25 credits)
const vendor = await agent.checkVendor({ vendor_name: 'Cloud EHR Inc' });
console.log(`Risk: ${vendor.risk_score}, BAA: ${vendor.baa_coverage}`);

Webhooks (2 methods)

// Register webhook for compliance events (25 credits)
const webhook = await agent.subscribeWebhook({
  npi: '1234567890',
  url: 'https://your-app.com/webhooks/hipaa',
  events: ['scan_completed', 'score_dropped', 'breach_detected'],
});
console.log(`Secret: ${webhook.secret}`); // Use for HMAC-SHA256 verification

// List active webhooks (25 credits)
const webhooks = await agent.listWebhooks({ npi: '1234567890' });

Error Handling

import { HIPAAAgent, HIPAAAgentError } from 'hipaa-agent';

try {
  const result = await agent.scan({ npi: '1234567890' });
} catch (err) {
  if (err instanceof HIPAAAgentError) {
    console.error(`Error ${err.code}: ${err.message}`);
    // err.code — HTTP status or JSON-RPC error code
    // err.details — additional context from the API
  }
}

Retry Behavior

The client automatically retries on transient failures:

• Retryable status codes: 429, 500, 502, 503
• Backoff schedule: 1s, 2s, 4s (exponential)
• Max retries: 3 (configurable)
• Non-retryable: 401, 403, 404, 400 (fail immediately)
• Network errors: Retried automatically

Type Exports

Every parameter and result type is exported for full TypeScript support:

import type {
  ScanPracticeParams,
  GetComplianceScoreResult,
  ReportFinding,
  Control,
  WebhookSubscription,
  // ... 60+ types available
} from 'hipaa-agent';

Requirements

• Node.js 18+ (native fetch required)
• TypeScript 5.0+ (for type definitions)
• Zero runtime dependencies

Links

• Documentation
• API Reference
• Get API Key

License

MIT