@simplysf/simply-data 2.3.26 → 2.4.0

package/README.md

@@ -31,14 +31,17 @@ Upload a file to a Salesforce org.
 ```
 USAGE
   $ sf simply data file upload -o <value> --file-path <value> [--json] [--flags-dir <value>] [--api-version <value>]
-    [--first-publish-location-id <value>] [--title <value>]
+    [--max-api-usage <value>] [--first-publish-location-id <value>] [--title <value>]
 
 FLAGS
   -o, --target-org=<value>                 (required) Username or alias of the target org. Not required if the
                                            `target-org` configuration variable is already set.
       --api-version=<value>                Override the api version used for api requests made by this command
-      --file-path=<value>                  (required) Path to the file to upload.
+      --file-path=<value>                  (required) Path to the file to upload. May be relative or absolute; only the
+                                           file's name is sent to the org.
       --first-publish-location-id=<value>  Specify a record Id that the file should be linked to.
+      --max-api-usage=<value>              [default: 20] Maximum percentage of the org's remaining API requests this run
+                                           may consume.
       --title=<value>                      Specify the title for the file being uploaded.
 
 GLOBAL FLAGS
@@ -50,13 +53,32 @@ DESCRIPTION
 
   Uploads a file to a Salesforce org.
 
+  Only the file's name is sent to the org — Salesforce stores it as the ContentVersion's PathOnClient and derives
+  FileExtension and FileType from it — so the local directory the file came from is never uploaded.
+
 EXAMPLES
   $ sf simply data file upload --file-path fileToUpload.txt --target-org myTargetOrg
 
   $ sf simply data file upload --file-path fileToUpload.txt --first-publish-location-id 0019000000DmehK --target-org myTargetOrg
+
+FLAG DESCRIPTIONS
+  --max-api-usage=<value>  Maximum percentage of the org's remaining API requests this run may consume.
+
+    Checked before any request is made, so a run that would exceed its budget stops without doing partial work. The
+    percentage applies to the requests the org has left today, not to its daily maximum — an org that has already used
+    most of its allocation gets a proportionally smaller budget.
+
+    Note that uploading a file costs two API requests, not one: the upload itself, and a follow-up query for the
+    resulting ContentDocumentId.
+
+    A run that cannot finish within the org's remaining requests is refused regardless of this value. To allow a larger
+    share, raise it; to allow the maximum, pass 100.
+
+    If the org's remaining allocation can't be read — reading it falls back to the limits API, which needs the "View
+    Setup and Configuration" permission — the command warns and proceeds rather than failing.
 ```
 
-_See code: [lib/commands/simply/data/file/upload.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-data@2.3.26/packages/simply-data/lib/commands/simply/data/file/upload.js)_
+_See code: [lib/commands/simply/data/file/upload.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-data@2.4.0/packages/simply-data/lib/commands/simply/data/file/upload.js)_
 
 ## `sf simply data files download`
 
@@ -65,12 +87,14 @@ Download files from a Salesforce org.
 ```
 USAGE
   $ sf simply data files download -o <value> --where-content-version <value> [--json] [--flags-dir <value>] [--api-version
-    <value>] [--max-parallel-jobs <value>]
+    <value>] [--max-api-usage <value>] [--max-parallel-jobs <value>]
 
 FLAGS
   -o, --target-org=<value>             (required) Username or alias of the target org. Not required if the `target-org`
                                        configuration variable is already set.
       --api-version=<value>            Override the api version used for api requests made by this command
+      --max-api-usage=<value>          [default: 20] Maximum percentage of the org's remaining API requests this run may
+                                       consume.
       --max-parallel-jobs=<value>      [default: 1] Maximum number of parallel jobs.
       --where-content-version=<value>  (required) WHERE clause for ContentVersion query.
 
@@ -91,6 +115,21 @@ EXAMPLES
   $ sf simply data files download --where-content-version "IsLatest=true" --max-parallel-jobs 5 --target-org myTargetOrg
 
 FLAG DESCRIPTIONS
+  --max-api-usage=<value>  Maximum percentage of the org's remaining API requests this run may consume.
+
+    Checked before any request is made, so a run that would exceed its budget stops without doing partial work. The
+    percentage applies to the requests the org has left today, not to its daily maximum — an org that has already used
+    most of its allocation gets a proportionally smaller budget.
+
+    Note that uploading a file costs two API requests, not one: the upload itself, and a follow-up query for the
+    resulting ContentDocumentId.
+
+    A run that cannot finish within the org's remaining requests is refused regardless of this value. To allow a larger
+    share, raise it; to allow the maximum, pass 100.
+
+    If the org's remaining allocation can't be read — reading it falls back to the limits API, which needs the "View
+    Setup and Configuration" permission — the command warns and proceeds rather than failing.
+
   --max-parallel-jobs=<value>  Maximum number of parallel jobs.
 
     By default the plugin will only process a single file download at a time. You can increase this value to allow for
@@ -101,7 +140,7 @@ FLAG DESCRIPTIONS
     Provide a WHERE clause to allow the plugin to specify which ContentVersion records should be downloaded.
 ```
 
