connector-ruby 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c22469b3849b241124a069729e5b127cb3459d4f9f55458a79b089fc3f33a28
-  data.tar.gz: 66fbf3cb744d58622775bed0a17840f6635984e9fc6a488ea507da5b2f5fbd6c
+  metadata.gz: 1de5c96a15261fbdc6a099b482fff88814b390a1d268e36b3fd0d1c50e518fb4
+  data.tar.gz: a78552343670e2581bfbb91dee27832f15afe8e5643a41edf26b04fa3ba26c8a
 SHA512:
-  metadata.gz: fef0557ed46edaf27e1c50b2e28e0cde341c8343fe394b96c51d3a46e17c1b62ccd2fbc88974abd41c3b59bf37f4b20349d2cd794ede451c7074107ebdd81824
-  data.tar.gz: 706e414863cc4f8d556166a6fd60d2a092593ded6bea22c6617768148e2c596e2121bbf6f934df5170680eeaf40d5421805db07348099a854de5466afd841d0e
+  metadata.gz: a148220f6acd6dc59d030e43eb7ff52de63d99d377f21b799d00af7c1f416c57633618392cdc418f12d427d4811846c9efc0d06bb36215e5d5dca54595ad08cd
+  data.tar.gz: f508ead3c9681cd3f5787a7835cf33280c7534cf7f0d194bae36912f9ec421df831d0daa57556c95272ad912817924799a9ccf83cb9eed97bddc4ead1bf54b19

data/CHANGELOG.md

@@ -1,11 +1,63 @@
 # Changelog
 
-## 0.1.0 (2026-03-09)
-
-- Initial release
-- WhatsApp Cloud API support (send text, buttons, image; parse webhooks)
-- Telegram Bot API support (send text, buttons, image; parse webhooks)
-- Unified Event model for normalized inbound messages
-- Webhook signature verification (WhatsApp HMAC-SHA256)
-- HTTP client with retry and timeout support
-- Configuration DSL
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-04-11
+
+Reshape release — the original v0.3.0 Rails-integration plan was redistributed
+to v0.4.0 (Rails integration) and v0.5.0 (channel expansion + advanced features)
+to unblock the downstream omnibot Phase 2.4 channel rollout, which needed
+webhook verification for all shipped channels plus a LiveChat transport.
+
+### Added
+- `WebhookVerifier.verify_messenger(payload, signature:, app_secret:)` — HMAC-SHA256 signature verification for Meta Messenger webhooks (`X-Hub-Signature-256` header).
+- `WebhookVerifier.verify_line(payload, signature:, channel_secret:)` — Base64 HMAC-SHA256 signature verification for LINE Messaging API webhooks (`X-Line-Signature` header), with case-sensitive comparison.
+- `WebhookVerifier.verify_slack(payload, timestamp:, signature:, signing_secret:, tolerance: 300)` — Slack v0 signature verification with replay protection. Rejects requests whose `X-Slack-Request-Timestamp` is outside the tolerance window (default 5 minutes).
+- `WebhookVerifier.verify_livechat(payload, expected_secret:)` — shared-secret verification for LiveChat webhooks. LiveChat does not use HMAC; it embeds a `secret_key` field in the webhook body.
+- `Channels::LiveChat` — minimal LiveChat (livechatinc.com / text.com) Agent API support: `send_text` + `parse_webhook`. Basic auth with a PAT (`base64(account_id:region:pat_value)`) and optional `X-Region` header.
+- `Configuration#livechat_pat` and `Configuration#livechat_region`.
+- `WebhookVerifier.secure_compare` now accepts `case_sensitive:` keyword (default `false` for hex signatures; pass `true` for Base64 or shared-secret comparisons).
+- Runtime dependency on the `base64` gem so `verify_line` works on Ruby 3.4+ (where `base64` was removed from default gems).
+
+### Changed
+- README rewritten to cover all 6 channels with per-channel webhook verification examples.
+
+### Notes
+- Rails integration work (Railtie, mountable WebhookController, install generator, ActiveJob integration, omnibot helper) has been moved to milestone v0.4.0.
+- Instagram, Discord, Email, conversation state, multi-tenancy, outbox pattern, signature rotation, and rich message adapters have been moved to milestone v0.5.0.
+
+## [0.2.0] - 2026-03-17
+
+### Added
+- **Channels:** Facebook Messenger (`Channels::Messenger`), LINE Messaging API (`Channels::Line`), Slack Web API (`Channels::Slack`). Each supports `send_text`, `send_buttons`, `send_image`, and `parse_webhook`, plus channel-specific rich types (Messenger quick replies, LINE flex, Slack blocks).
+- **WhatsApp rich message types:** templates, documents, location, contacts, reactions, interactive lists.
+- **Message builder DSL:** fluent API for constructing outbound messages.
+- **Batch sending:** `BatchSender` with rate limiting.
+- **Delivery tracking:** correlate sent message IDs with status webhooks.
+- **Typing indicators** and `mark_as_read` where the platform supports them.
+
+## [0.1.1] - 2026-03-09
+
+### Fixed
+- Telegram webhook verification now enforces the `X-Telegram-Bot-Api-Secret-Token` header set via `setWebhook`.
+- `parse_webhook` no longer crashes on malformed payloads with missing nested keys; nil guards throughout.
+- WhatsApp signature comparison handles differing byte lengths gracefully.
+- HTTP retry now applies exponential backoff for 429 responses (previously `RateLimitError` was raised but never retried).
+
+### Added
+- Input validation: reject empty `to`/`chat_id`, enforce WhatsApp/Telegram 4096-char text limits.
+- Phone number normalization for WhatsApp (strip spaces, enforce `+` prefix).
+- Raw response access on `ApiError` (`error.response`).
+- Logging hooks: `on_request`, `on_response`, `on_error` callbacks in `Configuration`.
+
+## [0.1.0] - 2026-03-09
+
+- Initial release.
+- WhatsApp Cloud API support (send text, buttons, image; parse webhooks).
+- Telegram Bot API support (send text, buttons, image; parse webhooks).
+- Unified `Event` model for normalized inbound messages.
+- Webhook signature verification (WhatsApp HMAC-SHA256).
+- HTTP client with retry and timeout support.
+- Configuration DSL.

