Package Exports

@arionhardison/wizard-api-client

Readme

Five-Step Wizard TypeScript Client

A comprehensive TypeScript client library for the Five-Step Wizard API, providing type-safe access to the wizard endpoints with support for asynchronous processing and real-time updates.

Features

✅ Complete TypeScript definitions for all wizard models and endpoints
✅ Support for asynchronous processing with job progress tracking
✅ WebSocket-based real-time updates for long-running operations
✅ Full versioning and snapshot system for deal objects
✅ Built-in authentication and token management
✅ Comprehensive error handling
✅ Supports browser environments
✅ Vue integration with example components

Installation

npm install @wizard/api-client

Quick Start

import { wizardApiClient, wizardSteps } from '@wizard/api-client';

// Start a new wizard
async function startWizard(problem: string, category: string) {
  try {
    const response = await wizardApiClient.startWizard({
      problem,
      category,
      metadata: {
        user_role: 'patient',
        session_id: 'abc123'
      }
    });
    
    if (response.data.success) {
      console.log('Wizard started successfully!');
      console.log('Deal ID:', response.data.data.deal.id);
      
      // Check if processing is asynchronous
      if (response.data.data.is_async) {
        console.log('Job ID:', response.data.data.job_id);
        
        // Poll for job completion
        const jobStatus = await wizardApiClient.pollJobStatus(response.data.data.job_id);
        console.log('Job completed:', jobStatus);
        
        // Get the updated deal
        const dealResponse = await wizardApiClient.getDeal(response.data.data.deal.id);
        console.log('Updated deal:', dealResponse.data.data);
      } else {
        console.log('Deal:', response.data.data.deal);
      }
    } else {
      console.error('Failed to start wizard:', response.data.message);
    }
  } catch (error) {
    console.error('API error:', error);
  }
}

Step Processing with Type-Safe Handlers

The client provides type-safe step handlers for each wizard step:

import { wizardSteps, WizardStep } from '@wizard/api-client';

// Process Step 1: Define Problem
async function processStep1(dealId: string, problem: string, category: string) {
  try {
    // Monitor progress
    const deal = await wizardSteps.defineProblems.process(
      dealId,
      {
        problem,
        category,
        sub_category: 'Autoimmune'
      },
      (progress) => {
        console.log(`Processing: ${progress}%`);
      }
    );
    
    console.log('Step 1 completed:', deal);
    return deal;
  } catch (error) {
    console.error('Error processing step 1:', error);
  }
}

// Process Step 2: Codify Solution
async function processStep2(dealId: string, solutions: any[]) {
  try {
    const deal = await wizardSteps.codifySolution.process(
      dealId,
      {
        solution_options: solutions,
        selected_solution: 0
      },
      (progress) => {
        console.log(`Processing: ${progress}%`);
      }
    );
    
    console.log('Step 2 completed:', deal);
    return deal;
  } catch (error) {
    console.error('Error processing step 2:', error);
  }
}

Real-Time Updates with WebSockets

The client supports WebSocket-based real-time updates for job progress:

// Add a listener for job updates
const removeListener = wizardApiClient.addJobListener(
  jobId,
  (jobStatus) => {
    console.log('Job progress:', jobStatus.progress);
    console.log('Job status:', jobStatus.status);
    console.log('Job message:', jobStatus.message);
    
    if (jobStatus.status === 'completed') {
      console.log('Job completed successfully!');
    } else if (jobStatus.status === 'failed') {
      console.error('Job failed:', jobStatus.error);
    }
  }
);

// Later, remove the listener when no longer needed
removeListener();

Version Management

The client provides full support for the versioning system:

// Get all snapshots for a deal
const snapshotsResponse = await wizardApiClient.getDealSnapshots(dealId);
const snapshots = snapshotsResponse.data.data;

// Get a specific snapshot
const snapshotResponse = await wizardApiClient.getDealSnapshot(dealId, version);
const snapshot = snapshotResponse.data.data;

// Compare two snapshots
const comparisonResponse = await wizardApiClient.compareDealSnapshots(
  dealId,
  baseVersion,
  compareVersion
);
const differences = comparisonResponse.data.data.differences;

// Restore a deal to a specific version
const restoredResponse = await wizardApiClient.restoreDealSnapshot(dealId, version);
const restoredDeal = restoredResponse.data.data;

// Create a new snapshot manually
const newSnapshotResponse = await wizardApiClient.createDealSnapshot(
  dealId,
  "Manual checkpoint before changes"
);

Vue Integration

The client comes with a complete Vue component example:

// Import the wizard Vue component
import WizardExample from '@wizard/api-client/examples/wizard-example.vue';

// Use it in your Vue app
<template>
  <WizardExample />
</template>

Full API Reference

Wizard API Client Methods

