@pipedream/salesforce_rest_api 1.13.0 → 1.14.0

package/actions/add-contact-to-campaign/add-contact-to-campaign.mjs

@@ -1,11 +1,16 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 import constants from "../../common/constants.mjs";
 
 export default {
   key: "salesforce_rest_api-add-contact-to-campaign",
   name: "Add Contact to Campaign",
-  description: "Adds an existing contact to an existing campaign. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.228.0.object_reference.meta/object_reference/sforce_api_objects_campaignmember.htm)",
-  version: "0.1.5",
+  description: "Add an existing contact to an existing campaign as a campaign member."
+    + " Use **Find Records** on `Contact` and on `Campaign` to look up the two IDs first."
+    + " The contact must already exist - use **Create Contact** if it does not."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.228.0.object_reference.meta/object_reference/sforce_api_objects_campaignmember.htm)",
+  version: "0.1.6",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/add-lead-to-campaign/add-lead-to-campaign.mjs

@@ -1,11 +1,16 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 import constants from "../../common/constants.mjs";
 
 export default {
   key: "salesforce_rest_api-add-lead-to-campaign",
   name: "Add Lead to Campaign",
-  description: "Adds an existing lead to an existing campaign. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.228.0.object_reference.meta/object_reference/sforce_api_objects_campaignmember.htm)",
-  version: "0.1.5",
+  description: "Add an existing lead to an existing campaign as a campaign member."
+    + " Use **Find Records** on `Lead` and on `Campaign` to look up the two IDs first."
+    + " The lead must already exist - use **Create Lead** if it does not."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.228.0.object_reference.meta/object_reference/sforce_api_objects_campaignmember.htm)",
+  version: "0.1.6",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/convert-soap-xml-to-json/convert-soap-xml-to-json.mjs

@@ -1,11 +1,16 @@
+// x-pd-ai: optimized
 import salesforce_rest_api from "../../salesforce_rest_api.app.mjs";
 import converter from "../../../helper_functions/actions/xml-to-json/xml-to-json.mjs";
 
 export default {
   key: "salesforce_rest_api-convert-soap-xml-to-json",
   name: "Convert SOAP XML Object to JSON",
-  description: "Converts a SOAP XML Object received from Salesforce to JSON",
-  version: "0.0.10",
+  description: "Convert a SOAP XML payload received from Salesforce into JSON."
+    + " Use this on the raw body delivered by an outbound-message trigger; it makes no API call."
+    + " Every other Salesforce action already returns JSON, so this is only needed for outbound-message workflows."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_om_outboundmessaging.htm)",
+  version: "0.0.11",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-account/create-account.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import account from "../../common/sobjects/account.mjs";
 
@@ -7,8 +8,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-account",
   name: "Create Account",
-  description: `Creates a Salesforce account. [See the documentation](${docsLink})`,
-  version: "0.3.6",
+  description: "Create a Salesforce account (a company or organization record)."
+    + " Use **Describe Object** on `Account` to discover which fields your org requires before calling."
+    + " For example, `Name` `Acme Corp` creates a minimal account and returns its new record ID."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.3.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-accounts-batch/create-accounts-batch.mjs

@@ -1,11 +1,17 @@
+// x-pd-ai: optimized
 import common from "../common/batch-operation.mjs";
 
 export default {
   ...common,
   key: "salesforce_rest_api-create-accounts-batch",
   name: "Create Accounts (Batch)",
-  description: "Create multiple Accounts in Salesforce using Bulk API 2.0. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/datafiles_understanding_bulk2_ingest.htm)",
-  version: "0.0.5",
+  description: "Create many Salesforce accounts in one job using Bulk API 2.0."
+    + " Use this instead of **Create Account** when inserting more than roughly 200 records - it is asynchronous and returns a job ID, not the created records."
+    + " Poll the job in Salesforce to confirm completion; a successful response means the job was accepted, not that every row loaded."
+    + " Input is a CSV file - supply a path under `/tmp` or a URL to download it from, with a header row of Salesforce field API names."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/datafiles_understanding_bulk2_ingest.htm)",
+  version: "0.0.6",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-attachment/create-attachment.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import attachment from "../../common/sobjects/attachment.mjs";
 import { getFileStream } from "@pipedream/platform";
@@ -17,8 +18,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-attachment",
   name: "Create Attachment",
