@pptb/types 1.0.10 → 1.0.12

package/dataverseAPI.d.ts

@@ -81,6 +81,7 @@ declare namespace DataverseAPI {
          *
          * @param entityLogicalName - Logical name of the entity (e.g., 'account', 'contact')
          * @param record - Record data to create
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          * @returns Object containing the created record ID and any returned fields
          *
          * @example
@@ -90,8 +91,14 @@ declare namespace DataverseAPI {
          *     telephone1: '555-0100'
          * });
          * console.log('Created account ID:', result.id);
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * const result = await dataverseAPI.create('account', {
+         *     name: 'Contoso Ltd'
+         * }, 'secondary');
          */
-        create: (entityLogicalName: string, record: Record<string, unknown>) => Promise<CreateResult>;
+        create: (entityLogicalName: string, record: Record<string, unknown>, connectionTarget?: "primary" | "secondary") => Promise<CreateResult>;
 
         /**
          * Retrieve a single record by ID
@@ -99,6 +106,7 @@ declare namespace DataverseAPI {
          * @param entityLogicalName - Logical name of the entity
          * @param id - GUID of the record
          * @param columns - Optional array of column names to retrieve (retrieves all if not specified)
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          * @returns Object containing the requested record
          *
          * @example
@@ -108,8 +116,12 @@ declare namespace DataverseAPI {
          *     ['name', 'emailaddress1', 'telephone1']
          * );
          * console.log('Account name:', account.name);
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * const account = await dataverseAPI.retrieve('account', 'guid-here', ['name'], 'secondary');
          */
-        retrieve: (entityLogicalName: string, id: string, columns?: string[]) => Promise<Record<string, unknown>>;
+        retrieve: (entityLogicalName: string, id: string, columns?: string[], connectionTarget?: "primary" | "secondary") => Promise<Record<string, unknown>>;
 
         /**
          * Update an existing record
@@ -117,30 +129,41 @@ declare namespace DataverseAPI {
          * @param entityLogicalName - Logical name of the entity
          * @param id - GUID of the record
          * @param record - Fields to update
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          *
          * @example
          * await dataverseAPI.update('account', 'guid-here', {
          *     name: 'Updated Account Name',
          *     description: 'Updated description'
          * });
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * await dataverseAPI.update('account', 'guid-here', { name: 'Updated' }, 'secondary');
          */
-        update: (entityLogicalName: string, id: string, record: Record<string, unknown>) => Promise<void>;
+        update: (entityLogicalName: string, id: string, record: Record<string, unknown>, connectionTarget?: "primary" | "secondary") => Promise<void>;
 
         /**
          * Delete a record
          *
          * @param entityLogicalName - Logical name of the entity
          * @param id - GUID of the record
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          *
          * @example
          * await dataverseAPI.delete('account', 'guid-here');
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * await dataverseAPI.delete('account', 'guid-here', 'secondary');
          */
-        delete: (entityLogicalName: string, id: string) => Promise<void>;
+        delete: (entityLogicalName: string, id: string, connectionTarget?: "primary" | "secondary") => Promise<void>;
 
         /**
          * Execute a FetchXML query
          *
          * @param fetchXml - FetchXML query string
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          * @returns Object with value array containing matching records
          *
          * @example
@@ -162,21 +185,27 @@ declare namespace DataverseAPI {
          * result.value.forEach(record => {
          *     console.log(record.name);
          * });
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * const result = await dataverseAPI.fetchXmlQuery(fetchXml, 'secondary');
          */
-        fetchXmlQuery: (fetchXml: string) => Promise<FetchXmlResult>;
+        fetchXmlQuery: (fetchXml: string, connectionTarget?: "primary" | "secondary") => Promise<FetchXmlResult>;
 
         /**
          * Retrieve multiple records (alias for fetchXmlQuery for backward compatibility)
          *
          * @param fetchXml - FetchXML query string
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          * @returns Object with value array containing matching records
          */
-        retrieveMultiple: (fetchXml: string) => Promise<FetchXmlResult>;
+        retrieveMultiple: (fetchXml: string, connectionTarget?: "primary" | "secondary") => Promise<FetchXmlResult>;
 
         /**
          * Execute a Dataverse Web API action or function
          *
          * @param request - Execute request configuration
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          * @returns Object containing the operation result
          *
          * @example
@@ -198,8 +227,15 @@ declare namespace DataverseAPI {
          *         FieldName: 'total_revenue'
          *     }
          * });
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * const result = await dataverseAPI.execute({
+         *     operationName: 'WhoAmI',
+         *     operationType: 'function'
+         * }, 'secondary');
          */
