Skip to content

SDK_UPDATE_SUMMARY.md

Latest commit

 

History

History
192 lines (141 loc) · 4.39 KB

SDK_UPDATE_SUMMARY.md

File metadata and controls

192 lines (141 loc) · 4.39 KB
Raw

SDK Update Summary - Content API Migration

✅ Changes Complete

Successfully updated @better-i18n/sdk to use the new dedicated Content API endpoint.

Files Modified

1. packages/sdk/src/client.ts

- const DEFAULT_API_BASE = "https://dash.better-i18n.com";
+ const DEFAULT_API_BASE = "https://content.better-i18n.com";

2. packages/sdk/src/content-api.ts

- const base = `${apiBase}/api/v1/content/${org}/${project}`;
+ const base = `${apiBase}/v1/content/${org}/${project}`;

3. .changeset/migrate-to-dedicated-api.md

  • Created changeset for major version bump (v0.4.0 → v1.0.0)
  • Comprehensive migration guide
  • Backward compatibility notes

Version Bump

Current: @better-i18n/sdk@0.4.0 Next: @better-i18n/sdk@1.0.0 (major - breaking change)

Breaking Changes

Default API Endpoint Changed

Before:

https://dash.better-i18n.com/api/v1/content/{org}/{project}/models

After:

https://content.better-i18n.com/v1/content/{org}/{project}/models

Impact

  • ✅ Users without custom apiBase → Automatically use new endpoint
  • ⚠️ Users with custom apiBase → Need to update to new URL
  • ✅ Old endpoint remains operational during transition

Benefits Delivered

  1. CORS Fixed - Wildcard origin for public access
  2. Better Performance - CDN caching (60s + 1h stale-while-revalidate)
  3. Clean URLs - Professional API domain
  4. Independent Scaling - Dedicated infrastructure

Next Steps

1. Publish New Version

cd ../better-i18n-oss

# Version and publish
bunx changeset version  # Updates version to 1.0.0
bun install             # Update lockfile
git add .
git commit -m "chore: release @better-i18n/sdk@1.0.0"
bunx changeset publish  # Publish to npm
git push --follow-tags

2. Update Documentation

  • Update SDK docs with new endpoint
  • Add migration guide to docs
  • Update examples and code samples

3. Notify Users

  • Announce v1.0.0 release
  • Share migration guide
  • Set deprecation timeline for old endpoint

Migration Guide for Users

Automatic (Recommended)

Most users don't specify apiBase, so they'll automatically use the new endpoint:

// Just update to v1.0.0 - no code changes needed
const client = createClient({
  project: "acme/web-app",
  apiKey: "bi18n_...",
});

Manual (Custom apiBase)

If you've customized the API base URL:

// Update from:
const client = createClient({
  project: "acme/web-app",
  apiKey: "bi18n_...",
  apiBase: "https://dash.better-i18n.com", // Old
});

// To:
const client = createClient({
  project: "acme/web-app",
  apiKey: "bi18n_...",
  apiBase: "https://content.better-i18n.com", // New
});

Temporary Rollback

If you need to stay on the old endpoint temporarily:

// Pin to v0.4.0 in package.json
{
  "dependencies": {
    "@better-i18n/sdk": "0.4.0"
  }
}

// Or override apiBase
const client = createClient({
  project: "acme/web-app",
  apiKey: "bi18n_...",
  apiBase: "https://dash.better-i18n.com",
});

Verification

Type Check

✅ bun run typecheck - PASSED

Changes Summary

  • 2 files modified (client.ts, content-api.ts)
  • 1 changeset created (major version bump)
  • 4 lines changed total
  • Zero breaking API changes (only endpoint URL)

Compatibility Matrix

SDK Version API Endpoint CORS Cache Status
v0.4.0 dash.better-i18n.com/api/v1/content ❌ ❌ Old
v1.0.0 content.better-i18n.com/v1/content ✅ ✅ New

Timeline

Week 1-2 (Current):

  • ✅ Deploy new Content API worker
  • ✅ Update SDK to v1.0.0
  • ✅ Publish to npm

Week 3-4:

  • Monitor adoption
  • Track error rates
  • Gather feedback

Month 2-3:

  • Add deprecation warning to old endpoint
  • Email remaining users on old endpoint

Month 4:

  • Redirect old → new (301)
  • Remove old REST routes

Success Metrics

  • ✅ SDK Updated: Default endpoint changed
  • ✅ Type Safety: Zero type errors
  • ✅ Changeset Created: Semantic versioning
  • ✅ Migration Guide: Comprehensive documentation
  • ✅ Backward Compatible: Old endpoint still works

Conclusion

SDK successfully migrated to the new dedicated Content API. Version bump to v1.0.0 reflects the breaking change in default endpoint. Users can upgrade seamlessly with automatic endpoint migration.

Ready for npm publish! 🚀