@pptb/types 1.2.4-beta.5 → 1.2.4

package/README.md

@@ -21,6 +21,7 @@ TypeScript type definitions for Power Platform ToolBox APIs, plus a built-in CLI
         - [Inter-Tool Invocation](#inter-tool-invocation)
             - [Caller: launching another tool with prefill data](#caller-launching-another-tool-with-prefill-data)
             - [Caller: tag-based capability discovery](#caller-tag-based-capability-discovery)
+            - [Caller: tag-based capability discovery](#caller-tag-based-capability-discovery-1)
             - [Callee: reading prefill data and returning a result](#callee-reading-prefill-data-and-returning-a-result)
             - [Declaring your invocation contract](#declaring-your-invocation-contract)
     - [Dataverse API Examples](#dataverse-api-examples)
@@ -128,21 +129,26 @@ The validator checks every field that the official review pipeline inspects:
 
 In addition to `package.json`, the validator automatically checks a `pptb.config.json` file if one is present in the same directory. This file declares tool-to-tool communication contracts and other PPTB-specific metadata.
 
-| Field                               | Required | Rules                                                                                                                                            |
-| ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `invocation.version`                | ✅\*\*   | Must be a valid **semantic version** string (e.g. `"1.0.0"`). Tool developers own this version and bump it when the invocation contract changes. |
-| `invocation.capabilities`           | ❌       | Array of non-empty string tags (e.g. `["entity-picker"]`). Used by callers to discover this tool via `findToolsByCapability`.                    |
-| `invocation.prefill`                | ❌       | JSON-schema-style object describing data callers can pre-populate                                                                                |
-| `invocation.prefill.properties`     | ❌       | Map of property names to `{ type?, enum?, items? }` descriptors                                                                                  |
-| `invocation.returnTopic`            | ❌       | JSON-schema-style object describing the data this tool returns to its caller                                                                     |
-| `invocation.returnTopic.properties` | ❌       | Map of property names to `{ type?, enum?, items? }` descriptors                                                                                  |
+| Field                               | Required | Rules                                                                                                                                                       |
+| ----------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `invocation.version`                | ✅\*\*   | Must be a valid **semantic version** string (e.g. `"1.0.0"`). Tool developers own this version and bump it when the invocation contract changes.            |
+| `invocation.capabilities`           | ❌       | Array of non-empty string tags (e.g. `["entity-picker"]`). Used by callers to discover this tool via `findToolsByCapability`.                               |
+| `invocation.prefill`                | ❌       | JSON-schema-style object describing data callers can pre-populate                                                                                           |
+| `invocation.prefill.properties`     | ❌       | Map of property names to `{ type?, enum?, items? }` descriptors                                                                                             |
+| `invocation.returnTopic`            | ❌       | JSON-schema-style object describing the data this tool returns to its caller                                                                                |
+| `invocation.returnTopic.properties` | ❌       | Map of property names to `{ type?, enum?, items? }` descriptors                                                                                             |
+| `agents`                            | ❌       | Top-level agent contract for external automation; when present, must include `version` and may include `invokable`, `modes`, `defaultMode`, and `timeoutMS` |
+| `agents.version`                    | ✅       | Must be a valid semantic version string (e.g. `1.0.0`)                                                                                                      |
+| `agents.invokable`                  | ❌       | Boolean indicating whether an external (non-PPTB) automation agent may launch this tool programmatically                                                    |
+| `agents.modes`                      | ❌       | Array of supported invocation modes (`"one-way"`, `"two-way"`)                                                                                              |
+| `agents.defaultMode`                | ❌       | Default mode when the agent does not request one explicitly                                                                                                 |
+| `agents.timeoutMS`                  | ❌       | Optional timeout hint in milliseconds for two-way calls                                                                                                     |
 
 > \*\* Required only when the `invocation` object is present.
 
 **Example `pptb.config.json`:**
 
 ```json
-{
     "invocation": {
         "version": "1.0.0",
         "capabilities": ["entity-picker"],
@@ -159,6 +165,13 @@ In addition to `package.json`, the validator automatically checks a `pptb.config
                 "error": { "type": "string" }
             }
         }
+    },
+    "agents": {
+        "version": "1.0.0",
+        "invokable": true,
+        "modes": ["one-way", "two-way"],
+        "defaultMode": "two-way",
+        "timeoutMS": 12000
     }
 }
 ```
@@ -329,6 +342,21 @@ if (result !== null) {
 
 #### Caller: tag-based capability discovery
 
+```typescript
+// Find all installed tools that declare the "entity-picker" capability
+const pickers = await toolboxAPI.invocation.findToolsByCapability("entity-picker");
+if (pickers.length > 0) {
+    const picker = pickers[0] as { id: string };
+    const result = await toolboxAPI.invocation.launchTool(picker.id, { entityName: "account" });
+} else {
+    // User dismissed the picker (closed window or clicked "Return to Caller" banner)
+}
+```
+
+> **One-at-a-time**: only one active callee per caller is supported. A second `launchTool` call while a callee is open throws `"A callee invocation is already in progress"`.
+
+#### Caller: tag-based capability discovery
+
 ```typescript
 // Find all installed tools that declare the "entity-picker" capability
 const pickers = await toolboxAPI.invocation.findToolsByCapability("entity-picker");

package/dataverseAPI.d.ts

@@ -1544,6 +1544,12 @@ declare global {
          */
         dataverseAPI: DataverseAPI.API;
     }
+    interface GlobalThis {
+        /**
+         * Dataverse Web API accessible to headless tools via globalThis
+         */
+        dataverseAPI: DataverseAPI.API;
+    }
 }
 
 export = DataverseAPI;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pptb/types",
-  "version": "1.2.4-beta.5",
+  "version": "1.2.4",
   "description": "Type definitions for Power Platform ToolBox APIs and validity checks for tool packages",
   "main": "index.d.ts",
   "types": "index.d.ts",

package/powerplatformAPI.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Power Platform ToolBox - Power Platform API Type Definitions
+ *
+ * Power Platform Admin APIs exposed to tools via window.powerplatformAPI
+ * https://learn.microsoft.com/en-us/rest/api/power-platform/
+ */
+
+declare namespace PowerPlatformAPI {
+    /**
+     * Power Platform API category response type
+     */
+    export interface PowerPlatformResponse {
+        [key: string]: unknown;
+    }
+
+    /**
+     * Generic HTTP method type
+     */
+    export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+    /**
+     * Power Platform API category client interface
+     * Provides generic HTTP methods for each API category
+     */
+    export interface CategoryClient {
+        /**
+         * Make a GET request to the category endpoint
+         * @param path Relative path after the category base URL (e.g., "environments/{environmentId}/apps/{app}?api-version=2024-10-01")
+         * @param connectionTarget Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
+         * @param headers Optional custom headers
+         */
+        Get: (path?: string, connectionTarget?: "primary" | "secondary", headers?: Record<string, string>) => Promise<PowerPlatformResponse>;
+
+        /**
+         * Make a POST request to the category endpoint
+         * @param path Relative path after the category base URL
+         * @param body Optional request body
+         * @param connectionTarget Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
+         * @param headers Optional custom headers
+         */
+        Post: (path?: string, body?: unknown, connectionTarget?: "primary" | "secondary", headers?: Record<string, string>) => Promise<PowerPlatformResponse>;
+
+        /**
+         * Make a PUT request to the category endpoint
+         * @param path Relative path after the category base URL
+         * @param body Optional request body
+         * @param connectionTarget Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
+         * @param headers Optional custom headers
+         */
+        Put: (path?: string, body?: unknown, connectionTarget?: "primary" | "secondary", headers?: Record<string, string>) => Promise<PowerPlatformResponse>;
+
+        /**
+         * Make a PATCH request to the category endpoint
+         * @param path Relative path after the category base URL
+         * @param body Optional request body
+         * @param connectionTarget Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
+         * @param headers Optional custom headers
+         */
+        Patch: (path?: string, body?: unknown, connectionTarget?: "primary" | "secondary", headers?: Record<string, string>) => Promise<PowerPlatformResponse>;
+
+        /**
+         * Make a DELETE request to the category endpoint
+         * @param path Relative path after the category base URL
+         * @param connectionTarget Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
+         * @param headers Optional custom headers
+         * @param body Optional request body (for DELETE with payload)
+         */
+        Delete: (path?: string, connectionTarget?: "primary" | "secondary", headers?: Record<string, string>, body?: unknown) => Promise<PowerPlatformResponse>;
+    }
+
+    /**
+     * Power Platform Analytics API
+     * https://api.powerplatform.com/analytics
+     */
+    export interface Analytics extends CategoryClient {}
+
+    /**
+     * Power Platform App Management API
+     * https://api.powerplatform.com/appmanagement
+     */
+    export interface AppManagement extends CategoryClient {}
+
+    /**
+     * Power Platform Authorization API
+     * https://api.powerplatform.com/authorization
+     */
+    export interface Authorization extends CategoryClient {}
+
+    /**
+     * Power Platform Connectivity API
+     * https://api.powerplatform.com/connectivity
+     */
+    export interface Connectivity extends CategoryClient {}
+
+    /**
+     * Power Platform Copilot Studio API
+     * https://api.powerplatform.com/copilotstudio
+     */
+    export interface CopilotStudio extends CategoryClient {}
+
+    /**
+     * Power Platform Dynamics API
+     * https://api.powerplatform.com/dynamics
+     */
+    export interface Dynamics extends CategoryClient {}
+
+    /**
+     * Power Platform Environment Management API
+     * https://api.powerplatform.com/environmentmanagement
+     */
+    export interface EnvironmentManagement extends CategoryClient {}
+
+    /**
+     * Power Platform Governance API
+     * https://api.powerplatform.com/governance
+     */
+    export interface Governance extends CategoryClient {}
+
+    /**
+     * Power Platform Licensing API
+     * https://api.powerplatform.com/licensing
+     */
+    export interface Licensing extends CategoryClient {}
+
+    /**
+     * Power Platform Power Apps API
+     * https://api.powerplatform.com/powerapps
+     */
+    export interface PowerApps extends CategoryClient {}
+
+    /**
+     * Power Platform Power Automate API
+     * https://api.powerplatform.com/powerautomate
+     */
+    export interface PowerAutomate extends CategoryClient {}
+
+    /**
+     * Power Platform Power Pages API
+     * https://api.powerplatform.com/powerpages
+     */
+    export interface PowerPages extends CategoryClient {}
+
+    /**
+     * Power Platform Resource Query API
+     * https://api.powerplatform.com/resourcequery
+     */
+    export interface ResourceQuery extends CategoryClient {}
+
+    /**
+     * Power Platform User Management API
+     * https://api.powerplatform.com/usermanagement
+     */
+    export interface UserManagement extends CategoryClient {}
+
+    /**
+     * Power Platform Workflow Agents API
+     * https://api.powerplatform.com/workflowagents
+     */
+    export interface WorkflowAgents extends CategoryClient {}
+
+    /**
+     * Main Power Platform API interface
+     * Each category exposes generic HTTP methods (Get, Post, Put, Patch, Delete)
+     */
+    export interface API {
+        Analytics: Analytics;
+        AppManagement: AppManagement;
+        Authorization: Authorization;
+        Connectivity: Connectivity;
+        CopilotStudio: CopilotStudio;
+        Dynamics: Dynamics;
+        EnvironmentManagement: EnvironmentManagement;
+        Governance: Governance;
+        Licensing: Licensing;
+        PowerApps: PowerApps;
+        PowerAutomate: PowerAutomate;
+        PowerPages: PowerPages;
+        ResourceQuery: ResourceQuery;
+        UserManagement: UserManagement;
+        WorkflowAgents: WorkflowAgents;
+    }
+}
+
+/**
+ * Global window interface extension for Power Platform API
+ */
+declare global {
+    interface GlobalThis {
+        /**
+         * Power Platform Admin API accessible to headless tools
+         */
+        powerplatformAPI: PowerPlatformAPI.API;
+    }
+
+    interface Window {
+        /**
+         * Power Platform Admin API accessible to tools
+         * @example
+         * // Get admin app from Power Apps
+         * const app = await powerplatformAPI.PowerApps.Get('environments/{environmentId}/apps/{app}?api-version=2024-10-01');
+         */
+        powerplatformAPI: PowerPlatformAPI.API;
+    }
+}
+
+export = PowerPlatformAPI;
+export as namespace PowerPlatformAPI;

package/pptbConfig.d.ts

@@ -25,6 +25,13 @@
  *         "error": { "type": "string" }
  *       }
  *     }
