@oomol-lab/open-connector 1.9.0 → 1.9.1

package/src/providers/salesforce/runtime-automation.js

@@ -0,0 +1,64 @@
+import { recordOrEmpty } from "../../core/cast.js";
+import { providerInputError } from "../provider-runtime.js";
+import { queryPath, segment } from "./context.js";
+function invocablePath(d, base, detail) {
+    if (d.category === "standard" && d.actionType !== undefined)
+        throw providerInputError("actionType is only valid for custom actions");
+    if (d.category === "custom" && detail && !d.actionType)
+        throw providerInputError("Custom actions require actionType");
+    return `${base}/actions/${segment(d.category)}${d.actionType ? `/${segment(d.actionType)}` : ""}${detail ? `/${segment(d.actionName)}` : ""}`;
+}
+async function sendEmail(d, c) {
+    const email = recordOrEmpty(d.email);
+    const recipients = [email.recipientAddresses, email.ccAddresses, email.bccAddresses].reduce((sum, list) => sum + (Array.isArray(list) ? list.length : 0), email.recipientId ? 1 : 0);
+    if (!recipients || recipients > 150)
+        throw providerInputError("Email requires between 1 and 150 recipients");
+    if (email.senderType === "OrgWideEmailAddress" && !email.senderAddress)
+        throw providerInputError("OrgWideEmailAddress requires senderAddress");
+    if (email.logEmailOnSend && !email.recipientId && !email.relatedRecordId)
+        throw providerInputError("logEmailOnSend requires recipientId or relatedRecordId");
+    return c.items(`${c.base}/actions/standard/emailSimple`, "POST", { inputs: [email] });
+}
+export const salesforceAutomationHandlers = {
+    async list_email_templates(d, c) {
+        const filters = [
+            d.includeInactive ? undefined : "IsActive = true",
+            d.folderId ? `FolderId = '${String(d.folderId)}'` : undefined,
+        ].filter(Boolean);
+        const q = `SELECT Id, Name, DeveloperName, Subject, TemplateType, FolderId, IsActive FROM EmailTemplate${filters.length ? ` WHERE ${filters.join(" AND ")}` : ""} ORDER BY Name LIMIT ${d.limit ?? 200}`;
+        return c.object(queryPath(`${c.base}/query`, { q }));
+    },
+    async get_email_template(d, c) {
+        return {
+            record: await c.object(queryPath(`${c.base}/sobjects/EmailTemplate/${segment(d.templateId)}`, {
+                fields: "Id,Name,DeveloperName,Subject,Body,HtmlValue,TemplateType,FolderId,IsActive",
+            })),
+        };
+    },
+    send_email: sendEmail,
+    send_email_from_template: sendEmail,
+    async list_invocable_actions(d, c) {
+        return { result: await c.request(invocablePath(d, c.base, false)) };
+    },
+    async describe_invocable_action(d, c) {
+        return { result: await c.request(invocablePath(d, c.base, true)) };
+    },
+    async invoke_action(d, c) {
+        return c.items(invocablePath(d, c.base, true), "POST", { inputs: d.inputs });
+    },
+    async list_quick_actions(d, c) {
+        return {
+            result: await c.request(`${c.base}${d.objectName ? `/sobjects/${segment(d.objectName)}` : ""}/quickActions/`),
+        };
+    },
+    async get_quick_action_defaults(d, c) {
+        return {
+            result: await c.request(`${c.base}/sobjects/${segment(d.objectName)}/quickActions/${segment(d.actionName)}/defaultValues/${d.contextId ? segment(d.contextId) : ""}`),
+        };
+    },
+    async execute_quick_action(d, c) {
+        return {
+            result: await c.request(`${c.base}${d.objectName ? `/sobjects/${segment(d.objectName)}` : ""}/quickActions/${segment(d.actionName)}`, "POST", { contextId: d.contextId, record: d.fields }),
+        };
+    },
+};

package/src/providers/salesforce/runtime-base.d.ts

