@salesforce/packaging 4.5.0 → 4.6.0

package/lib/interfaces/packagingInterfacesAndType.d.ts

@@ -106,6 +106,44 @@ export type PackageVersionListResult = {
     HasMetadataRemoved?: boolean;
     Language?: string;
 };
+export type PackagePushRequestListQueryOptions = {
+    packageId: string;
+    scheduledLastDays?: number;
+    status?: 'Created' | 'Cancelled' | 'Pending' | 'In Progress' | 'Failed' | 'Succeeded';
+    isMigration?: boolean;
+};
+export type PackagePushRequestListResult = {
+    Id: string;
+    PackageVersionId: string;
+    PackageVersion: {
+        Name: string;
+        MajorVersion: string;
+        MinorVersion: string;
+    };
+    Status: string;
+    ScheduledStartTime: string;
+    StartTime: string;
+    EndTime: string;
+    OrgsScheduled: number;
+    OrgsUpgradeSucceeded: number;
+    OrgsUpgradeFailed: number;
+};
+export type PackagePushScheduleQueryOptions = {
+    packageVersionId: string;
+    scheduledStartTime?: string;
+    orgList: string;
+};
+export type PackagePushScheduleResult = {
+    PushRequestId: string;
+    ScheduledStartTime: string | undefined;
+    Status: string;
+};
+export type PackagePushRequestReportQueryOptions = {
+    packagePushRequestId: string;
+};
+export type PackagePushRequestAbortQueryOptions = {
+    packagePushRequestId: string;
+};
 export type PackageInstallCreateRequest = Partial<Pick<PackageInstallRequest, 'ApexCompileType' | 'EnableRss' | 'NameConflictResolution' | 'PackageInstallSource' | 'Password' | 'SecurityType' | 'SkipHandlers' | 'UpgradeType'>> & Pick<PackagingSObjects.PackageInstallRequest, 'SubscriberPackageVersionKey'>;
 export type Package1Display = {
     MetadataPackageVersionId: string;
@@ -391,3 +429,33 @@ export declare const Package1VersionEvents: {
     };
 };
 export type PackageXml = Pick<Package, 'types' | 'version'>;
+export type PackagePushRequestReportResult = {
+    PackageVersion: {
+        MetadataPackage: {
+            Name: string;
+            NamespacePrefix: string;
+        };
+        MetadataPackageId: string;
+        Name: string;
+        MajorVersion: string;
+        MinorVersion: string;
+    };
+    Id: string;
+    PackageVersionId: string;
+    Status: string;
+    ScheduledStartTime: string | null;
+    StartTime: string | null;
+    EndTime: string | null;
+    DurationSeconds: number | null;
+};
+export type PackagePushRequestJobCountByStatusResult = {
+    expr0: number;
+};
+export type PackagePushRequestReportJobFailuresResult = {
+    ErrorMessage: string;
+    ErrorDetails: string;
+    ErrorTitle: string;
+    ErrorSeverity: string;
+    ErrorType: string;
+    PackagePushJobId: string;
+};

package/lib/package/index.d.ts

@@ -1,4 +1,5 @@
 export * from './package';
 export * from './packageVersion';
 export * from './subscriberPackageVersion';
+export * from './packagePushUpgrade';
 export { VersionNumber } from './versionNumber';

package/lib/package/index.js

@@ -24,6 +24,7 @@ exports.VersionNumber = void 0;
 __exportStar(require("./package"), exports);
 __exportStar(require("./packageVersion"), exports);
 __exportStar(require("./subscriberPackageVersion"), exports);
+__exportStar(require("./packagePushUpgrade"), exports);
 var versionNumber_1 = require("./versionNumber");
 Object.defineProperty(exports, "VersionNumber", { enumerable: true, get: function () { return versionNumber_1.VersionNumber; } });
 //# sourceMappingURL=index.js.map

package/lib/package/packagePushUpgrade.d.ts

