Sync next with main after two patch releases

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Change Log
 
+## 0.5.2
+
+### New Features & Improvements
+
+- **Updated Migration API for Integrations**: This release introduces API versioning for the DocumentDB extension API and adds support for a new, more robust v0.3.0 API. The changes update documentation, interfaces, and implementation to reflect the new API version, including stricter provider registration and context validation. The migration provider workflow and usage examples have been clarified, and deprecated API versions are documented. Additional improvements include dependency updates, better credential handling, and minor localization and client registration changes. [#321](https://github.com/microsoft/vscode-documentdb/issues/321), [#322](https://github.com/microsoft/vscode-documentdb/pull/322)
+
+## 0.5.1
+
+### Fixes
+
+- **Connection String Parsing**: Resolved an issue where connection strings containing special characters (e.g., `@`) in query parameters, such as those from Azure Cosmos DB (`appName=@myaccount@`), would fail to parse. The connection string parser now properly sanitizes query parameters before parsing, ensuring reliable connections. [#314](https://github.com/microsoft/vscode-documentdb/issues/314), [#316](https://github.com/microsoft/vscode-documentdb/pull/316)
+
 ## 0.5.0
 
 ### New Features & Improvements

api/README.md

@@ -4,25 +4,32 @@
 
 This package provides the Extension API for integrating with the VS Code DocumentDB extension.
 
+## API Versioning
+
+- **v0.3.0 (Latest)**: The current and only supported version. It requires the extension context for provider registration and enforces a one-provider-per-extension rule.
+- **v0.2.0 (Deprecated)**: This version is deprecated and will be removed in a future release. New integrations should not use it.
+
 ## Installation
 
 ```bash
-npm install --save-dev @<to be published>
+npm install --save-dev vscode-documentdb-api-experimental-beta
 ```
 
-## Usage
+## Usage (v0.3.0)
 
 ```typescript
+import * as vscode from 'vscode';
 import {
   getDocumentDBExtensionApi,
-  MigrationProvider,
-  MigrationProviderPickItem,
-  ActionsOptions,
-} from '@microsoft/vscode-documentdb-api';
+  type DocumentDBExtensionApiV030, // Import the v0.3.0 API interface
+  type MigrationProvider,
+  type MigrationProviderPickItem,
+  type ActionsOptions,
+} from 'vscode-documentdb-api-experimental-beta';
 
 export async function activate(context: vscode.ExtensionContext) {
-  // Get the DocumentDB extension API
-  const api = await getDocumentDBExtensionApi(context, '0.1.0');
+  // Get the DocumentDB extension API and cast it to the v0.3.0 type
+  const api = (await getDocumentDBExtensionApi(context, '0.3.0')) as DocumentDBExtensionApiV030;
 
   // Create your migration provider
   const myProvider: MigrationProvider = {
@@ -67,8 +74,9 @@ export async function activate(context: vscode.ExtensionContext) {
     },
   };
 
-  // Register your provider
-  api.migration.registerProvider(myProvider);
+  // Register your provider using the extension context.
+  // Note: Each extension can only register one provider.
+  api.migration.registerProvider(context, myProvider);
 }
 ```
 
@@ -90,25 +98,25 @@ A migration provider must implement the following interface:
 
 **Required Methods:**
 
-- `getAvailableActions(options?: ActionsOptions)`: Returns a list of actions the user can choose from
-- `executeAction(id?: string)`: Executes the selected action or a default action
+- `getAvailableActions(options?: ActionsOptions)`: Returns a list of actions the user can choose from.
+- `executeAction(id?: string)`: Executes the selected action or a default action.
 
 **Optional Properties:**
 
-- `requiresAuthentication`: Indicates if authentication is required for the default operation (when no custom actions are provided)
+- `requiresAuthentication`: Indicates if authentication is required for the default operation (when no custom actions are provided).
 
 **Optional Methods:**
 
-- `getLearnMoreUrl()`: Returns a URL for more information about the provider
+- `getLearnMoreUrl()`: Returns a URL for more information about the provider.
 
 ### Workflow
 
 The migration provider workflow follows these steps:
 
-1. **Get Available Actions**: The system calls `getAvailableActions()` to retrieve a list of possible operations
-2. **User Selection**: If actions are returned, they are presented to the user for selection
-3. **Execute Action**: The system calls `executeAction()` with the selected action's ID
-4. **Default Execution**: If `getAvailableActions()` returns an empty array, `executeAction()` is called immediately without parameters
+1.  **Get Available Actions**: The system calls `getAvailableActions()` to retrieve a list of possible operations.
+2.  **User Selection**: If actions are returned, they are presented to the user for selection.
+3.  **Execute Action**: The system calls `executeAction()` with the selected action's ID.
+4.  **Default Execution**: If `getAvailableActions()` returns an empty array, `executeAction()` is called immediately without parameters.
 
 ### Supporting Interfaces