data/README.md

@@ -1,59 +1,188 @@
 # connector-ruby
 
-Unified channel messaging SDK for Ruby. Framework-agnostic SDK for sending/receiving messages across chat platforms.
+Unified channel messaging SDK for Ruby. Send and receive messages across **WhatsApp, Telegram, Facebook Messenger, LINE, Slack, and LiveChat** with a consistent API, normalized webhook events, and first-class signature verification for every channel.
 
 ## Installation
 
 ```ruby
-gem "connector-ruby", "~> 0.1"
+gem "connector-ruby", "~> 0.3"
 ```
 
-## Supported Channels
+```ruby
+require "connector_ruby"
+```
 
-- WhatsApp Cloud API
-- Telegram Bot API
+## Channel support
 
-## Usage
+| Channel | Send text | Send buttons | Send image | Rich messages | Parse webhook | Verify webhook |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| WhatsApp   | ✅ | ✅ | ✅ | templates, documents, location, contacts, reactions, lists | ✅ | ✅ |
+| Telegram   | ✅ | ✅ | ✅ | documents, location | ✅ | ✅ |
+| Messenger  | ✅ | ✅ | ✅ | quick replies | ✅ | ✅ |
+| LINE       | ✅ | ✅ | ✅ | flex messages | ✅ | ✅ |
+| Slack      | ✅ | ✅ | ✅ | blocks | ✅ | ✅ |
+| LiveChat   | ✅ | — | — | *(minimal in v0.3.0)* | ✅ | ✅ |
 