@@ -0,0 +1,2 @@
+import type { SalesforceHandler } from "./context.ts";
+export declare const salesforceBaseHandlers: Record<string, SalesforceHandler>;

package/src/providers/salesforce/runtime-base.js

@@ -0,0 +1,51 @@
+import { requiredResponseRecord } from "../provider-runtime.js";
+import { queryPath, segment } from "./context.js";
+import { salesforceRequest } from "./transport.js";
+export const salesforceBaseHandlers = {
+    async list_objects(_d, c) {
+        return c.object(`${c.base}/sobjects/`);
+    },
+    async describe_object(d, c) {
+        return c.object(`${c.base}/sobjects/${segment(d.objectName)}/describe`);
+    },
+    async query(d, c) {
+        const headers = new Headers({ authorization: `Bearer ${c.accessToken}` });
+        if (d.batchSize !== undefined)
+            headers.set("Sforce-Query-Options", `batchSize=${d.batchSize}`);
+        return requiredResponseRecord((await salesforceRequest(new URL(queryPath(`${c.base}/${d.includeDeleted ? "queryAll" : "query"}`, { q: d.soql }), c.origin), { headers }, c.fetcher, c.signal)).body, "Salesforce query");
+    },
+    async query_more(d, c) {
+        const headers = new Headers({ authorization: `Bearer ${c.accessToken}` });
+        if (d.batchSize !== undefined)
+            headers.set("Sforce-Query-Options", `batchSize=${d.batchSize}`);
+        return requiredResponseRecord((await salesforceRequest(new URL(String(d.nextRecordsUrl), c.origin), { headers }, c.fetcher, c.signal)).body, "Salesforce query");
+    },
+    async get_record(d, c) {
+        return {
+            record: await c.object(queryPath(`${c.base}/sobjects/${segment(d.objectName)}/${segment(d.recordId)}`, { fields: d.fields })),
+        };
+    },
+    async create_record(d, c) {
+        return c.object(`${c.base}/sobjects/${segment(d.objectName)}`, "POST", d.fields);
+    },
+    async update_record(d, c) {
+        const result = await c.request(`${c.base}/sobjects/${segment(d.objectName)}/${segment(d.recordId)}`, "PATCH", d.fields);
+        return result === undefined
+            ? { success: true, id: d.recordId }
+            : requiredResponseRecord(result, "Salesforce response");
+    },
+    async delete_record(d, c) {
+        const result = await c.request(`${c.base}/sobjects/${segment(d.objectName)}/${segment(d.recordId)}`, "DELETE");
+        return result === undefined
+            ? { success: true, id: d.recordId }
+            : requiredResponseRecord(result, "Salesforce response");
+    },
+    async upsert_record(d, c) {
+        const result = await c.request(queryPath(`${c.base}/sobjects/${segment(d.objectName)}/${segment(d.externalIdField)}/${segment(d.externalId)}`, {
+            updateOnly: d.updateOnly,
+        }), "PATCH", d.fields);
+        return result === undefined
+            ? { success: true, created: false }
+            : requiredResponseRecord(result, "Salesforce response");
+    },
+};

package/src/providers/salesforce/runtime-bulk.d.ts

@@ -0,0 +1,2 @@
+import type { SalesforceHandler } from "./context.ts";
+export declare const salesforceBulkHandlers: Record<string, SalesforceHandler>;

package/src/providers/salesforce/runtime-bulk.js

