Home
JS SDK (Browser)
JS SDK (Server)
FAQ
Home
JS SDK (Browser)
JS SDK (Server)
FAQ

Migration Guide

This guide helps you migrate between different versions of the Asterisms JS SDK Backend.

Version 3.x to 4.x (Future)

Version 4.x is not yet released. This section will be updated when available.

Version 2.x to 3.x

Breaking Changes

1. SDK Factory Function Name Change

Before (v2.x):

import { createAsterismsBackendSDK } from '@asterisms/sdk-backend';

const sdk = createAsterismsBackendSDK(props);

After (v3.x):

import { getAsterismsBackendSDK } from '@asterisms/sdk-backend';

const sdk = getAsterismsBackendSDK(props);

2. SvelteKit Integration Changes

Before (v2.x):

import { createSvelteKitSDK } from '@asterisms/sdk-backend';

const provider = createSvelteKitSDK(props);

After (v3.x):

import { createSvelteKitBackendSDK } from '@asterisms/sdk-backend';

const provider = createSvelteKitBackendSDK(props);

3. Configuration Property Changes

Before (v2.x):

const sdk = getAsterismsBackendSDK({
  appId: 'com.example.app',
  host: 'asterisms.example.com'
  // ... other props
});

After (v3.x):

const sdk = getAsterismsBackendSDK({
  bundleId: 'com.example.app',
  domain: 'asterisms.example.com'
  // ... other props
});

4. Service Method Changes

Before (v2.x):

const auth = sdk.auth();
const data = sdk.data();

After (v3.x):

const auth = sdk.authorization();
const storage = sdk.storage();

Migration Steps

Step 1: Update Dependencies

npm update @asterisms/sdk-backend @asterisms/common-core

Step 2: Update Factory Function Calls

Find and replace all instances:

# Search for old factory function
grep -r "createAsterismsBackendSDK" src/

# Replace with new factory function
sed -i 's/createAsterismsBackendSDK/getAsterismsBackendSDK/g' src/**/*.ts

Step 3: Update SvelteKit Integration

Replace SvelteKit integration code:

// OLD
import { createSvelteKitSDK } from '@asterisms/sdk-backend';

// NEW
import { createSvelteKitBackendSDK } from '@asterisms/sdk-backend';

Step 4: Update Configuration

Update your SDK configuration:

// OLD
const sdk = getAsterismsBackendSDK({
  appId: 'com.example.app',
  host: 'asterisms.example.com'
  // ... other props
});

// NEW
const sdk = getAsterismsBackendSDK({
  bundleId: 'com.example.app',
  domain: 'asterisms.example.com'
  // ... other props
});

Step 5: Update Service Calls

Update service method calls:

// OLD
const auth = sdk.auth();
const data = sdk.data();

// NEW
const auth = sdk.authorization();
const storage = sdk.storage();

Step 6: Update Environment Variables

Update your environment variables:

# OLD
ASTERISMS_APP_ID=com.example.app
ASTERISMS_HOST=asterisms.example.com

# NEW
ASTERISMS_BUNDLE_ID=com.example.app
ASTERISMS_DOMAIN=asterisms.example.com

Step 7: Test Your Application

  1. Update your test files to use the new API
  2. Run your test suite
  3. Test all SDK integrations manually
  4. Verify all services work correctly

Common Migration Issues

Issue 1: TypeScript Errors

Problem: TypeScript compilation errors after upgrade

Solution: Update TypeScript types and imports:

// Update imports
import type { AsterismsBackendSDK, AsterismsBackendSDKInitProps } from '@asterisms/sdk-backend';

// Update type annotations
const sdk: AsterismsBackendSDK = getAsterismsBackendSDK(props);

Issue 2: Service Method Not Found

Problem: sdk.auth() is not a function

Solution: Update service method names:

// OLD
const auth = sdk.auth();
const data = sdk.data();
const notify = sdk.notify();

// NEW
const auth = sdk.authorization();
const storage = sdk.storage();
const notifications = sdk.notifications();

Issue 3: Configuration Errors

Problem: Invalid configuration properties

Solution: Update configuration property names:

// Check the new configuration interface
interface AsterismsBackendSDKInitProps {
  bundleId: string; // was: appId
  domain: string; // was: host
  subdomain: string; // was: subdomain
  httpServiceAdapterFactory: HttpServiceAdapterFactory;
  registrationData: RegistrationData;
  // ... other props
}

Version 1.x to 2.x

Breaking Changes

1. Package Structure Changes

Before (v1.x):

