Breaking Changes

This document tracks all breaking changes across Qirvo Plugin SDK versions, providing detailed migration instructions for each change.

Version 2.0.0
Version 1.2.0
Version 1.1.0
Migration Checklist
Deprecation Timeline

Version 2.0.0

Major Breaking Changes

1. Manifest Format Changes

What Changed:

Manifest version bumped to 2.0
Permission format changed from dot-notation to kebab-case
New required fields added

Before (v1.x):

{
  "manifestVersion": 1,
  "permissions": [
    "api.external",
    "storage.read",
    "storage.write"
  ]
}

After (v2.0):

{
  "manifestVersion": 2,
  "permissions": [
    "network-access",
    "storage-read", 
    "storage-write"
  ],
  "runtime": {
    "version": "2.0",
    "environment": "browser"
  }
}

Migration Steps:

Update manifestVersion to 2
Convert permissions using the mapping table below
Add required runtime section

Permission Mapping:

Old Format	New Format
`api.external`	`network-access`
`storage.read`	`storage-read`
`storage.write`	`storage-write`
`filesystem.read`	`filesystem-access`
`filesystem.write`	`filesystem-access`
`notifications.show`	`notifications`
`clipboard.read`	`clipboard-read`
`clipboard.write`	`clipboard-write`

2. Plugin API Changes

What Changed:

BasePlugin class constructor signature changed
Lifecycle methods renamed
Context API restructured

Before (v1.x):

export class MyPlugin extends BasePlugin {
  constructor(config: PluginConfig) {
    super(config);
  }
  
  async onInit(): Promise<void> {
    // Initialization code
  }
  
  async onDestroy(): Promise<void> {
    // Cleanup code
  }
}

After (v2.0):

export class MyPlugin extends BasePlugin {
  constructor(context: PluginContext, config: PluginConfig) {
    super(context, config);
  }
  
  async initialize(): Promise<void> {
    // Initialization code
  }
  
  async cleanup(): Promise<void> {
    // Cleanup code
  }
  
  async destroy(): Promise<void> {
    // Final cleanup
  }
}

Migration Steps:

Update constructor to accept PluginContext as first parameter
Rename onInit() to initialize()
Rename onDestroy() to cleanup()
Add new destroy() method if needed

3. Storage API Changes

What Changed:

Storage API moved from global to context
Method signatures updated
Added encryption support

Before (v1.x):

// Global storage access
await qirvo.storage.set('key', 'value');
const value = await qirvo.storage.get('key');

After (v2.0):

// Context-based storage access
await this.context.storage.set('key', 'value');
const value = await this.context.storage.get('key');

// With encryption (optional)
await this.context.storage.setSecure('key', 'value');
const value = await this.context.storage.getSecure('key');

Migration Steps:

Replace qirvo.storage with this.context.storage
Update all storage method calls
Consider using secure storage for sensitive data

4. Event System Changes

What Changed:

Event system completely redesigned
New event types and patterns
Improved type safety

Before (v1.x):

// Old event system
qirvo.events.on('user-action', (data) => {
  console.log('User action:', data);
});

qirvo.events.emit('plugin-event', { data: 'value' });

After (v2.0):

// New event system with types
this.context.events.subscribe<UserActionEvent>('user:action', (event) => {
  console.log('User action:', event.data);
});

this.context.events.emit('plugin:custom-event', { 
  data: 'value',
  timestamp: Date.now()
});

Migration Steps:

Replace qirvo.events with this.context.events
Update event names to use colon notation
Add proper TypeScript types for events
Update event handlers to use new signature

Minor Breaking Changes

5. Configuration Schema

What Changed:

Configuration validation is now required
Schema format updated

Before (v1.x):

// No schema validation
export const config = {
  apiKey: '',
  timeout: 5000
};

After (v2.0):

// Required schema validation
export const configSchema = {
  type: 'object',
  properties: {
    apiKey: { type: 'string', required: true },
    timeout: { type: 'number', default: 5000, minimum: 1000 }
  }
};

export const config = {
  apiKey: '',
  timeout: 5000
};

6. Hook System Changes

What Changed:

Hook registration API updated
New hook types added
Improved error handling

Before (v1.x):

qirvo.hooks.register('before-save', async (data) => {
  return processData(data);
});

After (v2.0):

this.context.hooks.register({
  type: 'middleware',
  event: 'before-save',
  handler: async (data, context) => {
    return processData(data);
  },
  priority: 10
});

Version 1.2.0