speak-upgrade-migration

Speak Upgrade & Migration

Overview

Guide for upgrading Speak SDK versions and handling breaking changes in language learning integrations.

Prerequisites

• Current Speak SDK installed
• Git for version control
• Test suite available
• Staging environment

Instructions

Step 1: Check Current Version

# Check installed version
npm list @speak/language-sdk

# Check latest available version
npm view @speak/language-sdk version

# Check for updates
npm outdated @speak/language-sdk

Step 2: Review Changelog

# Open changelog
open https://github.com/speak/language-sdk/releases

# Or check locally if available
cat node_modules/@speak/language-sdk/CHANGELOG.md

Step 3: Create Upgrade Branch

git checkout -b upgrade/speak-sdk-vX.Y.Z

# Install new version
npm install @speak/language-sdk@latest

# Run tests
npm test

Step 4: Handle Common Breaking Changes

SDK Version History

Import Changes (v1 to v2)

// Before (v1.x)
import { Client, Lesson } from 'speak-sdk';
const client = new Client({ key: 'xxx' });

// After (v2.x)
import { SpeakClient, LessonSession } from '@speak/language-sdk';
const client = new SpeakClient({
  apiKey: 'xxx',
  appId: 'app_xxx',
});

Session API Changes (v2 to v3)

// Before (v2.x) - Promise-based
const session = await tutor.startLesson({ topic: 'greetings' });
const feedback = await session.submitResponse({ text: 'Hola' });

// After (v3.x) - Real-time streams
const session = tutor.createLessonStream({ topic: 'greetings' });
session.on('prompt', (prompt) => console.log(prompt));
session.on('feedback', (feedback) => console.log(feedback));
await session.send({ text: 'Hola', audio: audioBuffer });

Speech Recognition Changes

// Before (v2.x)
const result = await client.speech.recognize(audioBuffer);

// After (v3.x) - Streaming recognition
const recognizer = client.speech.createRecognizer({
  language: 'es',
  continuous: true,
});
recognizer.on('result', (result) => {
  console.log('Partial:', result.partial);
  console.log('Final:', result.final);
});
recognizer.start(audioStream);

Step 5: Migration Script

// scripts/migrate-speak-v3.ts
import { readdir, readFile, writeFile } from 'fs/promises';
import { join } from 'path';

const MIGRATIONS = [
  {
    pattern: /from 'speak-sdk'/g,
    replacement: "from '@speak/language-sdk'",
    description: 'Update import path',
  },
  {
    pattern: /new Client\(/g,
    replacement: 'new SpeakClient(',
    description: 'Rename Client to SpeakClient',
  },
  {
    pattern: /{ key:/g,
    replacement: '{ apiKey:',
    description: 'Rename key to apiKey',
  },
  {
    pattern: /\.startLesson\(/g,
    replacement: '.createLessonStream(',
    description: 'Update to streaming API',
  },
];

async function migrateFile(filePath: string): Promise<void> {
  let content = await readFile(filePath, 'utf-8');
  let modified = false;

  for (const migration of MIGRATIONS) {
    if (migration.pattern.test(content)) {
      console.log(`  Applying: ${migration.description}`);
      content = content.replace(migration.pattern, migration.replacement);
      modified = true;
    }
  }

  if (modified) {
    await writeFile(filePath, content);
    console.log(`  ✓ Updated: ${filePath}`);
  }
}

async function migrateProject(dir: string): Promise<void> {
  const files = await readdir(dir, { withFileTypes: true, recursive: true });

  for (const file of files) {
    if (file.isFile() && /\.(ts|tsx|js|jsx)$/.test(file.name)) {
      const filePath = join(file.parentPath, file.name);
      await migrateFile(filePath);
    }
  }
}

migrateProject('./src');

Step 6: Update Type Definitions

// types/speak-v3.d.ts

// Old types that changed
interface LegacySession {
  submitResponse(response: { text: string }): Promise<Feedback>;
}

// New streaming types
interface LessonStream {
  on(event: 'prompt', callback: (prompt: TutorPrompt) => void): void;
  on(event: 'feedback', callback: (feedback: Feedback) => void): void;
  on(event: 'error', callback: (error: SpeakError) => void): void;
  send(input: LessonInput): Promise<void>;
  close(): Promise<SessionSummary>;
}

// Adapter for gradual migration
class SessionAdapter {
  private stream: LessonStream;
  private feedbackPromise: Promise<Feedback> | null = null;

  constructor(stream: LessonStream) {
    this.stream = stream;
  }

  // Provide v2-style API on top of v3 streams
  async submitResponse(response: { text: string }): Promise<Feedback> {
    return new Promise((resolve, reject) => {
      this.stream.on('feedback', resolve);
      this.stream.on('error', reject);
      this.stream.send(response);
    });
  }
}

Deprecation Handling

// Monitor for deprecation warnings
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning' && warning.message.includes('speak')) {
      console.warn('[Speak SDK]', warning.message);

      // Log to tracking for proactive updates
      trackDeprecation({
        message: warning.message,
        stack: warning.stack,
        version: process.env.SPEAK_SDK_VERSION,
      });
    }
  });
}

// Graceful handling of deprecated features
async function getLesson(config: LessonConfig) {
  const client = getSpeakClient();

  // Check if using deprecated API
  if ('startLesson' in client.tutor) {
    console.warn('Using deprecated startLesson API. Update to createLessonStream.');
    // @ts-ignore - Deprecated but still works
    return await client.tutor.startLesson(config);
  }

  // New API
  return client.tutor.createLessonStream(config);
}

Rollback Procedure

# If upgrade fails, rollback to previous version
npm install @speak/language-sdk@2.x.x --save-exact

# Verify rollback
npm list @speak/language-sdk
npm test

Testing Upgrade in Staging

# Create feature flag for gradual rollout
export SPEAK_SDK_VERSION=3.x

# Deploy to staging
npm run deploy:staging

# Run comprehensive tests
npm run test:integration
npm run test:e2e

# Monitor for 24 hours
# Check:
# - Speech recognition accuracy
# - Lesson completion rates
# - Error rates
# - Latency metrics

Output

• Updated SDK version
• Fixed breaking changes
• Passing test suite
• Documented rollback procedure

Error Handling

Resources

• Speak Changelog
• Speak Migration Guide
• Speak API Versioning

Next Steps

For CI integration during upgrades, see speak-ci-integration.