Helpscout - new components (#19227)

* new actions

* versions

Author: michelle0927

components/help_scout/actions/add-note/add-note.mjs

@@ -4,7 +4,7 @@ export default {
   key: "help_scout-add-note",
   name: "Add Note to Conversation",
   description: "Adds a note to an existing conversation in Help Scout. [See the documentation](https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/note/)",
-  version: "0.0.3",
+  version: "0.0.4",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/help_scout/actions/create-customer/create-customer.mjs

@@ -13,7 +13,7 @@ export default {
   key: "help_scout-create-customer",
   name: "Create Customer",
   description: "Creates a new customer record in Help Scout. [See the documentation](https://developer.helpscout.com/mailbox-api/endpoints/customers/create/)",
-  version: "0.0.3",
+  version: "0.0.4",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/help_scout/actions/get-conversation-details/get-conversation-details.mjs

@@ -4,7 +4,7 @@ export default {
   key: "help_scout-get-conversation-details",
   name: "Get Conversation Details",
   description: "Retrieves the details of a specific conversation. [See the documentation](https://developer.helpscout.com/mailbox-api/endpoints/conversations/get/)",
-  version: "0.0.2",
+  version: "0.0.3",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/help_scout/actions/get-conversation-threads/get-conversation-threads.mjs

@@ -4,7 +4,7 @@ export default {
   key: "help_scout-get-conversation-threads",
   name: "Get Conversation Threads",
   description: "Retrieves the threads of a specific conversation. [See the documentation](https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/list/)",
-  version: "0.0.2",
+  version: "0.0.3",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/help_scout/actions/get-tag-by-id/get-tag-by-id.mjs

@@ -0,0 +1,31 @@
+import helpScout from "../../help_scout.app.mjs";
+
+export default {
+  key: "help_scout-get-tag-by-id",
+  name: "Get Tag by ID",
+  description: "Gets a tag by its ID. [See the documentation](https://developer.helpscout.com/mailbox-api/endpoints/tags/get/)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    helpScout,
+    tagId: {
+      propDefinition: [
+        helpScout,
+        "tagId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.helpScout.getTag({
+      $,
+      tagId: this.tagId,
+    });
+    $.export("$summary", `Successfully retrieved tag with ID ${this.tagId}`);
+    return response;
+  },
+};

components/help_scout/actions/list-tags/list-tags.mjs

@@ -0,0 +1,37 @@
+import helpScout from "../../help_scout.app.mjs";
+
+export default {
+  key: "help_scout-list-tags",
+  name: "List Tags",
+  description: "Lists all tags in Help Scout. [See the documentation](https://developer.helpscout.com/mailbox-api/endpoints/tags/list/)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    helpScout,
+    page: {
+      type: "integer",
+      label: "Page",
+      description: "The page number to return. Defaults to 1.",
+      default: 1,
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const response = await this.helpScout.listTags({
+      $,
+      params: {
+        page: this.page,
+      },
+    });
+    const length = response?._embedded?.tags?.length ?? 0;
+    $.export("$summary", `Successfully retrieved ${length} tag${length === 1
+      ? ""
+      : "s"}`);
+    return response;
+  },
+};

components/help_scout/actions/send-reply/send-reply.mjs

@@ -4,7 +4,7 @@ export default {
   key: "help_scout-send-reply",
   name: "Send Reply",
   description: "Sends a reply to a conversation. Be careful as this sends an actual email to the customer. [See the documentation](https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/reply/)",
-  version: "0.0.3",
+  version: "0.0.4",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/help_scout/actions/update-conversation/update-conversation.mjs

@@ -0,0 +1,56 @@
+import helpScout from "../../help_scout.app.mjs";
+import { CONVERSATION_OPERATIONS } from "../../common/constants.mjs";
+
+export default {
+  key: "help_scout-update-conversation",
+  name: "Update Conversation",
+  description: "Updates a conversation. [See the documentation](https://developer.helpscout.com/mailbox-api/endpoints/conversations/update/)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: true,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    helpScout,
+    conversationId: {
+      propDefinition: [
+        helpScout,
+        "conversationId",
+      ],
+    },
+    operation: {
+      type: "string",
+      label: "Operation",
+      description: "The operation to perform on the conversation",
+      options: CONVERSATION_OPERATIONS.map(({ label }) => label),
+    },
+    value: {
+      type: "string",
+      label: "Value",
+      description: "The value to use for the operation",
+    },
+  },
+  async run({ $ }) {
+    const operation = CONVERSATION_OPERATIONS.find(({ label }) => label === this.operation);
+    const value = operation.type === "boolean"
+      ? this.value === "true"
+      : operation.type === "number"
+        ? +this.value
+        : this.value;
+
+    const response = await this.helpScout.updateConversation({
+      conversationId: this.conversationId,
+      data: {
+        op: operation.operation,
+        path: operation.path,
+        value,
+      },
+    });
+
+    $.export("$summary", `Successfully updated conversation with ID ${this.conversationId}`);
+
+    return response;
+  },
+};

components/help_scout/common/constants.mjs

@@ -14,3 +14,48 @@ export const GENDER_OPTIONS = [
   "female",
   "unknown",
 ];
+
+export const CONVERSATION_OPERATIONS = [
+  {
+    label: "Change subject",
+    path: "/subject",
+    operation: "replace",
+    type: "string",
+  },
+  {
+    label: "Change customer",
+    path: "/primaryCustomer.id",
+    operation: "replace",
+    type: "number",
+  },
+  {
+    label: "Publish draft",
+    path: "/draft",
+    operation: "replace",
+    type: "boolean",
+  },
+  {
+    label: "Move conversation to another inbox",
+    path: "/mailboxId",
+    operation: "move",
+    type: "number",
+  },
+  {
+    label: "Change conversation status",
+    path: "/status",
+    operation: "replace",
+    type: "string",
+  },
+  {
+    label: "Change conversation owner",
+    path: "/assignTo",
+    operation: "replace",
+    type: "number",
+  },
+  {
+    label: "Un-assign conversation",
+    path: "/assignTo",
+    operation: "remove",
+    type: "number",
+  },
+];

components/help_scout/help_scout.app.mjs

@@ -7,7 +7,7 @@ export default {
     agentId: {
       type: "string",
       label: "Agent ID",
-      description: "ID of the agent to whom the conversation is assigned.",
+      description: "ID of the agent to whom the conversation is assigned",
     },
     conversationId: {
       type: "string",
@@ -31,7 +31,7 @@ export default {
     customerId: {
       type: "string",
       label: "Customer ID",
-      description: "The unique identifier of the customer.",
+      description: "The unique identifier of the customer",
       async options({ page }) {
         const { _embedded: { customers } } = await this.listCustomers({
           params: {
@@ -50,7 +50,7 @@ export default {
     userId: {
       type: "string",
       label: "User ID",
-      description: "The unique identifier of the user.",
+      description: "The unique identifier of the user",
       async options({ page }) {
         const { _embedded: { users } } = await this.listUsers({
           params: {
@@ -66,10 +66,28 @@ export default {
         }));
       },
     },
+    tagId: {
+      type: "string",
+      label: "Tag ID",
+      description: "The unique identifier of the tag",
+      async options({ page }) {
+        const { _embedded: { tags } } = await this.listTags({
+          params: {
+            page: page + 1,
+          },
+        });
+        return tags.map(({
+          id: value, name: label,
+        }) => ({
+          label,
+          value,
+        }));
+      },
+    },
     text: {
       type: "string",
       label: "Text",
-      description: "The content of the note.",
+      description: "The content of the note",
     },
   },
   methods: {
@@ -90,6 +108,14 @@ export default {
         ...opts,
       });
     },
+    getTag({
+      tagId, ...opts
+    }) {
+      return this._makeRequest({
+        path: `/tags/${tagId}`,
+        ...opts,
+      });
+    },
     listConversations(opts = {}) {
       return this._makeRequest({
         path: "/conversations",
@@ -108,6 +134,12 @@ export default {
         ...opts,
       });
     },
+    listTags(opts = {}) {
+      return this._makeRequest({
+        path: "/tags",
+        ...opts,
+      });
+    },
     createWebhook(opts = {}) {
       return this._makeRequest({
         method: "POST",
@@ -162,5 +194,14 @@ export default {
         ...opts,
       });
     },
+    updateConversation({
+      conversationId, ...opts
+    }) {
+      return this._makeRequest({
+        method: "PATCH",
+        path: `/conversations/${conversationId}`,
+        ...opts,
+      });
+    },
   },
 };