-### WhatsApp
+## Quickstart
 
 ```ruby
-client = ConnectorRuby::WhatsApp.new(
-  phone_number_id: "...",
-  access_token: "..."
+# WhatsApp Cloud API
+wa = ConnectorRuby::WhatsApp.new(
+  access_token: ENV["WHATSAPP_TOKEN"],
+  phone_number_id: ENV["WHATSAPP_PHONE_ID"]
 )
+wa.send_text(to: "+6281234567890", text: "Hello!")
+
+# Telegram Bot API
+tg = ConnectorRuby::Telegram.new(bot_token: ENV["TELEGRAM_BOT_TOKEN"])
+tg.send_text(to: "chat_id", text: "Hello!")
+
+# Facebook Messenger
+fb = ConnectorRuby::Messenger.new(page_access_token: ENV["MESSENGER_PAGE_TOKEN"])
+fb.send_text(to: "psid", text: "Hello!")
+
+# LINE Messaging API
+line = ConnectorRuby::Line.new(channel_access_token: ENV["LINE_CHANNEL_TOKEN"])
+line.send_text(to: "user_id", text: "Hello!")
+
+# Slack Web API
+slack = ConnectorRuby::Slack.new(bot_token: ENV["SLACK_BOT_TOKEN"])
+slack.send_text(channel: "C0123456", text: "Hello!")
+
+# LiveChat Agent API (Basic auth with a PAT)
+lc = ConnectorRuby::LiveChat.new(
+  pat: ENV["LIVECHAT_PAT"],       # base64(account_id:region:pat_value)
+  region: ENV["LIVECHAT_REGION"]  # e.g. "dal" — extracted from the PAT
+)
+lc.send_text(to: "CHAT_abc123", text: "Hello!")
+```
 
-client.send_text(to: "+62812...", text: "Hello!")
-client.send_buttons(to: "+62812...", body: "Choose:", buttons: [
-  { id: "opt1", title: "Option 1" },
-  { id: "opt2", title: "Option 2" }
-])
-client.send_image(to: "+62812...", url: "https://...")
+## Global configuration
 
-event = ConnectorRuby::WhatsApp.parse_webhook(request_body)
+Configure credentials once and every channel picks them up automatically:
+
+```ruby
+ConnectorRuby.configure do |c|
+  c.whatsapp_phone_number_id      = ENV["WHATSAPP_PHONE_ID"]
+  c.whatsapp_access_token         = ENV["WHATSAPP_TOKEN"]
+  c.telegram_bot_token            = ENV["TELEGRAM_BOT_TOKEN"]
+  c.messenger_page_access_token   = ENV["MESSENGER_PAGE_TOKEN"]
+  c.line_channel_access_token     = ENV["LINE_CHANNEL_TOKEN"]
+  c.slack_bot_token               = ENV["SLACK_BOT_TOKEN"]
+  c.livechat_pat                  = ENV["LIVECHAT_PAT"]
+  c.livechat_region               = ENV["LIVECHAT_REGION"]
+
+  # HTTP client
+  c.http_timeout      = 30
+  c.http_retries      = 3
+  c.http_open_timeout = 10
+
+  # Instrumentation callbacks
+  c.on_request  = ->(method:, url:, headers:, body:) { Rails.logger.info("[connector] → #{method} #{url}") }
+  c.on_response = ->(status:, body:)                  { Rails.logger.info("[connector] ← #{status}") }
+  c.on_error    = ->(error:)                          { Sentry.capture_exception(error) }
+end
 ```
 
