@pptb/types 1.2.7-beta.1 → 1.2.7-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +45 -33
- package/dataverseAPI.d.ts +2 -1
- package/index.d.ts +2 -0
- package/package.json +2 -1
- package/powerplatformAPI.d.ts +6 -5
- package/pptbConfig.d.ts +14 -1
- package/toolManifest.d.ts +29 -0
- package/toolboxAPI.d.ts +16 -3
package/README.md
CHANGED
|
@@ -107,44 +107,56 @@ npx pptb-validate path/to/package.json
|
|
|
107
107
|
|
|
108
108
|
The validator checks every field that the official review pipeline inspects:
|
|
109
109
|
|
|
110
|
-
| Field | Required | Rules
|
|
111
|
-
| -------------------------------- | -------- |
|
|
112
|
-
| `name` | ✅ | Must be a string
|
|
113
|
-
| `version` | ✅ | Must be a string
|
|
114
|
-
| `displayName` | ✅ | Must be a string
|
|
115
|
-
| `description` | ✅ | Must be a string
|
|
116
|
-
| `license` | ✅ | Must be one of the approved OSS licenses (MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, GPL-2.0, GPL-3.0, LGPL-3.0, ISC, AGPL-3.0-only)
|
|
117
|
-
| `contributors` | ✅ | Non-empty array; each entry needs a `name`
|
|
118
|
-
| `configurations.repository` | ✅ | Valid, reachable URL
|
|
119
|
-
| `configurations.readmeUrl` | ✅ | Valid URL; must **not** be hosted on `github.com` (use `raw.githubusercontent.com`)
|
|
120
|
-
| `configurations.website` | ❌ | Valid, reachable URL when provided
|
|
121
|
-
| `configurations.funding` | ❌ | Valid, reachable URL when provided
|
|
122
|
-
| `icon` | ❌ | Relative path to a `.svg` file bundled under `dist/`; must not be an HTTP URL or an absolute path
|
|
123
|
-
| `cspExceptions` | ❌ | When present: must not be empty; only recognised directives; each directive must be a non-empty array
|
|
124
|
-
| `features.
|
|
125
|
-
| `features.
|
|
126
|
-
| `features.
|
|
127
|
-
|
|
128
|
-
|
|
110
|
+
| Field | Required | Rules |
|
|
111
|
+
| -------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
112
|
+
| `name` | ✅ | Must be a string |
|
|
113
|
+
| `version` | ✅ | Must be a string |
|
|
114
|
+
| `displayName` | ✅ | Must be a string |
|
|
115
|
+
| `description` | ✅ | Must be a string |
|
|
116
|
+
| `license` | ✅ | Must be one of the approved OSS licenses (MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, GPL-2.0, GPL-3.0, LGPL-3.0, ISC, AGPL-3.0-only) |
|
|
117
|
+
| `contributors` | ✅ | Non-empty array; each entry needs a `name` |
|
|
118
|
+
| `configurations.repository` | ✅ | Valid, reachable URL |
|
|
119
|
+
| `configurations.readmeUrl` | ✅ | Valid URL; must **not** be hosted on `github.com` (use `raw.githubusercontent.com`) |
|
|
120
|
+
| `configurations.website` | ❌ | Valid, reachable URL when provided |
|
|
121
|
+
| `configurations.funding` | ❌ | Valid, reachable URL when provided |
|
|
122
|
+
| `icon` | ❌ | Relative path to a `.svg` file bundled under `dist/`; must not be an HTTP URL or an absolute path |
|
|
123
|
+
| `cspExceptions` | ❌ | When present: must not be empty; only recognised directives; each directive must be a non-empty array |
|
|
124
|
+
| `features.connections` | ❌ | Number `0..10` for an exact count, or `{ min?, max? }` where `0 <= min <= max <= 10`; defaults to exactly one connection |
|
|
125
|
+
| `features.minAPI` | ❌ | Valid semver string when provided |
|
|
126
|
+
| `features.multiConnection` | ❌ | **Deprecated.** Legacy cardinality field; use `features.connections` instead. Required with legacy feature declarations only. |
|
|
127
|
+
| `features.connectionRequirement` | ❌ | **Deprecated.** Legacy required/optional field; use `features.connections` instead. |
|
|
128
|
+
|
|
129
|
+
Modern and legacy connection fields must not be combined. `connections: 0` means the tool never uses a connection; `{ "min": 0, "max": 1 }` means a connection is optional. Legacy fields remain supported for existing tools and produce a validation warning.
|
|
130
|
+
|
|
131
|
+
Examples:
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
{ "features": { "connections": 1 } }
|
|
135
|
+
{ "features": { "connections": { "min": 1, "max": 5 } } }
|
|
136
|
+
{ "features": { "connections": 0 } }
|
|
137
|
+
```
|
|
129
138
|
|
|
130
139
|
#### pptb.config.json (optional)
|
|
131
140
|
|
|
132
141
|
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.
|
|
133
142
|
|
|
134
|
-
| Field | Required | Rules
|
|
135
|
-
| ----------------------------------- | -------- |
|
|
136
|
-
| `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.
|
|
137
|
-
| `invocation.capabilities` | ❌ | Array of non-empty string tags (e.g. `["entity-picker"]`). Used by callers to discover this tool via `findToolsByCapability`.
|
|
138
|
-
| `invocation.prefill` | ❌ | JSON-schema-style object describing data callers can pre-populate
|
|
139
|
-
| `invocation.prefill.properties` | ❌ | Map of property names to `{ type?, enum?, items? }` descriptors
|
|
140
|
-
| `invocation.returnTopic` | ❌ | JSON-schema-style object describing the data this tool returns to its caller
|
|
141
|
-
| `invocation.returnTopic.properties` | ❌ | Map of property names to `{ type?, enum?, items? }` descriptors
|
|
142
|
-
| `agents` | ❌ | Top-level agent contract for external automation; when present, must include `version` and may include `invokable`, `modes`, `defaultMode`, and `
|
|
143
|
-
| `agents.version` | ✅ | Must be a valid semantic version string (e.g. `1.0.0`)
|
|
144
|
-
| `agents.invokable` | ❌ | Boolean indicating whether an external (non-PPTB) automation agent may launch this tool programmatically
|
|
145
|
-
| `agents.modes` | ❌ | Array of supported invocation modes (`"one-way"`, `"two-way"`)
|
|
146
|
-
| `agents.defaultMode` | ❌ | Default mode when the agent does not request one explicitly
|
|
147
|
-
| `agents.timeoutMS` | ❌ | Optional timeout hint in milliseconds for two-way calls
|
|
143
|
+
| Field | Required | Rules |
|
|
144
|
+
| ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
145
|
+
| `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. |
|
|
146
|
+
| `invocation.capabilities` | ❌ | Array of non-empty string tags (e.g. `["entity-picker"]`). Used by callers to discover this tool via `findToolsByCapability`. |
|
|
147
|
+
| `invocation.prefill` | ❌ | JSON-schema-style object describing data callers can pre-populate |
|
|
148
|
+
| `invocation.prefill.properties` | ❌ | Map of property names to `{ type?, enum?, items? }` descriptors |
|
|
149
|
+
| `invocation.returnTopic` | ❌ | JSON-schema-style object describing the data this tool returns to its caller |
|
|
150
|
+
| `invocation.returnTopic.properties` | ❌ | Map of property names to `{ type?, enum?, items? }` descriptors |
|
|
151
|
+
| `agents` | ❌ | Top-level agent contract for external automation; when present, must include `version` and may include `invokable`, `modes`, `defaultMode`, `timeoutMS`, `headless`, `executionModes`, `defaultExecutionMode`, and `headlessEntry` |
|
|
152
|
+
| `agents.version` | ✅ | Must be a valid semantic version string (e.g. `1.0.0`) |
|
|
153
|
+
| `agents.invokable` | ❌ | Boolean indicating whether an external (non-PPTB) automation agent may launch this tool programmatically |
|
|
154
|
+
| `agents.modes` | ❌ | Array of supported invocation modes (`"one-way"`, `"two-way"`) |
|
|
155
|
+
| `agents.defaultMode` | ❌ | Default mode when the agent does not request one explicitly |
|
|
156
|
+
| `agents.timeoutMS` | ❌ | Optional timeout hint in milliseconds for two-way calls |
|
|
157
|
+
| `agents.executionModes` | ❌ | Array of supported execution modes (`"windowed"`, `"headless"`) |
|
|
158
|
+
| `agents.defaultExecutionMode` | ❌ | Default execution mode when the agent does not request one explicitly |
|
|
159
|
+
| `agents.headlessEntry` | ❌ | Path to the compiled automated runtime entry point |
|
|
148
160
|
|
|
149
161
|
> \*\* Required only when the `invocation` object is present.
|
|
150
162
|
|
package/dataverseAPI.d.ts
CHANGED
|
@@ -6,7 +6,8 @@
|
|
|
6
6
|
|
|
7
7
|
declare namespace DataverseAPI {
|
|
8
8
|
export type AdditionalHeaders = Record<string, string>;
|
|
9
|
-
|
|
9
|
+
/** Legacy aliases remain supported; numeric targets are zero-based slot indexes. */
|
|
10
|
+
export type ConnectionTarget = "primary" | "secondary" | number;
|
|
10
11
|
export type BatchMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
|
|
11
12
|
|
|
12
13
|
export interface BatchRequest {
|
package/index.d.ts
CHANGED
|
@@ -19,9 +19,11 @@
|
|
|
19
19
|
/// <reference path="./dataverseAPI.d.ts" />
|
|
20
20
|
/// <reference path="./powerplatformAPI.d.ts" />
|
|
21
21
|
/// <reference path="./pptbConfig.d.ts" />
|
|
22
|
+
/// <reference path="./toolManifest.d.ts" />
|
|
22
23
|
|
|
23
24
|
// Re-export all namespaces for convenience
|
|
24
25
|
export * from "./dataverseAPI";
|
|
25
26
|
export * from "./powerplatformAPI";
|
|
26
27
|
export * from "./pptbConfig";
|
|
27
28
|
export * from "./toolboxAPI";
|
|
29
|
+
export * from "./toolManifest";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pptb/types",
|
|
3
|
-
"version": "1.2.7-beta.
|
|
3
|
+
"version": "1.2.7-beta.2",
|
|
4
4
|
"description": "Type definitions for Power Platform ToolBox APIs and validity checks for tool packages",
|
|
5
5
|
"main": "index.d.ts",
|
|
6
6
|
"types": "index.d.ts",
|
|
@@ -31,6 +31,7 @@
|
|
|
31
31
|
"dataverseAPI.d.ts",
|
|
32
32
|
"powerplatformAPI.d.ts",
|
|
33
33
|
"pptbConfig.d.ts",
|
|
34
|
+
"toolManifest.d.ts",
|
|
34
35
|
"bin/",
|
|
35
36
|
"README.md"
|
|
36
37
|
],
|
package/powerplatformAPI.d.ts
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
*/
|
|
7
7
|
|
|
8
8
|
declare namespace PowerPlatformAPI {
|
|
9
|
+
export type ConnectionTarget = "primary" | "secondary" | number;
|
|
9
10
|
/**
|
|
10
11
|
* Power Platform API category response type
|
|
11
12
|
*/
|
|
@@ -29,7 +30,7 @@ declare namespace PowerPlatformAPI {
|
|
|
29
30
|
* @param connectionTarget Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
|
|
30
31
|
* @param headers Optional custom headers
|
|
31
32
|
*/
|
|
32
|
-
Get: (path?: string, connectionTarget?:
|
|
33
|
+
Get: (path?: string, connectionTarget?: ConnectionTarget, headers?: Record<string, string>) => Promise<PowerPlatformResponse>;
|
|
33
34
|
|
|
34
35
|
/**
|
|
35
36
|
* Make a POST request to the category endpoint
|
|
@@ -38,7 +39,7 @@ declare namespace PowerPlatformAPI {
|
|
|
38
39
|
* @param connectionTarget Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
|
|
39
40
|
* @param headers Optional custom headers
|
|
40
41
|
*/
|
|
41
|
-
Post: (path?: string, body?: unknown, connectionTarget?:
|
|
42
|
+
Post: (path?: string, body?: unknown, connectionTarget?: ConnectionTarget, headers?: Record<string, string>) => Promise<PowerPlatformResponse>;
|
|
42
43
|
|
|
43
44
|
/**
|
|
44
45
|
* Make a PUT request to the category endpoint
|
|
@@ -47,7 +48,7 @@ declare namespace PowerPlatformAPI {
|
|
|
47
48
|
* @param connectionTarget Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
|
|
48
49
|
* @param headers Optional custom headers
|
|
49
50
|
*/
|
|
50
|
-
Put: (path?: string, body?: unknown, connectionTarget?:
|
|
51
|
+
Put: (path?: string, body?: unknown, connectionTarget?: ConnectionTarget, headers?: Record<string, string>) => Promise<PowerPlatformResponse>;
|
|
51
52
|
|
|
52
53
|
/**
|
|
53
54
|
* Make a PATCH request to the category endpoint
|
|
@@ -56,7 +57,7 @@ declare namespace PowerPlatformAPI {
|
|
|
56
57
|
* @param connectionTarget Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
|
|
57
58
|
* @param headers Optional custom headers
|
|
58
59
|
*/
|
|
59
|
-
Patch: (path?: string, body?: unknown, connectionTarget?:
|
|
60
|
+
Patch: (path?: string, body?: unknown, connectionTarget?: ConnectionTarget, headers?: Record<string, string>) => Promise<PowerPlatformResponse>;
|
|
60
61
|
|
|
61
62
|
/**
|
|
62
63
|
* Make a DELETE request to the category endpoint
|
|
@@ -65,7 +66,7 @@ declare namespace PowerPlatformAPI {
|
|
|
65
66
|
* @param headers Optional custom headers
|
|
66
67
|
* @param body Optional request body (for DELETE with payload)
|
|
67
68
|
*/
|
|
68
|
-
Delete: (path?: string, connectionTarget?:
|
|
69
|
+
Delete: (path?: string, connectionTarget?: ConnectionTarget, headers?: Record<string, string>, body?: unknown) => Promise<PowerPlatformResponse>;
|
|
69
70
|
}
|
|
70
71
|
|
|
71
72
|
/**
|
package/pptbConfig.d.ts
CHANGED
|
@@ -32,7 +32,10 @@
|
|
|
32
32
|
* "invokable": true,
|
|
33
33
|
* "modes": ["one-way", "two-way"],
|
|
34
34
|
* "defaultMode": "two-way",
|
|
35
|
-
* "timeoutMS": 12000
|
|
35
|
+
* "timeoutMS": 12000,
|
|
36
|
+
* "executionModes": ["windowed", "headless"],
|
|
37
|
+
* "defaultExecutionMode": "headless",
|
|
38
|
+
* "headlessEntry": "dist/headless.js"
|
|
36
39
|
* }
|
|
37
40
|
* }
|
|
38
41
|
* ```
|
|
@@ -103,6 +106,7 @@ export interface JsonSchemaObject {
|
|
|
103
106
|
* when it finishes.
|
|
104
107
|
*/
|
|
105
108
|
export type AgentInvocationMode = "one-way" | "two-way";
|
|
109
|
+
export type AgentExecutionMode = "windowed" | "headless";
|
|
106
110
|
|
|
107
111
|
/**
|
|
108
112
|
* Agent-specific launch contract for external automation callers.
|
|
@@ -113,6 +117,9 @@ export type AgentInvocationMode = "one-way" | "two-way";
|
|
|
113
117
|
* - `modes`: supported MCP invocation modes for this tool.
|
|
114
118
|
* - `defaultMode`: fallback mode when the caller does not specify one.
|
|
115
119
|
* - `timeoutMS`: optional timeout hint, in milliseconds, for two-way calls.
|
|
120
|
+
* - `executionModes`: supported execution modes for this tool.
|
|
121
|
+
* - `defaultExecutionMode`: fallback execution mode when the caller does not specify one.
|
|
122
|
+
* - `headlessEntry`: path to the compiled automated runtime entry point.
|
|
116
123
|
*/
|
|
117
124
|
export interface AgentsConfig {
|
|
118
125
|
/** Semantic version of this agent contract. */
|
|
@@ -127,6 +134,12 @@ export interface AgentsConfig {
|
|
|
127
134
|
defaultMode?: AgentInvocationMode;
|
|
128
135
|
/** Optional timeout hint, in milliseconds, for agent-driven two-way calls. */
|
|
129
136
|
timeoutMS?: number;
|
|
137
|
+
/** Execution modes supported by the tool. */
|
|
138
|
+
executionModes?: AgentExecutionMode[];
|
|
139
|
+
/** Default execution mode when an agent does not request one explicitly. */
|
|
140
|
+
defaultExecutionMode?: AgentExecutionMode;
|
|
141
|
+
/** Path to the compiled automated runtime entry point. */
|
|
142
|
+
headlessEntry?: string;
|
|
130
143
|
}
|
|
131
144
|
|
|
132
145
|
export interface InvocationConfig {
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/** Exact connection count or permitted connection-count range in a tool package.json. */
|
|
2
|
+
export type ToolConnectionRequirement = number | ToolConnectionRange;
|
|
3
|
+
|
|
4
|
+
export interface ToolConnectionRange {
|
|
5
|
+
/** Minimum number of connections required; defaults to 1. */
|
|
6
|
+
min?: number;
|
|
7
|
+
/** Maximum number of connections available; defaults to min. */
|
|
8
|
+
max?: number;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
/** Feature declarations supported in a tool package.json `features` object. */
|
|
12
|
+
export interface ToolPackageFeatures {
|
|
13
|
+
/** Exact count from 0 to 10, or a range with 0 <= min <= max <= 10. */
|
|
14
|
+
connections?: ToolConnectionRequirement;
|
|
15
|
+
/**
|
|
16
|
+
* Legacy connection cardinality setting. Use `connections` for new tools.
|
|
17
|
+
* @deprecated Use `connections` instead.
|
|
18
|
+
*/
|
|
19
|
+
multiConnection?: "required" | "optional" | "none";
|
|
20
|
+
/**
|
|
21
|
+
* Legacy connection-required setting. Use `connections` for new tools.
|
|
22
|
+
* @deprecated Use `connections` instead.
|
|
23
|
+
*/
|
|
24
|
+
connectionRequirement?: "required" | "optional";
|
|
25
|
+
/** Minimum ToolBox API version required by this tool. */
|
|
26
|
+
minAPI?: string;
|
|
27
|
+
/** Restrict connection selection to connections enabled for the Power Platform API. */
|
|
28
|
+
enabledForPowerPlatformAPI?: boolean;
|
|
29
|
+
}
|
package/toolboxAPI.d.ts
CHANGED
|
@@ -5,6 +5,9 @@
|
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
7
|
declare namespace ToolBoxAPI {
|
|
8
|
+
/** Legacy string aliases remain supported; numeric targets are zero-based slot indexes. */
|
|
9
|
+
export type ConnectionTarget = "primary" | "secondary" | number;
|
|
10
|
+
|
|
8
11
|
/**
|
|
9
12
|
* Tool context containing connection information
|
|
10
13
|
* NOTE: accessToken is NOT included for security - tools must use dataverseAPI
|
|
@@ -16,6 +19,10 @@ declare namespace ToolBoxAPI {
|
|
|
16
19
|
connectionId?: string | null;
|
|
17
20
|
secondaryConnectionUrl?: string | null;
|
|
18
21
|
secondaryConnectionId?: string | null;
|
|
22
|
+
/** All connection slots; index 0 is primary and index 1 is secondary. */
|
|
23
|
+
connectionIds?: Array<string | null>;
|
|
24
|
+
/** URLs for connection slots, aligned with `connectionIds`. */
|
|
25
|
+
connectionUrls?: Array<string | null>;
|
|
19
26
|
/**
|
|
20
27
|
* Invocation metadata injected by PPTB when the tool is launched by another
|
|
21
28
|
* tool or by the MCP server. Tools should treat this as optional and
|
|
@@ -172,9 +179,15 @@ declare namespace ToolBoxAPI {
|
|
|
172
179
|
getActiveConnection: () => Promise<Connection | null>;
|
|
173
180
|
|
|
174
181
|
/**
|
|
175
|
-
*
|
|
182
|
+
* @deprecated Use `getConnection("secondary")` or `getConnections()[1]` for slot-aware connection access.
|
|
176
183
|
*/
|
|
177
184
|
getSecondaryConnection: () => Promise<Connection | null>;
|
|
185
|
+
|
|
186
|
+
/** Get every configured connection slot, preserving null/unassigned slots. */
|
|
187
|
+
getConnections: () => Promise<Array<Connection | null>>;
|
|
188
|
+
|
|
189
|
+
/** Get one connection by its zero-based slot or legacy name. */
|
|
190
|
+
getConnection: (target: ConnectionTarget) => Promise<Connection | null>;
|
|
178
191
|
}
|
|
179
192
|
|
|
180
193
|
/**
|
|
@@ -225,7 +238,7 @@ declare namespace ToolBoxAPI {
|
|
|
225
238
|
* Defaults to `"primary"`. Pass `"secondary"` for multi-connection tools that
|
|
226
239
|
* want to open the URL in the secondary connection's browser context.
|
|
227
240
|
*/
|
|
228
|
-
openInConnectionBrowser: (url: string, connectionTarget?:
|
|
241
|
+
openInConnectionBrowser: (url: string, connectionTarget?: ConnectionTarget) => Promise<void>;
|
|
229
242
|
}
|
|
230
243
|
|
|
231
244
|
/**
|
|
@@ -531,7 +544,7 @@ declare namespace ToolBoxAPI {
|
|
|
531
544
|
launchTool: (
|
|
532
545
|
targetToolId: string,
|
|
533
546
|
prefillData?: Record<string, unknown>,
|
|
534
|
-
options?: { primaryConnectionId?: string | null; secondaryConnectionId?: string | null; noReturn?: boolean },
|
|
547
|
+
options?: { primaryConnectionId?: string | null; secondaryConnectionId?: string | null; connectionIds?: Array<string | null>; noReturn?: boolean },
|
|
535
548
|
) => Promise<unknown>;
|
|
536
549
|
|
|
537
550
|
/**
|