WIP: External API for migration extensions

.eslintignore

@@ -1,6 +1,9 @@
 /dist
 /out
 /node_modules
+/api/dist
+/api/node_modules
+vscode-documentdb-api.d.ts
 **/__mocks__/**
 **/*.d.ts
 .eslintrc.js

.github/workflows/api-extractor.yaml

@@ -0,0 +1,49 @@
+name: 'API: Extract Public Typings'
+
+# 📘 This workflow verifies that API typings can be generated and rolled up cleanly.
+# It runs on:
+# - Pushes to `main` (validate committed state)
+# - PRs to any branch (validate incoming changes)
+
+on:
+    push:
+        branches:
+            - main
+    pull_request:
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+    cancel-in-progress: true
+
+jobs:
+    extract-api-typings:
+        name: 📤 Extract API Typings
+        runs-on: ubuntu-latest
+
+        defaults:
+            run:
+                working-directory: './api' # Ensure the workflow runs in the 'api' folder
+
+        steps:
+            - name: ✅ Checkout Repository
+              uses: actions/checkout@v4
+
+            - name: 🛠 Setup Node.js Environment
+              uses: actions/setup-node@v4
+              with:
+                  node-version-file: .nvmrc
+                  cache: 'npm'
+
+            - name: 💾 Restore npm Cache
+              uses: actions/cache@v3
+              with:
+                  path: ~/.npm
+                  key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
+                  restore-keys: |
+                      ${{ runner.os }}-node-
+
+            - name: 📦 Install Dependencies (npm ci)
+              run: npm ci
+
+            - name: 🧬 Run API Extractor
+              run: npm run api-extractor

.github/workflows/api-publish.yaml

@@ -1,20 +1,50 @@
-name: "API: Publish to npm"
-
-# 🚀 This workflow manually publishes the API package to npm.
-# It should only be triggered via GitHub's UI or CLI using `workflow_dispatch`.
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  echo:
-    runs-on: ubuntu-latest
-    steps:
-      - run: echo "dummy action"
+name: 'API: Publish to npm'
+
+# 🚀 This workflow manually publishes the API package to npm.
+# It should only be triggered via GitHub's UI or CLI using `workflow_dispatch`.
+
+on:
+    workflow_dispatch:
+
+permissions:
+    contents: read
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.run_id }}
+    cancel-in-progress: true
+
+jobs:
+    publish-api-package:
+        name: 🚀 Publish API Package to npm
+        runs-on: ubuntu-latest
+
+        defaults:
+            run:
+                working-directory: './api' # Ensure the workflow runs in the 'api' folder
+
+        steps:
+            - name: ✅ Checkout Repository
+              uses: actions/checkout@v4
+
+            - name: 🛠 Setup Node.js Environment
+              uses: actions/setup-node@v4
+              with:
+                  node-version-file: .nvmrc
+                  cache: 'npm'
+
+            - name: 💾 Restore npm Cache
+              uses: actions/cache@v3
+              with:
+                  path: ~/.npm
+                  key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
+                  restore-keys: |
+                      ${{ runner.os }}-node-
+
+            - name: 📦 Install Dependencies (npm ci)
+              run: npm ci
+
+            - name: 🚀 Publish Package to npm
+              uses: JS-DevTools/npm-publish@v1
+              with:
+                  package: ./api/package.json
+                  token: ${{ secrets.EXPERIMENTAL_NPM_ACCESS_TOKEN }}

api/README.md

