技能 编程开发 Exa.js SDK升级与迁移指南

Exa.js SDK升级与迁移指南

v20260423
exa-upgrade-migration
本指南提供了一个结构化的流程,用于安全升级`exa-js` SDK。它详细介绍了如何检查当前和最新版本,处理潜在的重大变化,并验证API的兼容性(如搜索和内容抓取)。遵循这些步骤,可确保SDK的平稳可靠迁移。
获取技能
405 次下载
概览

Exa Upgrade & Migration

Current State

!npm list exa-js 2>/dev/null | grep exa-js || echo 'exa-js not installed'
!npm view exa-js version 2>/dev/null || echo 'cannot check latest'

Overview

Guide for upgrading the exa-js SDK. The SDK import is import Exa from "exa-js" and the client is instantiated with new Exa(apiKey). This skill covers checking for updates, handling breaking changes, and validating after upgrade.

Instructions

Step 1: Check Current vs Latest Version

set -euo pipefail
echo "Current version:"
npm list exa-js 2>/dev/null || echo "Not installed"

echo ""
echo "Latest available:"
npm view exa-js version

echo ""
echo "Changelog:"
npm view exa-js repository.url

Step 2: Create Upgrade Branch

set -euo pipefail
git checkout -b upgrade/exa-js-latest
npm install exa-js@latest
npm test

Step 3: Verify API Compatibility

import Exa from "exa-js";

async function verifyUpgrade() {
  const exa = new Exa(process.env.EXA_API_KEY);
  const checks = [];

  // Check 1: Basic search
  try {
    const r = await exa.search("upgrade test", { numResults: 1 });
    checks.push({ method: "search", status: "OK", results: r.results.length });
  } catch (err: any) {
    checks.push({ method: "search", status: "FAIL", error: err.message });
  }

  // Check 2: searchAndContents
  try {
    const r = await exa.searchAndContents("upgrade test", {
      numResults: 1,
      text: { maxCharacters: 100 },
      highlights: { maxCharacters: 100 },
    });
    checks.push({
      method: "searchAndContents",
      status: "OK",
      hasText: !!r.results[0]?.text,
      hasHighlights: !!r.results[0]?.highlights,
    });
  } catch (err: any) {
    checks.push({ method: "searchAndContents", status: "FAIL", error: err.message });
  }

  // Check 3: findSimilar
  try {
    const r = await exa.findSimilar("https://nodejs.org", { numResults: 1 });
    checks.push({ method: "findSimilar", status: "OK", results: r.results.length });
  } catch (err: any) {
    checks.push({ method: "findSimilar", status: "FAIL", error: err.message });
  }

  // Check 4: getContents
  try {
    const r = await exa.getContents(["https://nodejs.org"], { text: true });
    checks.push({ method: "getContents", status: "OK", hasContent: !!r.results[0]?.text });
  } catch (err: any) {
    checks.push({ method: "getContents", status: "FAIL", error: err.message });
  }

  console.table(checks);
  const allPassed = checks.every(c => c.status === "OK");
  console.log(`\nUpgrade verification: ${allPassed ? "PASSED" : "FAILED"}`);
  return allPassed;
}

Step 4: Common Breaking Change Patterns

// Import style (has been stable)
import Exa from "exa-js";  // default export

// Constructor (has been stable)
const exa = new Exa("api-key");

// If upgrading from a very old version, check:
// - Method names: searchAndContents (not searchWithContents)
// - findSimilarAndContents (not findSimilarWithContents)
// - Parameter names: numResults (not num_results)
// - Content options: text, highlights, summary as objects

// Check for deprecated parameters
// - livecrawl may be replaced by maxAgeHours in newer versions
// - Check changelog for parameter renames

Step 5: Rollback Procedure

set -euo pipefail
# If tests fail, rollback
npm install exa-js@<previous-version> --save-exact
git checkout -- package-lock.json  # restore lockfile
npm test  # verify rollback works

Upgrade Checklist

  • [ ] Create branch: upgrade/exa-js-latest
  • [ ] Run npm install exa-js@latest
  • [ ] Run full test suite: npm test
  • [ ] Run upgrade verification script (checks all methods)
  • [ ] Check for deprecation warnings in output
  • [ ] Review changelog for breaking changes
  • [ ] Update any changed parameter names
  • [ ] Merge after all checks pass

Error Handling

IssueCauseSolution
Import error after upgradeAPI changeCheck import Exa from "exa-js" still works
Method not foundRenamed methodCheck SDK changelog
Type errorsParameter type changesUpdate TypeScript types
Tests failBreaking changeReview changelog, update code

Resources

Next Steps

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

信息
分类 编程开发
名称 exa-upgrade-migration
版本 v20260423
大小 4.9KB
更新时间 2026-04-28
语言