@pipedream/salesforce_rest_api 1.13.0 → 1.14.0

package/actions/get-case/get-case.mjs

@@ -1,10 +1,15 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
   key: "salesforce_rest_api-get-case",
   name: "Get Case",
-  description: "Retrieves a case by its ID. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm)",
-  version: "0.0.5",
+  description: "Retrieve one Salesforce case by its record ID."
+    + " Use **List Cases** to find the ID first, or when you want to search cases rather than fetch a known one."
+    + " Use **List Case Feed Items** and **List Case Comments** to read the case's activity and comment thread."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm)",
+  version: "0.0.6",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/get-current-user/get-current-user.mjs

@@ -1,10 +1,11 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
   key: "salesforce_rest_api-get-current-user",
   name: "Get Current User",
   description: "Returns the authenticated Salesforce user's ID, name, email, and organization ID. Call this first when the user says 'my leads', 'my opportunities', 'my cases', or any first-person query. Use `user_id` as the OwnerId filter in **SOQL Search** (e.g. `WHERE OwnerId = '{user_id}'`) and `organization_id` to construct Salesforce UI URLs. [See the documentation](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_using_userinfo_endpoint.htm).",
-  version: "0.0.1",
+  version: "0.0.2",
   type: "action",
   annotations: {
     destructiveHint: false,

package/actions/get-knowledge-articles/get-knowledge-articles.mjs

@@ -1,11 +1,16 @@
+// x-pd-ai: optimized
 import common from "../common/knowledge.mjs";
 
 export default {
   ...common,
   key: "salesforce_rest_api-get-knowledge-articles",
   name: "Get Knowledge Articles",
-  description: "Get a page of online articles for the given language and category through either search or query. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/sforce_api_rest_retrieve_article_list.htm)",
-  version: "0.0.3",
+  description: "Retrieve a page of online Knowledge articles for a language and data category, by search or query."
+    + " Use **List Knowledge Data Category Groups** to discover valid category values first, and **List Knowledge Articles** to browse article records instead."
+    + " Returns published article content, so responses can be large - narrow by category or search term."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/sforce_api_rest_retrieve_article_list.htm)",
+  version: "0.0.4",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/get-knowledge-data-category-groups/get-knowledge-data-category-groups.mjs

@@ -1,11 +1,16 @@
+// x-pd-ai: optimized
 import common from "../common/knowledge.mjs";
 
 export default {
   ...common,
   key: "salesforce_rest_api-get-knowledge-data-category-groups",
   name: "Get Knowledge Data Category Groups",
-  description: "Fetch data category groups visible to the current user. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/resources_knowledge_support_dcgroups.htm)",
-  version: "0.0.3",
+  description: "List the Knowledge data category groups visible to the current user."
+    + " Call this before **Get Knowledge Articles** to discover the valid category group and category names to filter by."
+    + " Returns only categories the authenticated user can see, so results vary per user."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/resources_knowledge_support_dcgroups.htm)",
+  version: "0.0.4",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/get-record-by-id/get-record-by-id.mjs

@@ -1,10 +1,15 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
   key: "salesforce_rest_api-get-record-by-id",
   name: "Get Record by ID",
-  description: "Retrieves a record by its ID. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm)",
-  version: "0.0.2",
+  description: "Retrieve one Salesforce record of any object type by its record ID."
+    + " Use **Find Records** to look up records by criteria, or **SOQL Query** when you need related fields or a filtered set."
+    + " Use **List Objects** to discover object types if you are unsure of the type name."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm)",
+  version: "0.0.3",
   type: "action",
   annotations: {
     destructiveHint: false,

package/actions/get-related-records/get-related-records.mjs

@@ -1,4 +1,4 @@
-// vandelay-test-dr
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
@@ -11,8 +11,10 @@ export default {
     + " Contact → Cases, Opportunities, Tasks;"
     + " Opportunity → OpportunityLineItems, Tasks."
     + " Use **Describe Object** to discover available relationship names if unsure"
-    + " (look for `relationshipName` on reference fields).",
-  version: "0.0.1",
+    + " (look for `relationshipName` on reference fields)."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_relationships.htm)",
+  version: "0.0.2",
   type: "action",
   annotations: {
     readOnlyHint: true,

package/actions/get-user/get-user.mjs

@@ -1,10 +1,15 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
   key: "salesforce_rest_api-get-user",
   name: "Get User",
-  description: "Retrieves a user by their ID. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm)",
-  version: "0.0.5",
+  description: "Retrieve one Salesforce user by their record ID."
+    + " Use **Get Current User** for the authenticated user instead of looking up an ID."
+    + " Record owner fields such as `OwnerId` hold user IDs - pass one here to resolve it to a name and email."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm)",
+  version: "0.0.6",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/get-user-info/get-user-info.mjs

@@ -1,4 +1,4 @@
-// vandelay-test-dr
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
@@ -9,8 +9,10 @@ export default {
     + " **Must be called before any query that uses first-person language ('my', 'I', 'me').**"
     + " The `userId` can be used as an `OwnerId` filter in SOQL queries (e.g. `WHERE OwnerId = '{userId}'`)."
     + " The `instanceUrl` is needed to construct clickable links to Salesforce records:"
-    + " `{instanceUrl}/lightning/r/{objectType}/{recordId}/view`.",
-  version: "0.0.1",
+    + " `{instanceUrl}/lightning/r/{objectType}/{recordId}/view`."
+    + " "
+    + "[See the documentation](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_using_userinfo_endpoint.htm&type=5)",
+  version: "0.0.2",
   type: "action",
   annotations: {
     readOnlyHint: true,

package/actions/insert-blob-data/insert-blob-data.mjs

@@ -1,10 +1,15 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
 
 export default {
   key: "salesforce_rest_api-insert-blob-data",
   name: "Insert Blob Data",
-  description: "Inserts blob data in Salesforce standard objects. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.228.0.api_rest.meta/api_rest/dome_sobject_insert_update_blob.htm)",
-  version: "0.2.12",
+  description: "Upload binary file data to a Salesforce object such as `ContentVersion` or `Attachment`."
+    + " Use this for Salesforce Files (`ContentVersion`); use **Create Attachment** only for the legacy attachment object."
+    + " The file content must be supplied as a file path or URL, not as raw bytes in the request."
+    + " "
+    + "[See the documentation](https://developer.salesforce.com/docs/atlas.en-us.228.0.api_rest.meta/api_rest/dome_sobject_insert_update_blob.htm)",
+  version: "0.2.13",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/actions/list-case-comments/list-case-comments.mjs

@@ -1,10 +1,19 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
+import constants from "../../common/constants.mjs";
+import {
+  assertSalesforceId, buildFieldList, truncationNote,
+} from "../../common/soql.mjs";
 
 export default {
   key: "salesforce_rest_api-list-case-comments",
   name: "List Case Comments",
-  description: "Lists all comments for a case. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm)",
-  version: "0.0.5",
+  description: "List the comments on a Salesforce case, newest first."
+    + " Use this for the case's comment thread only - use **List Case Feed Items** for the full activity trail (status changes, logged calls, emails) or **List Email Messages** for emails on the case."
+    + " Find the case ID with **List Cases** first."
+    + " For example, case ID `5005g00001ABCDeAAI` with `Limit` `20` returns that case's twenty most recent comments."
+    + " [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_casecomment.htm)",
+  version: "0.1.0",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
@@ -18,20 +27,55 @@ export default {
         salesforce,
         "recordId",
         () => ({
-          objType: "Case",
+          objType: constants.OBJECT_TYPE.CASE,
         }),
       ],
+      label: "Case ID",
+      description: "The ID of the case to retrieve comments for (15- or 18-character Salesforce ID, e.g. `5005g00001ABCDeAAI`). Use the **List Cases** action to retrieve case IDs.",
+    },
+    fields: {
+      propDefinition: [
+        salesforce,
+        "fieldsToObtain",
+        () => ({
+          objType: constants.OBJECT_TYPE.CASE_COMMENT,
+        }),
+      ],
+      label: "Fields",
+      description: "The CaseComment fields to return. Defaults to every field on the object. `Id` is always returned.",
+      optional: true,
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: `The maximum number of comments to return. Valid values are integers from 1 through ${constants.MAX_LIMIT}. Omit to return every comment Salesforce sends in one batch.`,
+      min: 1,
+      max: constants.MAX_LIMIT,
+      optional: true,
     },
   },
   async run({ $ }) {
-    const fields = (await this.salesforce.getFieldsForObjectType("CaseComment")).map(({ name }) => name);
-    let query = `SELECT ${fields.join(", ")} FROM CaseComment WHERE ParentId = '${this.caseId}'`;
+    const caseId = assertSalesforceId(this.caseId, "Case ID");
+
+    const allFields = (await this.salesforce
+      .getFieldsForObjectType(constants.OBJECT_TYPE.CASE_COMMENT))
+      .map(({ name }) => name);
+    const fields = buildFieldList(this.fields, allFields);
+
+    let query = `SELECT ${fields.join(", ")} FROM ${constants.OBJECT_TYPE.CASE_COMMENT}`
+      + ` WHERE ParentId = '${caseId}' 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} comments for case with ID ${this.caseId}`);
+    const { records } = response;
+    $.export("$summary", `Successfully retrieved ${records.length} comment${records.length === 1
+      ? ""
+      : "s"} for case with ID ${caseId}.${truncationNote(response, records.length)}`);
     return records;
   },
 };

package/actions/list-case-feed-items/list-case-feed-items.mjs

@@ -0,0 +1,73 @@
+// x-pd-ai: optimized
+import salesforce from "../../salesforce_rest_api.app.mjs";
+import constants from "../../common/constants.mjs";
+import {
+  assertSalesforceId, escapeSoqlString,
+} from "../../common/soql.mjs";
+
+export default {
+  key: "salesforce_rest_api-list-case-feed-items",
+  name: "List Case Feed Items",
+  description: "List the feed (Chatter) entries on a case, newest first."
+    + " Use this to read a case's activity trail - text posts, status changes, logged calls, email events and case comment events - in one call."
+    + " The case feed only exists when feed tracking is enabled for Cases in the Salesforce org, so an org without it returns no records."
+    + " [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_associated_objects_feed.htm)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    salesforce,
+    caseId: {
+      propDefinition: [
+        salesforce,
+        "recordId",
+        () => ({
+          objType: constants.OBJECT_TYPE.CASE,
+        }),
+      ],
+      label: "Case ID",
+      description: "The ID of the case to retrieve feed items for (15- or 18-character Salesforce ID, e.g. `5005g00001ABCDeAAI`). Use the **List Cases** action to retrieve case IDs.",
+    },
+    feedItemType: {
+      type: "string",
+      label: "Feed Item Type",
+      description: "Return only feed items of this type. By default, feed items of all types are returned.",
+      options: constants.CASE_FEED_ITEM_TYPES,
+      optional: true,
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: "The maximum number of feed items to return. Valid values are integers from 1 through 1000. Default is 100.",
+      default: constants.DEFAULT_LIMIT,
+      min: 1,
+      max: constants.MAX_LIMIT,
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const caseId = assertSalesforceId(this.caseId, "Case ID");
+
+    const fields = (await this.salesforce.getFieldsForObjectType(constants.OBJECT_TYPE.CASE_FEED))
+      .map(({ name }) => name);
+
+    let query = `SELECT ${fields.join(", ")} FROM ${constants.OBJECT_TYPE.CASE_FEED} WHERE ParentId = '${caseId}'`;
+    if (this.feedItemType) {
+      query += ` AND Type = '${escapeSoqlString(this.feedItemType)}'`;
+    }
+    query += ` ORDER BY CreatedDate DESC, Id DESC LIMIT ${this.limit || constants.DEFAULT_LIMIT}`;
+
+    const { records } = await this.salesforce.query({
+      $,
+      query,
+    });
+    $.export("$summary", `Successfully retrieved ${records.length} feed item${records.length === 1
+      ? ""
+      : "s"} for case with ID ${this.caseId}`);
+    return records;
+  },
+};

package/actions/list-cases/list-cases.mjs

@@ -0,0 +1,131 @@
+// x-pd-ai: optimized
+import salesforce from "../../salesforce_rest_api.app.mjs";
+import constants from "../../common/constants.mjs";
+import {
+  assertSalesforceId, escapeSoqlString, toSoqlDateTimeLiteral,
+} from "../../common/soql.mjs";
+
+export default {
+  key: "salesforce_rest_api-list-cases",
+  name: "List Cases",
+  description: "List Salesforce support cases, newest first."
+    + " Use this to find a case and its ID."
+    + " Every filter is optional and they combine with AND - call with no filters to see the most recent cases."
+    + " For example, `Status` `New` with `Limit` `10` returns the ten newest open cases."
+    + " Status values are org-configurable."
+    + " [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_case.htm)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    salesforce,
+    caseNumber: {
+      type: "string",
+      label: "Case Number",
+      description: "Return only the case with this case number, e.g. `00001024`. This is the human-readable number shown in the Salesforce UI, not the record ID.",
+      optional: true,
+    },
+    subject: {
+      type: "string",
+      label: "Subject Contains",
+      description: "Return only cases whose subject contains this text (case-insensitive), e.g. `rotor`.",
+      optional: true,
+    },
+    status: {
+      type: "string",
+      label: "Status",
+      description: `Return only cases with this exact status, e.g. \`${constants.CASE_DEFAULT_STATUSES[0]}\`. Org-configurable - use **Describe Object** on \`Case\` to list the valid values.`,
+      optional: true,
+    },
+    accountId: {
+      type: "string",
+      label: "Account ID",
+      description: "Return only cases on this account (15- or 18-character Salesforce ID, e.g. `001P500000dGpZLIA0`). Use **Find Records** on `Account` to look one up.",
+      optional: true,
+    },
+    isClosed: {
+      type: "boolean",
+      label: "Is Closed",
+      description: "Set to `true` to return only closed cases, or `false` for only open ones. Omit to return both.",
+      optional: true,
+    },
+    createdAfter: {
+      type: "string",
+      label: "Created After",
+      description: "Return only cases created on or after this moment. ISO 8601 date (`2026-08-01`) or date-time (`2026-08-01T00:00:00Z`).",
+      optional: true,
+    },
+    fields: {
+      propDefinition: [
+        salesforce,
+        "fieldsToObtain",
+        () => ({
+          objType: constants.OBJECT_TYPE.CASE,
+        }),
+      ],
+      label: "Fields",
+      description: `The Case fields to return. Defaults to a compact set: ${constants.CASE_LIST_FIELDS.join(", ")}. \`Id\` is always returned.`,
+      optional: true,
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: `The maximum number of cases to return. Valid values are integers from 1 through ${constants.MAX_LIMIT}. Default is ${constants.DEFAULT_LIMIT}.`,
+      default: constants.DEFAULT_LIMIT,
+      min: 1,
+      max: constants.MAX_LIMIT,
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    // Id is always selected: a caller narrowing Fields to save context would
+    // otherwise lose the ID that every follow-up case action needs.
+    const fields = [
+      ...new Set([
+        "Id",
+        ...this.fields?.length
+          ? this.fields
+          : constants.CASE_LIST_FIELDS,
+      ]),
+    ];
+
+    const conditions = [];
+    if (this.caseNumber) {
+      conditions.push(`CaseNumber = '${escapeSoqlString(this.caseNumber)}'`);
+    }
+    if (this.subject) {
+      conditions.push(`Subject LIKE '%${escapeSoqlString(this.subject)}%'`);
+    }
+    if (this.status) {
+      conditions.push(`Status = '${escapeSoqlString(this.status)}'`);
+    }
+    if (this.accountId) {
+      conditions.push(`AccountId = '${assertSalesforceId(this.accountId, "Account ID")}'`);
+    }
+    if (typeof this.isClosed === "boolean") {
+      conditions.push(`IsClosed = ${this.isClosed}`);
+    }
+    if (this.createdAfter) {
+      conditions.push(`CreatedDate >= ${toSoqlDateTimeLiteral(this.createdAfter, "Created After")}`);
+    }
+
+    let query = `SELECT ${fields.join(", ")} FROM ${constants.OBJECT_TYPE.CASE}`;
+    if (conditions.length) {
+      query += ` WHERE ${conditions.join(" AND ")}`;
+    }
+    query += ` ORDER BY CreatedDate DESC, Id DESC LIMIT ${this.limit || constants.DEFAULT_LIMIT}`;
+
+    const { records } = await this.salesforce.query({
+      $,
+      query,
+    });
+    $.export("$summary", `Successfully retrieved ${records.length} case${records.length === 1
+      ? ""
+      : "s"}`);
+    return records;
+  },
+};

package/actions/list-email-messages/list-email-messages.mjs

@@ -1,10 +1,19 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
+import constants from "../../common/constants.mjs";
+import {
+  assertSalesforceId, buildFieldList, truncationNote,
+} from "../../common/soql.mjs";
 
 export default {
   key: "salesforce_rest_api-list-email-messages",
   name: "List Email Messages",
-  description: "Lists all email messages for a case. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm)",
-  version: "0.0.5",
+  description: "List Salesforce email messages, newest first, optionally scoped to one case."
+    + " Returns the full email records including subject and body - use **List Case Feed Items** instead if you only need to know that an email happened."
+    + " Find the case ID with **List Cases** first."
+    + " Omit `Case ID` to list the most recent emails across the org, which can be large - set `Limit`."
+    + " [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_emailmessage.htm)",
+  version: "0.1.0",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
@@ -18,26 +27,64 @@ export default {
         salesforce,
         "recordId",
         () => ({
-          objType: "Case",
+          objType: constants.OBJECT_TYPE.CASE,
         }),
       ],
       label: "Case ID",
-      description: "The ID of the case to retrieve email messages for",
+      description: "The ID of the case to retrieve email messages for (15- or 18-character Salesforce ID, e.g. `5005g00001ABCDeAAI`). Use the **List Cases** action to retrieve case IDs. Omit to list emails across all records.",
+      optional: true,
+    },
+    fields: {
+      propDefinition: [
+        salesforce,
+        "fieldsToObtain",
+        () => ({
+          objType: constants.OBJECT_TYPE.EMAIL_MESSAGE,
+        }),
+      ],
+      label: "Fields",
+      description: "The EmailMessage fields to return. Defaults to every field on the object, which includes the full message body. `Id` is always returned.",
+      optional: true,
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: `The maximum number of email messages to return. Valid values are integers from 1 through ${constants.MAX_LIMIT}. Omit to return every message Salesforce sends in one batch.`,
+      min: 1,
+      max: constants.MAX_LIMIT,
       optional: true,
     },
   },
   async run({ $ }) {
-    const fields = (await this.salesforce.getFieldsForObjectType("EmailMessage")).map(({ name }) => name);
-    let query = `SELECT ${fields.join(", ")} FROM EmailMessage`;
-    if (this.caseId) {
-      query += ` WHERE RelatedToId = '${this.caseId}'`;
+    const caseId = this.caseId
+      ? assertSalesforceId(this.caseId, "Case ID")
+      : null;
+
+    const allFields = (await this.salesforce
+      .getFieldsForObjectType(constants.OBJECT_TYPE.EMAIL_MESSAGE))
+      .map(({ name }) => name);
+    const fields = buildFieldList(this.fields, allFields);
+
+    let query = `SELECT ${fields.join(", ")} FROM ${constants.OBJECT_TYPE.EMAIL_MESSAGE}`;
+    if (caseId) {
+      query += ` WHERE RelatedToId = '${caseId}'`;
+    }
+    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} email messages for case with ID ${this.caseId}`);
+    const { records } = response;
+    const scope = caseId
+      ? ` for case with ID ${caseId}`
+      : "";
+    $.export("$summary", `Successfully retrieved ${records.length} email message${records.length === 1
+      ? ""
+      : "s"}${scope}.${truncationNote(response, records.length)}`);
     return records;
   },
 };

package/actions/list-email-templates/list-email-templates.mjs

@@ -1,10 +1,18 @@
+// x-pd-ai: optimized
 import salesforce from "../../salesforce_rest_api.app.mjs";
+import constants from "../../common/constants.mjs";
+import {
+  buildFieldList, truncationNote,
+} from "../../common/soql.mjs";
 
 export default {
   key: "salesforce_rest_api-list-email-templates",
   name: "List Email Templates",
-  description: "Lists all email templates. [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_emailtemplate.htm)",
-  version: "0.0.5",
+  description: "List Salesforce email templates, newest first."
+    + " Use this to find a template and its ID before sending with **Send Email**, or before editing with **Update Email Template**."
+    + " For example, run with `Limit` `50`, then pass the `Id` of the template you want to **Send Email**."
+    + " [See the documentation](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_emailtemplate.htm)",
+  version: "0.1.0",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
@@ -13,16 +21,47 @@ export default {
   type: "action",
   props: {
     salesforce,
+    fields: {
+      propDefinition: [
+        salesforce,
+        "fieldsToObtain",
+        () => ({
+          objType: constants.OBJECT_TYPE.EMAIL_TEMPLATE,
+        }),
+      ],
+      label: "Fields",
+      description: "The EmailTemplate fields to return. Defaults to every field on the object, which includes the full template body. `Id` is always returned.",
+      optional: true,
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: `The maximum number of templates to return. Valid values are integers from 1 through ${constants.MAX_LIMIT}. Omit to return every template Salesforce sends in one batch.`,
+      min: 1,
+      max: constants.MAX_LIMIT,
+      optional: true,
+    },
   },
   async run({ $ }) {
-    const fields = (await this.salesforce.getFieldsForObjectType("EmailTemplate")).map(({ name }) => name);
-    const query = `SELECT ${fields.join(", ")} FROM EmailTemplate`;
+    const allFields = (await this.salesforce
+      .getFieldsForObjectType(constants.OBJECT_TYPE.EMAIL_TEMPLATE))
+      .map(({ name }) => name);
+    const fields = buildFieldList(this.fields, allFields);
 
-    const { records } = await this.salesforce.query({
+    let query = `SELECT ${fields.join(", ")} FROM ${constants.OBJECT_TYPE.EMAIL_TEMPLATE}`
+      + " ORDER BY CreatedDate DESC, Id DESC";
+    if (this.limit) {
+      query += ` LIMIT ${this.limit}`;
+    }
+
+    const response = await this.salesforce.query({
       $,
       query,
     });
-    $.export("$summary", `Sucessfully retrieved ${records.length} email templates`);
+    const { records } = response;
+    $.export("$summary", `Successfully retrieved ${records.length} email template${records.length === 1
+      ? ""
+      : "s"}.${truncationNote(response, records.length)}`);
     return records;
   },
 };