-        execute: (request: ExecuteRequest) => Promise<Record<string, unknown>>;
+        execute: (request: ExecuteRequest, connectionTarget?: "primary" | "secondary") => Promise<Record<string, unknown>>;
 
         /**
          * Get metadata for a specific entity
@@ -207,6 +243,7 @@ declare namespace DataverseAPI {
          * @param entityLogicalName - Logical name of the entity
          * @param searchByLogicalName - Whether to search by logical name (true) or metadata ID (false)
          * @param selectColumns - Optional array of column names to retrieve (retrieves all if not specified)
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          * @returns Object containing entity metadata
          *
          * @example
@@ -220,12 +257,17 @@ declare namespace DataverseAPI {
          * console.log('Entity Metadata ID:', metadata.MetadataId);
          * console.log('Logical Name:', metadata.LogicalName);
          * console.log('Display Name:', metadata.DisplayName?.LocalizedLabels[0]?.Label);
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * const metadata = await dataverseAPI.getEntityMetadata('account', true, ['LogicalName'], 'secondary');
          */
-        getEntityMetadata: (entityLogicalName: string, searchByLogicalName: boolean, selectColumns?: string[]) => Promise<EntityMetadata>;
+        getEntityMetadata: (entityLogicalName: string, searchByLogicalName: boolean, selectColumns?: string[], connectionTarget?: "primary" | "secondary") => Promise<EntityMetadata>;
 
         /**
          * Get metadata for all entities
          * @param selectColumns - Optional array of column names to retrieve (retrieves LogicalName, DisplayName, MetadataId by default)
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          * @returns Object with value array containing all entity metadata
          *
          * @example
@@ -234,8 +276,12 @@ declare namespace DataverseAPI {
          * allEntities.value.forEach(entity => {
          *     console.log(`${entity.LogicalName} - ${entity.DisplayName?.LocalizedLabels[0]?.Label}`);
          * });
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * const allEntities = await dataverseAPI.getAllEntitiesMetadata(['LogicalName'], 'secondary');
          */
-        getAllEntitiesMetadata: (selectColumns?: string[]) => Promise<EntityMetadataCollection>;
+        getAllEntitiesMetadata: (selectColumns?: string[], connectionTarget?: "primary" | "secondary") => Promise<EntityMetadataCollection>;
 
         /**
          * Get related metadata for a specific entity (attributes, relationships, etc.)
@@ -243,6 +289,7 @@ declare namespace DataverseAPI {
          * @param entityLogicalName - Logical name of the entity
          * @param relatedPath - Path after EntityDefinitions(LogicalName='name') (e.g., 'Attributes', 'OneToManyRelationships', 'ManyToOneRelationships', 'ManyToManyRelationships', 'Keys')
          * @param selectColumns - Optional array of column names to retrieve (retrieves all if not specified)
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          * @returns Object containing the related metadata
          *
          * @example
@@ -266,13 +313,18 @@ declare namespace DataverseAPI {
          *     'OneToManyRelationships'
          * );
          * console.log('One-to-many relationships:', relationships.value);
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * const attributes = await dataverseAPI.getEntityRelatedMetadata('account', 'Attributes', ['LogicalName'], 'secondary');
          */
-        getEntityRelatedMetadata: (entityLogicalName: string, relatedPath: string, selectColumns?: string[]) => Promise<Record<string, unknown>>;
+        getEntityRelatedMetadata: (entityLogicalName: string, relatedPath: string, selectColumns?: string[], connectionTarget?: "primary" | "secondary") => Promise<Record<string, unknown>>;
 
         /**
          * Get solutions from the environment
          *
          * @param selectColumns - Required array of column names to retrieve (must contain at least one column)
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          * @returns Object with value array containing solutions
          *
          * @example
@@ -287,13 +339,18 @@ declare namespace DataverseAPI {
          * solutions.value.forEach(solution => {
          *     console.log(`${solution.friendlyname} (${solution.uniquename}) - v${solution.version}`);
          * });
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * const solutions = await dataverseAPI.getSolutions(['uniquename'], 'secondary');
          */