@@ -0,0 +1,98 @@
+import { recordOrEmpty, requiredString } from "../../core/cast.js";
+import { providerInputError, providerResponseError, ProviderRequestError } from "../provider-runtime.js";
+import { queryPath, segment } from "./context.js";
+import { downloadSalesforceSource, requireSalesforceTransit, saveSalesforceDownload } from "./media.js";
+function jobResult(job, kind, version) {
+    return {
+        handle: { jobId: requiredString(job.id, "Bulk job ID", providerResponseError), kind, apiVersion: version },
+        state: requiredString(job.state, "Bulk job state", providerResponseError),
+        job,
+    };
+}
+function jobPath(handle) {
+    return `/services/data/v${segment(handle.apiVersion)}/jobs/${segment(handle.kind)}/${segment(handle.jobId)}`;
+}
+async function readJob(d, c) {
+    const handle = recordOrEmpty(d.handle);
+    const job = await c.object(jobPath(handle));
+    return { ...jobResult(job, String(handle.kind), String(handle.apiVersion)), path: jobPath(handle) };
+}
+export const salesforceBulkHandlers = {
+    async submit_bulk_query(d, c) {
+        return jobResult(await c.object(`${c.base}/jobs/query`, "POST", {
+            operation: d.includeDeleted ? "queryAll" : "query",
+            query: d.soql,
+            contentType: "CSV",
+            columnDelimiter: d.columnDelimiter,
+            lineEnding: d.lineEnding,
+        }), "query", c.version);
+    },
+    async get_bulk_query_result(d, c) {
+        const { path, ...output } = await readJob(d, c);
+        if (output.state !== "JobComplete" || d.download === false)
+            return output;
+        requireSalesforceTransit(c);
+        const downloaded = await c.response(queryPath(`${path}/results`, { locator: d.locator, maxRecords: d.maxRecords }), { headers: { accept: "text/csv" } }, async (response, signal) => {
+            const locator = response.headers.get("Sforce-Locator");
+            if (!locator) {
+                await response.body?.cancel();
+                throw providerResponseError("Salesforce query results are missing Sforce-Locator; pagination completeness is unknown");
+            }
+            const count = response.headers.get("Sforce-NumberOfRecords");
+            const result = await saveSalesforceDownload(c, response, `${output.handle.jobId}.csv`, "text/csv", signal);
+            return {
+                result,
+                nextLocator: locator === "null" ? null : locator,
+                numberOfRecords: count !== null && Number.isFinite(Number(count)) ? Number(count) : undefined,
+            };
+        });
+        return { ...output, ...downloaded };
+    },
+    async submit_bulk_ingest(d, c) {
+        if (d.operation === "upsert" && !d.externalIdField)
+            throw providerInputError("Bulk upsert requires externalIdField");
+        const source = await downloadSalesforceSource(String(d.csvUrl), 100_000_000, c);
+        let created;
+        try {
+            created = await c.object(`${c.base}/jobs/ingest`, "POST", {
+                object: d.objectName,
+                operation: d.operation,
+                contentType: "CSV",
+                externalIdFieldName: d.externalIdField,
+                assignmentRuleId: d.assignmentRuleId,
+                columnDelimiter: d.columnDelimiter,
+                lineEnding: d.lineEnding,
+            });
+            const id = requiredString(created.id, "Bulk job ID", providerResponseError);
+            await c.response(`${c.base}/jobs/ingest/${segment(id)}/batches`, {
+                method: "PUT",
+                headers: { "content-type": "text/csv", "content-length": String(source.sizeBytes) },
+                body: source.body,
+            }, async (response) => {
+                await response.body?.cancel();
+            });
+            return jobResult(await c.object(`${c.base}/jobs/ingest/${segment(id)}`, "PATCH", { state: "UploadComplete" }), "ingest", c.version);
+        }
+        catch (error) {
+            if (!created)
+                throw error;
+            throw new ProviderRequestError(error instanceof ProviderRequestError ? error.status : 502, `Salesforce ingest job ${String(created.id)} was created but submission failed. Inspect or cancel this ingest job with API ${c.version} before resubmitting. ${error instanceof Error ? error.message : "Unknown failure"}`, undefined, error instanceof ProviderRequestError ? error.code : "provider_error");
+        }
+        finally {
+            await source.cleanup();
+        }
+    },
+    async get_bulk_ingest_result(d, c) {
+        const { path, ...output } = await readJob(d, c);
+        if (!["JobComplete", "Failed", "Aborted"].includes(output.state) || d.download === false)
+            return output;
+        requireSalesforceTransit(c);
+        const type = String(d.resultType ?? (output.state === "JobComplete" ? "failedResults" : "unprocessedrecords"));
+        const result = await c.response(`${path}/${type}`, { headers: { accept: "text/csv" } }, (response, signal) => saveSalesforceDownload(c, response, `${output.handle.jobId}-${type}.csv`, "text/csv", signal));
+        return { ...output, result };
+    },
+    async cancel_bulk_job(d, c) {
+        const handle = recordOrEmpty(d.handle);
+        return jobResult(await c.object(jobPath(handle), "PATCH", { state: "Aborted" }), String(handle.kind), String(handle.apiVersion));
+    },
+};