-_See code: [lib/commands/simply/data/files/download.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-data@2.3.26/packages/simply-data/lib/commands/simply/data/files/download.js)_
+_See code: [lib/commands/simply/data/files/download.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-data@2.4.0/packages/simply-data/lib/commands/simply/data/files/download.js)_
 
 ## `sf simply data files upload`
 
@@ -110,13 +149,15 @@ Upload files to a Salesforce org.
 ```
 USAGE
   $ sf simply data files upload -o <value> --file-path <value> [--json] [--flags-dir <value>] [--api-version <value>]
-    [--max-parallel-jobs <value>]
+    [--max-api-usage <value>] [--max-parallel-jobs <value>]
 
 FLAGS
   -o, --target-org=<value>         (required) Username or alias of the target org. Not required if the `target-org`
                                    configuration variable is already set.
       --api-version=<value>        Override the api version used for api requests made by this command
       --file-path=<value>          (required) Path to the csv file that specifies the upload.
+      --max-api-usage=<value>      [default: 20] Maximum percentage of the org's remaining API requests this run may
+                                   consume.
       --max-parallel-jobs=<value>  [default: 1] Maximum number of parallel jobs.
 
 GLOBAL FLAGS
@@ -140,13 +181,32 @@ FLAG DESCRIPTIONS
     The csv file must specify the columns PathOnClient and Title. Optionally, a FirstPublishLocationId can be specified
     to have it linked directly to a Salesforce record after upload.
 
+    PathOnClient is the local path each file is read from, and may be relative or absolute. Only the file's name is sent
+    to the org — Salesforce stores it as the ContentVersion's PathOnClient and derives FileExtension and FileType from
+    it — so the local directory the file came from is never uploaded.
+
+  --max-api-usage=<value>  Maximum percentage of the org's remaining API requests this run may consume.
+
+    Checked before any request is made, so a run that would exceed its budget stops without doing partial work. The
+    percentage applies to the requests the org has left today, not to its daily maximum — an org that has already used
+    most of its allocation gets a proportionally smaller budget.
+
+    Note that uploading a file costs two API requests, not one: the upload itself, and a follow-up query for the
+    resulting ContentDocumentId.
+
+    A run that cannot finish within the org's remaining requests is refused regardless of this value. To allow a larger
+    share, raise it; to allow the maximum, pass 100.
+
+    If the org's remaining allocation can't be read — reading it falls back to the limits API, which needs the "View
+    Setup and Configuration" permission — the command warns and proceeds rather than failing.
+
   --max-parallel-jobs=<value>  Maximum number of parallel jobs.
 
     By default the plugin will only process a single file upload at a time. You can increase this value to allow for
     quasi concurrent uploads. Please note that setting this value too high can cause performance issues.
 ```
 
-_See code: [lib/commands/simply/data/files/upload.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-data@2.3.26/packages/simply-data/lib/commands/simply/data/files/upload.js)_
+_See code: [lib/commands/simply/data/files/upload.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-data@2.4.0/packages/simply-data/lib/commands/simply/data/files/upload.js)_
 <!-- commandsstop -->
 
 ## License

package/lib/commands/simply/data/file/upload.d.ts