-  description: `Creates an Attachment on a parent object. [See the documentation](${docsLink})`,
-  version: "0.5.8",
+  description: "Attach a file to an existing Salesforce record (classic `Attachment` object)."
+    + " Use **Find Records** to get the parent record ID first."
+    + " For newer orgs prefer Salesforce Files - use **Insert Blob Data** with `ContentVersion` instead."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.5.9",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-campaign/create-campaign.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import campaign from "../../common/sobjects/campaign.mjs";
 
@@ -7,8 +8,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-campaign",
   name: "Create Campaign",
-  description: `Creates a marketing campaign. [See the documentation](${docsLink})`,
-  version: "0.3.6",
+  description: "Create a Salesforce marketing campaign."
+    + " Use **Add Contact to Campaign** or **Add Lead to Campaign** afterwards to populate its members."
+    + " For example, `Name: \"Summer 2026 Webinar\"` creates the campaign and returns its ID."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.3.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-case/create-case.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import caseObj from "../../common/sobjects/case.mjs";
 
@@ -7,8 +8,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-case",
   name: "Create Case",
-  description: `Creates a Case, which represents a customer issue or problem. [See the documentation](${docsLink})`,
-  version: "0.3.6",
+  description: "Create a Salesforce support case (a customer issue or request)."
+    + " Use **List Cases** to check whether a matching case already exists before creating a duplicate."
+    + " After creating, use **Create Case Comment** to add notes or **List Case Feed Items** to read its activity."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.3.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-casecomment/create-casecomment.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import caseComment from "../../common/sobjects/caseComment.mjs";
 
@@ -16,8 +17,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-casecomment",
   name: "Create Case Comment",
-  description: `Creates a Case Comment on a selected Case. [See the documentation](${docsLink})`,
-  version: "0.3.6",
+  description: "Add a comment to an existing Salesforce case."
+    + " Use **List Cases** to find the case ID, and **List Case Comments** to read the existing thread first."
+    + " Comments are visible in the case feed - **List Case Feed Items** shows them as `CaseCommentPost` entries."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.3.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-contact/create-contact.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import contact from "../../common/sobjects/contact.mjs";
 
@@ -7,8 +8,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-contact",
   name: "Create Contact",
-  description: `Creates a contact. [See the documentation](${docsLink})`,
-  version: "0.3.6",
+  description: "Create a Salesforce contact (a person associated with an account)."
+    + " Use **Find Records** on `Account` to get the `AccountId` that links this contact to a company."
+    + " Use **Describe Object** on `Contact` to discover which fields your org requires."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.3.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-content-note/create-content-note.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 /* eslint-disable no-unused-vars */
 import common, { getProps } from "../common/base-create-update.mjs";
 import contentNote from "../../common/sobjects/content-note.mjs";
@@ -27,8 +28,14 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-content-note",
   name: "Create Content Note",
-  description: `Creates a content note. [See the documentation](${docsLink}) and [Set Up Notes](https://help.salesforce.com/s/articleView?id=sales.notes_admin_setup.htm&type=5).`,
-  version: "0.0.7",
+  description: "Create an enhanced Salesforce content note (rich text, stored in Salesforce Files)."
+    + " Use this rather than **Create Note** on modern orgs; **Create Note** writes the classic plain-text note object."
+    + " Use **Update Content Note** to edit one afterwards."
+    + " "
+    + "Notes must be enabled in the org first - see [Set Up Notes](https://help.salesforce.com/s/articleView?id=sales.notes_admin_setup.htm&type=5)."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.0.8",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-crm-record/create-crm-record.mjs

