@pptb/types 1.2.7-beta.4 → 1.2.7-beta.5

package/README.md

@@ -256,6 +256,18 @@ The ToolBox API provides organized namespaces for different functionality:
 
 ### Connections
 
+Declare an exact count or range with `features.connections`, for example `3`, `{ "min": 0, "max": 3 }`, or `{ "min": 1, "max": 4 }`. Exact `0` means no connections. Counts are bounded to 0–10; object defaults are min 1 and max equal to the resolved min. Remove the deprecated `multiConnection` and `connectionRequirement` fields when migrating; existing legacy-only tools remain supported.
+
+```typescript
+const slots = await toolboxAPI.connections.getConnections();
+const third = await toolboxAPI.connections.getConnection(2);
+if (third) {
+    const records = await dataverseAPI.queryData("accounts?$select=name&$top=5", 2);
+}
+```
+
+Targets are zero-based; `"primary"` and `"secondary"` alias 0 and 1. Null slots retain their positions, so never filter the array before routing requests. `getSecondaryConnection()` is deprecated but supported; use `getConnection(1)` or `(await getConnections())[1]`. See the [connection-slot author guide](https://github.com/PowerPlatformToolBox/desktop-app/blob/main/docs/N_CONNECTION_TOOL_AUTHOR_GUIDE.md) for migration and lifecycle examples.
+
 ```typescript
 // Get the active Dataverse connection
 const connection = await toolboxAPI.connections.getActiveConnection();
@@ -690,6 +702,13 @@ Core platform features organized into namespaces:
 
 #### Connections
 
+- **getConnections()**: Promise<Array<Connection | null>>
+    - Returns configured slots, preserving null gaps; not necessarily padded to the declared maximum.
+- **getConnection(target: "primary" | "secondary" | number)**: Promise<Connection | null>
+    - Gets one slot by zero-based index or legacy alias. Unassigned slots return null; negative/fractional targets reject.
+- **getSecondaryConnection()**: Promise<Connection | null>
+    - Deprecated compatibility adapter; prefer `getConnection("secondary")`.
+
 - **getActiveConnection()**: Promise<Connection | null>
     - Returns the currently active connection or null if none is active
     - Includes `enabledForPowerPlatformAPI` so tools can decide whether to use Power Platform API
@@ -784,7 +803,7 @@ Core platform features organized into namespaces:
 - **launchTool(targetToolId, prefillData?, options?)**: Promise\<unknown\>
     - Launches the specified tool, optionally with prefill data
     - Returns a Promise that resolves with the data returned by the callee, or `null` if it closes without returning or the user clicks the "Return to Caller" banner
-    - The callee automatically inherits the caller's FXS connection; pass `options.primaryConnectionId` to override
+    - The callee inherits the caller's full positional connection array, bounded by its declared maximum; `options.connectionIds` replaces the array and legacy overrides affect only slots 0/1
     - Only one active callee per caller is allowed; throws `"A callee invocation is already in progress"` if a callee is already open
     - Pass `options.noReturn: true` for one-way "Send To" flows; the banner is suppressed entirely for the callee
 
@@ -835,13 +854,13 @@ Complete HTTP client for interacting with Microsoft Dataverse:
     - Supports both bound and unbound operations
 - **publishCustomizations(tableLogicalName?: string)**: Promise<void>
     - Publishes pending customizations. When `tableLogicalName` is omitted it runs PublishAllXml; otherwise it publishes only the specified table.
-- **deploySolution(base64SolutionContent: string | ArrayBuffer | ArrayBufferView, options?: DeploySolutionOptions, connectionTarget?: "primary" | "secondary")**: Promise<{ImportJobId: string}>
+- **deploySolution(base64SolutionContent: string | ArrayBuffer | ArrayBufferView, options?: DeploySolutionOptions, connectionTarget?: "primary" | "secondary" | number)**: Promise<{ImportJobId: string}>
     - Deploys (imports) a solution to the Dataverse environment
     - Accepts either a base64-encoded solution zip string or raw binary data (Buffer, ArrayBuffer, Uint8Array)
     - Always supplies `PublishWorkflows` and `OverwriteUnmanagedCustomizations` booleans to Dataverse, defaulting to `false` when you omit them
     - Supports optional parameters for customizing the import (publishWorkflows, overwriteUnmanagedCustomizations, skipProductUpdateDependencies, convertToManaged)
     - Returns an ImportJobId for tracking the import progress
-- **getImportJobStatus(importJobId: string, connectionTarget?: "primary" | "secondary")**: Promise<Record<string, unknown>>
+- **getImportJobStatus(importJobId: string, connectionTarget?: "primary" | "secondary" | number)**: Promise<Record<string, unknown>>
     - Gets the status of a solution import job
     - Returns import job details including progress, completion status, and error information
     - Use to track the progress of a solution deployment initiated with deploySolution
@@ -852,6 +871,8 @@ Generic HTTP client for Power Platform Admin APIs covering all categories:
 
 #### Category Methods
 
+`connectionTarget` accepts zero-based numeric slots plus `"primary"` / `"secondary"`. For example, `powerplatformAPI.PowerApps.Get("apps", 2)` routes to slot 3. Calling an API with an unassigned slot returns a missing-connection error.
+
 Each category (Analytics, AppManagement, Authorization, Connectivity, CopilotStudio, Dynamics, EnvironmentManagement, Governance, Licensing, PowerApps, PowerAutomate, PowerPages, ResourceQuery, UserManagement, WorkflowAgents) exposes:
 
 - **Get(path?, connectionTarget?, headers?)**: Promise<PowerPlatformResponse>

package/package.json

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

package/pptbConfig.d.ts

@@ -174,15 +174,40 @@ export interface InvocationConfig {
 }
 
 /**
- * The shape of a tool's `pptb.config.json` file.
- *
- * This file lives alongside `package.json` in the tool's package root.
- * All sections are optional; the file itself is optional.  When present it
- * is validated by `pptb-validate` in addition to `package.json`.
+ * Author-facing runtime policy. Latest maps to native LatestMajor in later runtime work.
  */
+export type WorkerRollForward = "Disable" | "Latest" | "Minor" | "Major";
+export type WorkerTargetFramework = "net8.0" | "net9.0" | "net10.0";
+export type WorkerPlatform = "all" | "windows-x64" | "windows-arm64" | "macos-x64" | "macos-arm64" | "linux-x64" | "linux-arm64";
+
+/** Declarative metadata only; no worker execution API is available yet. */
+export interface WorkerDeclaration {
+    kind: "dotnet-tool";
+    packageId: string;
+    /** Exact NuGet version; ranges, floating versions and tags are forbidden. */
+    packageVersion: string;
+    command: string;
+    dotnet: {
+        targetFramework: WorkerTargetFramework;
+        /** Stable major.minor.patch matching the executable target framework. */
+        minimumRuntimeVersion: string;
+        /** Defaults to Major when omitted. Explicit null/empty/unknown values are invalid. */
+        rollForward?: WorkerRollForward;
+    };
+    /** Required unique aliases; all must appear alone and names the versioned officially supported PPTB platform matrix. */
+    platforms: WorkerPlatform[];
+}
+
+export interface NormalizedWorkerDeclaration extends WorkerDeclaration {
+    dotnet: WorkerDeclaration["dotnet"] & { rollForward: WorkerRollForward };
+}
+
+/** Optional package-root config, validated alongside package.json by pptb-validate. */
 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;
+    /** Native worker declarations keyed by stable ID. Requires package.json features.minAPI. */
+    workers?: Record<string, WorkerDeclaration>;
 }

package/toolboxAPI.d.ts

@@ -169,6 +169,34 @@ declare namespace ToolBoxAPI {
         error?: string;
     }
 
+    const workerHandleBrand: unique symbol;
+    export type WorkerHandle = string & { readonly [workerHandleBrand]: true };
+
+    export type WorkerRpcMessage =
+        | { jsonrpc: "2.0"; method: string; id?: string | number; params?: unknown[] | Record<string, unknown> }
+        | { jsonrpc: "2.0"; id: string | number | null; result: unknown }
+        | { jsonrpc: "2.0"; id: string | number | null; error: { code: number; message: string; data?: unknown } };
+
+    export interface WorkerSnapshot {
+        state: "starting" | "running" | "stopping" | "exited" | "failed";
+        failure?: string;
+        stderr: { bytes: number; truncated: boolean; summary: "Worker stderr redacted" };
+    }
+
+    export interface WorkerStart {
+        handle: WorkerHandle;
+        ready: Promise<void>;
+    }
+
+    export interface WorkersAPI {
+        start(workerId: string): Promise<WorkerStart>;
+        send(handle: WorkerHandle, message: WorkerRpcMessage): Promise<void>;
+        onMessage(handle: WorkerHandle, callback: (message: WorkerRpcMessage) => void): () => void;
+        onExit(handle: WorkerHandle, callback: (snapshot: WorkerSnapshot) => void): () => void;
+        stop(handle: WorkerHandle): Promise<void>;
+        dispose(handle: WorkerHandle): Promise<void>;
+    }
+
     /**
      * Connections namespace - restricted access for tools
      */
@@ -179,7 +207,7 @@ declare namespace ToolBoxAPI {
         getActiveConnection: () => Promise<Connection | null>;
 
         /**
-         * @deprecated Use `getConnection("secondary")` or `getConnections()[1]` for slot-aware connection access.
+         * @deprecated Use `getConnection("secondary")` or `(await getConnections())[1]` for slot-aware connection access.
          */
         getSecondaryConnection: () => Promise<Connection | null>;
 
@@ -406,6 +434,9 @@ declare namespace ToolBoxAPI {
      * Main ToolBox API exposed to tools via window.toolboxAPI
      */
     export interface API {
+        /** Start and communicate with a worker declared by this tool's manifest. */
+        workers: WorkersAPI;
+
         /**
          * Connection-related operations (restricted)
          */