@@ -9,6 +9,7 @@ export default class DataFileUpload extends SfCommand<ContentVersion> {
         'file-path': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'first-publish-location-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         title: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'max-api-usage': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         'api-version': import("@oclif/core/interfaces").OptionFlag<string | undefined>;
         'target-org': import("@oclif/core/interfaces").OptionFlag<import("@salesforce/core").Org>;
         'flags-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/lib/commands/simply/data/file/upload.js

@@ -17,6 +17,8 @@ import { Messages } from '@salesforce/core';
 import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
 import { requireConnection, targetOrgFlags } from '@simplysf/simply-plugin-kit';
 import { uploadContentVersion } from '../../../../common/contentVersionUtils.js';
+import { apiBudgetFlags, assertApiBudget } from '../../../../common/apiBudgetFlag.js';
+import { REQUESTS_PER_UPLOAD } from '../../../../common/apiCost.js';
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@simplysf/simply-data', 'simply.data.file.upload');
 /** Uploads a single local file to a Salesforce org as a `ContentVersion`. */
@@ -27,6 +29,7 @@ export default class DataFileUpload extends SfCommand {
     static flags = {
         ...SfCommand.baseFlags,
         ...targetOrgFlags,
+        ...apiBudgetFlags,
         'file-path': Flags.directory({
             summary: messages.getMessage('flags.file-path.summary'),
             required: true,
@@ -43,6 +46,7 @@ export default class DataFileUpload extends SfCommand {
         const { flags } = await this.parse(DataFileUpload);
         // Authorize to the target org
         const targetOrgConnection = requireConnection(flags);
+        await assertApiBudget(targetOrgConnection, REQUESTS_PER_UPLOAD, flags['max-api-usage'], (message) => this.warn(message));
         this.spinner.start('Uploading file', '', { stdout: true });
         const contentVersion = await uploadContentVersion(targetOrgConnection, flags['file-path'], flags['title'], flags['first-publish-location-id']);
         this.spinner.stop();

package/lib/commands/simply/data/file/upload.js.map

@@ -1 +1 @@
-{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../../../../src/commands/simply/data/file/upload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAGjF,QAAQ,CAAC,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;AAE3F,6EAA6E;AAC7E,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,SAAyB;IAC5D,MAAM,CAAU,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,CAAU,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACjE,MAAM,CAAU,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAE5D,MAAM,CAAU,KAAK,GAAG;QAC7B,GAAG,SAAS,CAAC,SAAS;QACtB,GAAG,cAAc;QACjB,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC;YAC3B,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,yBAAyB,CAAC;YACvD,QAAQ,EAAE,IAAI;SACf,CAAC;QACF,2BAA2B,EAAE,KAAK,CAAC,MAAM,CAAC;YACxC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,yCAAyC,CAAC;SACxE,CAAC;QACF,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC;YAClB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,qBAAqB,CAAC;SACpD,CAAC;KACH,CAAC;IAEF,6CAA6C;IACtC,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAEnD,8BAA8B;QAC9B,MAAM,mBAAmB,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAErD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAE3D,MAAM,cAAc,GAAG,MAAM,oBAAoB,CAC/C,mBAAmB,EACnB,KAAK,CAAC,WAAW,CAAC,EAClB,KAAK,CAAC,OAAO,CAAC,EACd,KAAK,CAAC,2BAA2B,CAAC,CACnC,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAEpB,OAAO,cAAc,CAAC;IACxB,CAAC"}
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../../../../src/commands/simply/data/file/upload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAGpE,QAAQ,CAAC,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;AAE3F,6EAA6E;AAC7E,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,SAAyB;IAC5D,MAAM,CAAU,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,CAAU,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACjE,MAAM,CAAU,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAE5D,MAAM,CAAU,KAAK,GAAG;QAC7B,GAAG,SAAS,CAAC,SAAS;QACtB,GAAG,cAAc;QACjB,GAAG,cAAc;QACjB,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC;YAC3B,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,yBAAyB,CAAC;YACvD,QAAQ,EAAE,IAAI;SACf,CAAC;QACF,2BAA2B,EAAE,KAAK,CAAC,MAAM,CAAC;YACxC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,yCAAyC,CAAC;SACxE,CAAC;QACF,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC;YAClB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,qBAAqB,CAAC;SACpD,CAAC;KACH,CAAC;IAEF,6CAA6C;IACtC,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAEnD,8BAA8B;QAC9B,MAAM,mBAAmB,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAErD,MAAM,eAAe,CAAC,mBAAmB,EAAE,mBAAmB,EAAE,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAClG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CACnB,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAE3D,MAAM,cAAc,GAAG,MAAM,oBAAoB,CAC/C,mBAAmB,EACnB,KAAK,CAAC,WAAW,CAAC,EAClB,KAAK,CAAC,OAAO,CAAC,EACd,KAAK,CAAC,2BAA2B,CAAC,CACnC,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAEpB,OAAO,cAAc,CAAC;IACxB,CAAC"}

package/lib/commands/simply/data/files/download.d.ts

@@ -14,6 +14,7 @@ export default class DataFilesDownload extends SfCommand<void> {
     static readonly flags: {
         'max-parallel-jobs': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         'where-content-version': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'max-api-usage': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         'api-version': import("@oclif/core/interfaces").OptionFlag<string | undefined>;
         'target-org': import("@oclif/core/interfaces").OptionFlag<import("@salesforce/core").Org>;
         'flags-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/lib/commands/simply/data/files/download.js

@@ -20,6 +20,8 @@ import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
 import { requireConnection, targetOrgFlags } from '@simplysf/simply-plugin-kit';
 import { createCsvFileWriter } from '@simplysf/simply-core';
 import { downloadContentVersion } from '../../../../common/contentVersionUtils.js';
+import { apiBudgetFlags, assertApiBudget } from '../../../../common/apiBudgetFlag.js';
+import { REQUESTS_PER_DOWNLOAD, requestsForQuery } from '../../../../common/apiCost.js';
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@simplysf/simply-data', 'simply.data.files.download');
 /**
@@ -37,6 +39,7 @@ export default class DataFilesDownload extends SfCommand {
     static flags = {
         ...SfCommand.baseFlags,
         ...targetOrgFlags,
+        ...apiBudgetFlags,
         'max-parallel-jobs': Flags.integer({
             summary: messages.getMessage('flags.max-parallel-jobs.summary'),
             description: messages.getMessage('flags.max-parallel-jobs.description'),
@@ -59,6 +62,9 @@ export default class DataFilesDownload extends SfCommand {
             scanAll: false,
         });
         const contentVersionDownloads = result.records;
+        // The query above already ran through jsforce, so `connection.limitInfo` is populated and the
+        // budget check gets the free header path rather than spending a request on the limits API.
+        await assertApiBudget(targetOrgConnection, contentVersionDownloads.length * REQUESTS_PER_DOWNLOAD + requestsForQuery(contentVersionDownloads.length), flags['max-api-usage'], (message) => this.warn(message));
         this.spinner.start('Initializing file download', '\n', { stdout: true });
         if (!fs.existsSync('download')) {
             fs.mkdirSync('download');

package/lib/commands/simply/data/files/download.js.map

@@ -1 +1 @@
-{"version":3,"file":"download.js","sourceRoot":"","sources":["../../../../../src/commands/simply/data/files/download.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../../../../../src/commands/simply/data/files/download.ts"],"names":[],"mappings":"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"}

package/lib/commands/simply/data/files/upload.d.ts

@@ -15,6 +15,7 @@ export default class DataFilesUpload extends SfCommand<void> {
     static readonly flags: {
         'file-path': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'max-parallel-jobs': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'max-api-usage': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         'api-version': import("@oclif/core/interfaces").OptionFlag<string | undefined>;
         'target-org': import("@oclif/core/interfaces").OptionFlag<import("@salesforce/core").Org>;
         'flags-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/lib/commands/simply/data/files/upload.js

@@ -21,6 +21,9 @@ import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
 import { requireConnection, targetOrgFlags } from '@simplysf/simply-plugin-kit';
 import { createCsvFileWriter } from '@simplysf/simply-core';
 import { uploadContentVersion } from '../../../../common/contentVersionUtils.js';
+import { apiBudgetFlags, assertApiBudget } from '../../../../common/apiBudgetFlag.js';
+import { countCsvRows } from '../../../../common/countCsvRows.js';
+import { REQUESTS_PER_UPLOAD } from '../../../../common/apiCost.js';
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@simplysf/simply-data', 'simply.data.files.upload');
 /**
@@ -39,6 +42,7 @@ export default class DataFilesUpload extends SfCommand {
     static flags = {
         ...SfCommand.baseFlags,
         ...targetOrgFlags,
+        ...apiBudgetFlags,
         'file-path': Flags.directory({
             summary: messages.getMessage('flags.file-path.summary'),
             description: messages.getMessage('flags.file-path.description'),
@@ -54,6 +58,11 @@ export default class DataFilesUpload extends SfCommand {
         const { flags } = await this.parse(DataFilesUpload);
         // Authorize to the target org
         const targetOrgConnection = requireConnection(flags);
+        // The upload streams this CSV row by row, so the row count is not otherwise known until the
+        // work is already underway. Counting first costs one extra local read and no API requests,
+        // and it is what lets the budget be checked before anything is sent.
+        const rowCount = await countCsvRows(flags['file-path']);
+        await assertApiBudget(targetOrgConnection, rowCount * REQUESTS_PER_UPLOAD, flags['max-api-usage'], (message) => this.warn(message));
         this.spinner.start('Initializing file upload', '\n', { stdout: true });
         if (!fs.existsSync('upload')) {
             fs.mkdirSync('upload');

package/lib/commands/simply/data/files/upload.js.map

@@ -1 +1 @@
-{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../../../../src/commands/simply/data/files/upload.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../../../../src/commands/simply/data/files/upload.ts"],"names":[],"mappings":"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"}

package/lib/common/apiBudgetFlag.d.ts

@@ -0,0 +1,26 @@
+import { type ApiBudgetResult } from '@simplysf/simply-core';
+import type { Connection } from '@salesforce/core';
+/** Default share of the org's remaining API requests a single run may consume. */
+export declare const DEFAULT_MAX_API_USAGE = 20;
+/**
+ * `--max-api-usage`, shared by every command that can count its requests in advance.
+ *
+ * Declared once so the three file commands cannot drift apart on the default or the bounds.
+ */
+export declare const apiBudgetFlags: {
+    'max-api-usage': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+};
+/**
+ * Check a planned run against the org's remaining API allocation, and stop it if it does not fit.
+ *
+ * Call this before making any of the requests being counted — the value of the check is entirely
+ * in nothing having happened when it fails.
+ *
+ * @param connection - The org connection.
+ * @param plannedRequests - How many API requests the run is about to make.
+ * @param maxUsagePercent - The `--max-api-usage` value.
+ * @param warn - Called when the allocation could not be read, so the command can surface it.
+ * @returns The check result, for inclusion in the command's JSON output.
+ * @throws {SfError} If the run would exceed its budget.
+ */
+export declare function assertApiBudget(connection: Connection, plannedRequests: number, maxUsagePercent: number, warn: (message: string) => void): Promise<ApiBudgetResult>;

package/lib/common/apiBudgetFlag.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2026, Clay Chipps.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Messages } from '@salesforce/core';
+import { Flags } from '@salesforce/sf-plugins-core';
+import { apiBudgetError, checkApiBudget } from '@simplysf/simply-core';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@simplysf/simply-data', 'apiBudget');
+/** Default share of the org's remaining API requests a single run may consume. */
+export const DEFAULT_MAX_API_USAGE = 20;
+/**
+ * `--max-api-usage`, shared by every command that can count its requests in advance.
+ *
+ * Declared once so the three file commands cannot drift apart on the default or the bounds.
+ */
+export const apiBudgetFlags = {
+    'max-api-usage': Flags.integer({
+        summary: messages.getMessage('flags.max-api-usage.summary'),
+        description: messages.getMessage('flags.max-api-usage.description'),
+        default: DEFAULT_MAX_API_USAGE,
+        min: 1,
+        max: 100,
+    }),
+};
+/**
+ * Check a planned run against the org's remaining API allocation, and stop it if it does not fit.
+ *
+ * Call this before making any of the requests being counted — the value of the check is entirely
+ * in nothing having happened when it fails.
+ *
+ * @param connection - The org connection.
+ * @param plannedRequests - How many API requests the run is about to make.
+ * @param maxUsagePercent - The `--max-api-usage` value.
+ * @param warn - Called when the allocation could not be read, so the command can surface it.
+ * @returns The check result, for inclusion in the command's JSON output.
+ * @throws {SfError} If the run would exceed its budget.
+ */
+export async function assertApiBudget(connection, plannedRequests, maxUsagePercent, warn) {
+    const result = await checkApiBudget(connection, plannedRequests, { maxUsagePercent });
+    if (result.status === 'unavailable') {
+        warn(messages.getMessage('warning.budgetUnavailable', [result.reason ?? 'unknown reason']));
+        return result;
+    }
+    if (result.status === 'exceeded') {
+        throw apiBudgetError(result, maxUsagePercent);
+    }
+    return result;
+}
+//# sourceMappingURL=apiBudgetFlag.js.map

package/lib/common/apiBudgetFlag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiBudgetFlag.js","sourceRoot":"","sources":["../../src/common/apiBudgetFlag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAwB,MAAM,uBAAuB,CAAC;AAG7F,QAAQ,CAAC,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,uBAAuB,EAAE,WAAW,CAAC,CAAC;AAE7E,kFAAkF;AAClF,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC;QAC7B,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,6BAA6B,CAAC;QAC3D,WAAW,EAAE,QAAQ,CAAC,UAAU,CAAC,iCAAiC,CAAC;QACnE,OAAO,EAAE,qBAAqB;QAC9B,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,GAAG;KACT,CAAC;CACH,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAsB,EACtB,eAAuB,EACvB,eAAuB,EACvB,IAA+B;IAE/B,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,UAAU,EAAE,eAAe,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;IAEtF,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,2BAA2B,EAAE,CAAC,MAAM,CAAC,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAC;QAE5F,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,cAAc,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/lib/common/apiCost.d.ts

@@ -0,0 +1,23 @@
+/**
+ * API requests consumed per file uploaded.
+ *
+ * **Two, not one.** Salesforce's create response returns only the new `ContentVersion` id, so
+ * `uploadContentVersion` follows it with a query for `ContentDocumentId`. Both count toward the
+ * org's daily allocation. Counting one per file here would under-budget every upload by half.
+ */
+export declare const REQUESTS_PER_UPLOAD = 2;
+/** API requests consumed per file downloaded — a single GET of the `VersionData` blob. */
+export declare const REQUESTS_PER_DOWNLOAD = 1;
+/**
+ * Records jsforce returns per query round trip before it has to fetch another batch.
+ *
+ * Used to estimate how many requests a record query costs on top of the per-file work.
+ */
+export declare const QUERY_BATCH_SIZE = 2000;
+/**
+ * Estimate the API requests a record query costs, including its `queryMore` round trips.
+ *
+ * @param recordCount - How many records the query returns.
+ * @returns The number of requests, at least 1.
+ */
+export declare function requestsForQuery(recordCount: number): number;

package/lib/common/apiCost.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2026, Clay Chipps.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * API requests consumed per file uploaded.
+ *
+ * **Two, not one.** Salesforce's create response returns only the new `ContentVersion` id, so
+ * `uploadContentVersion` follows it with a query for `ContentDocumentId`. Both count toward the
+ * org's daily allocation. Counting one per file here would under-budget every upload by half.
+ */
+export const REQUESTS_PER_UPLOAD = 2;
+/** API requests consumed per file downloaded — a single GET of the `VersionData` blob. */
+export const REQUESTS_PER_DOWNLOAD = 1;
+/**
+ * Records jsforce returns per query round trip before it has to fetch another batch.
+ *
+ * Used to estimate how many requests a record query costs on top of the per-file work.
+ */
+export const QUERY_BATCH_SIZE = 2000;
+/**
+ * Estimate the API requests a record query costs, including its `queryMore` round trips.
+ *
+ * @param recordCount - How many records the query returns.
+ * @returns The number of requests, at least 1.
+ */
+export function requestsForQuery(recordCount) {
+    return Math.max(1, Math.ceil(recordCount / QUERY_BATCH_SIZE));
+}
+//# sourceMappingURL=apiCost.js.map

package/lib/common/apiCost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiCost.js","sourceRoot":"","sources":["../../src/common/apiCost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAErC,0FAA0F;AAC1F,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,GAAG,gBAAgB,CAAC,CAAC,CAAC;AAChE,CAAC"}

package/lib/common/contentVersionUtils.d.ts

@@ -14,12 +14,17 @@ export declare function downloadContentVersion(targetOrgConnection: Connection,
 /**
  * Upload a local file as a new `ContentVersion`.
  *
+ * Only the file's name is sent to the org as `PathOnClient`, not the local path it was read from.
+ * Salesforce derives `FileExtension` and `FileType` from that value, so the name is all it needs —
+ * and sending the rest would publish the uploader's local directory layout into the org, where it
+ * is visible to anyone who can query `ContentVersion`.
+ *
  * @param targetOrgConnection - The org connection to upload to.
- * @param pathOnClient - The local filesystem path of the file to upload.
- * @param title - The `ContentVersion` title. Defaults to the file's basename.
+ * @param filePath - The local filesystem path of the file to upload. Stays local.
+ * @param title - The `ContentVersion` title. Defaults to the file's name.
  * @param firstPublishLocationId - The ID of the record/library to attach the resulting
  * `ContentDocument` to, if any.
  * @returns The created `ContentVersion`, re-queried to include `ContentDocumentId`.
  * @throws {SfError} If the org returns a non-2xx response.
  */
-export declare function uploadContentVersion(targetOrgConnection: Connection, pathOnClient: string, title?: string, firstPublishLocationId?: string): Promise<ContentVersion>;
+export declare function uploadContentVersion(targetOrgConnection: Connection, filePath: string, title?: string, firstPublishLocationId?: string): Promise<ContentVersion>;

package/lib/common/contentVersionUtils.js

@@ -20,6 +20,33 @@ import { SfError } from '@salesforce/core';
 import { contentVersionMultipart } from './multipart.js';
 /** How much of an error response body to include in a thrown error before truncating. */
 const MAX_ERROR_BODY_LENGTH = 2000;
+/** Matches the `api-usage=used/limit` portion of a `Sforce-Limit-Info` response header. */
+const API_USAGE_PATTERN = /api-usage=(?<used>\d+)\/(?<limit>\d+)/;
+/**
+ * Feed a raw `fetch` response's `Sforce-Limit-Info` header back into the connection.
+ *
+ * Salesforce reports API consumption on every REST response, and jsforce normally parses it into
+ * `connection.limitInfo`. These two functions call `fetch` directly, so jsforce never sees their
+ * responses and the readings would otherwise be lost — leaving `limitInfo` stale at whatever the
+ * last jsforce-issued request reported, which for an upload run is "nothing at all".
+ *
+ * Keeping it current costs one header parse and makes the reading available to the API budget
+ * check and to any later running check.
+ *
+ * @param connection - The connection whose `limitInfo` should be updated.
+ * @param response - The response to read the header from.
+ */
+function recordApiUsage(connection, response) {
+    const match = API_USAGE_PATTERN.exec(response.headers.get('sforce-limit-info') ?? '');
+    if (match?.groups) {
+        connection.limitInfo = {
+            apiUsage: {
+                used: Number.parseInt(match.groups.used, 10),
+                limit: Number.parseInt(match.groups.limit, 10),
+            },
+        };
+    }
+}
 /**
  * Turn a non-2xx response into an `SfError`.
  *
@@ -58,6 +85,7 @@ export async function downloadContentVersion(targetOrgConnection, contentVersion
             Authorization: `Bearer ${targetOrgConnection.accessToken}`,
         },
     });
+    recordApiUsage(targetOrgConnection, response);
     // Checked before the write stream is opened, so a failed download leaves nothing behind.
     if (!response.ok) {
         throw await responseError(response, `Download of ContentVersion ${contentVersionDownload.Id}`);
@@ -71,26 +99,32 @@ export async function downloadContentVersion(targetOrgConnection, contentVersion
 /**
  * Upload a local file as a new `ContentVersion`.
  *
+ * Only the file's name is sent to the org as `PathOnClient`, not the local path it was read from.
+ * Salesforce derives `FileExtension` and `FileType` from that value, so the name is all it needs —
+ * and sending the rest would publish the uploader's local directory layout into the org, where it
+ * is visible to anyone who can query `ContentVersion`.
+ *
  * @param targetOrgConnection - The org connection to upload to.
- * @param pathOnClient - The local filesystem path of the file to upload.
- * @param title - The `ContentVersion` title. Defaults to the file's basename.
+ * @param filePath - The local filesystem path of the file to upload. Stays local.
+ * @param title - The `ContentVersion` title. Defaults to the file's name.
  * @param firstPublishLocationId - The ID of the record/library to attach the resulting
  * `ContentDocument` to, if any.
  * @returns The created `ContentVersion`, re-queried to include `ContentDocumentId`.
  * @throws {SfError} If the org returns a non-2xx response.
  */
-export async function uploadContentVersion(targetOrgConnection, pathOnClient, title, firstPublishLocationId) {
+export async function uploadContentVersion(targetOrgConnection, filePath, title, firstPublishLocationId) {
     // Check that we have access to the file
-    await fs.promises.access(pathOnClient, fs.constants.F_OK);
+    await fs.promises.access(filePath, fs.constants.F_OK);
+    const fileName = path.basename(filePath);
     const contentVersionCreateRequest = {
         FirstPublishLocationId: firstPublishLocationId,
-        PathOnClient: pathOnClient,
-        Title: title ?? path.basename(pathOnClient),
+        PathOnClient: fileName,
+        Title: title ?? fileName,
     };
     const { contentType, createBody } = contentVersionMultipart({
         entity: contentVersionCreateRequest,
-        filePath: pathOnClient,
-        filename: path.basename(pathOnClient),
+        filePath,
+        filename: fileName,
     });
     const response = await fetch(`${targetOrgConnection.baseUrl()}/sobjects/ContentVersion`, {
         method: 'POST',
@@ -102,8 +136,9 @@ export async function uploadContentVersion(targetOrgConnection, pathOnClient, ti
             'Content-Type': contentType,
         },
     });
+    recordApiUsage(targetOrgConnection, response);
     if (!response.ok) {
-        throw await responseError(response, `Upload of "${pathOnClient}"`);
+        throw await responseError(response, `Upload of "${filePath}"`);
     }
     const data = (await response.json());
     const queryResult = await targetOrgConnection.singleRecordQuery(`SELECT ContentDocumentId, FileExtension, Id, Title FROM ContentVersion WHERE Id='${data.id}'`);

package/lib/common/contentVersionUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"contentVersionUtils.js","sourceRoot":"","sources":["../../src/common/contentVersionUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contentVersionUtils.js","sourceRoot":"","sources":["../../src/common/contentVersionUtils.ts"],"names":[],"mappings":"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"}

package/lib/common/countCsvRows.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Count the data rows in a CSV, excluding its header.
+ *
+ * Parses rather than counting newlines: a quoted field may contain line breaks, so `\n` counting
+ * over-reports and would budget for uploads that never happen. The parser options match the ones
+ * the upload itself uses, so the count and the work cannot disagree.
+ *
+ * This reads the file a second time rather than buffering the parsed rows. The trade is a cheap
+ * sequential local read against unbounded memory on exactly the large inputs where checking the
+ * budget matters most.
+ *
+ * @param filePath - Path to the CSV.
+ * @returns The number of data rows.
+ */
+export declare function countCsvRows(filePath: string): Promise<number>;

package/lib/common/countCsvRows.js

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2026, Clay Chipps.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import fs from 'node:fs';
+import { parse } from 'csv-parse';
+/**
+ * Count the data rows in a CSV, excluding its header.
+ *
+ * Parses rather than counting newlines: a quoted field may contain line breaks, so `\n` counting
+ * over-reports and would budget for uploads that never happen. The parser options match the ones
+ * the upload itself uses, so the count and the work cannot disagree.
+ *
+ * This reads the file a second time rather than buffering the parsed rows. The trade is a cheap
+ * sequential local read against unbounded memory on exactly the large inputs where checking the
+ * budget matters most.
+ *
+ * @param filePath - Path to the CSV.
+ * @returns The number of data rows.
+ */
+export async function countCsvRows(filePath) {
+    const parser = fs.createReadStream(filePath).pipe(parse({ bom: true, columns: true }));
+    let rows = 0;
+    for await (const record of parser) {
+        // The record itself is not needed, only that the parser produced one.
+        void record;
+        rows++;
+    }
+    return rows;
+}
+//# sourceMappingURL=countCsvRows.js.map

package/lib/common/countCsvRows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"countCsvRows.js","sourceRoot":"","sources":["../../src/common/countCsvRows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,MAAM,MAAM,GAAG,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAEvF,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAClC,sEAAsE;QACtE,KAAK,MAAM,CAAC;QACZ,IAAI,EAAE,CAAC;IACT,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/messages/apiBudget.md

@@ -0,0 +1,17 @@
+# flags.max-api-usage.summary
+
+Maximum percentage of the org's remaining API requests this run may consume.
+
+# flags.max-api-usage.description
+
+Checked before any request is made, so a run that would exceed its budget stops without doing partial work. The percentage applies to the requests the org has left today, not to its daily maximum — an org that has already used most of its allocation gets a proportionally smaller budget.
+
+Note that uploading a file costs two API requests, not one: the upload itself, and a follow-up query for the resulting ContentDocumentId.
+
+A run that cannot finish within the org's remaining requests is refused regardless of this value. To allow a larger share, raise it; to allow the maximum, pass 100.
+
+If the org's remaining allocation can't be read — reading it falls back to the limits API, which needs the "View Setup and Configuration" permission — the command warns and proceeds rather than failing.
+
+# warning.budgetUnavailable
+
+Could not read the org's remaining API requests, so the --max-api-usage budget was not checked: %s

package/messages/simply.data.file.upload.md

@@ -6,9 +6,11 @@ Upload a file to a Salesforce org.
 
 Uploads a file to a Salesforce org.
 
+Only the file's name is sent to the org — Salesforce stores it as the ContentVersion's PathOnClient and derives FileExtension and FileType from it — so the local directory the file came from is never uploaded.
+
 # flags.file-path.summary
 
-Path to the file to upload.
+Path to the file to upload. May be relative or absolute; only the file's name is sent to the org.
 
 # flags.first-publish-location-id.summary
 

package/messages/simply.data.files.upload.md

@@ -14,6 +14,8 @@ Path to the csv file that specifies the upload.
 
 The csv file must specify the columns PathOnClient and Title. Optionally, a FirstPublishLocationId can be specified to have it linked directly to a Salesforce record after upload.
 
+PathOnClient is the local path each file is read from, and may be relative or absolute. Only the file's name is sent to the org — Salesforce stores it as the ContentVersion's PathOnClient and derives FileExtension and FileType from it — so the local directory the file came from is never uploaded.
+
 # flags.max-parallel-jobs.summary
 
 Maximum number of parallel jobs.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simplysf/simply-data",
   "description": "Utilities for working with data",
-  "version": "2.3.26",
+  "version": "2.4.0",
   "author": "@ClayChipps",
   "homepage": "https://github.com/SimplySF/simply-node",
   "bugs": "https://github.com/SimplySF/simply-node/issues",
@@ -65,7 +65,7 @@
     "@salesforce/core": "^8.30.0",
     "@salesforce/kit": "^3.2.6",
     "@salesforce/sf-plugins-core": "^12.2.16",
-    "@simplysf/simply-core": "^1.3.0",
+    "@simplysf/simply-core": "^1.4.0",
     "@simplysf/simply-plugin-kit": "^1.0.4",
     "csv-parse": "^7.0.2",
     "p-queue": "^9.2.0"
@@ -214,5 +214,5 @@
       "output": []
     }
   },
-  "gitHead": "b347839b65111c6691ebf541d89dd7308fc51152"
+  "gitHead": "714cbc02c9cac7b8eb745a5be607e281af238751"
 }