@pptb/types 1.0.14 → 1.0.17

package/README.md

@@ -1,6 +1,6 @@
 # @pptb/types
 
-TypeScript type definitions for Power Platform Tool Box APIs.
+TypeScript type definitions for Power Platform ToolBox APIs.
 
 -   [@pptb/types](#pptbtypes)
     -   [Installation](#installation)
@@ -273,7 +273,7 @@ await dataverseAPI.publishCustomizations("account");
 
 ## API Reference
 
-The Power Platform Tool Box exposes two main APIs to tools:
+The Power Platform ToolBox exposes two main APIs to tools:
 
 ### ToolBox API (`window.toolboxAPI`)
 

package/dataverseAPI.d.ts

@@ -1,5 +1,5 @@
 /**
- * Power Platform Tool Box - Dataverse API Type Definitions
+ * Power Platform ToolBox - Dataverse API Type Definitions
  *
  * Dataverse Web API exposed to tools via window.dataverseAPI
  */
@@ -23,10 +23,21 @@ declare namespace DataverseAPI {
         DisplayName?: {
             LocalizedLabels: Array<{ Label: string; LanguageCode: number }>;
         };
-        Attributes?: unknown[];
         [key: string]: unknown;
     }
 
+    export type EntityRelatedMetadataBasePath = "Attributes" | "Keys" | "ManyToOneRelationships" | "OneToManyRelationships" | "ManyToManyRelationships" | "Privileges";
+
+    export type EntityRelatedMetadataPath =
+        | EntityRelatedMetadataBasePath
+        | `${EntityRelatedMetadataBasePath}/${string}`
+        | `${EntityRelatedMetadataBasePath}(${string})`
+        | `${EntityRelatedMetadataBasePath}(${string})/${string}`;
+
+    type EntityRelatedMetadataRecordPath = `${EntityRelatedMetadataBasePath}/${string}` | `${EntityRelatedMetadataBasePath}(${string})` | `${EntityRelatedMetadataBasePath}(${string})/${string}`;
+
+    export type EntityRelatedMetadataResponse<P extends EntityRelatedMetadataPath> = P extends EntityRelatedMetadataRecordPath ? Record<string, unknown> : { value: Record<string, unknown>[] };
+
     /**
      * Entity metadata collection response
      */
@@ -307,6 +318,47 @@ declare namespace DataverseAPI {
          * console.log('Filtered attributes:', attributes.value);
          *
          * @example
+         * // Get a single attribute definition (returns an object, not a collection)
+         * const nameAttribute = await dataverseAPI.getEntityRelatedMetadata(
+         *     'account',
+         *     "Attributes(LogicalName='name')"
+         * );
+         * console.log('Attribute type:', nameAttribute.AttributeType);
+         *
+         * @example
+         * // Drill into an attribute's option set
+         * const industryOptions = await dataverseAPI.getEntityRelatedMetadata(
+         *     'account',
+         *     "Attributes(LogicalName='industrycode')/OptionSet"
+         * );
+         * console.log('Industry options:', industryOptions.Options);
+         *
+         * @example
+         * // Retrieve keys defined on the entity
+         * const keys = await dataverseAPI.getEntityRelatedMetadata('account', 'Keys');
+         * console.log('Entity keys:', keys.value);
+         *
+         * @example
+         * // Retrieve many-to-one relationships (collection)
+         * const m2oRelationships = await dataverseAPI.getEntityRelatedMetadata('account', 'ManyToOneRelationships');
+         * console.log('Many-to-one count:', m2oRelationships.value.length);
+         *
+         * @example
+         * // Retrieve one-to-many relationships (collection)
+         * const o2mRelationships = await dataverseAPI.getEntityRelatedMetadata('account', 'OneToManyRelationships');
+         * console.log('One-to-many relationships:', o2mRelationships.value.map((rel) => rel.SchemaName));
+         *
+         * @example
+         * // Retrieve many-to-many relationships (collection)
+         * const m2mRelationships = await dataverseAPI.getEntityRelatedMetadata('account', 'ManyToManyRelationships');
+         * console.log('Many-to-many relationships:', m2mRelationships.value.map((rel) => rel.SchemaName));
+         *
+         * @example
+         * // Retrieve privileges (collection)
+         * const privileges = await dataverseAPI.getEntityRelatedMetadata('account', 'Privileges');
+         * console.log('Privilege names:', privileges.value.map((priv) => priv.Name));
+         *
+         * @example
          * // Get one-to-many relationships
          * const relationships = await dataverseAPI.getEntityRelatedMetadata(
          *     'account',
@@ -318,7 +370,12 @@ declare namespace DataverseAPI {
          * // Multi-connection tool using secondary connection
          * const attributes = await dataverseAPI.getEntityRelatedMetadata('account', 'Attributes', ['LogicalName'], 'secondary');
          */
-        getEntityRelatedMetadata: (entityLogicalName: string, relatedPath: string, selectColumns?: string[], connectionTarget?: "primary" | "secondary") => Promise<Record<string, unknown>>;
+        getEntityRelatedMetadata: <P extends EntityRelatedMetadataPath>(
+            entityLogicalName: string,
+            relatedPath: P,
+            selectColumns?: string[],
+            connectionTarget?: "primary" | "secondary",
+        ) => Promise<EntityRelatedMetadataResponse<P>>;
 
         /**
          * Get solutions from the environment
@@ -356,7 +413,7 @@ declare namespace DataverseAPI {
          * @example
          * // Get top 10 active accounts with specific fields
          * const result = await dataverseAPI.queryData(
-         *     '$select=name,emailaddress1,telephone1&$filter=statecode eq 0&$orderby=name&$top=10'
+         *     'accounts?$select=name,emailaddress1,telephone1&$filter=statecode eq 0&$orderby=name&$top=10'
          * );
          * console.log(`Found ${result.value.length} records`);
          * result.value.forEach(record => {
@@ -366,7 +423,7 @@ declare namespace DataverseAPI {
          * @example
          * // Query with expand to include related records
          * const result = await dataverseAPI.queryData(
-         *     '$select=name,accountid&$expand=contact_customer_accounts($select=fullname,emailaddress1)&$top=5'
+         *     'accounts?$select=name,accountid&$expand=contact_customer_accounts($select=fullname,emailaddress1)&$top=5'
          * );
          *
          * @example
@@ -377,7 +434,7 @@ declare namespace DataverseAPI {
          *
          * @example
          * // Multi-connection tool using secondary connection
-         * const result = await dataverseAPI.queryData('$filter=statecode eq 0', 'secondary');
+         * const result = await dataverseAPI.queryData('contacts?$filter=statecode eq 0', 'secondary');
          */
         queryData: (odataQuery: string, connectionTarget?: "primary" | "secondary") => Promise<{ value: Record<string, unknown>[] }>;
 

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Power Platform Tool Box API Type Definitions
+ * Power Platform ToolBox API Type Definitions
  *
  * This is the main entry point for TypeScript type definitions.
  * Tools can reference specific APIs they need:
@@ -18,5 +18,5 @@
 /// <reference path="./dataverseAPI.d.ts" />
 
 // Re-export all namespaces for convenience
-export * from "./toolboxAPI";
 export * from "./dataverseAPI";
+export * from "./toolboxAPI";

package/package.json

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

package/toolboxAPI.d.ts

@@ -1,5 +1,5 @@
 /**
- * Power Platform Tool Box - ToolBox API Type Definitions
+ * Power Platform ToolBox - ToolBox API Type Definitions
  *
  * Core ToolBox API exposed to tools via window.toolboxAPI
  */
@@ -179,16 +179,6 @@ declare namespace ToolBoxAPI {
          */
         copyToClipboard: (text: string) => Promise<void>;
 
-        /**
-         * Open a save file dialog and write content
-         */
-        saveFile: (defaultPath: string, content: any) => Promise<string | null>;
-
-        /**
-         * Open a native dialog to select either a file or a folder and return the chosen path
-         */
-        selectPath: (options?: SelectPathOptions) => Promise<string | null>;
-
         /**
          * Get the current UI theme (light or dark)
          */
@@ -220,6 +210,65 @@ declare namespace ToolBoxAPI {
         hideLoading: () => Promise<void>;
     }
 
+    /**
+     * FileSystem namespace - filesystem operations for tools
+     */
+    export interface FileSystemAPI {
+        /**
+         * Read a file as UTF-8 text
+         * Ideal for configs (pcfconfig.json, package.json)
+         */
+        readText: (path: string) => Promise<string>;
+
+        /**
+         * Read a file as raw binary data (Buffer)
+         * For images, ZIPs, manifests that need to be hashed, uploaded, or parsed as non-text
+         * Returns a Node.js Buffer which Electron can properly serialize over IPC
+         * Tools can convert to ArrayBuffer using buffer.buffer if needed
+         */
+        readBinary: (path: string) => Promise<Buffer>;
+
+        /**
+         * Check if a file or directory exists
+         * Lightweight existence check before attempting reads/writes
+         */
+        exists: (path: string) => Promise<boolean>;
+
+        /**
+         * Get file or directory metadata
+         * Confirms users picked the correct folder/file and shows info in UI
+         */
+        stat: (path: string) => Promise<{ type: "file" | "directory"; size: number; mtime: string }>;
+
+        /**
+         * Read directory contents
+         * Enumerate folder contents when tools need to show selectable files or validate structure
+         */
+        readDirectory: (path: string) => Promise<Array<{ name: string; type: "file" | "directory" }>>;
+
+        /**
+         * Write text content to a file
+         * Save generated files (manifests, logs) without forcing users through save dialog
+         */
+        writeText: (path: string, content: string) => Promise<void>;
+
+        /**
+         * Create a directory (recursive)
+         * Ensure target folders exist before writing scaffolding artifacts
+         */
+        createDirectory: (path: string) => Promise<void>;
+
+        /**
+         * Open a save file dialog and write content
+         */
+        saveFile: (defaultPath: string, content: any) => Promise<string | null>;
+
+        /**
+         * Open a native dialog to select either a file or a folder and return the chosen path
+         */
+        selectPath: (options?: SelectPathOptions) => Promise<string | null>;
+    }
+
     /**
      * Terminal namespace - context-aware terminal operations
      */
@@ -323,6 +372,11 @@ declare namespace ToolBoxAPI {
          */
         utils: UtilsAPI;
 
+        /**
+         * Filesystem operations
+         */
+        fileSystem: FileSystemAPI;
+
         /**
          * Tool-specific settings (context-aware)
          */