-### Telegram
+## Parsing inbound webhooks
+
+Every channel exposes a `parse_webhook` class method that returns a normalized `ConnectorRuby::Event`:
+
+```ruby
+event = ConnectorRuby::WhatsApp.parse_webhook(request.raw_post)
+# => #<ConnectorRuby::Event type=:message channel=:whatsapp from="+6281..." text="Hi">
+
+event.message?            # => true
+event.text                # => "Hi"
+event.from                # => "+6281234567890"
+event.channel             # => :whatsapp
+event.metadata            # => channel-specific extras
+```
+
+Same shape for `Telegram`, `Messenger`, `Line`, `Slack`, `LiveChat`.
+
+## Webhook verification
+
+Each channel has its own verification contract. `WebhookVerifier` has a dedicated method per provider — don't hand-roll HMACs in your controllers.
 
 ```ruby
-client = ConnectorRuby::Telegram.new(bot_token: "...")
+# WhatsApp — X-Hub-Signature-256: sha256=<hex>
+ConnectorRuby::WebhookVerifier.verify_whatsapp(
+  request.raw_post,
+  signature: request.headers["X-Hub-Signature-256"],
+  app_secret: ENV["WHATSAPP_APP_SECRET"]
+)
+
+# Telegram — X-Telegram-Bot-Api-Secret-Token (configured via setWebhook)
+ConnectorRuby::WebhookVerifier.verify_telegram(
+  token: ENV["TELEGRAM_BOT_TOKEN"],
+  payload: request.raw_post,
+  secret_token: ENV["TELEGRAM_WEBHOOK_SECRET"],
+  header_value: request.headers["X-Telegram-Bot-Api-Secret-Token"]
+)
+
+# Messenger — X-Hub-Signature-256: sha256=<hex>
+ConnectorRuby::WebhookVerifier.verify_messenger(
+  request.raw_post,
+  signature: request.headers["X-Hub-Signature-256"],
+  app_secret: ENV["FB_APP_SECRET"]
+)
+
+# LINE — X-Line-Signature: <base64 HMAC-SHA256>
+ConnectorRuby::WebhookVerifier.verify_line(
+  request.raw_post,
+  signature: request.headers["X-Line-Signature"],
+  channel_secret: ENV["LINE_CHANNEL_SECRET"]
+)
+
+# Slack — X-Slack-Signature + X-Slack-Request-Timestamp (with replay protection)
+ConnectorRuby::WebhookVerifier.verify_slack(
+  request.raw_post,
+  timestamp: request.headers["X-Slack-Request-Timestamp"],
+  signature: request.headers["X-Slack-Signature"],
+  signing_secret: ENV["SLACK_SIGNING_SECRET"]
+  # tolerance: 300  # default; override if your clock skew demands it
+)
 
-client.send_text(chat_id: 12345, text: "Hello!")
-event = ConnectorRuby::Telegram.parse_webhook(request_body)
+# LiveChat — shared secret_key embedded IN the JSON body (no header, no HMAC)
+ConnectorRuby::WebhookVerifier.verify_livechat(
+  request.raw_post,
+  expected_secret: ENV["LIVECHAT_WEBHOOK_SECRET"]
+)
 ```
 
-### Configuration
+All verifiers return `true`/`false` and use a constant-time comparison internally. Slack verification additionally rejects timestamps outside a 5-minute tolerance window (configurable via `tolerance:`) to prevent replay attacks.
+
+> **Why LiveChat is different:** LiveChat does not sign webhooks with HMAC. Every webhook body contains a `secret_key` field, and verification is a constant-time compare between that field and the shared secret configured in your LiveChat webhook settings. See `WebhookVerifier.verify_livechat` for the production-tested implementation.
+
+## Additional features (v0.2.0)
+
+- **Message builder DSL** — fluent API: `ConnectorRuby::Message.to("+62...").text("Hi").buttons([...]).send_via(wa)`
+- **Batch sending** — `BatchSender` with rate limiting for bulk outbound
+- **Delivery tracking** — correlate sent message IDs with status webhooks
+- **Rich WhatsApp types** — templates, documents, location, contacts, reactions, interactive lists
+- **Typing indicators** — `send_typing` / `mark_as_read` where supported
+
+## Error handling
+
+All API failures raise `ConnectorRuby::ApiError` (or its subclasses `AuthenticationError`, `RateLimitError`). Rate limits are automatically retried with exponential backoff; after `http_retries` attempts the error propagates so you can observe and alert.
 
 ```ruby
-ConnectorRuby.configure do |config|
-  config.whatsapp_phone_number_id = ENV["WA_PHONE_ID"]
-  config.whatsapp_access_token = ENV["WA_TOKEN"]
-  config.telegram_bot_token = ENV["TG_TOKEN"]
-  config.http_timeout = 30
-  config.http_retries = 3
+begin
+  wa.send_text(to: "+6281...", text: "Hi")
+rescue ConnectorRuby::AuthenticationError => e
+  # 401 — bad token
+rescue ConnectorRuby::RateLimitError => e
+  # 429 after retries exhausted
+rescue ConnectorRuby::ApiError => e
+  # other 4xx/5xx; inspect e.status, e.body, e.response
 end
 ```
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## License
 
 MIT

data/connector-ruby.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.authors = ["Johannes Dwi Cahyo"]
   spec.email = ["johannes@example.com"]
   spec.summary = "Unified channel messaging SDK for Ruby"
-  spec.description = "Framework-agnostic SDK for sending/receiving messages across chat platforms. Supports WhatsApp Cloud API, Telegram Bot API, and more."
+  spec.description = "Framework-agnostic SDK for sending/receiving messages across chat platforms. Supports WhatsApp Cloud API, Telegram Bot API, Facebook Messenger, LINE Messaging API, Slack Web API, and LiveChat Agent API."
   spec.homepage = "https://github.com/johannesdwicahyo/connector-ruby"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.0.0"
