@pptb/types 1.0.0

package/README.md

@@ -0,0 +1,254 @@
+# @pptb/types
+
+TypeScript type definitions for Power Platform Tool Box API.
+
+## Installation
+
+```bash
+npm install --save-dev @pptb/types
+```
+
+## Usage
+
+### In your TypeScript tool
+
+```typescript
+/// <reference types="@pptb/types" />
+
+// Access the ToolBox API
+const toolbox = window.toolboxAPI;
+
+// Get connection context
+const context = await toolbox.getToolContext();
+console.log("Connection URL:", context.connectionUrl);
+console.log("Access Token:", context.accessToken);
+
+// Subscribe to events
+toolbox.onToolboxEvent((event, payload) => {
+    console.log("Event:", payload.event, "Data:", payload.data);
+});
+
+// Show notifications
+await toolbox.showNotification({
+    title: "Success",
+    body: "Operation completed successfully",
+    type: "success",
+});
+```
+
+### Type-safe event handling
+
+```typescript
+toolbox.onToolboxEvent((event, payload) => {
+    switch (payload.event) {
+        case "connection:updated":
+            console.log("Connection updated:", payload.data);
+            break;
+        case "tool:loaded":
+            console.log("Tool loaded:", payload.data);
+            break;
+    }
+});
+```
+
+## API Reference
+
+Below are the APIs exposed to tools via `window.toolboxAPI`. All methods return Promises and are safe to `await` in modern browsers/Electron webviews.
+
+### Settings
+
+-   getUserSettings(): Promise<any>
+
+    -   Returns the entire user settings object stored by the ToolBox.
+
+-   updateUserSettings(settings: any): Promise<void>
+
+    -   Merges and persists the provided settings object into the user settings store.
+
+-   getSetting(key: string): Promise<any>
+
+    -   Retrieves a single setting value by key from user settings.
+
+-   setSetting(key: string, value: any): Promise<void>
+    -   Sets or updates a single setting key/value in user settings.
+
+### Connections
+
+-   addConnection(connection: any): Promise<void>
+
+    -   Adds a new Dataverse connection definition to the ToolBox.
+
+-   updateConnection(id: string, updates: any): Promise<void>
+
+    -   Applies partial updates to an existing connection by its id.
+
+-   deleteConnection(id: string): Promise<void>
+
+    -   Removes an existing connection by its id.
+
+-   getConnections(): Promise<ToolBox.DataverseConnection[]>
+
+    -   Returns all saved Dataverse connections.
+
+-   setActiveConnection(id: string): Promise<void>
+
+    -   Marks the specified connection as the active connection for the current session.
+
+-   getActiveConnection(): Promise<ToolBox.DataverseConnection | null>
+
+    -   Returns the currently active connection or null if none is active.
+
+-   disconnectConnection(): Promise<void>
+    -   Clears the active connection for the current session.
+
+### Tools
+
+-   getAllTools(): Promise<ToolBox.Tool[]>
+
+    -   Returns all tools known to the ToolBox (installed/managed).
+
+-   getTool(toolId: string): Promise<ToolBox.Tool>
+
+    -   Returns metadata about a specific tool by its id.
+
+-   loadTool(packageName: string): Promise<ToolBox.Tool>
+
+    -   Loads a tool (initializes/activates) by npm package name.
+
+-   unloadTool(toolId: string): Promise<void>
+
+    -   Unloads a tool instance by its id.
+
+-   installTool(packageName: string): Promise<ToolBox.Tool>
+
+    -   Installs a tool from npm (and registers it with the ToolBox).
+
+-   uninstallTool(packageName: string, toolId: string): Promise<void>
+
+    -   Uninstalls a previously installed tool and removes it from the ToolBox.
+
+-   getToolWebviewHtml(packageName: string, connectionUrl?: string, accessToken?: string): Promise<string | null>
+
+    -   Returns an HTML string suitable for a tool's webview. Optional connection credentials can be passed for bootstrapping.
+
+-   getToolContext(): Promise<ToolBox.ToolContext>
+    -   Returns the current tool context including `toolId`, `connectionUrl`, and `accessToken` when available.
+
+### Tool Settings
+
+-   getToolSettings(toolId: string): Promise<any>
+
+    -   Returns tool-scoped settings for the specified tool id.
+
+-   updateToolSettings(toolId: string, settings: any): Promise<void>
+    -   Merges and persists tool-scoped settings for the specified tool id.
+
+### Notifications
+
+-   showNotification(options: ToolBox.NotificationOptions): Promise<void>
+    -   Displays a ToolBox notification. `options.type` supports `info | success | warning | error` and `duration` in ms (0 = persistent).
+
+### Clipboard
+
+-   copyToClipboard(text: string): Promise<void>
+    -   Copies the provided text into the system clipboard.
+
+### File operations
+
+-   saveFile(defaultPath: string, content: any): Promise<string | null>
+    -   Opens a save dialog and writes the content. Returns the saved file path or null if canceled.
+
+### Terminal operations
+
+-   createTerminal(toolId: string, options: ToolBox.TerminalOptions): Promise<ToolBox.Terminal>
+
+    -   Creates a new terminal attached to the tool with the given options (name, shell, cwd, env).
+
+-   executeTerminalCommand(terminalId: string, command: string): Promise<ToolBox.TerminalCommandResult>
+
+    -   Executes a command in the specified terminal and returns its result.
+
+-   closeTerminal(terminalId: string): Promise<void>
+
+    -   Closes the specified terminal.
+
+-   getTerminal(terminalId: string): Promise<ToolBox.Terminal | undefined>
+
+    -   Gets a single terminal by id, if it exists.
+
+-   getToolTerminals(toolId: string): Promise<ToolBox.Terminal[]>
+
+    -   Lists all terminals created by a specific tool.
+
+-   getAllTerminals(): Promise<ToolBox.Terminal[]>
+
+    -   Lists all existing terminals managed by the ToolBox.
+
+-   setTerminalVisibility(terminalId: string, visible: boolean): Promise<void>
+    -   Shows or hides the terminal UI for the specified terminal id.
+
+### Events
+
+-   getEventHistory(limit?: number): Promise<ToolBox.ToolBoxEventPayload[]>
+
+    -   Returns recent ToolBox events, newest first. Use `limit` to cap the number of entries.
+
+-   onToolboxEvent(callback: (event: any, payload: ToolBox.ToolBoxEventPayload) => void): void
+
+    -   Subscribes to ToolBox events (e.g., `tool:loaded`, `connection:updated`, `terminal:output`).
+
+-   removeToolboxEventListener(callback: (event: any, payload: ToolBox.ToolBoxEventPayload) => void): void
+    -   Removes a previously registered event listener.
+
+### Auto-update
+
+-   checkForUpdates(): Promise<void>
+
+    -   Triggers an update check.
+
+-   downloadUpdate(): Promise<void>
+
+    -   Starts downloading an available update.
+
+-   quitAndInstall(): Promise<void>
+
+    -   Quits the app and installs a downloaded update.
+
+-   getAppVersion(): Promise<string>
+
+    -   Returns the current application version.
+
+-   onUpdateChecking(callback: () => void): void
+
+    -   Called when an update check has started.
+
+-   onUpdateAvailable(callback: (info: any) => void): void
+
+    -   Called when an update is available; `info` provides update metadata.
+
+-   onUpdateNotAvailable(callback: () => void): void
+
+    -   Called when no updates are available.
+
+-   onUpdateDownloadProgress(callback: (progress: any) => void): void
+
+    -   Called periodically with download progress information.
+
+-   onUpdateDownloaded(callback: (info: any) => void): void
+
+    -   Called once an update has been downloaded and is ready to install.
+
+-   onUpdateError(callback: (error: string) => void): void
+    -   Called when an update-related error occurs.
+
+## Publishing the package to npm
+
+This is an organization scoped package so use the following command to deploy to npm
+
+```bash
+npm publish --access public
+```
+
+## License
+
+GPL-3.0

