Migration Guide

Move your integration from Q-Core v1.x to v2.0. This guide covers breaking changes, new features, and step-by-step instructions to ensure a smooth transition.

Overview

Q-Core v2.0 introduces significant improvements in performance, security, and developer experience. While we have minimized breaking changes, several structural updates require attention to your codebase.

Prerequisites

• Ensure you are running Node.js 18+ or compatible runtime.
• Back up your current configuration and database.
• Review the Changelog for the complete list of changes.

Step-by-Step Migration

1. Update Dependencies

Remove the old SDK and install the new v2.0 package.

bashCopy
# Uninstall v1
npm uninstall @that-is-a-q/core

# Install v2
npm install @that-is-a-q/core@2.0.0
                    

2. Update Initialization

The client initialization has moved to an async factory pattern for better error handling and credential validation.

javascriptCopy
// ❌ Old Way (v1.x)
const client = new QClient({
  apiKey: process.env.Q_API_KEY
});

// ✅ New Way (v2.0)
const client = await QClient.create({
  credentials: {
    apiKey: process.env.Q_API_KEY,
    // Optional: Region hint for lower latency
    region: 'us-east-1' 
  }
});
                    

3. Refactor API Calls

Method signatures have been standardized. All methods now return a unified QResponse object.

javascriptCopy
// ❌ Old Way
const data = await client.data.fetch(id);

// ✅ New Way
const response = await client.resources.get({
  id,
  options: { expand: ['metadata', 'relations'] }
});

if (response.ok) {
  const { data } = response;
  console.log(data);
}
                    

4. Handle Authentication Changes

API Keys are now rotated automatically if you use the managed secret store. If you are managing keys manually, update your environment variables to use the new Q_CREDENTIALS format.

Breaking Changes Summary

Area	Change	Impact
SDK Init	Sync constructor to Async factory	High
Response Object	Raw data to QResponse wrapper	Medium
Webhooks	Signature validation algorithm updated (HMAC-SHA256)	Medium
Pagination	Cursor-based only (Offset removed)	Low

Post-Migration Checklist

• Run your test suite to catch any unhandled type changes.
• Verify webhooks are signing with the new algorithm.
• Check error handling logic for the new error codes.
• Monitor logs for DEPRECATION warnings.

Need Help?

If you encounter issues during migration, our team is here to assist.

• Join our Discord channel for community support.
• Email our migration team at migrate@thatisaq.com.
• Search the Knowledge Base for common errors.