@pptb/types 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @pptb/types
 
-TypeScript type definitions for Power Platform Tool Box API.
+TypeScript type definitions for Power Platform Tool Box APIs.
 
 ## Installation
 
@@ -8,238 +8,339 @@ TypeScript type definitions for Power Platform Tool Box API.
 npm install --save-dev @pptb/types
 ```
 
+## Overview
+
+The `@pptb/types` package provides TypeScript definitions for two main APIs:
+
+1. **ToolBox API** (`window.toolboxAPI`) - Core platform features (connections, utilities, terminals, events)
+2. **Dataverse API** (`window.dataverseAPI`) - Microsoft Dataverse Web API operations
+
 ## Usage
 
-### In your TypeScript tool
+### Include all type definitions
 
 ```typescript
 /// <reference types="@pptb/types" />
 
-// Access the ToolBox API
+// Both APIs are now available
 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",
-});
+const dataverse = window.dataverseAPI;
 ```
 
-### Type-safe event handling
+### Include specific API types
 
 ```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
+// Only ToolBox API types
+/// <reference types="@pptb/types/toolboxAPI" />
 
--   getUserSettings(): Promise<any>
+// Only Dataverse API types
+/// <reference types="@pptb/types/dataverseAPI" />
+```
 
-    -   Returns the entire user settings object stored by the ToolBox.
+## ToolBox API Examples
 
--   updateUserSettings(settings: any): Promise<void>
+The ToolBox API provides organized namespaces for different functionality:
 
-    -   Merges and persists the provided settings object into the user settings store.
+### Connections
 
--   getSetting(key: string): Promise<any>
+```typescript
+// Get the active Dataverse connection
+const connection = await toolboxAPI.connections.getActiveConnection();
+if (connection) {
+    console.log("Connected to:", connection.url);
+    console.log("Environment:", connection.environment);
+}
+```
 
-    -   Retrieves a single setting value by key from user settings.
+### Utilities
 
--   setSetting(key: string, value: any): Promise<void>
-    -   Sets or updates a single setting key/value in user settings.
+```typescript
+// Show a notification
+await toolboxAPI.utils.showNotification({
+    title: "Success",
+    body: "Operation completed successfully",
+    type: "success",
+    duration: 3000,
+});
 
-### Connections
+// Copy to clipboard
+await toolboxAPI.utils.copyToClipboard("Text to copy");
 
--   addConnection(connection: any): Promise<void>
+// Save a file
+const filePath = await toolboxAPI.utils.saveFile("output.json", JSON.stringify(data, null, 2));
+if (filePath) {
+    console.log("File saved to:", filePath);
+}
 
-    -   Adds a new Dataverse connection definition to the ToolBox.
+// Get current theme
+const theme = await toolboxAPI.utils.getCurrentTheme();
+console.log("Current theme:", theme); // "light" or "dark"
+```
 
--   updateConnection(id: string, updates: any): Promise<void>
+### Terminal Operations
 
-    -   Applies partial updates to an existing connection by its id.
+```typescript
+// Create a terminal (tool ID is automatically determined)
+const terminal = await toolboxAPI.terminal.create({
+    name: "My Terminal",
+    cwd: "/path/to/directory",
+});
 
--   deleteConnection(id: string): Promise<void>
+// Execute a command
+const result = await toolboxAPI.terminal.execute(terminal.id, "npm install");
+console.log("Exit code:", result.exitCode);
+console.log("Output:", result.output);
 
-    -   Removes an existing connection by its id.
+// List all terminals for this tool
+const terminals = await toolboxAPI.terminal.list();
 
--   getConnections(): Promise<ToolBox.DataverseConnection[]>
+// Close a terminal
+await toolboxAPI.terminal.close(terminal.id);
+```
 
-    -   Returns all saved Dataverse connections.
+### Events
 
--   setActiveConnection(id: string): Promise<void>
+```typescript
+// Subscribe to events
+toolboxAPI.events.on((event, payload) => {
+    console.log("Event:", payload.event, "Data:", payload.data);
 
-    -   Marks the specified connection as the active connection for the current session.
+    switch (payload.event) {
+        case "connection:updated":
+            console.log("Connection updated:", payload.data);
+            break;
+        case "terminal:output":
+            console.log("Terminal output:", payload.data);
+            break;
+    }
+});
 
