connectors 0.1.0

data/app/connectors/gmail/mime_builder.rb

@@ -0,0 +1,261 @@
+require "base64"
+require "securerandom"
+require "time"
+
+module Gmail
+  # Minimal RFC 5322 / RFC 2045 / RFC 2047 / RFC 2231 builder for the Gmail
+  # `users.messages.send` and `users.drafts.create` endpoints. Gmail wants
+  # the entire message as base64url-encoded MIME in a `raw` field — there's
+  # no JSON shortcut for `body`/`subject`/`attachments`.
+  #
+  # Handles:
+  #   1. text only                        → text/plain
+  #   2. html only                        → text/html
+  #   3. html + text                      → multipart/alternative
+  #   4. (any of the above) + attachments → multipart/mixed
+  #   5. empty body (drafts)              → empty text/plain
+  #
+  # Non-ASCII data is handled via:
+  #   - Subject + From/To/Cc display-name phrases: RFC 2047 encoded-word
+  #   - Attachment filenames: RFC 2231 continuation (filename*=UTF-8''…)
+  #   - Bodies: base64 transfer-encoded UTF-8
+  #
+  # n8n parity: their Gmail node uses nodemailer's mail-composer for the
+  # same job. We hand-roll because Gmail only needs the simple subset.
+  class MimeBuilder
+    CRLF = "\r\n".freeze
+
+    def self.build(**opts)
+      new(**opts).build
+    end
+
+    # Like `.build`, but allows an empty body (drafts only — Gmail's
+    # `users.drafts.create` accepts empty messages).
+    def self.build_draft(**opts)
+      new(**opts.merge(allow_empty: true)).build
+    end
+
+    def initialize(to: nil, subject: nil, from: nil, cc: nil, bcc: nil, reply_to: nil,
+                   html: nil, text: nil, attachments: nil, headers: nil,
+                   thread_id: nil, in_reply_to: nil, references: nil,
+                   allow_empty: false)
+      @to          = Array(to).reject { |v| v.to_s.empty? }
+      @cc          = Array(cc).reject { |v| v.to_s.empty? }
+      @bcc         = Array(bcc).reject { |v| v.to_s.empty? }
+      @reply_to    = Array(reply_to).reject { |v| v.to_s.empty? }
+      @from        = from
+      @subject     = subject.to_s
+      @html        = html
+      @text        = text
+      @attachments = Array(attachments)
+      @headers     = headers || {}
+      @thread_id   = thread_id
+      @in_reply_to = in_reply_to
+      @references  = references
+      @allow_empty = allow_empty
+
+      return if allow_empty
+
+      raise ArgumentError, "send_message requires html or text" if @html.nil? && @text.nil?
+      raise ArgumentError, "send_message requires at least one recipient" if @to.empty?
+    end
+
+    # Returns the full MIME message as a base64url-encoded string, ready to
+    # drop into Gmail's `raw` field.
+    def build
+      Base64.urlsafe_encode64(raw_message, padding: false)
+    end
+
+    def raw_message
+      if @attachments.any?
+        build_multipart_mixed
+      elsif @html && @text
+        build_multipart_alternative
+      elsif @html
+        build_part(content_type: "text/html; charset=UTF-8", body: @html, with_headers: true)
+      else
+        # Covers text-only AND empty-body drafts (text becomes "").
+        build_part(content_type: "text/plain; charset=UTF-8", body: @text || "", with_headers: true)
+      end
+    end
+
+    private
+
+    def build_multipart_alternative
+      boundary = "alt_#{SecureRandom.hex(8)}"
+      body = +""
+      body << "--#{boundary}" << CRLF
+      body << inline_part(content_type: "text/plain; charset=UTF-8", body: @text)
+      body << "--#{boundary}" << CRLF
+      body << inline_part(content_type: "text/html; charset=UTF-8", body: @html)
+      body << "--#{boundary}--" << CRLF
+
+      headers_lines("multipart/alternative; boundary=\"#{boundary}\"") + CRLF + body
+    end
+
+    def build_multipart_mixed
+      boundary = "mix_#{SecureRandom.hex(8)}"
+      body = +""
+
+      body << "--#{boundary}" << CRLF
+      if @html && @text
+        body << build_multipart_alternative_without_headers
+      elsif @html
+        body << inline_part(content_type: "text/html; charset=UTF-8", body: @html)
+      else
+        body << inline_part(content_type: "text/plain; charset=UTF-8", body: @text || "")
+      end
+
+      @attachments.each do |att|
+        body << "--#{boundary}" << CRLF
+        body << inline_attachment(att)
+      end
+      body << "--#{boundary}--" << CRLF
+
+      headers_lines("multipart/mixed; boundary=\"#{boundary}\"") + CRLF + body
+    end
+
+    def build_multipart_alternative_without_headers
+      boundary = "alt_#{SecureRandom.hex(8)}"
+      part = +""
+      part << "Content-Type: multipart/alternative; boundary=\"#{boundary}\"" << CRLF << CRLF
+      part << "--#{boundary}" << CRLF
+      part << inline_part(content_type: "text/plain; charset=UTF-8", body: @text || "")
+      part << "--#{boundary}" << CRLF
+      part << inline_part(content_type: "text/html; charset=UTF-8", body: @html || "")
+      part << "--#{boundary}--" << CRLF
+      part
+    end
+
+    def build_part(content_type:, body:, with_headers:)
+      header_block = with_headers ? headers_lines(content_type) : ""
+      "#{header_block}#{CRLF}#{base64_wrapped(body)}"
+    end
+
+    def inline_part(content_type:, body:)
+      part = +""
+      part << "Content-Type: #{content_type}" << CRLF
+      part << "Content-Transfer-Encoding: base64" << CRLF << CRLF
+      part << base64_wrapped(body) << CRLF
+      part
+    end
+
+    def inline_attachment(att)
+      filename     = att[:filename] || att["filename"] || "attachment"
+      content_type = att[:content_type] || att["content_type"] || "application/octet-stream"
+      content      = att[:content] || att["content"]
+      raise ArgumentError, "attachment #{filename.inspect} missing `content`" if content.to_s.empty?
+
+      cid           = att[:content_id] || att["content_id"]
+      disposition   = (att[:disposition] || att["disposition"] || "attachment").to_s
+
+      part = +""
+      part << "Content-Type: #{content_type}; #{filename_param(filename)}" << CRLF
+      part << "Content-Disposition: #{disposition}; #{filename_param(filename, disposition: true)}" << CRLF
+      part << "Content-ID: <#{cid}>" << CRLF if cid
+      part << "Content-Transfer-Encoding: base64" << CRLF << CRLF
+      part << base64_normalize(content) << CRLF
+      part
+    end
+
+    def headers_lines(content_type)
+      lines = []
+      lines << "MIME-Version: 1.0"
+      lines << "Date: #{Time.now.utc.rfc2822}"
+      lines << "From: #{encode_address(@from)}"               if @from
+      lines << "To: #{format_address_list(@to)}"              if @to.any?
+      lines << "Cc: #{format_address_list(@cc)}"              if @cc.any?
+      lines << "Bcc: #{format_address_list(@bcc)}"            if @bcc.any?
+      lines << "Reply-To: #{format_address_list(@reply_to)}"  if @reply_to.any?
+      lines << "Subject: #{encode_rfc2047(@subject)}"
+      lines << "In-Reply-To: #{@in_reply_to}"                 if @in_reply_to
+      lines << "References: #{@references}"                   if @references
+      lines << "Message-ID: <#{SecureRandom.uuid}@flow>"
+      @headers.each { |k, v| lines << "#{k}: #{v}" }
+      lines << "Content-Type: #{content_type}"
+      # multipart containers don't carry a transfer-encoding line — each
+      # sub-part declares its own.
+      lines << "Content-Transfer-Encoding: base64" unless content_type.start_with?("multipart")
+      lines.join(CRLF) + CRLF
+    end
+
+    def format_address_list(list)
+      list.map { |a| encode_address(a) }.join(", ")
+    end
+
+    # If the address has a display-name phrase, RFC 2047-encode the phrase
+    # when it carries non-ASCII chars. Examples:
+    #   "héllo@example.com"        → "héllo@example.com"           (ASCII addr-spec, passes through)
+    #   "Héllo <h@example.com>"    → "=?UTF-8?B?SMOpbGxv?= <h@example.com>"
+    #   "h@example.com"            → "h@example.com"
+    def encode_address(address)
+      addr = address.to_s
+      if (m = addr.match(/\A(.+?)\s*<(.+)>\z/))
+        phrase, mailbox = m[1].strip, m[2].strip
+        encoded_phrase = encode_rfc2047(phrase)
+        "#{encoded_phrase} <#{mailbox}>"
+      else
+        addr
+      end
+    end
+
+    # RFC 2047 encoded-word for non-ASCII text. ASCII strings pass through
+    # unchanged. Long inputs are chunked into multiple encoded-words at
+    # 70-byte boundaries (the RFC allows up to 75; 70 gives breathing room).
+    def encode_rfc2047(text)
+      str = text.to_s
+      return str if str.ascii_only?
+
+      bytes = str.dup.force_encoding(Encoding::UTF_8).bytes
+      chunks = []
+      chunks << [] while false # placeholder; built below
+      buf = []
+      bytes.each do |b|
+        if buf.length >= 45  # 45 raw bytes ≈ 60 base64 chars + wrapper → ~75 total
+          chunks << buf
+          buf = []
+        end
+        buf << b
+      end
+      chunks << buf unless buf.empty?
+
+      chunks.map { |chunk|
+        "=?UTF-8?B?#{Base64.strict_encode64(chunk.pack('C*'))}?="
+      }.join(" ")
+    end
+
+    # Builds `name="ascii"` for plain ASCII filenames; RFC 2231-continuation
+    # `filename*=UTF-8''…percent…encoded…` for non-ASCII. `name` (Content-
+    # Type) vs `filename` (Content-Disposition) handled via `disposition:`.
+    def filename_param(filename, disposition: false)
+      key = disposition ? "filename" : "name"
+      if filename.ascii_only?
+        %Q(#{key}="#{filename.gsub('"', '\\"')}")
+      else
+        encoded = percent_encode(filename)
+        %Q(#{key}*=UTF-8''#{encoded})
+      end
+    end
+
+    def percent_encode(str)
+      str.b.unpack("C*").map { |b|
+        # Allow only the RFC 2231 attribute-char set; percent-encode everything else.
+        if (b >= 0x30 && b <= 0x39) || (b >= 0x41 && b <= 0x5A) || (b >= 0x61 && b <= 0x7A) || [ 0x2D, 0x2E, 0x5F, 0x7E ].include?(b)
+          b.chr
+        else
+          format("%%%02X", b)
+        end
+      }.join
+    end
+
+    def base64_wrapped(body)
+      str = body.to_s.dup.force_encoding(Encoding::UTF_8)
+      Base64.encode64(str).gsub("\n", CRLF)
+    end
+
+    def base64_normalize(b64)
+      stripped = b64.to_s.delete("\r\n ")
+      stripped.scan(/.{1,76}/).join(CRLF)
+    end
+  end
+end

data/app/connectors/gmail/mime_parser.rb

@@ -0,0 +1,106 @@
+require "base64"
+
+module Gmail
+  # Parses Google's `messages.get?format=full` payload tree into a clean,
+  # downstream-friendly shape. Mirrors the work `parseRawEmail` does in
+  # n8n's `Gmail/GenericFunctions.ts` (which delegates to mailparser).
+  #
+  # Google returns:
+  #   { payload: {
+  #       headers: [{name, value}, ...],
+  #       mimeType: "...",
+  #       body: { data: <base64url>, attachmentId: ... },
+  #       parts: [ recursive parts ... ]
+  #     } }
+  #
+  # We flatten that into:
+  #   { from:, to:, cc:, bcc:, reply_to:, subject:, date:,
+  #     headers: { ... lowercased keys ... },
+  #     text:, html:, attachments: [{filename, content_type, size, attachment_id}, ...] }
+  class MimeParser
+    HEADERS_TO_LIFT = %w[from to cc bcc reply-to subject date].freeze
+
+    def self.parse(payload)
+      new(payload).parse
+    end
+
+    def initialize(payload)
+      @payload = payload || {}
+    end
+
+    def parse
+      headers = headers_hash(@payload["headers"])
+
+      result = {
+        "headers" => headers,
+        "subject" => headers["subject"],
+        "from"    => headers["from"],
+        "to"      => split_list(headers["to"]),
+        "cc"      => split_list(headers["cc"]),
+        "bcc"     => split_list(headers["bcc"]),
+        "reply_to" => split_list(headers["reply-to"]),
+        "date"    => headers["date"],
+        "text"    => nil,
+        "html"    => nil,
+        "attachments" => []
+      }
+
+      walk(@payload, result)
+      result.compact
+    end
+
+    private
+
+    def walk(part, result)
+      mime_type = part["mimeType"].to_s
+      filename  = part["filename"].to_s
+      body      = part["body"] || {}
+
+      if filename.empty?
+        case mime_type
+        when "text/plain"
+          result["text"] ||= decode_body_data(body["data"])
+        when "text/html"
+          result["html"] ||= decode_body_data(body["data"])
+        end
+      elsif body["attachmentId"]
+        result["attachments"] << {
+          "filename"      => filename,
+          "content_type"  => mime_type,
+          "size"          => body["size"],
+          "attachment_id" => body["attachmentId"]
+        }
+      elsif body["data"]
+        # Inline attachment with body data already present.
+        result["attachments"] << {
+          "filename"      => filename,
+          "content_type"  => mime_type,
+          "size"          => body["size"],
+          "content"       => body["data"]
+        }
+      end
+
+      Array(part["parts"]).each { |child| walk(child, result) }
+    end
+
+    def headers_hash(arr)
+      Array(arr).each_with_object({}) do |h, acc|
+        next unless h.is_a?(Hash) && h["name"]
+        acc[h["name"].downcase] = h["value"]
+      end
+    end
+
+    def split_list(value)
+      return nil if value.nil?
+      value.to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+
+    def decode_body_data(b64)
+      return nil if b64.to_s.empty?
+      padded = b64 + "=" * ((4 - b64.length % 4) % 4)
+      Base64.urlsafe_decode64(padded)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/app/connectors/gmail/polling.rb

@@ -0,0 +1,154 @@
+module Gmail
+  # Polling trigger logic. Invoked once per scheduler tick by
+  # `Connectors::PollRunner.run(grant)`, which threads in the per-grant
+  # scratch hash stored at `grant.static_data["polling"]`.
+  #
+  # n8n parity: `packages/nodes-base/nodes/Google/Gmail/GmailTrigger.node.ts`.
+  # Key invariants we copy 1:1:
+  #
+  #   * Cursor = `last_checked_at` (unix seconds). First-ever poll bootstraps
+  #     the cursor to `now` and emits nothing.
+  #   * Query: `after:<last_checked_at> -in:scheduled` plus any author-
+  #     supplied filters. Gmail's `after:` is INCLUSIVE at the second
+  #     boundary, so we maintain `possible_duplicates` — ids emitted at
+  #     exactly the cursor second — and exclude them from the next list.
+  #   * For each new id, fetch full message via Api.request, run through
+  #     MimeParser, return the parsed envelope.
+  #   * Drafts (`labelIds includes DRAFT`) skipped unless `include_drafts`.
+  #   * Sent-but-not-Inbox messages skipped (Gmail emits them as both
+  #     SENT and INBOX when the user is the recipient; we want the inbound
+  #     copy, not the outbound).
+  #
+  # Filters are passed via `grant.static_data["polling"]["filters"]` so the
+  # workflow author can configure them per-trigger when the automations
+  # engine hooks this up:
+  #
+  #   {
+  #     "q"               => "from:boss has:attachment",  # raw Gmail search
+  #     "label_ids"       => ["INBOX", "Label_42"],
+  #     "sender"          => "alerts@stripe.com",
+  #     "read_status"     => "unread",                     # unread | read | both
+  #     "include_spam_trash" => false,
+  #     "include_drafts"  => false,
+  #     "max_results"     => 25                            # per poll
+  #   }
+  class Polling
+    DEFAULT_MAX_RESULTS = 25
+
+    def initialize(grant, static_data, now: nil)
+      @grant       = grant
+      @sd          = static_data
+      @now         = now || Time.now.to_i
+      @connector   = grant.connector
+      @client      = @connector.client
+      @filters     = (static_data["filters"] || {}).transform_keys(&:to_s)
+      @max_results = (@filters["max_results"] || DEFAULT_MAX_RESULTS).to_i
+    end
+
+    def run
+      first_run = @sd["last_checked_at"].nil?
+
+      if first_run
+        @sd["last_checked_at"]      = @now
+        @sd["possible_duplicates"]  = []
+        return []
+      end
+
+      list_body = Api.request(
+        @client, :get, "users/me/messages",
+        query: build_query,
+        resource: "message"
+      )
+
+      ids = Array(list_body["messages"]).map { |m| m["id"] }
+      duplicates = Array(@sd["possible_duplicates"])
+      ids -= duplicates
+      return [] if ids.empty?
+
+      messages = []
+      max_internal_date = 0
+
+      ids.first(@max_results).each do |id|
+        full = Api.request(@client, :get, "users/me/messages/#{id}",
+                            query: { format: "full" }, resource: "message")
+        next if skip?(full)
+
+        envelope = MimeParser.parse(full["payload"]) if full["payload"]
+        internal_date = full["internalDate"].to_i / 1000   # Gmail uses ms
+
+        messages << {
+          "id"            => full["id"],
+          "thread_id"     => full["threadId"],
+          "label_ids"     => full["labelIds"],
+          "snippet"       => full["snippet"],
+          "envelope"      => envelope,
+          "internal_date" => internal_date
+        }.compact
+
+        max_internal_date = internal_date if internal_date > max_internal_date
+      end
+
+      advance_cursor(messages, max_internal_date)
+      messages
+    end
+
+    private
+
+    # Gmail search syntax. n8n's prepareQuery is the reference; the order
+    # of clauses doesn't matter to Gmail, but keep the same join scheme so
+    # diffs against n8n are easy to read.
+    def build_query
+      qs = {}
+      qs["labelIds[]"]      = Array(@filters["label_ids"]) if @filters["label_ids"]
+      qs[:maxResults]       = @max_results
+      qs[:includeSpamTrash] = true if @filters["include_spam_trash"]
+
+      q_parts = []
+      q_parts << @filters["q"] if @filters["q"].to_s.length.positive?
+      q_parts << "from:#{@filters['sender']}" if @filters["sender"].to_s.length.positive?
+
+      status = @filters["read_status"].to_s
+      q_parts << "is:#{status}" if status == "unread" || status == "read"
+
+      # Boundary-inclusive `after:` — same behavior n8n leans on; we
+      # de-dupe via possible_duplicates rather than narrowing the window.
+      q_parts << "after:#{@sd['last_checked_at']}"
+
+      # `-in:scheduled` matches n8n's v1.4+ guard (scheduled-send drafts
+      # appear in users.messages.list but aren't real inbound mail yet).
+      q_parts << "-in:scheduled"
+
+      qs[:q] = q_parts.join(" ")
+      qs
+    end
+
+    def skip?(message)
+      label_ids = Array(message["labelIds"])
+      return true if label_ids.include?("DRAFT") && !@filters["include_drafts"]
+      return true if label_ids.include?("SENT") && !label_ids.include?("INBOX")
+      false
+    end
+
+    # Advance `last_checked_at` to the newest message we just emitted,
+    # and capture the ids at that boundary for next-poll deduplication.
+    def advance_cursor(messages, max_internal_date)
+      return if messages.empty?
+
+      previous_cursor = @sd["last_checked_at"].to_i
+      next_cursor     = [ max_internal_date, previous_cursor ].max
+
+      ids_at_boundary = messages.select { |m| m["internal_date"] == next_cursor }
+                                 .map { |m| m["id"] }
+
+      if next_cursor == previous_cursor
+        # Cursor didn't move — same second as last time. Append new ids
+        # to the existing dedupe set rather than replacing it.
+        existing = Array(@sd["possible_duplicates"])
+        @sd["possible_duplicates"] = (existing + ids_at_boundary).uniq
+      else
+        @sd["last_checked_at"]     = next_cursor
+        @sd["possible_duplicates"] = ids_at_boundary
+      end
+    end
+  end
+end

data/app/connectors/remote_mcp/connector.rb

@@ -0,0 +1,18 @@
+module RemoteMcp
+  class Connector < Connectors::Connector
+    connector key: :mcp, auth: :api_key, base_url: nil, display_name: "MCP server",
+      documentation_url: "https://modelcontextprotocol.io/specification/2026-07-28"
+
+    mcp
+
+    credentials do
+      field :server_url, type: "string", required: true, display_name: "Server URL"
+      field :auth_mode, type: "options", required: true, default: "none", display_name: "Authentication mode",
+        options: [ { name: "Public server", value: "none" }, { name: "Bearer token", value: "bearer" }, { name: "Custom headers", value: "headers" }, { name: "OAuth", value: "oauth" } ]
+      field :bearer_token, type: "string", secret: true, display_name: "Bearer token", display_options: { show: { auth_mode: [ "bearer" ] } }
+      field :headers, type: "json", secret: true, display_name: "Custom headers", display_options: { show: { auth_mode: [ "headers" ] } }
+      field :client_information, type: "json", secret: true, display_name: "Pre-registered OAuth client (optional)", display_options: { show: { auth_mode: [ "oauth" ] } }
+      field :authorization_server, type: "string", display_name: "Authorization server (optional)", display_options: { show: { auth_mode: [ "oauth" ] } }
+    end
+  end
+end