package/src/providers/salesforce/runtime-data.d.ts

@@ -0,0 +1,2 @@
+import type { SalesforceHandler } from "./context.ts";
+export declare const salesforceDataHandlers: Record<string, SalesforceHandler>;

package/src/providers/salesforce/runtime-data.js

@@ -0,0 +1,207 @@
+import { recordOrEmpty } from "../../core/cast.js";
+import { providerInputError } from "../provider-runtime.js";
+import { requiredResponseRecord } from "../provider-runtime.js";
+import { queryPath, segment } from "./context.js";
+import { salesforceRequest, salesforceOrigin } from "./transport.js";
+function rejectReservedFields(fields) {
+    if (Object.keys(fields).some((key) => ["attributes", "id"].includes(key.toLowerCase())))
+        throw providerInputError("Use recordId and objectName instead of fields.Id or fields.attributes");
+}
+function validateComposite(requests, graph) {
+    const references = new Set();
+    let collectionQueries = 0;
+    for (const request of requests) {
+        if (Object.keys(recordOrEmpty(request.httpHeaders)).some((header) => ["accept", "authorization", "content-type"].includes(header.toLowerCase())))
+            throw providerInputError("Composite subrequests inherit Accept, Authorization and Content-Type; do not override them");
+        const ref = String(request.referenceId);
+        if (references.has(ref))
+            throw providerInputError("Composite reference IDs must be unique");
+        references.add(ref);
+        const path = String(request.url);
+        const resourcePath = path.split("?")[0];
+        const parts = resourcePath.split("/");
+        if (!path.startsWith("/services/data/v") ||
+            parts.length < 5 ||
+            path.includes("\\") ||
+            path.includes("#") ||
+            parts.slice(4).some((part) => {
+                try {
+                    const decoded = decodeURIComponent(part);
+                    return decoded === "." || decoded === "..";
+                }
+                catch {
+                    return true;
+                }
+            }))
+            throw providerInputError("Invalid composite resource URL");
+        const resource = parts[4]?.split("?")[0];
+        const collection = resource === "composite" && parts[5]?.split("?")[0] === "sobjects";
+        if (resource !== "sobjects" && (graph || (!collection && resource !== "query" && resource !== "queryAll")))
+            throw providerInputError("Resource is not supported by Salesforce Composite");
+        if (collection || resource === "query" || resource === "queryAll")
+            collectionQueries++;
+    }
+    if (!graph && collectionQueries > 5)
+        throw providerInputError("Composite allows at most five queries or collections");
+}
+function validateTree(records, rootType) {
+    let count = 0;
+    const types = new Set();
+    const refs = new Set();
+    function visit(nodes, depth, root) {
+        if (depth > 5)
+            throw providerInputError("Record trees support at most five levels");
+        for (const node of nodes) {
+            const record = recordOrEmpty(node);
+            const attrs = recordOrEmpty(record.attributes);
+            if (typeof attrs.type !== "string" ||
+                typeof attrs.referenceId !== "string" ||
+                !attrs.referenceId ||
+                (root && attrs.type !== rootType))
+                throw providerInputError("Tree records require attributes.type and referenceId; root type must match objectName");
+            if (refs.has(attrs.referenceId))
+                throw providerInputError("Tree reference IDs must be unique");
+            refs.add(attrs.referenceId);
+            types.add(attrs.type);
+            count++;
+            if (count > 200 || types.size > 5)
+                throw providerInputError("Record trees allow 200 records and five object types");
+            for (const value of Object.values(record)) {
+                const nested = recordOrEmpty(value);
+                if (Array.isArray(nested.records))
+                    visit(nested.records, depth + 1, false);
+            }
+        }
+    }
+    visit(records, 1, true);
+}
+export const salesforceDataHandlers = {
+    async search_records(d, c) {
+        return c.object(queryPath(`${c.base}/search`, { q: d.sosl }));
+    },
+    async parameterized_search(d, c) {
+        return c.object(`${c.base}/parameterizedSearch`, "POST", d.request);
+    },
+    async get_record_by_external_id(d, c) {
+        return {
+            record: await c.object(queryPath(`${c.base}/sobjects/${segment(d.objectName)}/${segment(d.externalIdField)}/${segment(d.externalId)}`, { fields: d.fields })),
+        };
+    },
+    async get_related_records(d, c) {
+        return {
+            result: await c.request(queryPath(`${c.base}/sobjects/${segment(d.objectName)}/${segment(d.recordId)}/${d.relationships.map(segment).join("/")}`, { fields: d.fields })),
+        };
+    },
+    async list_updated_records(d, c) {
+        validateWindow(d);
+        return c.object(queryPath(`${c.base}/sobjects/${segment(d.objectName)}/updated/`, {
+            start: d.start,
+            end: d.end,
+        }));
+    },
+    async list_deleted_records(d, c) {
+        validateWindow(d);
+        return c.object(queryPath(`${c.base}/sobjects/${segment(d.objectName)}/deleted/`, {
+            start: d.start,
+            end: d.end,
+        }));
+    },
+    async get_record_counts(d, c) {
+        return c.object(queryPath(`${c.base}/limits/recordCount`, { sObjects: d.objectNames }));
+    },
+    async get_records(d, c) {
+        return c.items(`${c.base}/composite/sobjects/${segment(d.objectName)}`, "POST", {
+            recordIds: d.recordIds,
+            fieldNames: d.fields,
+        });
+    },
+    async create_records(d, c) {
+        return collectionWrite(d, c, false);
+    },
+    async update_records(d, c) {
+        return collectionWrite(d, c, true);
+    },
+    async upsert_records(d, c) {
+        const records = d.records.map((fields) => {
+            rejectReservedFields(fields);
+            if (!Object.hasOwn(fields, String(d.externalIdField)))
+                throw providerInputError("Each upsert record must contain the external ID field");
+            return { ...fields, attributes: { type: d.objectName } };
+        });
+        return c.items(`${c.base}/composite/sobjects/${segment(d.objectName)}/${segment(d.externalIdField)}`, "PATCH", {
+            records,
+            allOrNone: d.allOrNone,
+        });
+    },
+    async delete_records(d, c) {
+        return c.items(queryPath(`${c.base}/composite/sobjects`, { ids: d.recordIds, allOrNone: d.allOrNone }), "DELETE");
+    },
+    async create_record_tree(d, c) {
+        validateTree(d.records, String(d.objectName));
+        return c.object(`${c.base}/composite/tree/${segment(d.objectName)}`, "POST", {
+            records: d.records,
+        });
+    },
+    async execute_composite(d, c) {
+        validateComposite(d.requests, false);
+        return c.object(`${c.base}/composite`, "POST", {
+            compositeRequest: d.requests,
+            allOrNone: d.allOrNone,
+            collateSubrequests: d.collateSubrequests,
+        });
+    },
+    async execute_composite_graph(d, c) {
+        const graphs = d.graphs;
+        if (new Set(graphs.map((g) => g.graphId)).size !== graphs.length ||
+            graphs.reduce((sum, g) => sum + g.compositeRequest.length, 0) > 500)
+            throw providerInputError("Graphs require unique IDs and at most 500 total subrequests");
+        for (const graph of graphs)
+            validateComposite(graph.compositeRequest, true);
+        return c.object(`${c.base}/composite/graph`, "POST", { graphs });
+    },
+    async list_list_views(d, c) {
+        return c.object(`${c.base}/sobjects/${segment(d.objectName)}/listviews`);
+    },
+    async describe_list_view(d, c) {
+        return c.object(`${c.base}/sobjects/${segment(d.objectName)}/listviews/${segment(d.listViewId)}/describe`);
+    },
+    async get_list_view_records(d, c) {
+        return c.object(queryPath(`${c.base}/sobjects/${segment(d.objectName)}/listviews/${segment(d.listViewId)}/results`, {
+            limit: d.limit,
+            offset: d.offset,
+        }));
+    },
+    async get_picklist_values(d, c) {
+        return c.object(`${c.base}/ui-api/object-info/${segment(d.objectName)}/picklist-values/${segment(d.recordTypeId)}`);
+    },
+    async get_current_user(_d, c) {
+        const url = new URL(String(c.providerSecret?.identityUrl));
+        salesforceOrigin(url.origin, "identityUrl");
+        return {
+            user: requiredResponseRecord((await salesforceRequest(url, { headers: { authorization: `Bearer ${c.accessToken}` } }, c.fetcher, c.signal))
+                .body, "Salesforce identity"),
+        };
+    },
+    async get_org_limits(_d, c) {
+        return { limits: await c.object(`${c.base}/limits`) };
+    },
+};
+function validateWindow(d) {
+    if (Date.parse(String(d.start)) >= Date.parse(String(d.end)))
+        throw providerInputError("start must precede end");
+}
+async function collectionWrite(d, c, update) {
+    const records = d.records.map((entry) => {
+        const fields = recordOrEmpty(entry.fields);
+        rejectReservedFields(fields);
+        return {
+            ...fields,
+            attributes: { type: entry.objectName },
+            Id: update ? entry.recordId : undefined,
+        };
+    });
+    return c.items(`${c.base}/composite/sobjects`, update ? "PATCH" : "POST", {
+        records,
+        allOrNone: d.allOrNone,
+    });
+}