--   getActiveConnection(): Promise<ToolBox.DataverseConnection | null>
+// Get event history
+const history = await toolboxAPI.events.getHistory(10); // Last 10 events
+```
 
-    -   Returns the currently active connection or null if none is active.
+## Dataverse API Examples
 
--   disconnectConnection(): Promise<void>
-    -   Clears the active connection for the current session.
+The Dataverse API provides direct access to Microsoft Dataverse operations:
 
-### Tools
+### CRUD Operations
 
--   getAllTools(): Promise<ToolBox.Tool[]>
+```typescript
+// Create a record
+const result = await dataverseAPI.create("account", {
+    name: "Contoso Ltd",
+    emailaddress1: "info@contoso.com",
+    telephone1: "555-0100",
+});
+console.log("Created account ID:", result.id);
 
-    -   Returns all tools known to the ToolBox (installed/managed).
+// Retrieve a record
+const account = await dataverseAPI.retrieve("account", result.id, ["name", "emailaddress1", "telephone1"]);
+console.log("Account name:", account.name);
 
--   getTool(toolId: string): Promise<ToolBox.Tool>
+// Update a record
+await dataverseAPI.update("account", result.id, {
+    name: "Updated Account Name",
+    description: "Updated description",
+});
 
-    -   Returns metadata about a specific tool by its id.
+// Delete a record
+await dataverseAPI.delete("account", result.id);
+```
 
--   loadTool(packageName: string): Promise<ToolBox.Tool>
+### FetchXML Queries
 
-    -   Loads a tool (initializes/activates) by npm package name.
+```typescript
+const fetchXml = `
+<fetch top="10">
+  <entity name="account">
+    <attribute name="name" />
+    <attribute name="emailaddress1" />
+    <filter>
+      <condition attribute="statecode" operator="eq" value="0" />
+    </filter>
+    <order attribute="name" />
+  </entity>
+</fetch>
+`;
+
+const result = await dataverseAPI.fetchXmlQuery(fetchXml);
+console.log(`Found ${result.value.length} records`);
+result.value.forEach((record) => {
+    console.log(record.name);
+});
+```
 
--   unloadTool(toolId: string): Promise<void>
+### Metadata Operations
 
-    -   Unloads a tool instance by its id.
+```typescript
+// Get entity metadata
+const metadata = await dataverseAPI.getEntityMetadata("account");
+console.log("Display Name:", metadata.DisplayName?.LocalizedLabels[0]?.Label);
+console.log("Attributes:", metadata.Attributes?.length);
+
+// Get all entities
+const allEntities = await dataverseAPI.getAllEntitiesMetadata();
+console.log(`Total entities: ${allEntities.value.length}`);
+```
 
--   installTool(packageName: string): Promise<ToolBox.Tool>
+### Execute Actions/Functions
 
-    -   Installs a tool from npm (and registers it with the ToolBox).
+```typescript
+// Execute WhoAmI function
+const whoAmI = await dataverseAPI.execute({
+    operationName: "WhoAmI",
+    operationType: "function",
+});
+console.log("User ID:", whoAmI.UserId);
+
+// Execute bound action
+const result = await dataverseAPI.execute({
+    entityName: "account",
+    entityId: accountId,
+    operationName: "CalculateRollupField",
+    operationType: "action",
+    parameters: {
+        FieldName: "total_revenue",
+    },
+});
+```
 
--   uninstallTool(packageName: string, toolId: string): Promise<void>
+## API Reference
 
-    -   Uninstalls a previously installed tool and removes it from the ToolBox.
+The Power Platform Tool Box exposes two main APIs to tools:
 
--   getToolWebviewHtml(packageName: string, connectionUrl?: string, accessToken?: string): Promise<string | null>
+### ToolBox API (`window.toolboxAPI`)
 
-    -   Returns an HTML string suitable for a tool's webview. Optional connection credentials can be passed for bootstrapping.
+Core platform features organized into namespaces:
 
--   getToolContext(): Promise<ToolBox.ToolContext>
-    -   Returns the current tool context including `toolId`, `connectionUrl`, and `accessToken` when available.
+#### Connections
 
-### Tool Settings
+-   **getActiveConnection()**: Promise<DataverseConnection | null>
+    -   Returns the currently active Dataverse connection or null if none is active
 
--   getToolSettings(toolId: string): Promise<any>
+#### Utils
 
-    -   Returns tool-scoped settings for the specified tool id.
+-   **showNotification(options: NotificationOptions)**: Promise<void>
 
--   updateToolSettings(toolId: string, settings: any): Promise<void>
-    -   Merges and persists tool-scoped settings for the specified tool id.
+    -   Displays a ToolBox notification. `options.type` supports `info | success | warning | error` and `duration` in ms (0 = persistent)
 
-### Notifications
+-   **copyToClipboard(text: string)**: Promise<void>
 
--   showNotification(options: ToolBox.NotificationOptions): Promise<void>
-    -   Displays a ToolBox notification. `options.type` supports `info | success | warning | error` and `duration` in ms (0 = persistent).
+    -   Copies the provided text into the system clipboard
 
-### Clipboard
+-   **saveFile(defaultPath: string, content: any)**: Promise<string | null>
 
--   copyToClipboard(text: string): Promise<void>
-    -   Copies the provided text into the system clipboard.
+    -   Opens a save dialog and writes the content. Returns the saved file path or null if canceled
 
-### File operations
+-   **getCurrentTheme()**: Promise<"light" | "dark">
+    -   Returns the current UI theme setting
 
--   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
 
-### Terminal operations
+-   **create(options: TerminalOptions)**: Promise<Terminal>
 
--   createTerminal(toolId: string, options: ToolBox.TerminalOptions): Promise<ToolBox.Terminal>
+    -   Creates a new terminal attached to the tool (tool ID is auto-determined)
 
-    -   Creates a new terminal attached to the tool with the given options (name, shell, cwd, env).
+-   **execute(terminalId: string, command: string)**: Promise<TerminalCommandResult>
 
--   executeTerminalCommand(terminalId: string, command: string): Promise<ToolBox.TerminalCommandResult>
+    -   Executes a command in the specified terminal and returns its result
 
-    -   Executes a command in the specified terminal and returns its result.
+-   **close(terminalId: string)**: Promise<void>
 
--   closeTerminal(terminalId: string): Promise<void>
+    -   Closes the specified terminal
 
-    -   Closes the specified terminal.
+-   **get(terminalId: string)**: Promise<Terminal | undefined>
 
--   getTerminal(terminalId: string): Promise<ToolBox.Terminal | undefined>
+    -   Gets a single terminal by id, if it exists
 
-    -   Gets a single terminal by id, if it exists.
+-   **list()**: Promise<Terminal[]>
 
--   getToolTerminals(toolId: string): Promise<ToolBox.Terminal[]>
+    -   Lists all terminals created by this tool
 
-    -   Lists all terminals created by a specific tool.
+-   **setVisibility(terminalId: string, visible: boolean)**: Promise<void>
+    -   Shows or hides the terminal UI for the specified terminal id
 
--   getAllTerminals(): Promise<ToolBox.Terminal[]>
+#### Events
 
-    -   Lists all existing terminals managed by the ToolBox.
+-   **getHistory(limit?: number)**: Promise<ToolBoxEventPayload[]>
 
--   setTerminalVisibility(terminalId: string, visible: boolean): Promise<void>
-    -   Shows or hides the terminal UI for the specified terminal id.
+    -   Returns recent ToolBox events for this tool, newest first. Use `limit` to cap the number of entries
 
-### Events
+-   **on(callback: (event: any, payload: ToolBoxEventPayload) => void)**: void
 
--   getEventHistory(limit?: number): Promise<ToolBox.ToolBoxEventPayload[]>
+    -   Subscribes to ToolBox events
+    -   Events available:
+        -   `tool:loaded` - A tool has been loaded
+        -   `tool:unloaded` - A tool has been unloaded
+        -   `connection:created` - A new connection was created
+        -   `connection:updated` - An existing connection was updated
+        -   `connection:deleted` - A connection was deleted
+        -   `notification:shown` - A notification was displayed
+        -   `terminal:created` - A new terminal was created
+        -   `terminal:closed` - A terminal was closed
+        -   `terminal:output` - Terminal produced output
+        -   `terminal:command:completed` - A terminal command finished executing
+        -   `terminal:error` - A terminal error occurred
 
-    -   Returns recent ToolBox events, newest first. Use `limit` to cap the number of entries.
+-   **off(callback: (event: any, payload: ToolBoxEventPayload) => void)**: void
+    -   Removes a previously registered event listener
 
--   onToolboxEvent(callback: (event: any, payload: ToolBox.ToolBoxEventPayload) => void): void
+### Dataverse API (`window.dataverseAPI`)
 
-    -   Subscribes to ToolBox events (e.g., `tool:loaded`, `connection:updated`, `terminal:output`).
+Complete HTTP client for interacting with Microsoft Dataverse:
 
--   removeToolboxEventListener(callback: (event: any, payload: ToolBox.ToolBoxEventPayload) => void): void
-    -   Removes a previously registered event listener.
+#### CRUD Operations
 
-### Auto-update
+-   **create(entityLogicalName: string, record: Record<string, unknown>)**: Promise<{id: string, ...}>
 
--   checkForUpdates(): Promise<void>
+    -   Creates a new record in Dataverse
+    -   Returns the created record ID and any returned fields
 
-    -   Triggers an update check.
+-   **retrieve(entityLogicalName: string, id: string, columns?: string[])**: Promise<Record<string, unknown>>
 
--   downloadUpdate(): Promise<void>
+    -   Retrieves a single record by ID
+    -   Optional columns array to select specific fields
 
-    -   Starts downloading an available update.
+-   **update(entityLogicalName: string, id: string, record: Record<string, unknown>)**: Promise<void>
 
--   quitAndInstall(): Promise<void>
+    -   Updates an existing record
 
-    -   Quits the app and installs a downloaded update.
+-   **delete(entityLogicalName: string, id: string)**: Promise<void>
+    -   Deletes a record
 
--   getAppVersion(): Promise<string>
+#### Query Operations
 
-    -   Returns the current application version.
+-   **fetchXmlQuery(fetchXml: string)**: Promise<{value: Record<string, unknown>[], ...}>
 
--   onUpdateChecking(callback: () => void): void
+    -   Executes a FetchXML query
+    -   Returns object with value array containing matching records
 
-    -   Called when an update check has started.
+-   **retrieveMultiple(fetchXml: string)**: Promise<{value: Record<string, unknown>[], ...}>
+    -   Alias for fetchXmlQuery for backward compatibility
 
--   onUpdateAvailable(callback: (info: any) => void): void
+#### Metadata Operations
 
-    -   Called when an update is available; `info` provides update metadata.
+-   **getEntityMetadata(entityLogicalName: string)**: Promise<EntityMetadata>
 
--   onUpdateNotAvailable(callback: () => void): void
+    -   Retrieves metadata for a specific entity
 
-    -   Called when no updates are available.
+-   **getAllEntitiesMetadata()**: Promise<{value: EntityMetadata[]}>
+    -   Retrieves metadata for all entities
 
--   onUpdateDownloadProgress(callback: (progress: any) => void): void
+#### Advanced Operations
 
-    -   Called periodically with download progress information.
+-   **execute(request: ExecuteRequest)**: Promise<Record<string, unknown>>
+    -   Executes a Dataverse Web API action or function
+    -   Supports both bound and unbound operations
 
--   onUpdateDownloaded(callback: (info: any) => void): void
+### Security Notes
 
-    -   Called once an update has been downloaded and is ready to install.
+-   **Access Tokens**: Tools do NOT have direct access to access tokens. All Dataverse operations are authenticated automatically by the platform.
+-   **Connection Context**: Tools only receive the connection URL, not sensitive credentials.
+-   **Secure Storage**: All tokens and secrets are encrypted and managed by the platform.
 
--   onUpdateError(callback: (error: string) => void): void
-    -   Called when an update-related error occurs.
+For detailed examples and best practices, see the [Dataverse API Documentation](../docs/DATAVERSE_API.md).
 
 ## Publishing the package to npm
 

package/dataverseAPI.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Power Platform Tool Box - Dataverse API Type Definitions
+ *
+ * Dataverse Web API exposed to tools via window.dataverseAPI
+ */
+
+declare namespace DataverseAPI {
+    /**
+     * FetchXML query result
+     */
+    export interface FetchXmlResult {
+        value: Record<string, unknown>[];
+        "@odata.context"?: string;
+        "@Microsoft.Dynamics.CRM.fetchxmlpagingcookie"?: string;
+    }
+
+    /**
+     * Entity metadata response
+     */
+    export interface EntityMetadata {
+        MetadataId: string;
+        LogicalName: string;
+        DisplayName?: {
+            LocalizedLabels: Array<{ Label: string; LanguageCode: number }>;
+        };
+        Attributes?: unknown[];
+        [key: string]: unknown;
+    }
+
+    /**
+     * Entity metadata collection response
+     */
+    export interface EntityMetadataCollection {
+        value: EntityMetadata[];
+    }
+
+    /**
+     * Record creation result
+     */
+    export interface CreateResult {
+        id: string;
+        [key: string]: unknown;
+    }
+
+    /**
+     * Execute operation request
+     */
+    export interface ExecuteRequest {
+        /**
+         * Name of the action or function to execute
+         */
+        operationName: string;
+
+        /**
+         * Type of operation - action or function
+         */
+        operationType: "action" | "function";
+
+        /**
+         * Entity logical name for bound operations
+         */
+        entityName?: string;
+
+        /**
+         * Record ID for bound operations
+         */
+        entityId?: string;
+
+        /**
+         * Parameters to pass to the operation
+         */
+        parameters?: Record<string, unknown>;
+    }
+
+    /**
+     * Dataverse Web API for CRUD operations, queries, and metadata
+     */
+    export interface API {
+        /**
+         * Create a new record in Dataverse
+         *
+         * @param entityLogicalName - Logical name of the entity (e.g., 'account', 'contact')
+         * @param record - Record data to create
+         * @returns Object containing the created record ID and any returned fields
+         *
+         * @example
+         * const result = await dataverseAPI.create('account', {
+         *     name: 'Contoso Ltd',
+         *     emailaddress1: 'info@contoso.com',
+         *     telephone1: '555-0100'
+         * });
+         * console.log('Created account ID:', result.id);
+         */
+        create: (entityLogicalName: string, record: Record<string, unknown>) => Promise<CreateResult>;
+
+        /**
+         * Retrieve a single record by ID
+         *
+         * @param entityLogicalName - Logical name of the entity
+         * @param id - GUID of the record
+         * @param columns - Optional array of column names to retrieve (retrieves all if not specified)
+         * @returns Object containing the requested record
+         *
+         * @example
+         * const account = await dataverseAPI.retrieve(
+         *     'account',
+         *     'guid-here',
+         *     ['name', 'emailaddress1', 'telephone1']
+         * );
+         * console.log('Account name:', account.name);
+         */
+        retrieve: (entityLogicalName: string, id: string, columns?: string[]) => Promise<Record<string, unknown>>;
+
+        /**
+         * Update an existing record
+         *
+         * @param entityLogicalName - Logical name of the entity
+         * @param id - GUID of the record
+         * @param record - Fields to update
+         *
+         * @example
+         * await dataverseAPI.update('account', 'guid-here', {
+         *     name: 'Updated Account Name',
+         *     description: 'Updated description'
+         * });
+         */
+        update: (entityLogicalName: string, id: string, record: Record<string, unknown>) => Promise<void>;
+
+        /**
+         * Delete a record
+         *
+         * @param entityLogicalName - Logical name of the entity
+         * @param id - GUID of the record
+         *
+         * @example
+         * await dataverseAPI.delete('account', 'guid-here');
+         */
+        delete: (entityLogicalName: string, id: string) => Promise<void>;
+
+        /**
+         * Execute a FetchXML query
+         *
+         * @param fetchXml - FetchXML query string
+         * @returns Object with value array containing matching records
+         *
+         * @example
+         * const fetchXml = `
+         * <fetch top="10">
+         *   <entity name="account">
+         *     <attribute name="name" />
+         *     <attribute name="emailaddress1" />
+         *     <filter>
+         *       <condition attribute="statecode" operator="eq" value="0" />
+         *     </filter>
+         *     <order attribute="name" />
+         *   </entity>
+         * </fetch>
+         * `;
+         *
+         * const result = await dataverseAPI.fetchXmlQuery(fetchXml);
+         * console.log(`Found ${result.value.length} records`);
+         * result.value.forEach(record => {
+         *     console.log(record.name);
+         * });
+         */
+        fetchXmlQuery: (fetchXml: string) => Promise<FetchXmlResult>;
+
+        /**
+         * Retrieve multiple records (alias for fetchXmlQuery for backward compatibility)
+         *
+         * @param fetchXml - FetchXML query string
+         * @returns Object with value array containing matching records
+         */
+        retrieveMultiple: (fetchXml: string) => Promise<FetchXmlResult>;
+
+        /**
+         * Execute a Dataverse Web API action or function
+         *
+         * @param request - Execute request configuration
+         * @returns Object containing the operation result
+         *
+         * @example
+         * // Execute WhoAmI function
+         * const result = await dataverseAPI.execute({
+         *     operationName: 'WhoAmI',
+         *     operationType: 'function'
+         * });
+         * console.log('User ID:', result.UserId);
+         *
+         * @example
+         * // Execute bound action
+         * const result = await dataverseAPI.execute({
+         *     entityName: 'account',
+         *     entityId: 'guid-here',
+         *     operationName: 'CalculateRollupField',
+         *     operationType: 'action',
+         *     parameters: {
+         *         FieldName: 'total_revenue'
+         *     }
+         * });
+         */
+        execute: (request: ExecuteRequest) => Promise<Record<string, unknown>>;
+
+        /**
+         * Get metadata for a specific entity
+         *
+         * @param entityLogicalName - Logical name of the entity
+         * @returns Object containing entity metadata
+         *
+         * @example
+         * const metadata = await dataverseAPI.getEntityMetadata('account');
+         * console.log('Display Name:', metadata.DisplayName?.LocalizedLabels[0]?.Label);
+         * console.log('Attributes:', metadata.Attributes?.length);
+         */
+        getEntityMetadata: (entityLogicalName: string) => Promise<EntityMetadata>;
+
+        /**
+         * Get metadata for all entities
+         *
+         * @returns Object with value array containing all entity metadata
+         *
+         * @example
+         * const allEntities = await dataverseAPI.getAllEntitiesMetadata();
+         * console.log(`Total entities: ${allEntities.value.length}`);
+         * allEntities.value.forEach(entity => {
+         *     console.log(`${entity.LogicalName} - ${entity.DisplayName?.LocalizedLabels[0]?.Label}`);
+         * });
+         */
+        getAllEntitiesMetadata: () => Promise<EntityMetadataCollection>;
+    }
+}
+
+/**
+ * Global window interface extension for Dataverse API
+ */
+declare global {
+    interface Window {
+        /**
+         * Dataverse Web API for interacting with Microsoft Dataverse
+         */
+        dataverseAPI: DataverseAPI.API;
+    }
+}
+
+export = DataverseAPI;
+export as namespace DataverseAPI;

package/index.d.ts

@@ -1,183 +1,22 @@
 /**
  * Power Platform Tool Box API Type Definitions
  *
- * Tools running in ToolBox webviews can access the ToolBox API via window.toolboxAPI
+ * This is the main entry point for TypeScript type definitions.
+ * Tools can reference specific APIs they need:
+ *
+ * For ToolBox API:
+ * /// <reference types="@pptb/types/toolboxAPI" />
+ *
+ * For Dataverse API:
+ * /// <reference types="@pptb/types/dataverseAPI" />
+ *
+ * Or reference all:
+ * /// <reference types="@pptb/types" />
  */
 
-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;
-    }
-}
+/// <reference path="./toolboxAPI.d.ts" />
+/// <reference path="./dataverseAPI.d.ts" />
 
-export = ToolBox;
-export as namespace ToolBox;
+// Re-export all namespaces for convenience
+export * from "./toolboxAPI";
+export * from "./dataverseAPI";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pptb/types",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "TypeScript type definitions for Power Platform Tool Box API",
   "main": "index.d.ts",
   "types": "index.d.ts",

package/toolboxAPI.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Power Platform Tool Box - ToolBox API Type Definitions
+ *
+ * Core ToolBox API exposed to tools via window.toolboxAPI
+ */
+
+declare namespace ToolBoxAPI {
+    /**
+     * Tool context containing connection information
+     * NOTE: accessToken is NOT included for security - tools must use dataverseAPI
+     */
+    export interface ToolContext {
+        toolId: string | null;
+        connectionUrl: 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>;
+        visible?: boolean; // Whether terminal should be visible initially (default: true)
+    }
+
+    /**
+     * 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;
+    }
+
+    /**
+     * Connections namespace - restricted access for tools
+     */
+    export interface ConnectionsAPI {
+        /**
+         * Get the currently active Dataverse connection
+         */
+        getActiveConnection: () => Promise<DataverseConnection | null>;
+    }
+
+    /**
+     * Utils namespace - utility functions for tools
+     */
+    export interface UtilsAPI {
+        /**
+         * Display a notification to the user
+         */
+        showNotification: (options: NotificationOptions) => Promise<void>;
+
+        /**
+         * Copy text to the system clipboard
+         */
+        copyToClipboard: (text: string) => Promise<void>;
+
+        /**
+         * Open a save file dialog and write content
+         */
+        saveFile: (defaultPath: string, content: any) => Promise<string | null>;
+
+        /**
+         * Get the current UI theme (light or dark)
+         */
+        getCurrentTheme: () => Promise<"light" | "dark">;
+    }
+
+    /**
+     * Terminal namespace - context-aware terminal operations
+     */
+    export interface TerminalAPI {
+        /**
+         * Create a new terminal (tool ID is auto-determined)
+         */
+        create: (options: TerminalOptions) => Promise<Terminal>;
+
+        /**
+         * Execute a command in a terminal
+         */
+        execute: (terminalId: string, command: string) => Promise<TerminalCommandResult>;
+
+        /**
+         * Close a terminal
+         */
+        close: (terminalId: string) => Promise<void>;
+
+        /**
+         * Get a terminal by ID
+         */
+        get: (terminalId: string) => Promise<Terminal | undefined>;
+
+        /**
+         * List all terminals for this tool
+         */
+        list: () => Promise<Terminal[]>;
+
+        /**
+         * Set terminal visibility
+         */
+        setVisibility: (terminalId: string, visible: boolean) => Promise<void>;
+    }
+
+    /**
+     * Events namespace - tool-specific event handling
+     */
+    export interface EventsAPI {
+        /**
+         * Get event history for this tool
+         */
+        getHistory: (limit?: number) => Promise<ToolBoxEventPayload[]>;
+
+        /**
+         * Subscribe to ToolBox events
+         */
+        on: (callback: (event: any, payload: ToolBoxEventPayload) => void) => void;
+
+        /**
+         * Unsubscribe from ToolBox events
+         */
+        off: (callback: (event: any, payload: ToolBoxEventPayload) => void) => void;
+    }
+
+    /**
+     * Settings namespace - context-aware tool settings
+     * All settings operations automatically use the current tool's ID
+     */
+    export interface SettingsAPI {
+        /**
+         * Get all settings for this tool
+         * @returns Promise resolving to an object with all settings (empty object if no settings exist)
+         */
+        getSettings: () => Promise<Record<string, any>>;
+
+        /**
+         * Get a specific setting by key
+         * @param key The setting key to retrieve
+         * @returns Promise resolving to the setting value, or undefined if not found
+         */
+        getSetting: (key: string) => Promise<any>;
+
+        /**
+         * Set a specific setting by key
+         * @param key The setting key to set
+         * @param value The value to store (can be any JSON-serializable value)
+         * @returns Promise that resolves when the setting is saved
+         */
+        setSetting: (key: string, value: any) => Promise<void>;
+
+        /**
+         * Set all settings (replaces entire settings object)
+         * @param settings The settings object to store
+         * @returns Promise that resolves when the settings are saved
+         */
+        setSettings: (settings: Record<string, any>) => Promise<void>;
+    }
+
+    /**
+     * Main ToolBox API exposed to tools via window.toolboxAPI
+     */
+    export interface API {
+        /**
+         * Connection-related operations (restricted)
+         */
+        connections: ConnectionsAPI;
+
+        /**
+         * Utility functions
+         */
+        utils: UtilsAPI;
+
+        /**
+         * Tool-specific settings (context-aware)
+         */
+        settings: SettingsAPI;
+
+        /**
+         * Terminal operations (context-aware)
+         */
+        terminal: TerminalAPI;
+
+        /**
+         * Event handling (tool-specific)
+         */
+        events: EventsAPI;
+
+        /**
+         * Get the current tool context
+         * @internal Used internally by the framework
+         */
+        getToolContext: () => Promise<ToolContext>;
+    }
+
+    /**
+     * Auto-update event handlers
+     */
+    export interface UpdateHandlers {
+        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 {
+        /**
+         * The organized ToolBox API for tools
+         */
+        toolboxAPI: ToolBoxAPI.API;
+
+        /**
+         * Tool context available at startup
+         */
+        TOOLBOX_CONTEXT?: ToolBoxAPI.ToolContext;
+    }
+}
+
+export = ToolBoxAPI;
+export as namespace ToolBoxAPI;