@@ -27,6 +27,10 @@ Gem::Specification.new do |spec|
   ]
   spec.require_paths = ["lib"]
 
+  # base64 was removed from Ruby's default gems in 3.4; add as a runtime
+  # dependency so verify_line can Base64-encode HMAC digests on any Ruby.
+  spec.add_dependency "base64", "~> 0.2"
+
   spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "webmock", "~> 3.0"

data/lib/connector_ruby/batch_sender.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ConnectorRuby
+  class BatchSender
+    RATE_LIMITS = {
+      whatsapp: { messages_per_second: 80 },
+      telegram: { messages_per_second: 30 },
+      messenger: { messages_per_second: 200 },
+      line: { messages_per_second: 100 },
+      slack: { messages_per_second: 1 }
+    }.freeze
+
+    def initialize(channel:)
+      @channel = channel
+      @results = []
+      @errors = []
+    end
+
+    def send_batch(messages)
+      rate = rate_limit_for(@channel)
+      delay = 1.0 / rate
+
+      messages.each_with_index do |msg, i|
+        sleep(delay) if i > 0
+        begin
+          result = yield msg
+          @results << { index: i, status: :sent, result: result }
+        rescue => e
+          @errors << { index: i, status: :failed, error: e.message }
+        end
+      end
+
+      { sent: @results, failed: @errors, total: messages.size }
+    end
+
+    private
+
+    def rate_limit_for(channel)
+      channel_sym = channel.class.name.split("::").last.downcase.to_sym
+      config = RATE_LIMITS[channel_sym] || { messages_per_second: 10 }
+      config[:messages_per_second]
+    end
+  end
+end

data/lib/connector_ruby/channels/line.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module ConnectorRuby
+  module Channels
+    class Line < Base
+      BASE_URL = "https://api.line.me/v2/bot/message"
+
+      def initialize(channel_access_token: nil)
+        @channel_access_token = channel_access_token || ConnectorRuby.configuration.line_channel_access_token
+        raise ConfigurationError, "LINE channel_access_token is required" unless @channel_access_token
+      end
+
+      def send_text(to:, text:)
+        validate_send!(to: to, text: text)
+        push_message(to, [{ type: "text", text: text }])
+      end
+
+      def send_buttons(to:, text:, buttons:)
+        validate_send!(to: to, text: text)
+        actions = buttons.map do |btn|
+          { type: "postback", label: btn[:title], data: btn[:id] }
+        end
+
+        template = {
+          type: "template",
+          altText: text,
+          template: {
+            type: "buttons",
+            text: text,
+            actions: actions
+          }
+        }
+        push_message(to, [template])
+      end
+
+      def send_image(to:, url:, caption: nil)
+        validate_send!(to: to)
+        messages = [{ type: "image", originalContentUrl: url, previewImageUrl: url }]
+        messages << { type: "text", text: caption } if caption
+        push_message(to, messages)
+      end
+
+      def send_flex(to:, alt_text:, contents:)
+        validate_send!(to: to)
+        flex = {
+          type: "flex",
+          altText: alt_text,
+          contents: contents
+        }
+        push_message(to, [flex])
+      end
+
+      def self.parse_webhook(body)
+        data = body.is_a?(String) ? JSON.parse(body) : body
+
+        events = data["events"]
+        return nil unless events&.any?
+
+        event_data = events[0]
+        case event_data["type"]
+        when "message"
+          parse_message(event_data)
+        when "postback"
+          parse_postback(event_data)
+        end
+      end
+
+      private
+
+      def push_message(to, messages)
+        payload = { to: to, messages: messages }
+        http_client.post("#{BASE_URL}/push", body: payload, headers: auth_headers)
+      end
+
+      def auth_headers
+        { "Authorization" => "Bearer #{@channel_access_token}" }
+      end
+
+      def validate_send!(to:, text: nil)
+        raise ConnectorRuby::Error, "Recipient 'to' cannot be nil or empty" if to.nil? || to.to_s.strip.empty?
+        if text
+          raise ConnectorRuby::Error, "Text cannot be nil or empty" if text.nil? || text.to_s.strip.empty?
+          raise ConnectorRuby::Error, "Text exceeds 5000 character limit" if text.length > 5000
+        end
+      end
+
+      def self.parse_message(event_data)
+        msg = event_data["message"]
+        Event.new(
+          type: :message,
+          channel: :line,
+          from: event_data.dig("source", "userId"),
+          text: msg["text"],
+          timestamp: event_data["timestamp"] ? Time.at(event_data["timestamp"].to_i / 1000) : nil,
+          message_id: msg["id"],
+          metadata: {
+            reply_token: event_data["replyToken"],
+            source_type: event_data.dig("source", "type"),
+            message_type: msg["type"]
+          }
+        )
+      end
+
+      def self.parse_postback(event_data)
+        Event.new(
+          type: :callback,
+          channel: :line,
+          from: event_data.dig("source", "userId"),
+          text: event_data.dig("postback", "data"),
+          timestamp: event_data["timestamp"] ? Time.at(event_data["timestamp"].to_i / 1000) : nil,
+          metadata: {
+            reply_token: event_data["replyToken"],
+            source_type: event_data.dig("source", "type")
+          }
+        )
+      end
+    end
+  end
+end