package/index.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Power Platform Tool Box API Type Definitions
+ *
+ * Tools running in ToolBox webviews can access the ToolBox API via window.toolboxAPI
+ */
+
+declare namespace ToolBox {
+    /**
+     * Tool context containing connection information
+     */
+    export interface ToolContext {
+        toolId: string | null;
+        connectionUrl: string | null;
+        accessToken: string | null;
+    }
+
+    /**
+     * Notification options
+     */
+    export interface NotificationOptions {
+        title: string;
+        body: string;
+        type?: "info" | "success" | "warning" | "error";
+        duration?: number; // Duration in milliseconds, 0 for persistent
+    }
+
+    /**
+     * Event types that can be emitted by the ToolBox
+     */
+    export type ToolBoxEvent = "tool:loaded" | "tool:unloaded" | "connection:created" | "connection:updated" | "connection:deleted" | "settings:updated" | "notification:shown" | "terminal:created" | "terminal:closed" | "terminal:output" | "terminal:command:completed" | "terminal:error";
+
+    /**
+     * Event payload for ToolBox events
+     */
+    export interface ToolBoxEventPayload {
+        event: ToolBoxEvent;
+        data: unknown;
+        timestamp: string;
+    }
+
+    /**
+     * Dataverse connection configuration
+     */
+    export interface DataverseConnection {
+        id: string;
+        name: string;
+        url: string;
+        environment: "Dev" | "Test" | "UAT" | "Production";
+        clientId?: string;
+        tenantId?: string;
+        createdAt: string;
+        lastUsedAt?: string;
+        isActive?: boolean;
+    }
+
+    /**
+     * Tool information
+     */
+    export interface Tool {
+        id: string;
+        name: string;
+        version: string;
+        description: string;
+        author: string;
+        icon?: string;
+    }
+
+    /**
+     * Terminal configuration options
+     */
+    export interface TerminalOptions {
+        name: string;
+        shell?: string;
+        cwd?: string;
+        env?: Record<string, string>;
+    }
+
+    /**
+     * Terminal instance
+     */
+    export interface Terminal {
+        id: string;
+        name: string;
+        toolId: string;
+        shell: string;
+        cwd: string;
+        isVisible: boolean;
+        createdAt: string;
+    }
+
+    /**
+     * Terminal command execution result
+     */
+    export interface TerminalCommandResult {
+        terminalId: string;
+        commandId: string;
+        output?: string;
+        exitCode?: number;
+        error?: string;
+    }
+
+    /**
+     * ToolBox API exposed to tools via window.toolboxAPI
+     */
+    export interface ToolBoxAPI {
+        // Settings
+        getUserSettings: () => Promise<any>;
+        updateUserSettings: (settings: any) => Promise<void>;
+        getSetting: (key: string) => Promise<any>;
+        setSetting: (key: string, value: any) => Promise<void>;
+
+        // Connections
+        addConnection: (connection: any) => Promise<void>;
+        updateConnection: (id: string, updates: any) => Promise<void>;
+        deleteConnection: (id: string) => Promise<void>;
+        getConnections: () => Promise<DataverseConnection[]>;
+        setActiveConnection: (id: string) => Promise<void>;
+        getActiveConnection: () => Promise<DataverseConnection | null>;
+        disconnectConnection: () => Promise<void>;
+
+        // Tools
+        getAllTools: () => Promise<Tool[]>;
+        getTool: (toolId: string) => Promise<Tool>;
+        loadTool: (packageName: string) => Promise<Tool>;
+        unloadTool: (toolId: string) => Promise<void>;
+        installTool: (packageName: string) => Promise<Tool>;
+        uninstallTool: (packageName: string, toolId: string) => Promise<void>;
+        getToolWebviewHtml: (packageName: string, connectionUrl?: string, accessToken?: string) => Promise<string | null>;
+        getToolContext: () => Promise<ToolContext>;
+
+        // Tool Settings
+        getToolSettings: (toolId: string) => Promise<any>;
+        updateToolSettings: (toolId: string, settings: any) => Promise<void>;
+
+        // Notifications
+        showNotification: (options: NotificationOptions) => Promise<void>;
+
+        // Clipboard
+        copyToClipboard: (text: string) => Promise<void>;
+
+        // File operations
+        saveFile: (defaultPath: string, content: any) => Promise<string | null>;
+
+        // Terminal operations
+        createTerminal: (toolId: string, options: TerminalOptions) => Promise<Terminal>;
+        executeTerminalCommand: (terminalId: string, command: string) => Promise<TerminalCommandResult>;
+        closeTerminal: (terminalId: string) => Promise<void>;
+        getTerminal: (terminalId: string) => Promise<Terminal | undefined>;
+        getToolTerminals: (toolId: string) => Promise<Terminal[]>;
+        getAllTerminals: () => Promise<Terminal[]>;
+        setTerminalVisibility: (terminalId: string, visible: boolean) => Promise<void>;
+
+        // Events
+        getEventHistory: (limit?: number) => Promise<ToolBoxEventPayload[]>;
+        onToolboxEvent: (callback: (event: any, payload: ToolBoxEventPayload) => void) => void;
+        removeToolboxEventListener: (callback: (event: any, payload: ToolBoxEventPayload) => void) => void;
+
+        // Auto-update
+        checkForUpdates: () => Promise<void>;
+        downloadUpdate: () => Promise<void>;
+        quitAndInstall: () => Promise<void>;
+        getAppVersion: () => Promise<string>;
+        onUpdateChecking: (callback: () => void) => void;
+        onUpdateAvailable: (callback: (info: any) => void) => void;
+        onUpdateNotAvailable: (callback: () => void) => void;
+        onUpdateDownloadProgress: (callback: (progress: any) => void) => void;
+        onUpdateDownloaded: (callback: (info: any) => void) => void;
+        onUpdateError: (callback: (error: string) => void) => void;
+    }
+}
+
+/**
+ * Global window interface extension for ToolBox tools
+ */
+declare global {
+    interface Window {
+        toolboxAPI: ToolBox.ToolBoxAPI;
+        TOOLBOX_CONTEXT?: ToolBox.ToolContext;
+    }
+}
+
+export = ToolBox;
+export as namespace ToolBox;

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@pptb/types",
+  "version": "1.0.0",
+  "description": "TypeScript type definitions for Power Platform Tool Box API",
+  "main": "index.d.ts",
+  "types": "index.d.ts",
+  "keywords": [
+    "powerplatform",
+    "pptb",
+    "toolbox",
+    "types",
+    "typescript",
+    "dataverse"
+  ],
+  "author": "Power Platform Tool Box",
+  "license": "GPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PowerPlatform-ToolBox/desktop-app.git",
+    "directory": "packages"
+  }
+}