@@ -1,4 +1,4 @@
-// vandelay-test-dr
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
@@ -19,8 +19,10 @@ export default {
     + "\n- Event: `Subject`, `StartDateTime`, `EndDateTime`"
     + "\n\n"
     + "To add a Contact/Lead to a Campaign, create a CampaignMember:"
-    + " `{\"CampaignId\": \"701xxx\", \"ContactId\": \"003xxx\"}` or `{\"CampaignId\": \"701xxx\", \"LeadId\": \"00Qxxx\"}`.",
-  version: "0.0.1",
+    + " `{\"CampaignId\": \"701xxx\", \"ContactId\": \"003xxx\"}` or `{\"CampaignId\": \"701xxx\", \"LeadId\": \"00Qxxx\"}`."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_create.htm)",
+  version: "0.0.2",
   type: "action",
   annotations: {
     readOnlyHint: false,

package/actions/create-event/create-event.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import event from "../../common/sobjects/event.mjs";
 
@@ -8,8 +9,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-event",
   name: "Create Event",
-  description: `Creates an event. [See the documentation](${docsLink})`,
-  version: "0.3.6",
+  description: "Create a Salesforce calendar event (a meeting or appointment with a start and end time)."
+    + " Use **Create Task** instead for to-do items with no scheduled time."
+    + " Use **Find Records** to get the `WhoId` (contact or lead) and `WhatId` (related record) you want to link."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.3.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-lead/create-lead.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import lead from "../../common/sobjects/lead.mjs";
 
@@ -7,8 +8,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-lead",
   name: "Create Lead",
-  description: `Creates a lead. [See the documentation](${docsLink})`,
-  version: "0.3.6",
+  description: "Create a Salesforce lead (an unqualified prospect not yet linked to an account)."
+    + " Use **Create Contact** instead when the person already belongs to a known account."
+    + " Use **Add Lead to Campaign** afterwards to attribute the lead to a campaign."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.3.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-note/create-note.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import note from "../../common/sobjects/note.mjs";
 import { NOTE_INFO_PROP } from "../../common/props-info.mjs";
@@ -17,8 +18,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-note",
   name: "Create Note",
-  description: `Creates a note. [See the documentation](${docsLink})`,
-  version: "0.3.7",
+  description: "Create a classic Salesforce note (up to 32 KB of plain text) attached to a parent record."
+    + " Prefer **Create Content Note** on modern orgs - classic notes are legacy and do not support rich text."
+    + " Use **Find Records** to get the parent record ID first."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.3.8",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-opportunities-batch/create-opportunities-batch.mjs

@@ -1,11 +1,18 @@
+// x-pd-ai: optimized
 import common from "../common/batch-operation.mjs";
 
 export default {
   ...common,
   key: "salesforce_rest_api-create-opportunities-batch",
   name: "Create Opportunities (Batch)",
-  description: "Create multiple Opportunities in Salesforce using Bulk API 2.0. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/datafiles_understanding_bulk2_ingest.htm)",
-  version: "0.0.5",
+  description: "Create many Salesforce opportunities in one job using Bulk API 2.0."
+    + " Use this instead of **Create Opportunity** when inserting more than roughly 200 records - it is asynchronous and returns a job ID, not the created records."
+    + " Every row needs `Name`, `StageName` and `CloseDate`."
+    + " Input is a CSV file - supply a path under `/tmp` or a URL to download it from, with a header row of Salesforce field API names."
+    + " Poll the job in Salesforce to confirm completion; a successful response means the job was accepted, not that every row loaded."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/datafiles_understanding_bulk2_ingest.htm)",
+  version: "0.0.6",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-opportunity/create-opportunity.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import opportunity from "../../common/sobjects/opportunity.mjs";
 
@@ -7,8 +8,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-opportunity",
   name: "Create Opportunity",
-  description: `Creates an opportunity. [See the documentation](${docsLink})`,
-  version: "0.3.6",
+  description: "Create a Salesforce opportunity (a potential deal with an amount and close date)."
+    + " Requires `Name`, `StageName` and `CloseDate` - use **Describe Object** on `Opportunity` to list the valid `StageName` values for your org."
+    + " Use **Find Records** on `Account` to get the `AccountId` to attach the deal to."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.3.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-record/create-record.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import {
   convertFieldsToProps, getAdditionalFields,
 } from "../../common/props-utils.mjs";
@@ -7,8 +8,12 @@ import { additionalFields } from "../common/base-create-update.mjs";
 export default {
   key: "salesforce_rest_api-create-record",
   name: "Create Record",
-  description: "Create a record of a given object. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_create.htm)",
-  version: "0.3.6",
+  description: "Create a Salesforce record of any object type, choosing fields interactively."
+    + " Prefer **Create CRM Record** in agent and API contexts - this action builds its field list dynamically, so the available inputs are not visible until an object type is chosen."
+    + " Use **List Objects** to discover object types and **Describe Object** to discover fields."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_create.htm)",
+  version: "0.3.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-task/create-task.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import task from "../../common/sobjects/task.mjs";
 
@@ -8,8 +9,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-task",
   name: "Create Task",
-  description: `Creates a task. [See the documentation](${docsLink})`,
-  version: "0.4.6",
+  description: "Create a Salesforce task (a to-do item with a due date, no specific time)."
+    + " Use **Create Event** instead for scheduled meetings with a start and end time."
+    + " Use **Find Records** to get the `WhoId` (contact or lead) and `WhatId` (related record) to link the task to."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.4.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/create-user/create-user.mjs

@@ -1,3 +1,4 @@
+// x-pd-ai: optimized
 import common, { getProps } from "../common/base-create-update.mjs";
 import user from "../../common/sobjects/user.mjs";
 
@@ -8,8 +9,12 @@ export default {
   ...common,
   key: "salesforce_rest_api-create-user",
   name: "Create User",
-  description: `Creates a Salesforce user. [See the documentation](${docsLink})`,
-  version: "0.1.6",
+  description: "Create a Salesforce user (a login for a person in your org)."
+    + " Requires an available user license and a unique `Username` in email form; the `Username` must be globally unique across all Salesforce orgs."
+    + " Use **Get User** or **Find Records** on `User` to check whether the person already has an account."
+    + " "
+    + `[See the documentation](${docsLink})`,
+  version: "0.1.7",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/delete-crm-record/delete-crm-record.mjs

@@ -1,13 +1,15 @@
-// vandelay-test-dr
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
   key: "salesforce_rest_api-delete-crm-record",
   name: "Delete Record",
   description:
-    "Permanently deletes a Salesforce record (moves to Recycle Bin for 15 days)."
-    + " Use **SOQL Query** to find the record ID if you only have the record name.",
-  version: "0.0.1",
+    "Delete a Salesforce record. This moves it to the Recycle Bin, where it stays recoverable for up to 15 days - storage limits can purge it sooner."
+    + " Use **SOQL Query** to find the record ID if you only have the record name."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_delete_record.htm)",
+  version: "0.0.2",
   type: "action",
   annotations: {
     readOnlyHint: false,

package/actions/delete-note/delete-note.mjs

@@ -1,11 +1,16 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 import { ConfigurationError } from "@pipedream/platform";
 
 export default {
   key: "salesforce_rest_api-delete-note",
   name: "Delete Note Or Content Note",
-  description: "Delete a note or content note from a Salesforce record. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_retrieve_delete.htm)",
-  version: "0.0.2",
+  description: "Delete a note or content note from a Salesforce record."
+    + " This moves the note to the Recycle Bin, where it stays recoverable for up to 15 days - storage limits can purge it sooner."
+    + " Use **Find Records** on `Note` or `ContentNote` to get the ID first."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_retrieve_delete.htm)",
+  version: "0.0.3",
   type: "action",
   annotations: {
     destructiveHint: true,

package/actions/delete-opportunity/delete-opportunity.mjs

@@ -1,10 +1,15 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
   key: "salesforce_rest_api-delete-opportunity",
   name: "Delete Opportunity",
-  description: "Deletes an opportunity. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.228.0.api_rest.meta/api_rest/dome_delete_record.htm)",
-  version: "0.3.4",
+  description: "Delete a Salesforce opportunity."
+    + " This moves the record to the Recycle Bin, where it stays recoverable for up to 15 days - storage limits can purge it sooner."
+    + " Use **Find Records** on `Opportunity` to get the ID first, and prefer **Update Opportunity** to set a Closed Lost stage when you want to keep the history."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.228.0.api_rest.meta/api_rest/dome_delete_record.htm)",
+  version: "0.3.5",
   annotations: {
     destructiveHint: true,
     openWorldHint: true,

package/actions/delete-record/delete-record.mjs

@@ -1,11 +1,16 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
   key: "salesforce_rest_api-delete-record",
   name: "Delete Record",
   description:
-    "Deletes an existing record in an object. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_retrieve_delete.htm)",
-  version: "0.2.4",
+    "Delete a Salesforce record of any object type."
+    + " This moves the record to the Recycle Bin, where it stays recoverable for up to 15 days - storage limits can purge it sooner."
+    + " Use **Find Records** or **SOQL Query** to confirm you have the right record ID before deleting."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_retrieve_delete.htm)",
+  version: "0.2.5",
   annotations: {
     destructiveHint: true,
     openWorldHint: true,

package/actions/describe-object/describe-object.mjs

@@ -1,4 +1,4 @@
-// vandelay-test-dr
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
@@ -10,8 +10,10 @@ export default {
     + " For picklist fields (like `StageName` on Opportunity, `Status` on Case), this returns all valid values"
     + " — use the API value, not the display label."
     + " Use the `fieldsFilter` parameter to narrow results — full object descriptions can be very large (100+ fields)."
-    + " Use **List Objects** if you're unsure of the object's API name.",
-  version: "0.0.1",
+    + " Use **List Objects** if you're unsure of the object's API name."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_describe.htm)",
+  version: "0.0.2",
   type: "action",
   annotations: {
     readOnlyHint: true,

package/actions/find-records/find-records.mjs

@@ -1,11 +1,21 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
+import constants from "../../common/constants.mjs";
+import {
+  assertSalesforceId, truncationNote,
+} from "../../common/soql.mjs";
 
 export default {
   key: "salesforce_rest_api-find-records",
   name: "Find Records",
-  description:
-    "Retrieves selected fields for some or all records of a selected object. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm)",
-  version: "0.2.4",
+  description: "Retrieve selected fields for records of any Salesforce object, either specific records by ID or the most recent ones."
+    + " Use this as the general-purpose record reader when no object-specific action fits - prefer **List Cases** for cases or **Get Record by ID** for a single known record."
+    + " Use **List Objects** to discover object types and **List Object Fields** to discover field names."
+    + " For example, `SObject Type` `Account` with `Fields to Obtain` `Id, Name` and `Limit` `25` returns the 25 most recently created accounts."
+    + " Leaving `Record ID(s)` empty returns recent records, not every record - Salesforce sends one batch, so set `Limit` and use **SOQL Query** when you need everything."
+    + " Newest-first ordering needs `CreatedDate`, so results are unordered on the few object types that lack it."
+    + " [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm)",
+  version: "0.3.0",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
@@ -19,7 +29,7 @@ export default {
         salesforce,
         "objectType",
       ],
-      description: "The type of object to obtain records of.",
+      description: "The type of object to obtain records of, e.g. `Account`. Use **List Objects** to discover the object types in this org.",
     },
     fieldsToObtain: {
       propDefinition: [
@@ -29,6 +39,7 @@ export default {
           objType: c.sobjectType,
         }),
       ],
+      description: "The fields to return, e.g. `Id`, `Name`. Use **List Object Fields** to discover field names for the selected object. Include `Id` if you plan to act on the records afterwards.",
     },
     recordIds: {
       propDefinition: [
@@ -41,8 +52,15 @@ export default {
       label: "Record ID(s)",
       type: "string[]",
       optional: true,
-      description:
-        "The record(s) to retrieve. If not specified, all records will be retrieved.",
+      description: "The specific record(s) to retrieve (15- or 18-character Salesforce IDs). Leave empty to retrieve the most recent records of this object type.",
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: `The maximum number of records to return. Valid values are integers from 1 through ${constants.MAX_LIMIT}. Omit to return every record Salesforce sends in one batch.`,
+      min: 1,
+      max: constants.MAX_LIMIT,
+      optional: true,
     },
   },
   async run({ $ }) {
@@ -52,21 +70,40 @@ export default {
       fieldsToObtain,
     } = this;
 
-    if (typeof recordIds === "string") recordIds = recordIds.split(",");
-    if (typeof fieldsToObtain === "string") fieldsToObtain = fieldsToObtain.split(",");
+    if (typeof recordIds === "string") {
+      recordIds = recordIds.split(",");
+    }
+    if (typeof fieldsToObtain === "string") {
+      fieldsToObtain = fieldsToObtain.split(",");
+    }
 
     let query = `SELECT ${fieldsToObtain.join(", ")} FROM ${sobjectType}`;
 
     if (recordIds?.length) {
-      query += ` WHERE Id IN ('${recordIds.join("','")}')`;
+      const ids = recordIds.map((id) => assertSalesforceId(id.trim(), "Record ID(s)"));
+      query += ` WHERE Id IN ('${ids.join("','")}')`;
+    } else {
+      // This action accepts any object type, and not every one has CreatedDate
+      // (PicklistValueInfo, for example). SOQL rejects the whole query rather than
+      // ignoring the clause, so only sort by it when the object actually has it.
+      const fields = await this.salesforce.getFieldsForObjectType(sobjectType);
+      const { CREATED_DATE: createdDate } = constants.FIELD_NAME;
+      if (fields.some(({ name }) => name === createdDate)) {
+        query += ` ORDER BY ${createdDate} DESC, Id DESC`;
+      }
+    }
+    if (this.limit) {
+      query += ` LIMIT ${this.limit}`;
     }
 
-    const { records } = await this.salesforce.query({
+    const response = await this.salesforce.query({
       $,
       query,
     });
-
-    $.export("$summary", `Sucessfully retrieved ${records.length} records`);
+    const { records } = response;
+    $.export("$summary", `Successfully retrieved ${records.length} ${sobjectType} record${records.length === 1
+      ? ""
+      : "s"}.${truncationNote(response, records.length)}`);
     return records;
   },
 };