package/src/providers/salesforce/runtime-files.d.ts

@@ -0,0 +1,2 @@
+import type { SalesforceHandler } from "./context.ts";
+export declare const salesforceFileHandlers: Record<string, SalesforceHandler>;

package/src/providers/salesforce/runtime-files.js

@@ -0,0 +1,108 @@
+import { recordOrEmpty, optionalString, requiredString } from "../../core/cast.js";
+import { providerInputError, providerResponseError, requiredResponseRecord } from "../provider-runtime.js";
+import { queryPath, segment } from "./context.js";
+import { downloadSalesforceSource, requireSalesforceTransit, saveSalesforceDownload } from "./media.js";
+export const salesforceFileHandlers = {
+    async upload_file(d, c) {
+        const filename = String(d.filename);
+        if (["\r", "\n", "\0", '"', "\\", "/"].some((char) => filename.includes(char)) ||
+            filename === "." ||
+            filename === "..")
+            throw providerInputError("filename must be a plain file name without header control characters");
+        const metadata = recordOrEmpty(d.metadata);
+        if (Object.keys(metadata).some((key) => ["versiondata", "id", "attributes"].includes(key.toLowerCase())))
+            throw providerInputError("metadata cannot include VersionData, Id or attributes");
+        const source = await downloadSalesforceSource(String(d.fileUrl), 2 * 1024 ** 3, c);
+        const boundary = `salesforce-${Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+        const encoder = new TextEncoder();
+        const prefix = encoder.encode(`--${boundary}\r\nContent-Disposition: form-data; name="entity_content"\r\nContent-Type: application/json\r\n\r\n${JSON.stringify({ Title: filename, PathOnClient: filename, ...metadata })}\r\n--${boundary}\r\nContent-Disposition: form-data; name="VersionData"; filename="${filename}"\r\nContent-Type: application/octet-stream\r\n\r\n`);
+        const suffix = encoder.encode(`\r\n--${boundary}--\r\n`);
+        const reader = source.body.getReader();
+        let started = false;
+        const body = new ReadableStream({
+            async pull(controller) {
+                if (!started) {
+                    started = true;
+                    controller.enqueue(prefix);
+                    return;
+                }
+                const chunk = await reader.read();
+                if (chunk.done) {
+                    controller.enqueue(suffix);
+                    controller.close();
+                    reader.releaseLock();
+                }
+                else
+                    controller.enqueue(chunk.value);
+            },
+            async cancel(reason) {
+                await reader.cancel(reason);
+                reader.releaseLock();
+            },
+        });
+        try {
+            return await c.response(`${c.base}/sobjects/ContentVersion`, {
+                method: "POST",
+                headers: {
+                    "content-type": `multipart/form-data; boundary=${boundary}`,
+                    "content-length": String(prefix.byteLength + source.sizeBytes + suffix.byteLength),
+                },
+                body,
+            }, async (response) => requiredResponseRecord(await response.json(), "ContentVersion result"));
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
+            await source.cleanup();
+        }
+    },
+    async get_file(d, c) {
+        return { record: await c.object(`${c.base}/sobjects/ContentDocument/${segment(d.fileId)}`) };
+    },
+    async download_file(d, c) {
+        requireSalesforceTransit(c);
+        const document = await c.object(queryPath(`${c.base}/sobjects/ContentDocument/${segment(d.fileId)}`, {
+            fields: "Id,Title,LatestPublishedVersionId,FileExtension",
+        }));
+        const versionId = d.versionId ?? requiredString(document.LatestPublishedVersionId, "latest file version ID", providerResponseError);
+        if (d.versionId) {
+            const version = await c.object(queryPath(`${c.base}/sobjects/ContentVersion/${segment(versionId)}`, { fields: "ContentDocumentId" }));
+            if (!sameSalesforceId(String(version.ContentDocumentId), String(d.fileId)))
+                throw providerInputError("versionId does not belong to fileId");
+        }
+        const extension = optionalString(document.FileExtension);
+        const name = `${optionalString(document.Title) ?? String(d.fileId)}${extension ? `.${extension}` : ""}`;
+        return c.response(`${c.base}/sobjects/ContentVersion/${segment(versionId)}/VersionData`, { method: "GET", headers: { accept: "application/octet-stream" } }, (response, signal) => saveSalesforceDownload(c, response, name, response.headers.get("content-type") ?? "application/octet-stream", signal));
+    },
+    async list_record_files(d, c) {
+        return c.object(queryPath(`${c.base}/query`, {
+            q: `SELECT Id, ContentDocumentId, LinkedEntityId, ShareType, Visibility, ContentDocument.Title, ContentDocument.LatestPublishedVersionId FROM ContentDocumentLink WHERE LinkedEntityId = '${d.recordId}'`,
+        }));
+    },
+    async list_file_shares(d, c) {
+        return c.object(queryPath(`${c.base}/query`, {
+            q: `SELECT Id, ContentDocumentId, LinkedEntityId, ShareType, Visibility FROM ContentDocumentLink WHERE ContentDocumentId = '${d.fileId}'`,
+        }));
+    },
+    async link_file(d, c) {
+        return c.object(`${c.base}/sobjects/ContentDocumentLink`, "POST", {
+            ContentDocumentId: d.fileId,
+            LinkedEntityId: d.recordId,
+            ShareType: d.shareType ?? "V",
+            Visibility: d.visibility,
+        });
+    },
+    async unlink_file(d, c) {
+        await c.request(`${c.base}/sobjects/ContentDocumentLink/${segment(d.linkId)}`, "DELETE");
+        return { success: true };
+    },
+    async delete_file(d, c) {
+        await c.request(`${c.base}/sobjects/ContentDocument/${segment(d.fileId)}`, "DELETE");
+        return { success: true };
+    },
+};
+function sameSalesforceId(left, right) {
+    return left.length === 18 && right.length === 18
+        ? left.toLowerCase() === right.toLowerCase()
+        : left.slice(0, 15) === right.slice(0, 15);
+}

package/src/providers/salesforce/transport.d.ts

@@ -0,0 +1,9 @@
+import { ProviderRequestError } from "../provider-runtime.ts";
+export declare const salesforceFileRequestTimeoutMs = 300000;
+export declare function salesforceOrigin(value: string, fieldName: string): string;
+export declare function withSalesforceResponse<T>(url: URL, init: RequestInit, fetcher: typeof fetch, consume: (response: Response, signal: AbortSignal) => Promise<T>, timeoutMs?: number, parentSignal?: AbortSignal): Promise<T>;
+export declare function readSalesforceError(response: Response): Promise<ProviderRequestError>;
+export declare function salesforceRequest(url: URL, init: RequestInit, fetcher: typeof fetch, signal?: AbortSignal): Promise<{
+    status: number;
+    body: unknown;
+}>;

package/src/providers/salesforce/transport.js

@@ -0,0 +1,65 @@
+import { optionalRecord, optionalString } from "../../core/cast.js";
+import { assertPublicHttpUrl } from "../../core/request.js";
+import { isAbortLikeError, providerInputError, providerResponseError, ProviderRequestError, providerUserAgent, runProviderRequest, } from "../provider-runtime.js";
+// File transfers have a deliberate five-minute budget; JSON uses the shared default.
+export const salesforceFileRequestTimeoutMs = 300_000;
+export function salesforceOrigin(value, fieldName) {
+    const url = assertPublicHttpUrl(value, { fieldName, createError: providerInputError });
+    if (url.protocol !== "https:" ||
+        !url.hostname.endsWith(".salesforce.com") ||
+        url.port ||
+        url.username ||
+        url.password ||
+        url.pathname !== "/" ||
+        url.search ||
+        url.hash) {
+        throw providerInputError(`${fieldName} must be a Salesforce HTTPS origin`);
+    }
+    return url.origin;
+}
+export async function withSalesforceResponse(url, init, fetcher, consume, timeoutMs, parentSignal) {
+    return runProviderRequest({ label: "Salesforce", timeoutMs, signal: parentSignal }, async (signal) => {
+        const headers = new Headers(init.headers);
+        if (!headers.has("accept"))
+            headers.set("accept", "application/json");
+        headers.set("user-agent", providerUserAgent);
+        const request = {
+            ...init,
+            headers,
+            signal,
+            redirect: "manual",
+            duplex: init.body instanceof ReadableStream ? "half" : undefined,
+        };
+        const response = await fetcher(url, request);
+        if (!response.ok)
+            throw await readSalesforceError(response);
+        return consume(response, signal);
+    });
+}
+export async function readSalesforceError(response) {
+    const payload = await response.json().catch((error) => {
+        if (isAbortLikeError(error))
+            throw error;
+        return undefined;
+    });
+    const error = optionalRecord(Array.isArray(payload) ? payload[0] : payload);
+    const code = optionalString(error?.errorCode) ?? optionalString(error?.error);
+    const message = optionalString(error?.message) ?? optionalString(error?.error_description);
+    // INVALID_SESSION_ID proves only the access token expired, not the refresh token.
+    return new ProviderRequestError(response.status, ["Salesforce", code, message ?? `HTTP ${response.status}`].filter(Boolean).join(": "), { errorCode: code, errorDescription: message }, "provider_error");
+}
+export function salesforceRequest(url, init, fetcher, signal) {
+    return withSalesforceResponse(url, init, fetcher, async (response) => {
+        const text = response.status === 204 ? "" : await response.text();
+        let body;
+        if (text) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                throw providerResponseError("Salesforce returned invalid JSON");
+            }
+        }
+        return { status: response.status, body };
+    }, undefined, signal);
+}

package/src/providers/sansan/actions.d.ts

@@ -0,0 +1,2 @@
+import type { ActionDefinition } from "../../core/types.ts";
+export declare const sansanActions: ActionDefinition[];