import { AsterismsSDK } from '@asterisms/backend-sdk';

After (v2.x):

import { getAsterismsBackendSDK } from '@asterisms/sdk-backend';

2. Initialization Changes

Before (v1.x):

const sdk = new AsterismsSDK({
  apiKey: 'your-api-key',
  endpoint: 'https://api.asterisms.com'
});

After (v2.x):

const sdk = getAsterismsBackendSDK({
  bundleId: 'com.example.app',
  domain: 'asterisms.example.com',
  subdomain: 'app',
  httpServiceAdapterFactory: createFetchAdapter(fetch),
  registrationData: {
    // registration data
  }
});

Migration Steps

Step 1: Update Package Name

npm uninstall @asterisms/backend-sdk
npm install @asterisms/sdk-backend

Step 2: Update Imports

// OLD
import { AsterismsSDK } from '@asterisms/backend-sdk';

// NEW
import { getAsterismsBackendSDK } from '@asterisms/sdk-backend';

Step 3: Update Initialization

Replace old initialization with new factory pattern:

// OLD
const sdk = new AsterismsSDK({
  apiKey: process.env.ASTERISMS_API_KEY,
  endpoint: process.env.ASTERISMS_ENDPOINT
});

// NEW
const sdk = getAsterismsBackendSDK({
  bundleId: process.env.ASTERISMS_BUNDLE_ID,
  domain: process.env.ASTERISMS_DOMAIN,
  subdomain: process.env.ASTERISMS_SUBDOMAIN,
  httpServiceAdapterFactory: createFetchAdapter(fetch),
  registrationData: {
    bundleId: process.env.ASTERISMS_BUNDLE_ID,
    capabilities: ['BACKEND_SERVICE'],
    description: 'Your Backend Service',
    name: 'Your Service',
    subdomain: process.env.ASTERISMS_SUBDOMAIN,
    title: 'Your Service'
  }
});

General Migration Tips

1. Use TypeScript

TypeScript will help catch many migration issues at compile time:

import type { AsterismsBackendSDK } from '@asterisms/sdk-backend';

const sdk: AsterismsBackendSDK = getAsterismsBackendSDK(props);

2. Check Documentation

Always refer to the latest API documentation:

3. Update Tests

Make sure to update your test files:

// Update test imports
import { getAsterismsBackendSDK } from '@asterisms/sdk-backend';

// Update test setup
beforeEach(() => {
  const sdk = getAsterismsBackendSDK(testProps);
  // ... test setup
});

4. Check Examples

Review the examples directory for updated patterns:

5. Environment Variables

Update your environment variable names:

# Common renames across versions
ASTERISMS_APP_ID -> ASTERISMS_BUNDLE_ID
ASTERISMS_HOST -> ASTERISMS_DOMAIN
ASTERISMS_API_KEY -> ASTERISMS_PRODUCT_AUTHORIZATION_KEY

6. Error Handling

Update error handling for new error types:

import { AsterismsSDKError } from '@asterisms/sdk-backend';

try {
  await sdk.boot();
} catch (error) {
  if (error instanceof AsterismsSDKError) {
    // Handle SDK-specific errors
  }
}

Version-Specific Notes

Version 3.4.x (Current)

  • Stable API with comprehensive service coverage
  • Full SvelteKit integration support
  • Complete TypeScript support
  • Production-ready error handling

Version 3.3.x

  • Added notification service
  • Improved error handling
  • Enhanced TypeScript definitions

Version 3.2.x

  • Added storage service improvements
  • Better SvelteKit integration
  • Performance optimizations

Version 3.1.x

  • Initial stable release
  • Core services implemented
  • Basic SvelteKit support

Getting Help

If you encounter issues during migration:

  1. Check the changelog for detailed version changes
  2. Review the troubleshooting guide for common issues
  3. Check the examples for updated patterns
  4. Submit an issue if you find bugs or need help

Migration Checklist

Use this checklist to ensure a successful migration:

  • Update package dependencies
  • Update factory function calls
  • Update configuration properties
  • Update service method calls
  • Update environment variables
  • Update TypeScript types
  • Update test files
  • Run test suite
  • Test all integrations
  • Deploy to staging
  • Test in production environment
  • Update documentation
  • Train team on changes

Post-Migration

After completing the migration:

  1. Monitor your application for any issues
  2. Update your team on the changes
  3. Review new features available in the latest version
  4. Consider performance improvements from the new version
  5. Update your documentation to reflect the changes

Next Steps

ON THIS PAGE