@simplysf/simply-data 2.3.25 → 2.3.27

package/README.md

@@ -37,7 +37,8 @@ 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.
       --title=<value>                      Specify the title for the file being uploaded.
 
@@ -50,13 +51,16 @@ 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
 ```
 
-_See code: [lib/commands/simply/data/file/upload.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-data@2.3.25/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.3.27/packages/simply-data/lib/commands/simply/data/file/upload.js)_
 
 ## `sf simply data files download`
 
@@ -101,7 +105,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.25/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.3.27/packages/simply-data/lib/commands/simply/data/files/download.js)_
 
 ## `sf simply data files upload`
 
@@ -140,13 +144,17 @@ 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-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.25/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.3.27/packages/simply-data/lib/commands/simply/data/files/upload.js)_
 <!-- commandsstop -->
 
 ## License

package/lib/common/contentVersionUtils.d.ts

@@ -8,16 +8,23 @@ import { ContentVersion, ContentVersionDownload } from './contentVersionTypes.js
  * `ContentDocumentId`, and `FileExtension` are used to build the output file path.
  * @param downloadDirectory - The local directory to write the file into.
  * @returns The local path the file was written to.
+ * @throws {SfError} If the org returns a non-2xx response, before any file is created.
  */
 export declare function downloadContentVersion(targetOrgConnection: Connection, contentVersionDownload: ContentVersionDownload, downloadDirectory: string): Promise<string>;
 /**
  * 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

@@ -15,9 +15,32 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import stream from 'node:stream';
-import FormData from 'form-data';
-import got from 'got';
+import stream, { Readable } from 'node:stream';
+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;
+/**
+ * Turn a non-2xx response into an `SfError`.
+ *
+ * `fetch` — unlike the `got` client this replaced — resolves successfully for 4xx and 5xx, so every
+ * call site has to check `response.ok` itself. Missing one is how an HTML error page ends up
+ * written to disk with a `.pdf` extension.
+ *
+ * @param response - The failed response. Its body is consumed.
+ * @param context - What was being attempted, used as the error message prefix.
+ * @returns An `SfError` carrying the status and as much of the body as is useful.
+ */
+async function responseError(response, context) {
+    let body = '';
+    try {
+        body = (await response.text()).slice(0, MAX_ERROR_BODY_LENGTH);
+    }
+    catch {
+        // A body we can't read is not worth failing differently over; the status still tells the story.
+    }
+    return new SfError(`${context} failed with HTTP ${response.status} ${response.statusText}${body ? `: ${body}` : ''}`, 'ContentVersionRequestError');
+}
 /**
  * Download a `ContentVersion`'s file data to a local directory.
  *
@@ -26,46 +49,69 @@ import got from 'got';
  * `ContentDocumentId`, and `FileExtension` are used to build the output file path.
  * @param downloadDirectory - The local directory to write the file into.
  * @returns The local path the file was written to.
+ * @throws {SfError} If the org returns a non-2xx response, before any file is created.
  */
 export async function downloadContentVersion(targetOrgConnection, contentVersionDownload, downloadDirectory) {
     const filePath = `${downloadDirectory}/${contentVersionDownload.ContentDocumentId}_${contentVersionDownload.Title.replaceAll(' ', '_')}.${contentVersionDownload.FileExtension}`;
-    await stream.promises.pipeline(got.stream(`${targetOrgConnection.baseUrl()}/sobjects/ContentVersion/${contentVersionDownload.Id}/VersionData`, {
+    const response = await fetch(`${targetOrgConnection.baseUrl()}/sobjects/ContentVersion/${contentVersionDownload.Id}/VersionData`, {
         headers: {
             Authorization: `Bearer ${targetOrgConnection.accessToken}`,
         },
-    }), fs.createWriteStream(filePath));
+    });
+    // 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}`);
+    }
+    if (!response.body) {
+        throw new SfError(`Download of ContentVersion ${contentVersionDownload.Id} returned an empty response body.`, 'ContentVersionRequestError');
+    }
+    await stream.promises.pipeline(Readable.fromWeb(response.body), fs.createWriteStream(filePath));
     return filePath;
 }
 /**
  * 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 form = new FormData();
-    form.append('entity_content', JSON.stringify(contentVersionCreateRequest), { contentType: 'application/json' });
-    form.append('VersionData', fs.createReadStream(pathOnClient), { filename: path.basename(pathOnClient) });
-    const data = await got.post(`${targetOrgConnection.baseUrl()}/sobjects/ContentVersion`, {
-        body: form,
+    const { contentType, createBody } = contentVersionMultipart({
+        entity: contentVersionCreateRequest,
+        filePath,
+        filename: fileName,
+    });
+    const response = await fetch(`${targetOrgConnection.baseUrl()}/sobjects/ContentVersion`, {
+        method: 'POST',
+        // `duplex: 'half'` is required by undici whenever the body is a stream.
+        body: Readable.toWeb(createBody()),
+        duplex: 'half',
         headers: {
             Authorization: `Bearer ${targetOrgConnection.accessToken}`,
-            'Content-Type': `multipart/form-data; boundary="${form.getBoundary()}"`,
+            'Content-Type': contentType,
         },
-        resolveBodyOnly: true,
-        responseType: 'json',
     });
+    if (!response.ok) {
+        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}'`);
     return queryResult;
 }

package/lib/common/contentVersionUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"contentVersionUtils.js","sourceRoot":"","sources":["../../src/common/contentVersionUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,QAAQ,MAAM,WAAW,CAAC;AACjC,OAAO,GAAG,MAAM,KAAK,CAAC;AAStB;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,mBAA+B,EAC/B,sBAA8C,EAC9C,iBAAyB;IAEzB,MAAM,QAAQ,GAAG,GAAG,iBAAiB,IACnC,sBAAsB,CAAC,iBACzB,IAAI,sBAAsB,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,sBAAsB,CAAC,aAAa,EAAE,CAAC;IAEhG,MAAM,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAC5B,GAAG,CAAC,MAAM,CAAC,GAAG,mBAAmB,CAAC,OAAO,EAAE,4BAA4B,sBAAsB,CAAC,EAAE,cAAc,EAAE;QAC9G,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,mBAAmB,CAAC,WAAqB,EAAE;SACrE;KACF,CAAC,EACF,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAC/B,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,mBAA+B,EAC/B,YAAoB,EACpB,KAAc,EACd,sBAA+B;IAE/B,wCAAwC;IACxC,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAE1D,MAAM,2BAA2B,GAAgC;QAC/D,sBAAsB,EAAE,sBAAsB;QAC9C,YAAY,EAAE,YAAY;QAC1B,KAAK,EAAE,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;KAC5C,CAAC;IAEF,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;IAC5B,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,IAAI,CAAC,SAAS,CAAC,2BAA2B,CAAC,EAAE,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAChH,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,CAAC,gBAAgB,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAEzG,MAAM,IAAI,GAA+B,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,EAAE;QAClH,IAAI,EAAE,IAAI;QACV,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,mBAAmB,CAAC,WAAqB,EAAE;YACpE,cAAc,EAAE,kCAAkC,IAAI,CAAC,WAAW,EAAE,GAAG;SACxE;QACD,eAAe,EAAE,IAAI;QACrB,YAAY,EAAE,MAAM;KACrB,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,MAAM,mBAAmB,CAAC,iBAAiB,CAC7D,oFAAoF,IAAI,CAAC,EAAE,GAAG,CAC/F,CAAC;IAEF,OAAO,WAA6B,CAAC;AACvC,CAAC"}
+{"version":3,"file":"contentVersionUtils.js","sourceRoot":"","sources":["../../src/common/contentVersionUtils.ts"],"names":[],"mappings":"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"}

package/lib/common/multipart.d.ts

@@ -0,0 +1,58 @@
+import { Readable } from 'node:stream';
+/**
+ * Generate a multipart boundary.
+ *
+ * The boundary must not appear anywhere in the encoded body. Rather than scanning the file to
+ * prove that, we use 128 bits of randomness, which makes an accidental collision less likely than
+ * a disk error corrupting the upload anyway.
+ *
+ * @returns A boundary string, comfortably under the 70-character limit.
+ */
+export declare function createBoundary(): string;
+/**
+ * Escape a filename for inclusion in a `Content-Disposition` header.
+ *
+ * Applies the same normalization the WHATWG `FormData` serializer does. Without it, a file named
+ * `my"file.pdf` would close the quoted string early, and one containing a newline could inject a
+ * header. The `form-data` package this replaced did neither.
+ *
+ * @param filename - The raw filename.
+ * @returns The filename with `"`, CR, and LF percent-encoded.
+ */
+export declare function escapeHeaderFilename(filename: string): string;
+/** A multipart request body, plus the `Content-Type` header value that describes it. */
+export type ContentVersionMultipart = {
+    /** The generated (or supplied) boundary. */
+    boundary: string;
+    /** The value for the request's `Content-Type` header, including the boundary. */
+    contentType: string;
+    /**
+     * Build the request body.
+     *
+     * This is a factory rather than a stream because a stream can only be consumed once, and a
+     * retried upload needs a fresh body. Each call re-opens the file.
+     */
+    createBody: () => Readable;
+};
+/**
+ * Build the `multipart/form-data` body for a `ContentVersion` create request.
+ *
+ * The shape here matches Salesforce's documented example exactly, including the trailing semicolon
+ * after `name="entity_content"` and the absence of a `filename` on that part. That absence is the
+ * reason this is hand-built rather than delegated to the platform's `FormData`: a `FormData` part
+ * carrying `Content-Type: application/json` is necessarily a `Blob`, and a `Blob` part always
+ * serializes with a filename.
+ *
+ * @param options - The entity metadata, the file to attach, and an optional fixed boundary.
+ * @param options.entity - Serialized as the JSON `entity_content` part.
+ * @param options.filePath - Path of the file streamed as the `VersionData` part.
+ * @param options.filename - Filename advertised for the `VersionData` part.
+ * @param options.boundary - Boundary to use. Defaults to a random one; pass a fixed value in tests.
+ * @returns The boundary, the `Content-Type` header value, and a body factory.
+ */
+export declare function contentVersionMultipart(options: {
+    entity: unknown;
+    filePath: string;
+    filename: string;
+    boundary?: string;
+}): ContentVersionMultipart;