@@ -0,0 +1,231 @@
+# DocumentDB Extension API
+
+⚠️ **Warning**: This is an experimental API for a feature currently in development. It is intended for internal use only. The API is unstable and subject to rapid changes, which may break compatibility without notice.
+
+This package provides the Extension API for integrating with the VS Code DocumentDB extension.
+
+## Installation
+
+```bash
+npm install --save-dev @microsoft/vscode-documentdb-api
+```
+
+## Usage
+
+```typescript
+import {
+  getDocumentDBExtensionApi,
+  MigrationProvider,
+  MigrationProviderPickItem,
+  ActionsOptions,
+} from '@microsoft/vscode-documentdb-api';
+
+export async function activate(context: vscode.ExtensionContext) {
+  // Get the DocumentDB extension API
+  const api = await getDocumentDBExtensionApi(context, '0.1.0');
+
+  // Create your migration provider
+  const myProvider: MigrationProvider = {
+    id: 'my-provider',
+    label: 'My Migration Provider',
+    description: 'Migrates data from X to Y',
+
+    async getAvailableActions(options?: ActionsOptions): Promise<MigrationProviderPickItem[]> {
+      // Return available actions for the user to choose from
+      return [
+        {
+          id: 'import-data',
+          label: 'Import Data',
+          description: 'Import data from source to destination',
+        },
+        {
+          id: 'export-data',
+          label: 'Export Data',
+          description: 'Export data from source',
+        },
+      ];
+    },
+
+    async executeAction(options?: ActionsOptions, id?: string): Promise<void> {
+      // Execute the selected action
+      // Use options for context like connection details
+      switch (id) {
+        case 'import-data':
+          // Perform import operation using options.connectionString, etc.
+          break;
+        case 'export-data':
+          // Perform export operation using options.databaseName, etc.
+          break;
+        default:
+          // Handle default action or no action selected
+          break;
+      }
+    },
+
+    getLearnMoreUrl() {
+      return 'https://example.com/learn-more';
+    },
+  };
+
+  // Register your provider
+  api.migration.registerProvider(myProvider);
+}
+```
+
+## API Reference
+
+### MigrationProvider
+
+A migration provider must implement the following interface:
+
+**Required Properties:**
+
+- `id`: Unique identifier for the provider (internal use, not shown to users)
+- `label`: Display name shown to users
+- `description`: Brief description of what the provider does
+
+**Optional Properties:**
+
+- `iconPath`: Icon for the provider (can be a URI, theme icon, or light/dark icon pair)
+
+**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
+
+**Optional Properties:**
+
+- `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
+
+### 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
+
+### Supporting Interfaces
+
+#### MigrationProviderPickItem
+
+Extends VS Code's `QuickPickItem` with additional properties:
+
+```typescript
+interface MigrationProviderPickItem extends vscode.QuickPickItem {
+  id: string;
+  requiresAuthentication?: boolean; // Indicates if authentication is required for this action
+}
+```
+
+#### ActionsOptions
+
+Optional parameters to customize available actions:
+
+```typescript
+interface ActionsOptions {
+  connectionString?: string;
+  databaseName?: string;
+  collectionName?: string;
+  extendedProperties?: { [key: string]: string | undefined };
+}
+```
+
+## Authentication Support
+
+The API supports flexible authentication requirements at both the provider and action levels:
+
+### Provider-Level Authentication
+
+Use the `requiresAuthentication` property on the provider for default operations:
+
+```typescript
+const provider: MigrationProvider = {
+  id: 'my-provider',
+  label: 'My Provider',
+  description: 'Provider requiring authentication',
+  requiresAuthentication: true, // Auth required for default action
+
+  async getAvailableActions(): Promise<MigrationProviderPickItem[]> {
+    return []; // No custom actions, uses default
+  },
+
+  async executeAction(): Promise<void> {
+    // This will only be called after authentication is verified
+  },
+};
+```
+
+### Action-Level Authentication
+
+Individual actions can specify their own authentication requirements:
+
+```typescript
+const provider: MigrationProvider = {
+  id: 'flexible-provider',
+  label: 'Flexible Provider',
+  description: 'Provider with mixed authentication requirements',
+
+  async getAvailableActions(): Promise<MigrationProviderPickItem[]> {
+    return [
+      {
+        id: 'public-action',
+        label: 'Public Action',
+        description: 'No authentication required',
+        requiresAuthentication: false,
+      },
+      {
+        id: 'private-action',
+        label: 'Private Action',
+        description: 'Authentication required',
+        requiresAuthentication: true,
+      },
+    ];
+  },
+
+  async executeAction(options?: ActionsOptions, id?: string): Promise<void> {
+    // Handle actions based on their authentication requirements
+    // Use options for context like connection details
+  },
+};
+```
+
+### Combined Authentication
+
+Both provider and action-level authentication can be used together:
+
+```typescript
+const provider: MigrationProvider = {
+  id: 'combined-provider',
+  label: 'Combined Provider',
+  description: 'Uses both authentication levels',
+  requiresAuthentication: true, // Default action requires auth
+
+  async getAvailableActions(): Promise<MigrationProviderPickItem[]> {
+    return [
+      {
+        id: 'demo',
+        label: 'Demo Mode',
+        description: 'No authentication needed for demo',
+        requiresAuthentication: false,
+      },
+      {
+        id: 'full-migration',
+        label: 'Full Migration',
+        description: 'Full migration with authentication',
+        requiresAuthentication: true,
+      },
+    ];
+  },
+
+  async executeAction(options?: ActionsOptions, id?: string): Promise<void> {
+    // Both default and custom actions handled appropriately
+    // Access context via options parameter
+  },
+};
+```

api/api-extractor.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
+  "bundledPackages": [],
+  "compiler": {
+    "tsconfigFilePath": "<projectFolder>/tsconfig.json"
+  },
+  "apiReport": {
+    "enabled": false
+  },
+  "docModel": {
+    "enabled": false
+  },
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "<projectFolder>/dist/vscode-documentdb-api.d.ts"
+  },
+  "tsdocMetadata": {
+    "enabled": false
+  }
+}