Method	Description
`startWizard(data)`	Start a new wizard session
`defineProblems(dealId, data)`	Process Step 1: Define Problem
`codifySolution(dealId, data)`	Process Step 2: Codify Solution
`setupProgram(dealId, data)`	Process Step 3: Setup Program
`executeProgram(dealId, data)`	Process Step 4: Execute Program
`verifyOutcome(dealId, data)`	Process Step 5: Verify Outcome
`getJobStatus(jobId)`	Get the status of a job
`pollJobStatus(jobId, interval, timeout)`	Poll for job completion
`getDeal(dealId)`	Get a deal by ID
`getDealSnapshots(dealId)`	Get all snapshots for a deal
`getDealSnapshot(dealId, version)`	Get a specific snapshot
`compareDealSnapshots(dealId, baseVersion, compareVersion)`	Compare two snapshots
`restoreDealSnapshot(dealId, version)`	Restore a deal to a specific version
`createDealSnapshot(dealId, comment)`	Create a new snapshot manually
`getWizardResponse(dealId)`	Get the complete wizard response
`addJobListener(jobId, listener)`	Add a listener for job updates

Type-Safe Step Handlers

Handler	Description
`wizardSteps.defineProblems`	Handler for Step 1: Define Problem
`wizardSteps.codifySolution`	Handler for Step 2: Codify Solution
`wizardSteps.setupProgram`	Handler for Step 3: Setup Program
`wizardSteps.executeProgram`	Handler for Step 4: Execute Program
`wizardSteps.verifyOutcome`	Handler for Step 5: Verify Outcome

Main Data Types

Type	Description
`DealData`	Core deal data structure
`ProgramData`	Program data structure
`ProtocolData`	Protocol data structure
`DealSnapshotData`	Deal snapshot data
`JobStatusData`	Job status data
`StepResultData`	Step processing result
`VersionComparisonData`	Snapshot comparison data

Enums

Enum	Description
`WizardStep`	Wizard step identifiers
`FeasibilityRating`	Solution feasibility ratings
`PayoutStatus`	Payout status options
`JobStatus`	Job processing status

Advanced Configuration

You can create custom client instances with specific configurations:

import { WizardApiClient } from '@wizard/api-client';

// Create a custom client
const customClient = new WizardApiClient({
  baseURL: 'https://custom-api.example.com/api',
  timeout: 60000, // 60 seconds
  withCredentials: true,
  headers: {
    'X-Custom-Header': 'value'
  }
});

Error Handling

The client provides consistent error handling:

try {
  const response = await wizardApiClient.getDeal('non-existent-id');
  // Process successful response
} catch (error) {
  if (error.response) {
    // Server returned an error response
    console.error('API Error:', error.response.data.message);
    
    // Handle validation errors
    if (error.response.status === 422 && error.response.data.errors) {
      Object.entries(error.response.data.errors).forEach(([field, messages]) => {
        console.error(`${field}: ${messages.join(', ')}`);
      });
    }
  } else if (error.request) {
    // Request was made but no response received (network error)
    console.error('Network error: No response received');
  } else {
    // Other errors
    console.error('Error:', error.message);
  }
}

Development

Building the client

npm run build

Running tests

npm test

HMS API Client

This package also includes the HMS API client for accessing other HMS API endpoints:

import { hmsApiClient } from '@wizard/api-client';

// Use the HMS API client
const response = await hmsApiClient.auth.login({
  email: 'user@example.com',
  password: 'password123'
});

For more information on the HMS API client, see the previous documentation.

Publishing

This package is published to GitHub Packages as @arionhardison/wizard-api-client.

Trigger

Publishes are driven by .github/workflows/publish.yml and fire on either:

A tag push matching v*.*.* (the canonical path)
workflow_dispatch — manual ad-hoc rerun via the Actions tab

The workflow runs npm ci, npm run test, npm run build, then publishes to https://npm.pkg.github.com using the built-in GITHUB_TOKEN — no extra secrets to configure on the repo.

Cutting a release

# 1. Bump the version in package.json (semver: patch / minor / major).
#    Edit "version" in package.json directly, or:
npm version patch --no-git-tag-version

# 2. Commit the bump.
git add package.json package-lock.json
git commit -m "release: vX.Y.Z"

# 3. Tag and push.
git tag vX.Y.Z
git push origin main --tags

The tag push triggers the workflow; on success the new version appears at https://github.com/ArionHardison/HMS-API-client/packages.

Consuming the package

GitHub Packages requires authenticated reads. Consumers need:

An .npmrc (project-level or ~/.npmrc) routing the scope to GH Packages:

@arionhardison:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

An NPM_TOKEN env var holding a GitHub Personal Access Token (classic) with the read:packages scope. In CI/CD, inject it via the platform's secret store. Inside GitHub Actions in the same org, secrets.GITHUB_TOKEN is sufficient; for cross-org or Vercel deployments, set NPM_TOKEN as a project env var.

Then:

npm install @arionhardison/wizard-api-client

License

MIT