package/lib/common/multipart.js

@@ -0,0 +1,92 @@
+/*
+ * 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 crypto from 'node:crypto';
+import fs from 'node:fs';
+import { Readable } from 'node:stream';
+/**
+ * Prefix for generated boundaries. Salesforce caps a boundary at 70 characters, so this plus the
+ * 32 hex characters appended to it has to stay under that.
+ */
+const BOUNDARY_PREFIX = 'simplyBoundary';
+/** CRLF, which is what RFC 2046 requires between multipart headers and parts — not a bare `\n`. */
+const CRLF = '\r\n';
+/**
+ * Generate a multipart boundary.
+ *
+ * The boundary must not appear anywhere in the encoded body. Rather than scanning the file to
+ * prove that, we use 128 bits of randomness, which makes an accidental collision less likely than
+ * a disk error corrupting the upload anyway.
+ *
+ * @returns A boundary string, comfortably under the 70-character limit.
+ */
+export function createBoundary() {
+    return `${BOUNDARY_PREFIX}${crypto.randomBytes(16).toString('hex')}`;
+}
+/**
+ * Escape a filename for inclusion in a `Content-Disposition` header.
+ *
+ * Applies the same normalization the WHATWG `FormData` serializer does. Without it, a file named
+ * `my"file.pdf` would close the quoted string early, and one containing a newline could inject a
+ * header. The `form-data` package this replaced did neither.
+ *
+ * @param filename - The raw filename.
+ * @returns The filename with `"`, CR, and LF percent-encoded.
+ */
+export function escapeHeaderFilename(filename) {
+    return filename.replaceAll('\r', '%0D').replaceAll('\n', '%0A').replaceAll('"', '%22');
+}
+/**
+ * Build the `multipart/form-data` body for a `ContentVersion` create request.
+ *
+ * The shape here matches Salesforce's documented example exactly, including the trailing semicolon
+ * after `name="entity_content"` and the absence of a `filename` on that part. That absence is the
+ * reason this is hand-built rather than delegated to the platform's `FormData`: a `FormData` part
+ * carrying `Content-Type: application/json` is necessarily a `Blob`, and a `Blob` part always
+ * serializes with a filename.
+ *
+ * @param options - The entity metadata, the file to attach, and an optional fixed boundary.
+ * @param options.entity - Serialized as the JSON `entity_content` part.
+ * @param options.filePath - Path of the file streamed as the `VersionData` part.
+ * @param options.filename - Filename advertised for the `VersionData` part.
+ * @param options.boundary - Boundary to use. Defaults to a random one; pass a fixed value in tests.
+ * @returns The boundary, the `Content-Type` header value, and a body factory.
+ */
+export function contentVersionMultipart(options) {
+    const boundary = options.boundary ?? createBoundary();
+    const entityJson = JSON.stringify(options.entity);
+    const filename = escapeHeaderFilename(options.filename);
+    const header = Buffer.from(`--${boundary}${CRLF}` +
+        `Content-Disposition: form-data; name="entity_content";${CRLF}` +
+        `Content-Type: application/json${CRLF}${CRLF}` +
+        `${entityJson}${CRLF}` +
+        `--${boundary}${CRLF}` +
+        `Content-Type: application/octet-stream${CRLF}` +
+        `Content-Disposition: form-data; name="VersionData"; filename="${filename}"${CRLF}${CRLF}`, 'utf8');
+    const footer = Buffer.from(`${CRLF}--${boundary}--${CRLF}`, 'utf8');
+    const createBody = () => Readable.from((async function* body() {
+        yield header;
+        yield* fs.createReadStream(options.filePath);
+        yield footer;
+    })());
+    return {
+        boundary,
+        // Unquoted, matching what `form-data` and jsforce emit. RFC 2046 permits quoting, but the
+        // unquoted form is the one known to work against this endpoint.
+        contentType: `multipart/form-data; boundary=${boundary}`,
+        createBody,
+    };
+}
+//# sourceMappingURL=multipart.js.map

