@salesforce/core-bundle 8.16.0 → 8.18.0

package/lib/index.d.ts

@@ -1698,6 +1698,7 @@ declare module '@salesforce/core-bundle/index' {
   export { ScratchOrgCache } from '@salesforce/core-bundle/org/scratchOrgCache';
   export { default as ScratchOrgSettingsGenerator } from '@salesforce/core-bundle/org/scratchOrgSettingsGenerator';
   export * from '@salesforce/core-bundle/util/sfdc';
+  export * from '@salesforce/core-bundle/util/mutex';
   export * from '@salesforce/core-bundle/testSetup';
 
 }
@@ -2666,6 +2667,8 @@ declare module '@salesforce/core-bundle/org/authInfo' {
       getFields(decrypt?: boolean): Readonly<AuthFields>;
       /**
        * Get the org front door (used for web based oauth flows)
+       *
+       * @deprecated Will be removed in the next major version. Use the `Org.getFrontDoorUrl()` method instead.
        */
       getOrgFrontDoorUrl(): string;
       /**
@@ -3224,6 +3227,39 @@ declare module '@salesforce/core-bundle/org/org' {
        * @ignore
        */
       constructor(options?: Org.Options);
+      /**
+       * Generate a URL to a metadata UI builder/setup section in an org.
+       *
+       * Bot: open in Agentforce Builder
+       * ApexPage: opens page
+       * Flow: open in Flow Builder
+       * FlexiPage: open in Lightning App Builder
+       * CustomObject: open in Object Manager
+       * ApexClass: open in Setup -> Apex Classes UI
+       *
+       * if you pass any other metadata type you'll get a path to Lightning App Builder
+       *
+       * @example
+       * // use SDR resolver:
+       * import { MetadataResolver } from '@salesforce/source-deploy-retrieve';
+       *
+       * const metadataResolver = new MetadataResolver();
+       * const components = metadataResolver.getComponentsFromPath(filePath);
+       * const typeName = components[0]?.type?.name;
+       *
+       * const metadataBuilderUrl = await org.getMetadataUIURL(typeName, filePath);
+       *
+       * @typeName Bot | ApexPage | Flow | FlexiPage | CustomObject | ApexClass
+       * @file Absolute file path to the metadata file
+       */
+      getMetadataUIURL(typeName: string, file: string): Promise<string>;
+      /**
+       * Get a Frontdoor URL
+       *
+       * This uses the UI Bridge API to generate a single-use Frontdoor URL:
+       * https://help.salesforce.com/s/articleView?id=xcloud.frontdoor_singleaccess.htm&type=5
+       */
+      getFrontDoorUrl(redirectUri?: string): Promise<string>;
       /**
        * create a sandbox from a production org
        * 'this' needs to be a production org with sandbox licenses available
@@ -6387,11 +6423,52 @@ declare module '@salesforce/core-bundle/util/mapKeys' {
 }
 declare module '@salesforce/core-bundle/util/mutex' {
   /**
-   * Simple mutex implementation using promises
+   * A mutual exclusion (mutex) class that ensures only one asynchronous operation
+   * can execute at a time, providing thread-safe execution of critical sections.
+   *
+   * @example
+   * ```typescript
+   * const mutex = new Mutex();
+   *
+   * // Only one of these will execute at a time
+   * mutex.lock(async () => {
+   *   // Critical section code here
+   *   return someAsyncOperation();
+   * });
+   * ```
    */
   export class Mutex {
+      /**
+       * Internal promise chain that maintains the mutex state.
+       * Each new lock acquisition is chained to this promise.
+       *
+       * @private
+       */
       private mutex;
+      /**
+       * Acquires the mutex lock and executes the provided function.
+       * The function will not execute until all previously queued operations complete.
+       *
+       * @template T - The return type of the function
+       * @param fn - The function to execute while holding the mutex lock. Can be synchronous or asynchronous.
+       * @returns A promise that resolves with the result of the function execution
+       *
+       * @example
+       * ```typescript
+       * const result = await mutex.lock(async () => {
+       *   // This code is guaranteed to run exclusively
+       *   return await someAsyncOperation();
+       * });
+       * ```
+       */
       lock<T>(fn: () => Promise<T> | T): Promise<T>;
+      /**
+       * Acquires the mutex by waiting for the current promise chain to resolve
+       * and returns a release function to unlock the mutex.
+       *
+       * @private
+       * @returns A promise that resolves to a function that releases the mutex lock
+       */
       private acquire;
   }
 

package/lib/index.js

@@ -12336,7 +12336,7 @@ var require_package2 = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@salesforce/core-bundle",
-      version: "8.16.0",
+      version: "8.18.0",
       description: "Core libraries to interact with SFDX projects, orgs, and APIs.",
       main: "lib/index",
       types: "lib/index.d.ts",
@@ -12373,7 +12373,7 @@ var require_package2 = __commonJS({
         "messageTransformer/messageTransformer.ts"
       ],
       dependencies: {
-        "@jsforce/jsforce-node": "^3.8.2",
+        "@jsforce/jsforce-node": "^3.9.1",
         "@salesforce/kit": "^3.2.2",
         "@salesforce/schemas": "^1.9.0",
         "@salesforce/ts-types": "^2.0.10",
@@ -15858,7 +15858,29 @@ var require_mutex = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.Mutex = void 0;
     var Mutex = class {
+      /**
+       * Internal promise chain that maintains the mutex state.
+       * Each new lock acquisition is chained to this promise.
+       *
+       * @private
+       */
       mutex = Promise.resolve();
+      /**
+       * Acquires the mutex lock and executes the provided function.
+       * The function will not execute until all previously queued operations complete.
+       *
+       * @template T - The return type of the function
+       * @param fn - The function to execute while holding the mutex lock. Can be synchronous or asynchronous.
+       * @returns A promise that resolves with the result of the function execution
+       *
+       * @example
+       * ```typescript
+       * const result = await mutex.lock(async () => {
+       *   // This code is guaranteed to run exclusively
+       *   return await someAsyncOperation();
+       * });
+       * ```
+       */
       async lock(fn) {
         const unlock = await this.acquire();
         try {
@@ -15867,6 +15889,13 @@ var require_mutex = __commonJS({
           unlock();
         }
       }
+      /**
+       * Acquires the mutex by waiting for the current promise chain to resolve
+       * and returns a release function to unlock the mutex.
+       *
+       * @private
+       * @returns A promise that resolves to a function that releases the mutex lock
+       */
       async acquire() {
         let release;
         const promise = new Promise((resolve) => {
@@ -33107,7 +33136,7 @@ var require_VERSION = __commonJS({
   "node_modules/@jsforce/jsforce-node/lib/VERSION.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.default = "3.8.2";
+    exports2.default = "3.9.1";
   }
 });
 
@@ -46282,6 +46311,49 @@ var require_connection = __commonJS({
        * @param options
        */
       async upsert(type2, records, extIdField, options = {}) {
+        return Array.isArray(records) ? (
+          // check the version whether SObject collection API is supported (46.0)
+          this._ensureVersion(46) ? this._upsertMany(type2, records, extIdField, options) : this._upsertParallel(type2, records, extIdField, options)
+        ) : this._upsertParallel(type2, records, extIdField, options);
+      }
+      /** @private */
+      async _upsertMany(type2, records, extIdField, options = {}) {
+        if (records.length === 0) {
+          return [];
+        }
+        if (records.length > MAX_DML_COUNT && options.allowRecursive) {
+          return [
+            ...await this._upsertMany(type2, records.slice(0, MAX_DML_COUNT), extIdField, options),
+            ...await this._upsertMany(type2, records.slice(MAX_DML_COUNT), extIdField, options)
+          ];
+        }
+        const _records = records.map((recordItem) => {
+          const { [extIdField]: extId, type: recordType, attributes, ...rec } = recordItem;
+          const sobjectType = recordType || attributes?.type || type2;
+          if (!extId) {
+            throw new Error("External ID is not found in record.");
+          }
+          if (!sobjectType) {
+            throw new Error("No SObject Type defined in record");
+          }
+          return { [extIdField]: extId, attributes: { type: sobjectType }, ...rec };
+        });
+        const url = [this._baseUrl(), "composite", "sobjects", type2, extIdField].join("/");
+        return this.request({
+          method: "PATCH",
+          url,
+          body: JSON.stringify({
+            allOrNone: options.allOrNone || false,
+            records: _records
+          }),
+          headers: {
+            ...options.headers || {},
+            "content-type": "application/json"
+          }
+        });
+      }
+      /** @private */
+      async _upsertParallel(type2, records, extIdField, options = {}) {
         const isArray = Array.isArray(records);
         const _records = Array.isArray(records) ? records : [records];
         if (_records.length > this._maxRequest) {
@@ -107787,10 +107859,13 @@ var require_org = __commonJS({
       __setModuleDefault2(result, mod);
       return result;
     };
+    var __importDefault3 = exports2 && exports2.__importDefault || function(mod) {
+      return mod && mod.__esModule ? mod : { "default": mod };
+    };
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.Org = exports2.SandboxEvents = exports2.OrgTypes = void 0;
     exports2.sandboxIsResumable = sandboxIsResumable;
-    var node_path_1 = require("node:path");
+    var node_path_1 = __importDefault3(require("node:path"));
     var fs = __importStar2(require("node:fs"));
     var kit_1 = require_lib2();
     var ts_types_1 = require_lib();
@@ -107810,7 +107885,7 @@ var require_org = __commonJS({
     var authInfo_12 = require_authInfo();
     var scratchOrgCreate_12 = require_scratchOrgCreate();
     var orgConfigProperties_12 = require_orgConfigProperties();
-    var messages = new messages_12.Messages("@salesforce/core-bundle", "org", /* @__PURE__ */ new Map([["notADevHub", "The provided dev hub username %s is not a valid dev hub."], ["noUsernameFound", "No username found."], ["noDevHubFound", "Unable to associate this scratch org with a DevHub."], ["deleteOrgHubError", "The Dev Hub org cannot be deleted."], ["insufficientAccessToDelete", "You do not have the appropriate permissions to delete a scratch org. Please contact your Salesforce admin."], ["scratchOrgNotFound", "Attempting to delete an expired or deleted org"], ["sandboxDeleteFailed", "The sandbox org deletion failed with a result of %s."], ["sandboxNotFound", "We can't find a SandboxProcess for the sandbox %s."], ["sandboxInfoCreateFailed", "The sandbox org creation failed with a result of %s."], ["sandboxInfoRefreshFailed", "The sandbox org refresh failed with a result of %s."], ["missingAuthUsername", "The sandbox %s does not have an authorized username."], ["orgPollingTimeout", "Sandbox status is %s; timed out waiting for completion."], ["NotFoundOnDevHub", "The scratch org does not belong to the dev hub username %s."], ["AuthInfoOrgIdUndefined", "AuthInfo orgId is undefined."], ["sandboxCreateNotComplete", "The sandbox creation has not completed."], ["SandboxProcessNotFoundBySandboxName", "We can't find a SandboxProcess with the SandboxName %s."], ["MultiSandboxProcessNotFoundBySandboxName", "We found more than one SandboxProcess with the SandboxName %s."], ["sandboxNotResumable", "The sandbox %s cannot resume with status of %s."]]));
+    var messages = new messages_12.Messages("@salesforce/core-bundle", "org", /* @__PURE__ */ new Map([["notADevHub", "The provided dev hub username %s is not a valid dev hub."], ["noUsernameFound", "No username found."], ["noDevHubFound", "Unable to associate this scratch org with a DevHub."], ["deleteOrgHubError", "The Dev Hub org cannot be deleted."], ["insufficientAccessToDelete", "You do not have the appropriate permissions to delete a scratch org. Please contact your Salesforce admin."], ["scratchOrgNotFound", "Attempting to delete an expired or deleted org"], ["sandboxDeleteFailed", "The sandbox org deletion failed with a result of %s."], ["sandboxNotFound", "We can't find a SandboxProcess for the sandbox %s."], ["sandboxInfoCreateFailed", "The sandbox org creation failed with a result of %s."], ["sandboxInfoRefreshFailed", "The sandbox org refresh failed with a result of %s."], ["missingAuthUsername", "The sandbox %s does not have an authorized username."], ["orgPollingTimeout", "Sandbox status is %s; timed out waiting for completion."], ["NotFoundOnDevHub", "The scratch org does not belong to the dev hub username %s."], ["AuthInfoOrgIdUndefined", "AuthInfo orgId is undefined."], ["sandboxCreateNotComplete", "The sandbox creation has not completed."], ["SandboxProcessNotFoundBySandboxName", "We can't find a SandboxProcess with the SandboxName %s."], ["MultiSandboxProcessNotFoundBySandboxName", "We found more than one SandboxProcess with the SandboxName %s."], ["sandboxNotResumable", "The sandbox %s cannot resume with status of %s."], ["FrontdoorURLError", "Failed to generate a frontdoor URL."], ["FlowIdNotFound", "ID not found for Flow %s."], ["CustomObjectIdNotFound", "ID not found for custom object %s."], ["ApexClassIdNotFound", "ID not found for Apex class %s."]]));
     var OrgTypes;
     (function(OrgTypes2) {
       OrgTypes2["Scratch"] = "scratch";
@@ -107877,6 +107952,105 @@ var require_org = __commonJS({
         super(options);
         this.options = options ?? {};
       }
+      /**
+       * Generate a URL to a metadata UI builder/setup section in an org.
+       *
+       * Bot: open in Agentforce Builder
+       * ApexPage: opens page
+       * Flow: open in Flow Builder
+       * FlexiPage: open in Lightning App Builder
+       * CustomObject: open in Object Manager
+       * ApexClass: open in Setup -> Apex Classes UI
+       *
+       * if you pass any other metadata type you'll get a path to Lightning App Builder
+       *
+       * @example
+       * // use SDR resolver:
+       * import { MetadataResolver } from '@salesforce/source-deploy-retrieve';
+       *
+       * const metadataResolver = new MetadataResolver();
+       * const components = metadataResolver.getComponentsFromPath(filePath);
+       * const typeName = components[0]?.type?.name;
+       *
+       * const metadataBuilderUrl = await org.getMetadataUIURL(typeName, filePath);
+       *
+       * @typeName Bot | ApexPage | Flow | FlexiPage | CustomObject | ApexClass
+       * @file Absolute file path to the metadata file
+       */
+      async getMetadataUIURL(typeName, file) {
+        const botFileNameToId = async (conn, filePath) => (await conn.singleRecordQuery(`SELECT id FROM BotDefinition WHERE DeveloperName='${node_path_1.default.basename(filePath, ".bot-meta.xml")}'`)).Id;
+        const flexiPageFilenameToId = async (conn, filePath) => (await conn.singleRecordQuery(`SELECT id FROM flexipage WHERE DeveloperName='${node_path_1.default.basename(filePath, ".flexipage-meta.xml")}'`, { tooling: true })).Id;
+        const flowFileNameToId = async (conn, filePath) => {
+          try {
+            const flow = await conn.singleRecordQuery(`SELECT DurableId FROM FlowVersionView WHERE FlowDefinitionView.ApiName = '${node_path_1.default.basename(filePath, ".flow-meta.xml")}' ORDER BY VersionNumber DESC LIMIT 1`);
+            return flow.DurableId;
+          } catch (error) {
+            throw messages.createError("FlowIdNotFound", [filePath]);
+          }
+        };
+        const customObjectFileNameToId = async (conn, filePath) => {
+          try {
+            const customObject = await conn.singleRecordQuery(`SELECT Id FROM CustomObject WHERE DeveloperName = '${node_path_1.default.basename(filePath.replace(/__c/g, ""), ".object-meta.xml")}'`, {
+              tooling: true
+            });
+            return customObject.Id;
+          } catch (error) {
+            throw messages.createError("CustomObjectIdNotFound", [filePath]);
+          }
+        };
+        const apexClassFileNameToId = async (conn, filePath) => {
+          try {
+            const apexClass = await conn.singleRecordQuery(`SELECT Id FROM ApexClass WHERE Name = '${node_path_1.default.basename(filePath, ".cls")}'`, {
+              tooling: true
+            });
+            return apexClass.Id;
+          } catch (error) {
+            throw messages.createError("ApexClassIdNotFound", [filePath]);
+          }
+        };
+        let redirectUri = "";
+        switch (typeName) {
+          case "ApexClass":
+            redirectUri = `lightning/setup/ApexClasses/page?address=%2F${await apexClassFileNameToId(this.connection, file)}`;
+            break;
+          case "CustomObject":
+            redirectUri = `lightning/setup/ObjectManager/${await customObjectFileNameToId(this.connection, file)}/Details/view`;
+            break;
+          case "Bot":
+            redirectUri = `/AiCopilot/copilotStudio.app#/copilot/builder?copilotId=${await botFileNameToId(this.connection, file)}`;
+            break;
+          case "ApexPage":
+            redirectUri = `/apex/${node_path_1.default.basename(file).replace(".page-meta.xml", "").replace(".page", "")}`;
+            break;
+          case "Flow":
+            redirectUri = `/builder_platform_interaction/flowBuilder.app?flowId=${await flowFileNameToId(this.connection, file)}`;
+            break;
+          case "FlexiPage":
+            redirectUri = `/visualEditor/appBuilder.app?pageId=${await flexiPageFilenameToId(this.connection, file)}`;
+            break;
+          default:
+            redirectUri = "/lightning/setup/FlexiPageList/home";
+            break;
+        }
+        return this.getFrontDoorUrl(redirectUri);
+      }
+      /**
+       * Get a Frontdoor URL
+       *
+       * This uses the UI Bridge API to generate a single-use Frontdoor URL:
+       * https://help.salesforce.com/s/articleView?id=xcloud.frontdoor_singleaccess.htm&type=5
+       */
+      async getFrontDoorUrl(redirectUri) {
+        await this.refreshAuth();
+        const singleAccessUrl = new URL("/services/oauth2/singleaccess", this.connection.instanceUrl);
+        if (redirectUri) {
+          singleAccessUrl.searchParams.append("redirect_uri", redirectUri);
+        }
+        const response = await this.connection.requestGet(singleAccessUrl.toString());
+        if (response.frontdoor_uri)
+          return response.frontdoor_uri;
+        throw new sfError_12.SfError(messages.getMessage("FrontdoorURLError")).setData(response);
+      }
       /**
        * create a sandbox from a production org
        * 'this' needs to be a production org with sandbox licenses available
@@ -108600,7 +108774,7 @@ var require_org = __commonJS({
       }
       async getLocalDataDir(orgDataPath) {
         const rootFolder = await config_12.Config.resolveRootFolder(false);
-        return (0, node_path_1.join)(rootFolder, global_12.Global.SFDX_STATE_FOLDER, orgDataPath ? orgDataPath : "orgs");
+        return node_path_1.default.join(rootFolder, global_12.Global.SFDX_STATE_FOLDER, orgDataPath ? orgDataPath : "orgs");
       }
       /**
        * Gets the sandboxProcessObject and then polls for it to complete.
@@ -108978,7 +109152,7 @@ var require_org = __commonJS({
       async removeSourceTrackingFiles() {
         try {
           const rootFolder = await config_12.Config.resolveRootFolder(false);
-          await fs.promises.rm((0, node_path_1.join)(rootFolder, global_12.Global.SF_STATE_FOLDER, "orgs", this.getOrgId()), {
+          await fs.promises.rm(node_path_1.default.join(rootFolder, global_12.Global.SF_STATE_FOLDER, "orgs", this.getOrgId()), {
             recursive: true,
             force: true
           });
@@ -109491,6 +109665,8 @@ var require_authInfo = __commonJS({
       }
       /**
        * Get the org front door (used for web based oauth flows)
+       *
+       * @deprecated Will be removed in the next major version. Use the `Org.getFrontDoorUrl()` method instead.
        */
       getOrgFrontDoorUrl() {
         const authFields = this.getFields(true);
@@ -123365,6 +123541,7 @@ Object.defineProperty(exports, "ScratchOrgSettingsGenerator", { enumerable: true
   return __importDefault2(scratchOrgSettingsGenerator_1).default;
 } });
 __exportStar2(require_sfdc(), exports);
+__exportStar2(require_mutex(), exports);
 __exportStar2(require_testSetup(), exports);
 /*! Bundled license information:
 

package/messages/org.md

@@ -69,3 +69,19 @@ We found more than one SandboxProcess with the SandboxName %s.
 # sandboxNotResumable
 
 The sandbox %s cannot resume with status of %s.
+
+# FrontdoorURLError
+
+Failed to generate a frontdoor URL.
+
+# FlowIdNotFound
+
+ID not found for Flow %s.
+
+# CustomObjectIdNotFound
+
+ID not found for custom object %s.
+
+# ApexClassIdNotFound
+
+ID not found for Apex class %s.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/core-bundle",
-  "version": "8.16.0",
+  "version": "8.18.0",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/index",
   "types": "lib/index.d.ts",
@@ -37,7 +37,7 @@
     "messageTransformer/messageTransformer.ts"
   ],
   "dependencies": {
-    "@jsforce/jsforce-node": "^3.8.2",
+    "@jsforce/jsforce-node": "^3.9.1",
     "@salesforce/kit": "^3.2.2",
     "@salesforce/schemas": "^1.9.0",
     "@salesforce/ts-types": "^2.0.10",