@lvce-editor/api 9.37.2 → 9.38.0

package/README.md

@@ -67,3 +67,34 @@ const registration = registerPortProvider({
 ```
 
 Ports queries matching extensions with the current workspace URI. Each extension may register one provider per scheme. Return an empty array when no ports are available, and dispose the registration when deactivating. The provider supplies addresses; the API does not create tunnels or change their visibility. Results from disposed registrations are discarded.
+
+## Authentication providers
+
+Extensions can contribute a functional authentication provider with session callbacks. The provider's stable `id` and display `label` identify it; requested scopes are passed to the callbacks, and session results include an account, access token, and granted scopes.
+
+```ts
+import { activate, registerAuthenticationProvider } from '@lvce-editor/api'
+
+await activate()
+const registration = registerAuthenticationProvider({
+  id: 'example',
+  label: 'Example Account',
+  async getSessions(scopes) {
+    return []
+  },
+  async createSession(scopes) {
+    return {
+      id: 'account-session',
+      accessToken: 'token',
+      account: { id: 'account', label: 'Example Account' },
+      scopes,
+    }
+  },
+  async removeSession(sessionId) {},
+})
+
+// Dispose the contribution when the extension deactivates.
+registration.dispose()
+```
+
+The editor can call `executeAuthenticationProviderGetSessions`, `executeAuthenticationProviderCreateSession`, and `executeAuthenticationProviderRemoveSession` by provider id. Session callbacks are responsible for account selection, consent, token storage, and revocation.

package/dist/index.d.ts

@@ -2,6 +2,9 @@ export { activate } from './parts/Activation/Activation.ts';
 export { getColorThemeNames } from './parts/ColorTheme/ColorTheme.ts';
 export { markdownToVirtualDom } from './parts/Markdown/Markdown.ts';
 export { getAccessToken, type GetAccessTokenOptions } from './parts/Authentication/Authentication.ts';
+export { executeAuthenticationProviderCreateSession, executeAuthenticationProviderGetSessions, executeAuthenticationProviderRemoveSession, getAuthenticationProviderRegistrySnapshot, registerAuthenticationProvider, resetAuthenticationProviderRegistry, } from './parts/AuthenticationProviderRegistry/AuthenticationProviderRegistry.ts';
+export type { AuthenticationAccount, AuthenticationProvider, AuthenticationSession } from './parts/AuthenticationProvider/AuthenticationProvider.ts';
+export type { AuthenticationProviderRegistrySnapshot } from './parts/AuthenticationProviderRegistrySnapshot/AuthenticationProviderRegistrySnapshot.ts';
 export { createElectronWebContentsView } from './parts/ElectronWebContentsView/ElectronWebContentsView.ts';
 export { executeCommand } from './parts/ExecuteCommand/ExecuteCommand.ts';
 export { showFileQuickPick, showQuickInput, showQuickPick } from './parts/QuickPick/QuickPick.ts';
@@ -19,6 +22,7 @@ export { exists, getFileHash, getFileHashes, mkdir, readAsObjectUrl, readDirWith
 export { registerFileChangeHandler, type FileChangeHandler, type FileChanges } from './parts/FileChangeHandler/FileChangeHandler.ts';
 export { executeFileSystemProviderGetOpenExternalPath, executeFileSystemProviderIsReadonly, executeFileSystemProviderMkdir, executeFileSystemProviderReadDirWithFileTypes, executeFileSystemProviderReadFile, executeFileSystemProviderRemove, executeFileSystemProviderRename, executeFileSystemProviderWriteFile, getFileSystemProviderRegistrySnapshot, registerFileSystemProvider, resetFileSystemProviderRegistry, } from './parts/FileSystemProviderRegistry/FileSystemProviderRegistry.ts';
 export { closeUri, confirm, getRecentlyOpenedWorkspaceUris, getWorkspaceFolder, getWorkspaceUri, handleWorkspaceRefresh, openUri, setWorkspaceUri, showErrorMessage, showNotification, type ConfirmOptions, type NotificationType, type ShowErrorMessageOptions, } from './parts/Host/Host.ts';
+export { preparePrettyError } from './parts/PrettyError/PrettyError.ts';
 export { executeHoverProvider, getHoverProviderRegistrySnapshot, registerHoverProvider, resetHoverProviderRegistry } from './parts/Hover/Hover.ts';
 export { executeSignatureHelpProvider, getSignatureHelpProviderRegistrySnapshot, registerSignatureHelpProvider, resetSignatureHelpProviderRegistry, } from './parts/SignatureHelp/SignatureHelp.ts';
 export { getPlatform, getUserDataDir, type Platform } from './parts/Platform/Platform.ts';

package/dist/index.js

@@ -2,6 +2,7 @@ export { activate } from "./parts/Activation/Activation.js";
 export { getColorThemeNames } from "./parts/ColorTheme/ColorTheme.js";
 export { markdownToVirtualDom } from "./parts/Markdown/Markdown.js";
 export { getAccessToken } from "./parts/Authentication/Authentication.js";
+export { executeAuthenticationProviderCreateSession, executeAuthenticationProviderGetSessions, executeAuthenticationProviderRemoveSession, getAuthenticationProviderRegistrySnapshot, registerAuthenticationProvider, resetAuthenticationProviderRegistry, } from "./parts/AuthenticationProviderRegistry/AuthenticationProviderRegistry.js";
 export { createElectronWebContentsView } from "./parts/ElectronWebContentsView/ElectronWebContentsView.js";
 export { executeCommand } from "./parts/ExecuteCommand/ExecuteCommand.js";
 export { showFileQuickPick, showQuickInput, showQuickPick } from "./parts/QuickPick/QuickPick.js";
@@ -19,6 +20,7 @@ export { exists, getFileHash, getFileHashes, mkdir, readAsObjectUrl, readDirWith
 export { registerFileChangeHandler } from "./parts/FileChangeHandler/FileChangeHandler.js";
 export { executeFileSystemProviderGetOpenExternalPath, executeFileSystemProviderIsReadonly, executeFileSystemProviderMkdir, executeFileSystemProviderReadDirWithFileTypes, executeFileSystemProviderReadFile, executeFileSystemProviderRemove, executeFileSystemProviderRename, executeFileSystemProviderWriteFile, getFileSystemProviderRegistrySnapshot, registerFileSystemProvider, resetFileSystemProviderRegistry, } from "./parts/FileSystemProviderRegistry/FileSystemProviderRegistry.js";
 export { closeUri, confirm, getRecentlyOpenedWorkspaceUris, getWorkspaceFolder, getWorkspaceUri, handleWorkspaceRefresh, openUri, setWorkspaceUri, showErrorMessage, showNotification, } from "./parts/Host/Host.js";
+export { preparePrettyError } from "./parts/PrettyError/PrettyError.js";
 export { executeHoverProvider, getHoverProviderRegistrySnapshot, registerHoverProvider, resetHoverProviderRegistry } from "./parts/Hover/Hover.js";
 export { executeSignatureHelpProvider, getSignatureHelpProviderRegistrySnapshot, registerSignatureHelpProvider, resetSignatureHelpProviderRegistry, } from "./parts/SignatureHelp/SignatureHelp.js";
 export { getPlatform, getUserDataDir } from "./parts/Platform/Platform.js";

package/dist/parts/AuthenticationProvider/AuthenticationProvider.d.ts

@@ -0,0 +1,17 @@
+export interface AuthenticationAccount {
+    readonly id: string;
+    readonly label: string;
+}
+export interface AuthenticationSession {
+    readonly accessToken: string;
+    readonly account: AuthenticationAccount;
+    readonly id: string;
+    readonly scopes: readonly string[];
+}
+export interface AuthenticationProvider {
+    readonly createSession: (scopes: readonly string[]) => Promise<AuthenticationSession> | AuthenticationSession;
+    readonly getSessions: (scopes: readonly string[]) => Promise<readonly AuthenticationSession[]> | readonly AuthenticationSession[];
+    readonly id: string;
+    readonly label: string;
+    readonly removeSession: (sessionId: string) => Promise<void> | void;
+}

package/dist/parts/AuthenticationProvider/AuthenticationProvider.js

@@ -0,0 +1 @@
+export {};

package/dist/parts/AuthenticationProviderRegistry/AuthenticationProviderRegistry.d.ts

@@ -0,0 +1,9 @@
+import type { AuthenticationProvider, AuthenticationSession } from '../AuthenticationProvider/AuthenticationProvider.ts';
+import type { AuthenticationProviderRegistrySnapshot } from '../AuthenticationProviderRegistrySnapshot/AuthenticationProviderRegistrySnapshot.ts';
+import type { Disposable } from '../Disposable/Disposable.ts';
+export declare const registerAuthenticationProvider: (provider: AuthenticationProvider) => Disposable;
+export declare const executeAuthenticationProviderGetSessions: (providerId: string, scopes: readonly string[]) => Promise<readonly AuthenticationSession[]>;
+export declare const executeAuthenticationProviderCreateSession: (providerId: string, scopes: readonly string[]) => Promise<AuthenticationSession>;
+export declare const executeAuthenticationProviderRemoveSession: (providerId: string, sessionId: string) => Promise<void>;
+export declare const getAuthenticationProviderRegistrySnapshot: () => AuthenticationProviderRegistrySnapshot;
+export declare const resetAuthenticationProviderRegistry: () => void;

package/dist/parts/AuthenticationProviderRegistry/AuthenticationProviderRegistry.js

@@ -0,0 +1,98 @@
+import * as ExtensionApiCommandRegistry from "../ExtensionApiCommandRegistry/ExtensionApiCommandRegistry.js";
+import { ExtensionApiError } from "../ExtensionApiError/ExtensionApiError.js";
+const providers = Object.create(null);
+const assertSession = (session, providerId) => {
+    if (!session || typeof session !== 'object') {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned an invalid session`);
+    }
+    const value = session;
+    if (typeof value.id !== 'string' || value.id.length === 0) {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned a session without an id`);
+    }
+    if (typeof value.accessToken !== 'string' || value.accessToken.length === 0) {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned a session without an access token`);
+    }
+    if (!Array.isArray(value.scopes) || value.scopes.some((scope) => typeof scope !== 'string' || scope.length === 0)) {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned a session with invalid scopes`);
+    }
+    if (!value.account || typeof value.account !== 'object') {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned a session without an account`);
+    }
+    const account = value.account;
+    if (typeof account.id !== 'string' || account.id.length === 0 || typeof account.label !== 'string' || account.label.length === 0) {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned a session with an invalid account`);
+    }
+    return session;
+};
+const assertScopes = (scopes) => {
+    if (!Array.isArray(scopes) || scopes.some((scope) => !(typeof scope === 'string' && scope.length > 0))) {
+        throw new ExtensionApiError('authentication scopes must be an array of non-empty strings');
+    }
+};
+const getProvider = (providerId) => {
+    const provider = providers[providerId];
+    if (!provider) {
+        throw new ExtensionApiError(`authentication provider ${providerId} not found`);
+    }
+    return provider;
+};
+export const registerAuthenticationProvider = (provider) => {
+    if (!provider) {
+        throw new ExtensionApiError('authentication provider is not defined');
+    }
+    const providerRecord = provider;
+    if (typeof providerRecord.id !== 'string' || providerRecord.id.length === 0) {
+        throw new ExtensionApiError('authentication provider is missing id');
+    }
+    const { id } = provider;
+    if (typeof providerRecord.label !== 'string' || providerRecord.label.length === 0) {
+        throw new ExtensionApiError(`authentication provider ${id} is missing label`);
+    }
+    for (const methodName of ['getSessions', 'createSession', 'removeSession']) {
+        if (typeof providerRecord[methodName] !== 'function') {
+            throw new ExtensionApiError(`authentication provider ${id} is missing ${methodName} function`);
+        }
+    }
+    if (id in providers) {
+        throw new ExtensionApiError(`authentication provider ${id} is already registered`);
+    }
+    providers[id] = provider;
+    ExtensionApiCommandRegistry.registerCommandMap(commandMap);
+    return {
+        dispose() {
+            delete providers[id];
+        },
+    };
+};
+export const executeAuthenticationProviderGetSessions = async (providerId, scopes) => {
+    assertScopes(scopes);
+    const sessions = await getProvider(providerId).getSessions(scopes);
+    if (!Array.isArray(sessions)) {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned invalid sessions`);
+    }
+    return sessions.map((session) => assertSession(session, providerId));
+};
+export const executeAuthenticationProviderCreateSession = async (providerId, scopes) => {
+    assertScopes(scopes);
+    return assertSession(await getProvider(providerId).createSession(scopes), providerId);
+};
+export const executeAuthenticationProviderRemoveSession = async (providerId, sessionId) => {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        throw new ExtensionApiError('authentication session id is missing');
+    }
+    await getProvider(providerId).removeSession(sessionId);
+};
+export const getAuthenticationProviderRegistrySnapshot = () => ({
+    providers: Object.values(providers).map(({ id, label }) => ({ id, label })),
+});
+export const resetAuthenticationProviderRegistry = () => {
+    for (const id of Object.keys(providers)) {
+        delete providers[id];
+    }
+};
+const commandMap = {
+    'ExtensionApi.executeAuthenticationProviderCreateSession': executeAuthenticationProviderCreateSession,
+    'ExtensionApi.executeAuthenticationProviderGetSessions': executeAuthenticationProviderGetSessions,
+    'ExtensionApi.executeAuthenticationProviderRemoveSession': executeAuthenticationProviderRemoveSession,
+    'ExtensionApi.getAuthenticationProviderRegistrySnapshot': getAuthenticationProviderRegistrySnapshot,
+};