data/lib/connector_ruby/channels/livechat.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "time"
+
+module ConnectorRuby
+  module Channels
+    # LiveChat (livechatinc.com / text.com) Agent API channel.
+    #
+    # Minimal v0.3.0 surface: send_text + parse_webhook. Buttons, images,
+    # and rich events are intentionally deferred to a later release.
+    #
+    # Authentication uses a Personal Access Token (PAT) with Basic auth.
+    # The PAT is typically stored as `base64(account_id:region:pat_value)`,
+    # and an `X-Region` header should be sent alongside it. Pass the
+    # pre-encoded PAT as `pat:` and the region string as `region:`.
+    #
+    # Webhook verification is handled separately by
+    # `ConnectorRuby::WebhookVerifier.verify_livechat`, because LiveChat
+    # authenticates webhooks via a `secret_key` field in the JSON body
+    # rather than via HMAC signatures.
+    class LiveChat < Base
+      BASE_URL = "https://api.livechatinc.com/v3.5/agent/action"
+
+      def initialize(pat: nil, region: nil)
+        @pat = pat || ConnectorRuby.configuration.livechat_pat
+        @region = region || ConnectorRuby.configuration.livechat_region
+        raise ConfigurationError, "LiveChat pat is required" unless @pat
+      end
+
+      def send_text(to:, text:)
+        validate_send!(to: to, text: text)
+        payload = {
+          chat_id: to,
+          event: { type: "message", text: text }
+        }
+        http_client.post("#{BASE_URL}/send_event", body: payload, headers: auth_headers)
+      end
+
+      def self.parse_webhook(body)
+        data = body.is_a?(String) ? JSON.parse(body) : body
+        return nil unless data.is_a?(Hash)
+        return nil unless data["action"] == "incoming_event"
+
+        payload = data["payload"]
+        return nil unless payload.is_a?(Hash)
+
+        event = payload["event"]
+        return nil unless event.is_a?(Hash) && event["type"] == "message"
+
+        Event.new(
+          type: :message,
+          channel: :livechat,
+          from: event["author_id"],
+          text: event["text"],
+          timestamp: parse_timestamp(event["created_at"]),
+          message_id: event["id"],
+          metadata: {
+            chat_id: payload["chat_id"],
+            thread_id: payload["thread_id"],
+            organization_id: data["organization_id"]
+          }
+        )
+      rescue JSON::ParserError
+        nil
+      end
+
+      def self.parse_timestamp(value)
+        return nil unless value
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      private
+
+      def auth_headers
+        headers = { "Authorization" => "Basic #{@pat}" }
+        headers["X-Region"] = @region if @region
+        headers
+      end
+
+      def validate_send!(to:, text:)
+        raise ConnectorRuby::Error, "Recipient 'to' cannot be nil or empty" if to.nil? || to.to_s.strip.empty?
+        raise ConnectorRuby::Error, "Text cannot be nil or empty" if text.nil? || text.to_s.strip.empty?
+      end
+    end
+  end
+end