@@ -0,0 +1,19 @@
+import { Connection, SfProject } from '@salesforce/core';
+import { PackagePushRequestListQueryOptions, PackagePushRequestListResult, PackagePushScheduleResult, PackagePushRequestReportQueryOptions, PackagePushRequestReportResult, PackagePushRequestReportJobFailuresResult, PackagePushRequestAbortQueryOptions } from '../interfaces';
+export type PackagePushRequestListOptions = {
+    connection: Connection;
+    packageId: string;
+    project?: SfProject;
+};
+export declare class PackagePushUpgrade {
+    constructor();
+    static list(connection: Connection, options?: PackagePushRequestListQueryOptions): Promise<PackagePushRequestListResult[]>;
+    static report(connection: Connection, options: PackagePushRequestReportQueryOptions): Promise<PackagePushRequestReportResult[]>;
+    static getFailedJobs(connection: Connection, options: PackagePushRequestReportQueryOptions): Promise<number>;
+    static getSucceededJobs(connection: Connection, options: PackagePushRequestReportQueryOptions): Promise<number>;
+    static getTotalJobs(connection: Connection, options: PackagePushRequestReportQueryOptions): Promise<number>;
+    static getJobFailureReasons(connection: Connection, options: PackagePushRequestReportQueryOptions): Promise<PackagePushRequestReportJobFailuresResult[]>;
+    static schedule(connection: Connection, packageVersionId: string, scheduleTime: string | undefined, orgList: string[], isMigration?: boolean): Promise<PackagePushScheduleResult>;
+    static abort(connection: Connection, options: PackagePushRequestAbortQueryOptions): Promise<boolean>;
+    private static writeJobErrorsToFile;
+}

package/lib/package/packagePushUpgrade.js

