Add internal notes support to Gorgias OAuth integration (#17605)

* Add internal notes support to Gorgias OAuth integration

- Add channel prop to create-ticket-message action with internal-note support
- Add conditional logic to skip sender/receiver validation for internal notes
- Create internal-note-created webhook source for monitoring internal note events
- Add JSDoc documentation to all methods
- Update package.json version

* Fix processHistoricalEvent error in internal-note-created source

Add empty deploy() hook to prevent base class from attempting to process
historical events, matching the pattern used in ticket-message-created source.
This resolves the "processHistoricalEvent is not implemented" error.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix linting errors in Gorgias OAuth components

- Fix multiline-ternary formatting in create-ticket-message.mjs
- Remove unused constants import from internal-note-created.mjs
- Add missing newline at end of internal-note-created.mjs

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* updates

* pnpm-lock.yaml

---------

Co-authored-by: Job Nijenhuis <job@neople.io>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Michelle Bergeron <michelle.bergeron@gmail.com>

Author: 4 people

components/gorgias_oauth/actions/create-ticket-message/create-ticket-message.mjs

@@ -7,7 +7,7 @@ export default {
   key: "gorgias_oauth-create-ticket-message",
   name: "Create Ticket Message",
   description: "Create a message for a ticket in the Gorgias system. [See the documentation](https://developers.gorgias.com/reference/create-ticket-message)",
-  version: "0.0.2",
+  version: "0.0.3",
   type: "action",
   props: {
     gorgiasOauth,
@@ -67,6 +67,15 @@ export default {
       label: "Message",
       description: "Message of the ticket. Accepts HTML",
     },
+    channel: {
+      propDefinition: [
+        gorgiasOauth,
+        "channel",
+      ],
+      optional: false,
+      default: "email",
+      reloadProps: true,
+    },
     via: {
       propDefinition: [
         gorgiasOauth,
@@ -101,13 +110,20 @@ export default {
     },
   },
   additionalProps(props) {
-    props.toUser.hidden = this.fromAgent;
-    props.fromCustomer.hidden = this.fromAgent;
-    props.toCustomer.hidden = !this.fromAgent;
+    const isInternalNote = this.channel === "internal-note";
+    props.toUser.hidden = this.fromAgent || isInternalNote;
+    props.fromCustomer.hidden = this.fromAgent || isInternalNote;
+    props.toCustomer.hidden = !this.fromAgent || isInternalNote;
     props.fromUser.hidden = !this.fromAgent;
     return {};
   },
   methods: {
+    /**
+     * Get attachment information from URL
+     * @param {object} $ - Step object
+     * @param {string} url - Attachment URL
+     * @returns {object} Content type and size information
+     */
     async getAttachmentInfo($, url) {
       const { headers } = await axios($, {
         method: "HEAD",
@@ -119,6 +135,13 @@ export default {
         size: headers["content-length"],
       };
     },
+    /**
+     * Get email address for user or customer
+     * @param {object} $ - Step object
+     * @param {string} id - User or customer ID
+     * @param {string} type - Type of email to get (from/to)
+     * @returns {string} Email address
+     */
     async getEmail($, id, type = "from") {
       const {
         gorgiasOauth: {
@@ -147,6 +170,12 @@ export default {
       throw new ConfigurationError("Must enter both Attachment URL and Attachment File Name");
     }
 
+    const isInternalNote = this.channel === "internal-note";
+
+    if (isInternalNote && this.fromAgent === false) {
+      throw new ConfigurationError("From Agent must be set to `true` when creating an internal note");
+    }
+
     let contentType, size;
     if (this.attachmentUrl) {
       ({
@@ -167,50 +196,61 @@ export default {
         ? "From User"
         : "From Customer"}" is required when "From Agent" is set to \`${this.fromAgent}\``);
     }
-    if (!toId) {
-      throw new ConfigurationError(`"${this.fromAgent
-        ? "To Customer"
-        : "To User"}" is required when "From Agent" is set to \`${this.fromAgent}\``);
+    // For internal notes, we don't need to validation
+    if (!isInternalNote) {
+      if (!toId) {
+        throw new ConfigurationError(`"${this.fromAgent
+          ? "To Customer"
+          : "To User"}" is required when "From Agent" is set to \`${this.fromAgent}\``);
+      }
     }
 
-    const response = await this.gorgiasOauth.createMessage({
-      $,
-      ticketId: this.ticketId,
-      data: {
-        channel: "email",
-        source: {
-          from: {
-            address: await this.getEmail($, fromId, "from"),
-          },
-          to: [
-            {
-              address: await this.getEmail($, toId, "to"),
-            },
-          ],
+    const messageData = {
+      channel: this.channel,
+      body_html: this.message,
+      via: this.via,
+      subject: this.subject,
+      from_agent: this.fromAgent,
+      sent_datetime: this.sentDatetime,
+      attachments: this.attachmentUrl && [
+        {
+          url: this.attachmentUrl,
+          name: this.attachmentName,
+          content_type: contentType,
+          size,
         },
-        body_html: this.message,
-        via: this.via,
-        subject: this.subject,
-        from_agent: this.fromAgent,
-        sent_datetime: this.sentDatetime,
-        attachments: this.attachmentUrl && [
+      ],
+      sender: {
+        id: fromId,
+      },
+    };
+
+    // Only add source and receiver for non-internal notes
+    if (!isInternalNote) {
+      messageData.source = {
+        from: {
+          address: await this.getEmail($, fromId, "from"),
+        },
+        to: [
           {
-            url: this.attachmentUrl,
-            name: this.attachmentName,
-            content_type: contentType,
-            size,
+            address: await this.getEmail($, toId, "to"),
           },
         ],
-        sender: {
-          id: fromId,
-        },
-        receiver: {
-          id: toId,
-        },
-      },
+      };
+      messageData.receiver = {
+        id: toId,
+      };
+    }
+
+    const response = await this.gorgiasOauth.createMessage({
+      $,
+      ticketId: this.ticketId,
+      data: messageData,
     });
 
-    $.export("$summary", `Succesfully created ticket message with ID: ${response.id}`);
+    $.export("$summary", `Successfully created ${isInternalNote
+      ? "internal note"
+      : "ticket message"} with ID: ${response.id}`);
 
     return response;
   },

components/gorgias_oauth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipedream/gorgias_oauth",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Pipedream Gorgias OAuth Components",
   "main": "gorgias_oauth.app.mjs",
   "keywords": [

components/gorgias_oauth/sources/internal-note-created/internal-note-created.mjs

@@ -0,0 +1,63 @@
+import base from "../common/base.mjs";
+import eventTypes from "../common/event-types.mjs";
+import sampleEmit from "./test-event.mjs";
+
+export default {
+  ...base,
+  key: "gorgias_oauth-internal-note-created",
+  name: "New Internal Note",
+  description: "Emit new event when an internal note is created on a ticket. [See the documentation](https://developers.gorgias.com/reference/the-event-object)",
+  version: "0.0.1",
+  type: "source",
+  props: {
+    ...base.props,
+    ticketId: {
+      propDefinition: [
+        base.props.gorgias_oauth,
+        "ticketId",
+      ],
+      optional: true,
+    },
+    sender: {
+      type: "string",
+      label: "Sender Email",
+      description: "Email address of the sender",
+      optional: true,
+    },
+  },
+  hooks: {
+    ...base.hooks,
+    deploy() {},
+  },
+  methods: {
+    ...base.methods,
+    /**
+     * Get the event type for internal notes
+     * @returns {string} The event type
+     */
+    getEventType() {
+      return eventTypes.TICKET_MESSAGE_CREATED;
+    },
+    /**
+     * Check if a message is relevant for this source
+     * @param {object} message - The message object
+     * @returns {boolean} Whether the message is relevant
+     */
+    isRelevant(message) {
+      return message.source.type === "internal-note"
+        && (!this.ticketId || message.ticket_id === this.ticketId)
+        && (!this.sender || message.sender?.email === this.sender);
+    },
+    /**
+     * Process and emit relevant events
+     * @param {object} event - The incoming event
+     */
+    async processEvent(event) {
+      const { message } = event;
+      if (this.isRelevant(message)) {
+        this.emitEvent(message);
+      }
+    },
+  },
+  sampleEmit,
+};

components/gorgias_oauth/sources/internal-note-created/test-event.mjs

@@ -0,0 +1,43 @@
+export default {
+  id: 123456789,
+  created_datetime: "2024-01-15T10:30:00Z",
+  updated_datetime: "2024-01-15T10:30:00Z",
+  ticket_id: 98765,
+  channel: "internal-note",
+  via: "internal-note",
+  source: {
+    type: "internal-note",
+    from: {
+      address: "agent@company.com",
+      name: "Support Agent"
+    },
+    to: []
+  },
+  sender: {
+    id: 456,
+    email: "agent@company.com",
+    name: "Support Agent"
+  },
+  receiver: null,
+  body_html: "<p>This is an internal note about the customer's issue.</p>",
+  body_text: "This is an internal note about the customer's issue.",
+  subject: "Internal Note",
+  from_agent: true,
+  sent_datetime: "2024-01-15T10:30:00Z",
+  attachments: [],
+  public: false,
+  stripped_html: "<p>This is an internal note about the customer's issue.</p>",
+  stripped_text: "This is an internal note about the customer's issue.",
+  stripped_signature: "",
+  message_id: "internal-note-123456789",
+  actions: [],
+  rule_id: null,
+  external_id: null,
+  tags: [],
+  integration_id: null,
+  last_sending_error: null,
+  opened_datetime: null,
+  clicked_datetime: null,
+  failed_datetime: null,
+  errors: []
+};