@pptb/types 1.0.13 → 1.0.16

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)
@@ -103,6 +103,16 @@ if (filePath) {
     console.log("File saved to:", filePath);
 }
 
+// Select a folder for exporting assets
+const targetFolder = await toolboxAPI.utils.selectPath({
+    type: "folder",
+    title: "Choose export directory",
+    defaultPath: "/Users/me/Downloads",
+});
+if (!targetFolder) {
+    console.log("User canceled folder selection");
+}
+
 // Get current theme
 const theme = await toolboxAPI.utils.getCurrentTheme();
 console.log("Current theme:", theme); // "light" or "dark"
@@ -263,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`)
 
@@ -288,6 +298,12 @@ Core platform features organized into namespaces:
 
     -   Opens a save dialog and writes the content. Returns the saved file path or null if canceled
 
+-   **selectPath(options?: SelectPathOptions)**: Promise<string | null>
+
+    -   Opens a native dialog to select either a file or folder (defaults to file)
+    -   Supports custom titles, button labels, default paths, and filters when selecting files
+    -   Returns the selected path or null if the user cancels
+
 -   **getCurrentTheme()**: Promise<"light" | "dark">
 
     -   Returns the current UI theme setting

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.13",
-    "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.16",
+  "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
  */
@@ -27,6 +27,26 @@ declare namespace ToolBoxAPI {
         duration?: number; // Duration in milliseconds, 0 for persistent
     }
 
+    /**
+     * File dialog filter definition
+     */
+    export interface FileDialogFilter {
+        name: string;
+        extensions: string[];
+    }
+
+    /**
+     * Options for selecting a file or folder path
+     */
+    export interface SelectPathOptions {
+        type?: "file" | "folder";
+        title?: string;
+        message?: string;
+        buttonLabel?: string;
+        defaultPath?: string;
+        filters?: FileDialogFilter[];
+    }
+
     /**
      * Event types that can be emitted by the ToolBox
      */
@@ -128,17 +148,17 @@ declare namespace ToolBoxAPI {
          * Get the currently active Dataverse connection
          */
         getActiveConnection: () => Promise<DataverseConnection | null>;
-        
+
         /**
          * Get the secondary connection for multi-connection tools
          */
         getSecondaryConnection: () => Promise<DataverseConnection | null>;
-        
+
         /**
          * Get the secondary connection URL for multi-connection tools
          */
         getSecondaryConnectionUrl: () => Promise<string | null>;
-        
+
         /**
          * Get the secondary connection ID for multi-connection tools
          */
@@ -164,6 +184,11 @@ declare namespace ToolBoxAPI {
          */
         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)
          */