Juicebox Upgrade Migration

Overview

Plan and execute safe Juicebox SDK version upgrades with minimal disruption.

Prerequisites

• Current SDK version identified
• Changelog reviewed
• Test environment available

Instructions

Step 1: Assess Current State

# Check current SDK version
npm list @juicebox/sdk

# Check for available updates
npm outdated @juicebox/sdk

# Review changelog
curl -s https://api.github.com/repos/juicebox-ai/sdk-js/releases/latest | jq '.body'

Step 2: Review Breaking Changes

// Common breaking changes between versions

// v1.x -> v2.x Migration
// OLD (v1.x)
const client = new JuiceboxClient(apiKey);
const results = await client.search(query);

// NEW (v2.x)
const client = new JuiceboxClient({ apiKey });
const results = await client.search.people({ query });

Step 3: Create Migration Script

// scripts/migrate-juicebox.ts

/**
 * Migration: v1.x -> v2.x
 *
 * Breaking changes:
 * 1. Client constructor now takes options object
 * 2. search() renamed to search.people()
 * 3. Result structure changed
 */

// Step 1: Update imports
// OLD: import JuiceboxClient from '@juicebox/sdk';
// NEW: import { JuiceboxClient } from '@juicebox/sdk';

// Step 2: Update client initialization
function migrateClientInit(code: string): string {
  return code.replace(
    /new JuiceboxClient\((\w+)\)/g,
    'new JuiceboxClient({ apiKey: $1 })'
  );
}

// Step 3: Update method calls
function migrateSearchCalls(code: string): string {
  return code.replace(
    /client\.search\(([^)]+)\)/g,
    'client.search.people({ query: $1 })'
  );
}

// Step 4: Update result handling
function migrateResultAccess(code: string): string {
  return code.replace(
    /results\.data/g,
    'results.profiles'
  );
}

Step 4: Staged Rollout

// lib/feature-flags.ts
export class JuiceboxVersionManager {
  private useNewVersion: boolean;

  constructor() {
    this.useNewVersion = process.env.JUICEBOX_USE_V2 === 'true';
  }

  async search(query: string, options?: SearchOptions) {
    if (this.useNewVersion) {
      return this.searchV2(query, options);
    }
    return this.searchV1(query, options);
  }

  private async searchV1(query: string, options?: SearchOptions) {
    // Legacy implementation
  }

  private async searchV2(query: string, options?: SearchOptions) {
    // New implementation
  }
}

Step 5: Validation Testing

// tests/migration.test.ts
import { describe, it, expect } from 'vitest';

describe('Migration Validation', () => {
  it('produces equivalent results with new SDK', async () => {
    const query = 'software engineer San Francisco';

    const oldResults = await legacyClient.search(query);
    const newResults = await newClient.search.people({ query });

    // Verify structure matches
    expect(newResults.profiles.length).toBe(oldResults.data.length);

    // Verify data matches
    expect(newResults.profiles[0].name).toBe(oldResults.data[0].name);
  });

  it('handles edge cases correctly', async () => {
    // Test empty results
    // Test error handling
    // Test pagination
  });
});

Migration Checklist

## SDK Upgrade Checklist

### Pre-Migration
- [ ] Current version documented
- [ ] Target version identified
- [ ] Changelog reviewed
- [ ] Breaking changes listed
- [ ] Migration script created

### Testing
- [ ] Unit tests updated
- [ ] Integration tests pass
- [ ] Performance benchmarks run
- [ ] Edge cases validated

### Deployment
- [ ] Staged rollout plan
- [ ] Feature flag configured
- [ ] Monitoring in place
- [ ] Rollback plan ready

### Post-Migration
- [ ] Old code removed
- [ ] Feature flag cleaned up
- [ ] Documentation updated
- [ ] Team notified

Rollback Plan

# Immediate rollback if issues detected
npm install @juicebox/sdk@1.x.x

# Or use feature flag
export JUICEBOX_USE_V2=false

Resources

• SDK Changelog
• Migration Guides

Next Steps

After upgrade, verify with juicebox-prod-checklist for production readiness.