package/dist/parts/AuthenticationProviderRegistrySnapshot/AuthenticationProviderRegistrySnapshot.d.ts

@@ -0,0 +1,6 @@
+export interface AuthenticationProviderRegistrySnapshot {
+    readonly providers: readonly {
+        readonly id: string;
+        readonly label: string;
+    }[];
+}

package/dist/parts/AuthenticationProviderRegistrySnapshot/AuthenticationProviderRegistrySnapshot.js

@@ -0,0 +1 @@
+export {};

package/dist/parts/PrettyError/PrettyError.d.ts

@@ -0,0 +1,7 @@
+export interface PrettyError {
+    readonly codeFrame?: string;
+    readonly message?: string;
+    readonly name?: string;
+    readonly stack?: string;
+}
+export declare const preparePrettyError: (error: unknown) => Promise<PrettyError>;

package/dist/parts/PrettyError/PrettyError.js

@@ -0,0 +1,35 @@
+import { executeCommand } from "../ExecuteCommand/ExecuteCommand.js";
+const serializeError = (error) => {
+    if (error instanceof Error) {
+        return {
+            code: error.code,
+            codeFrame: error.codeFrame,
+            constructor: { name: error.constructor.name },
+            message: error.message,
+            name: error.name,
+            stack: error.stack,
+        };
+    }
+    if (error && typeof error === 'object') {
+        const value = error;
+        const constructorName = Object.hasOwn(value, 'constructor') ? value.constructor?.name : undefined;
+        return {
+            code: value.code,
+            codeFrame: value.codeFrame,
+            constructor: constructorName ? { name: constructorName } : undefined,
+            message: value.message || value.errorMessage,
+            name: value.name || constructorName,
+            stack: value.stack || value.errorStack,
+        };
+    }
+    return { message: String(error) };
+};
+export const preparePrettyError = async (error) => {
+    const serialized = serializeError(error);
+    try {
+        return (await executeCommand('ErrorHandling.preparePrettyError', serialized));
+    }
+    catch {
+        return serialized;
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lvce-editor/api",
-  "version": "9.37.2",
+  "version": "9.38.0",
   "description": "Tree-shakeable extension API for Lvce Editor extensions.",
   "keywords": [
     "lvce-editor",