@@ -0,0 +1,269 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackagePushUpgrade = void 0;
+/*
+ * Copyright (c) 2024, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = __importDefault(require("node:util"));
+const core_1 = require("@salesforce/core");
+const packageUtils_1 = require("../utils/packageUtils");
+class PackagePushUpgrade {
+    constructor() { }
+    static async list(connection, options) {
+        try {
+            const whereClause = constructWhereList(options);
+            return await queryList(node_util_1.default.format(getListQuery(), whereClause), connection);
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                throw (0, packageUtils_1.applyErrorAction)((0, packageUtils_1.massageErrorMessage)(err));
+            }
+            throw err;
+        }
+    }
+    static async report(connection, options) {
+        try {
+            const whereClause = constructWhereReport(options);
+            return (await queryReport(node_util_1.default.format(getReportQuery(), whereClause), connection)).records;
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                throw (0, packageUtils_1.applyErrorAction)((0, packageUtils_1.massageErrorMessage)(err));
+            }
+            throw err;
+        }
+    }
+    static async getFailedJobs(connection, options) {
+        try {
+            const whereClause = constructWhereJobCountByStatus(options, 'Failed');
+            return (await queryJobCountByStatus(node_util_1.default.format(getJobCountByStatusQuery(), whereClause), connection)).records[0]
+                ?.expr0;
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                throw (0, packageUtils_1.applyErrorAction)((0, packageUtils_1.massageErrorMessage)(err));
+            }
+            throw err;
+        }
+    }
+    static async getSucceededJobs(connection, options) {
+        try {
+            const whereClause = constructWhereJobCountByStatus(options, 'Succeeded');
+            return (await queryJobCountByStatus(node_util_1.default.format(getJobCountByStatusQuery(), whereClause), connection)).records[0]
+                ?.expr0;
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                throw (0, packageUtils_1.applyErrorAction)((0, packageUtils_1.massageErrorMessage)(err));
+            }
+            throw err;
+        }
+    }
+    static async getTotalJobs(connection, options) {
+        try {
+            const whereClause = constructWhereJobCountByStatus(options);
+            return (await queryJobCountByStatus(node_util_1.default.format(getJobCountByStatusQuery(), whereClause), connection)).records[0]
+                ?.expr0;
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                throw (0, packageUtils_1.applyErrorAction)((0, packageUtils_1.massageErrorMessage)(err));
+            }
+            throw err;
+        }
+    }
+    static async getJobFailureReasons(connection, options) {
+        try {
+            const whereClause = constructWhereJobFailureReasons(options);
+            return (await queryJobFailureReasons(node_util_1.default.format(getJobFailureReasonsQuery(), whereClause), connection)).records;
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                throw (0, packageUtils_1.applyErrorAction)((0, packageUtils_1.massageErrorMessage)(err));
+            }
+            throw err;
+        }
+    }
+    static async schedule(connection, packageVersionId, scheduleTime, orgList, isMigration = false) {
+        let job;
+        try {
+            const packagePushRequestBody = {
+                PackageVersionId: packageVersionId,
+            };
+            if (scheduleTime) {
+                packagePushRequestBody.ScheduledStartTime = scheduleTime;
+            }
+            if (isMigration) {
+                packagePushRequestBody.IsMigration = true;
+            }
+            const pushRequestResult = await connection.request({
+                method: 'POST',
+                url: `/services/data/v${connection.getApiVersion()}/sobjects/packagepushrequest/`,
+                body: JSON.stringify(packagePushRequestBody),
+            });
+            const pushJobs = orgList.map((orgId) => ({
+                PackagePushRequestId: pushRequestResult.id,
+                SubscriberOrganizationKey: orgId,
+            }));
+            // Create PackagePushJob for each org using Bulk API v2
+            job = connection.bulk2.createJob({ operation: 'insert', object: 'PackagePushJob' });
+            await job.open();
+            await job.uploadData(pushJobs);
+            await job.close();
+            await job.poll(1000, 600_000);
+            // If there are any errors for a job, write all specific job errors to an output file
+            const jobErrors = await job.getFailedResults();
+            if (jobErrors.length > 0) {
+                const filePath = await this.writeJobErrorsToFile(pushRequestResult?.id, jobErrors);
+                throw new core_1.SfError(`Push upgrade failed, job errors have been written to file: ${filePath}`);
+            }
+            await connection.request({
+                method: 'PATCH',
+                url: `/services/data/v${connection.getApiVersion()}/sobjects/packagepushrequest/` + pushRequestResult?.id,
+                body: JSON.stringify({ Status: 'Pending' }),
+            });
+            return {
+                PushRequestId: pushRequestResult.id,
+                ScheduledStartTime: scheduleTime,
+                Status: 'Pending',
+            };
+        }
+        catch (err) {
+            if (job && err.name !== 'JobPollingTimeoutError') {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+                job.delete().catch((ignored) => ignored);
+            }
+            throw (0, packageUtils_1.applyErrorAction)((0, packageUtils_1.massageErrorMessage)(err));
+        }
+    }
+    static async abort(connection, options) {
+        try {
+            // Fetch the current status of the PackagePushRequest
+            const abortQuery = node_util_1.default.format(getPushRequestStatusQuery(), getPushRequestStatusWhereClause(options));
+            const queryResult = await queryReport(abortQuery, connection);
+            if (!queryResult.records || queryResult.records.length === 0) {
+                throw new Error('Can’t abort package push upgrade request. The specified push upgrade ID isn’t valid. Check the ID (starts with 0DV) and retry the command.');
+            }
+            const pushRequest = queryResult.records[0];
+            // Validate the current status
+            if (!['Created', 'Pending'].includes(pushRequest.Status)) {
+                throw new Error(`Can’t abort package push upgrade request with status '${pushRequest.Status}'. Only push upgrade requests with a status of 'Created' or 'Pending' can be cancelled.`);
+            }
+            // Abort the push request by setting its status to "Canceled"
+            await connection.request({
+                method: 'PATCH',
+                url: `/services/data/v${connection.getApiVersion()}/sobjects/packagepushrequest/` + options.packagePushRequestId,
+                body: JSON.stringify({ Status: 'Canceled' }),
+            });
+            // Return the updated PackagePushRequest details
+            return true;
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                throw (0, packageUtils_1.applyErrorAction)((0, packageUtils_1.massageErrorMessage)(err));
+            }
+            return false;
+        }
+    }
+    static async writeJobErrorsToFile(pushRequestId, jobErrors) {
+        const outputDir = node_path_1.default.join(process.cwd(), 'job_errors');
+        const outputFile = node_path_1.default.join(outputDir, `push_request_${pushRequestId}_errors.log`);
+        try {
+            await promises_1.default.mkdir(outputDir, { recursive: true });
+            const errorContent = jobErrors
+                .map((job, index) => `Job ${index + 1} Error:${JSON.stringify(job?.sf__Error, null, 2)}`)
+                .join('\n');
+            await promises_1.default.writeFile(outputFile, errorContent, 'utf-8');
+            return outputFile;
+        }
+        catch (error) {
+            throw new core_1.SfError('Error when saving job errors to file. ' + error.message);
+        }
+    }
+}
+exports.PackagePushUpgrade = PackagePushUpgrade;
+async function queryList(query, connection) {
+    const queryResult = await connection.autoFetchQuery(query, {});
+    return queryResult.records;
+}
+function constructWhereList(options) {
+    const where = [];
+    if (options?.packageId) {
+        where.push(`PackageVersion.MetadataPackageId = '${options.packageId}'`);
+    }
+    if (options?.status) {
+        where.push(`Status = '${options.status}'`);
+    }
+    if (options?.scheduledLastDays) {
+        const daysAgo = new Date();
+        daysAgo.setDate(daysAgo.getDate() - options.scheduledLastDays);
+        where.push(`ScheduledStartTime >= ${daysAgo.toISOString()}`);
+    }
+    if (options?.isMigration) {
+        where.push(`IsMigration = ${options.isMigration}`);
+    }
+    return where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
+}
+function getListQuery() {
+    // WHERE, if applicable
+    return ('SELECT Id, PackageVersionId, PackageVersion.Name, PackageVersion.MajorVersion, PackageVersion.MinorVersion, Status, ScheduledStartTime, StartTime, EndTime, IsMigration FROM PackagePushRequest ' +
+        '%s');
+}
+async function queryReport(query, connection) {
+    return connection.autoFetchQuery(query, {});
+}
+async function queryJobCountByStatus(query, connection) {
+    return connection.autoFetchQuery(query, {});
+}
+function constructWhereReport(options) {
+    const where = [];
+    where.push(`Id = '${options.packagePushRequestId}'`);
+    return `WHERE ${where.join(' AND ')}`;
+}
+function getReportQuery() {
+    const QUERY = 'SELECT PackageVersion.MetadataPackage.Name, PackageVersion.MajorVersion, PackageVersion.MinorVersion, PackageVersion.MetadataPackage.NamespacePrefix, PackageVersion.MetadataPackageId, PackageVersionId, PackageVersion.Name, Id, Status, ScheduledStartTime, StartTime, EndTime, DurationSeconds FROM PackagePushRequest ' +
+        '%s'; // WHERE, if applicable
+    return QUERY;
+}
+function constructWhereJobCountByStatus(options, status) {
+    const where = [];
+    where.push(`PackagePushRequestId = '${options.packagePushRequestId}'`);
+    if (status) {
+        where.push(`Status = '${status}'`);
+    }
+    return `WHERE ${where.join(' AND ')}`;
+}
+function getJobCountByStatusQuery() {
+    const QUERY = 'SELECT Count(Id) FROM PackagePushJob ' + '%s '; // WHERE, if applicable
+    return QUERY;
+}
+function constructWhereJobFailureReasons(options) {
+    const where = [];
+    where.push(`PackagePushJob.PackagePushRequestId = '${options.packagePushRequestId}'`);
+    return `WHERE ${where.join(' AND ')}`;
+}
+function getJobFailureReasonsQuery() {
+    const QUERY = 'SELECT ErrorMessage, ErrorDetails, ErrorTitle, ErrorSeverity, ErrorType from PackagePushError ' + '%s '; // WHERE, if applicable
+    return QUERY;
+}
+async function queryJobFailureReasons(query, connection) {
+    return connection.autoFetchQuery(query, {});
+}
+function getPushRequestStatusWhereClause(options) {
+    const where = [];
+    where.push(`Id = '${options.packagePushRequestId}'`);
+    return `WHERE ${where.join(' AND ')}`;
+}
+function getPushRequestStatusQuery() {
+    const QUERY = 'SELECT Id, Status FROM PackagePushRequest ' + '%s';
+    return QUERY;
+}
+//# sourceMappingURL=packagePushUpgrade.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/packaging",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "Packaging library for the Salesforce packaging platform",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",
@@ -42,7 +42,7 @@
   ],
   "dependencies": {
     "@jsforce/jsforce-node": "^3.6.5",
-    "@salesforce/core": "^8.8.5",
+    "@salesforce/core": "^8.11.1",
     "@salesforce/kit": "^3.2.3",
     "@salesforce/schemas": "^1.9.0",
     "@salesforce/source-deploy-retrieve": "^12.16.9",