-        getSolutions: (selectColumns: string[]) => Promise<{ value: Record<string, unknown>[] }>;
+        getSolutions: (selectColumns: string[], connectionTarget?: "primary" | "secondary") => Promise<{ value: Record<string, unknown>[] }>;
 
         /**
          * Query data from Dataverse using OData query parameters
          *
          * @param odataQuery - OData query string with parameters like $select, $filter, $orderby, $top, $skip, $expand
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
          * @returns Object with value array containing matching records
          *
          * @example
@@ -317,8 +374,62 @@ declare namespace DataverseAPI {
          * const result = await dataverseAPI.queryData(
          *     '$filter=contains(fullname, \'Smith\')&$top=20'
          * );
+         *
+         * @example
+         * // Multi-connection tool using secondary connection
+         * const result = await dataverseAPI.queryData('$filter=statecode eq 0', 'secondary');
+         */
+        queryData: (odataQuery: string, connectionTarget?: "primary" | "secondary") => Promise<{ value: Record<string, unknown>[] }>;
+
+        /**
+         * Create multiple records in Dataverse
+         *
+         * @param entityLogicalName - Logical name of the entity (e.g., 'account', 'contact')
+         * @param records - Array of record data to create, including the "@odata.type" property for each record
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
+         * @returns Array of strings representing the created record IDs
+         *
+         * @example
+         * const results = await dataverseAPI.createMultiple('account', [
+         *     { name: 'Contoso Ltd', "@odata.type": "Microsoft.Dynamics.CRM.account" },
+         *     { name: 'Fabrikam Inc', "@odata.type": "Microsoft.Dynamics.CRM.account" }
+         * ]);
+         */
+        createMultiple: (entityLogicalName: string, records: Record<string, unknown>[], connectionTarget?: "primary" | "secondary") => Promise<string[]>;
+
+        /**
+         * Update multiple records in Dataverse
+         * @param entityLogicalName - Logical name of the entity
+         * @param records - Array of record data to update, each including the "id" property and the "odata.type" property
+         * @param connectionTarget - Optional connection target for multi-connection tools ('primary' or 'secondary'). Defaults to 'primary'.
+         *
+         * @example
+         * await dataverseAPI.updateMultiple('account', [
+         *     { accountid: 'guid-1', name: 'Updated Name 1', "@odata.type": "Microsoft.Dynamics.CRM.account" },
+         *     { accountid: 'guid-2', name: 'Updated Name 2', "@odata.type": "Microsoft.Dynamics.CRM.account" }
+         * ]);
+         */
+        updateMultiple: (entityLogicalName: string, records: Record<string, unknown>[], connectionTarget?: "primary" | "secondary") => Promise<void>;
+         * Gets the Dataverse entity set (collection) name for the specified table.
+         *
+         * This is typically used when building OData queries where the collection name
+         * (entity set name) is required instead of the logical table name.
+         *
+         * Note: This is a utility method that applies pluralization rules and does not
+         * require an active connection to Dataverse.
+         *
+         * @param entityLogicalName - The logical name of the Dataverse table (for example, "account").
+         * @returns The corresponding entity set name (for example, "accounts").
+         *
+         * @example
+         * const entitySetName = await dataverseAPI.getEntitySetName('account');
+         * console.log(entitySetName); // Output: "accounts"
+         *
+         * @example
+         * const entitySetName = await dataverseAPI.getEntitySetName('opportunity');
+         * console.log(entitySetName); // Output: "opportunities"
          */
-        queryData: (odataQuery: string) => Promise<{ value: Record<string, unknown>[] }>;
+        getEntitySetName: (entityLogicalName: string) => Promise<string>;
     }
 }
 

package/package.json

@@ -1,22 +1,22 @@
 {
-  "name": "@pptb/types",
-  "version": "1.0.10",
-  "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.12",
+    "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"
+    }
+}

package/toolboxAPI.d.ts

@@ -12,6 +12,9 @@ declare namespace ToolBoxAPI {
     export interface ToolContext {
         toolId: string | null;
         connectionUrl: string | null;
+        connectionId?: string | null;
+        secondaryConnectionUrl?: string | null;
+        secondaryConnectionId?: string | null;
     }
 
     /**
@@ -62,6 +65,11 @@ declare namespace ToolBoxAPI {
         tenantId?: string;
         createdAt: string;
         lastUsedAt?: string;
+        /**
+         * @deprecated isActive is a legacy field that is no longer persisted.
+         * It may be present in older tool code but should not be relied upon.
+         * Use the connection context provided by the ToolBox API instead.
+         */
         isActive?: boolean;
     }
 
@@ -120,6 +128,21 @@ 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
+         */
+        getSecondaryConnectionId: () => Promise<string | null>;
     }
 
     /**