package/lib/common/multipart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.js","sourceRoot":"","sources":["../../src/common/multipart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;GAGG;AACH,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAEzC,mGAAmG;AACnG,MAAM,IAAI,GAAG,MAAM,CAAC;AAEpB;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,GAAG,eAAe,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,OAAO,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AACzF,CAAC;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAKvC;IACC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,cAAc,EAAE,CAAC;IACtD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,oBAAoB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAExD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CACxB,KAAK,QAAQ,GAAG,IAAI,EAAE;QACpB,yDAAyD,IAAI,EAAE;QAC/D,iCAAiC,IAAI,GAAG,IAAI,EAAE;QAC9C,GAAG,UAAU,GAAG,IAAI,EAAE;QACtB,KAAK,QAAQ,GAAG,IAAI,EAAE;QACtB,yCAAyC,IAAI,EAAE;QAC/C,iEAAiE,QAAQ,IAAI,IAAI,GAAG,IAAI,EAAE,EAC5F,MAAM,CACP,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,KAAK,QAAQ,KAAK,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;IAEpE,MAAM,UAAU,GAAG,GAAa,EAAE,CAChC,QAAQ,CAAC,IAAI,CACX,CAAC,KAAK,SAAS,CAAC,CAAC,IAAI;QACnB,MAAM,MAAM,CAAC;QACb,KAAK,CAAC,CAAC,EAAE,CAAC,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,MAAM,CAAC;IACf,CAAC,CAAC,EAAE,CACL,CAAC;IAEJ,OAAO;QACL,QAAQ;QACR,0FAA0F;QAC1F,gEAAgE;QAChE,WAAW,EAAE,iCAAiC,QAAQ,EAAE;QACxD,UAAU;KACX,CAAC;AACJ,CAAC"}

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.25",
+  "version": "2.3.27",
   "author": "@ClayChipps",
   "homepage": "https://github.com/SimplySF/simply-node",
   "bugs": "https://github.com/SimplySF/simply-node/issues",
@@ -68,8 +68,6 @@
     "@simplysf/simply-core": "^1.3.0",
     "@simplysf/simply-plugin-kit": "^1.0.4",
     "csv-parse": "^7.0.2",
-    "form-data": "^4.0.5",
-    "got": "14.6.6",
     "p-queue": "^9.2.0"
   },
   "devDependencies": {
@@ -216,5 +214,5 @@
       "output": []
     }
   },
-  "gitHead": "c3eece6a9447aa996f4515f53a6697e78e318b31"
+  "gitHead": "5227ae680ff4f42e4842b090e50826930dcc67b1"
 }