+ *   },
+ *   "agents": {
+ *     "version": "1.0.0",
+ *     "invokable": true,
+ *     "modes": ["one-way", "two-way"],
+ *     "defaultMode": "two-way",
+ *     "timeoutMS": 12000
  *   }
  * }
  * ```
@@ -49,14 +56,7 @@
  * | `plugin-inspector`   | Inspect or manage plugins and assemblies              |
  * | `pcf-control-builder`| Build or scaffold PCF controls                        |
  */
-export type KnownCapabilityTag =
-    | "fetchxml"
-    | "entity-picker"
-    | "record-selector"
-    | "solution-selector"
-    | "webresource-editor"
-    | "plugin-inspector"
-    | "pcf-control-builder";
+export type KnownCapabilityTag = "fetchxml" | "entity-picker" | "record-selector" | "solution-selector" | "webresource-editor" | "plugin-inspector" | "pcf-control-builder";
 
 /**
  * A capability tag string accepted by `invocation.capabilities` and
@@ -72,7 +72,7 @@ export type KnownCapabilityTag =
  * { "invocation": { "version": "1.0.0", "capabilities": ["fetchxml", "entity-picker"] } }
  * ```
  */
-export type CapabilityTag = KnownCapabilityTag | (string & {});
+export type CapabilityTag = KnownCapabilityTag | string;
 
 /** A JSON-schema-style property descriptor used inside invocation definitions. */
 export interface JsonSchemaProperty {
@@ -101,6 +101,30 @@ export interface JsonSchemaObject {
  * - `returnTopic` describes the data this tool will resolve back to its caller
  *   when it finishes.
  */
+export type AgentInvocationMode = "one-way" | "two-way";
+
+/**
+ * Agent-specific launch contract for external automation callers.
+ *
+ * - `version`: semantic version for the agent-facing contract.
+ * - `invokable`: opt-in flag that exposes the tool to the MCP server.
+ * - `modes`: supported MCP invocation modes for this tool.
+ * - `defaultMode`: fallback mode when the caller does not specify one.
+ * - `timeoutMS`: optional timeout hint, in milliseconds, for two-way calls.
+ */
+export interface AgentsConfig {
+    /** Semantic version of this agent contract. */
+    version: string;
+    /** Whether the tool may be invoked by an external agent. */
+    invokable?: boolean;
+    /** Invocation modes supported by the tool when called by an agent. */
+    modes?: AgentInvocationMode[];
+    /** Default mode used when an agent does not request a mode explicitly. */
+    defaultMode?: AgentInvocationMode;
+    /** Optional timeout hint, in milliseconds, for agent-driven two-way calls. */
+    timeoutMS?: number;
+}
+
 export interface InvocationConfig {
     /**
      * Semantic version of this invocation contract (e.g. "1.0.0").
@@ -142,4 +166,6 @@ export interface InvocationConfig {
 export interface PPTBConfig {
     /** Invocation contract – how this tool can be called by other tools. */
     invocation?: InvocationConfig;
+    /** Agent contract – how this tool can be called by external automation. */
+    agents?: AgentsConfig;
 }

package/toolboxAPI.d.ts

@@ -16,6 +16,18 @@ declare namespace ToolBoxAPI {
         connectionId?: string | null;
         secondaryConnectionUrl?: string | null;
         secondaryConnectionId?: string | null;
+        /**
+         * Invocation metadata injected by PPTB when the tool is launched by another
+         * tool or by the MCP server. Tools should treat this as optional and
+         * branch on `source`/`mode` rather than assuming it is always present.
+         */
+        invocationContext?: {
+            source?: "tool" | "mcp";
+            mode?: "one-way" | "two-way";
+            correlationId?: string;
+            timeoutMs?: number;
+            expectsResponse?: boolean;
+        };
     }
 
     /**
@@ -86,6 +98,7 @@ declare namespace ToolBoxAPI {
         environmentColor?: string;
         categoryColor?: string;
         enabledForPowerPlatformAPI?: boolean;
+        scopesForPowerPlatformAPI?: string[];
         createdAt?: string;
         lastUsedAt?: string;
         /**
@@ -461,16 +474,15 @@ declare namespace ToolBoxAPI {
         getLaunchContext: () => Promise<Record<string, unknown> | null>;
 
         /**
-         * Returns data back to the caller tool that launched this tool.
-         *
-         * The value resolves the `Promise` returned by the caller's
-         * `invocation.launchTool()` call.  **After calling `returnData`, PPTB
-         * automatically closes the callee window** — the callee does not need to
-         * close itself.
+         * Return data back to the tool that launched this one. If the tool was not
+         * launched by another tool, this is a no-op.
          *
-         * If this tool was not launched by another tool, the call is a no-op.
+         * For MCP launches, one-way mode may omit a payload entirely from the
+         * caller's response lifecycle, but the tool can still call `returnData()` to
+         * complete a local flow if it wants to.
          *
          * @param returnData The data to pass back to the caller
+         * @returns Promise that resolves when the data has been handed off
          */
         returnData: (returnData: Record<string, unknown>) => Promise<void>;
 
@@ -557,6 +569,19 @@ declare namespace ToolBoxAPI {
  * Global window interface extension for ToolBox tools
  */
 declare global {
+    interface GlobalThis {
+        /**
+         * The organized ToolBox API for headless tools.
+         * Windowed tools should continue to use window.toolboxAPI.
+         */
+        toolboxAPI: ToolBoxAPI.API;
+
+        /**
+         * Tool context available at startup
+         */
+        TOOLBOX_CONTEXT?: ToolBoxAPI.ToolContext;
+    }
+
     interface Window {
         /**
          * The organized ToolBox API for tools