open-wire 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b4a78b6f4bcdacc5ec15ad927dda0bcb677f6ae4eb0d64e51a43579dc4a6f0a
+  data.tar.gz: 7bca3016d72a127a1ed9ea26b228b797d1e2aa6b024f8c6b40f8f694f93cd78a
+SHA512:
+  metadata.gz: 79296d68c11e232cc4aa22054b6687cd8b9b8f85e0793c49c98f2d5c9ece0b4ce31c1c9bf25b3baa473e5726d4646452ed25f06ee8026813b7feafebcdd941e6
+  data.tar.gz: 2dd4177c8c722ab33e5f759d55d74577d97cfb70b362bb2033c005b6cb27c547c7265d5ff81b351d0ecb4ea1d5f3715a21f53c74285616684669383f4206eeff

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tiny Bubble Company
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,42 @@
+# Open-Wire Ruby gem (`open-wire`)
+
+Protocol client and webhook helpers for [open-wire/1](https://openwire.rails-agent.com/docs/protocol).
+
+## Install
+
+```ruby
+# Gemfile
+gem "open-wire", "~> 0.1"
+```
+
+```bash
+gem install open-wire
+```
+
+## Send
+
+```ruby
+client = OpenWire::Client.new(
+  base_url: "https://openwire.rails-agent.com",
+  api_key: ENV["OPEN_WIRE_API_KEY"]
+)
+
+client.send_message(
+  installation_id: "inst_…",
+  to: { id: "C123", kind: "channel" },
+  text: "Hello from Rails",
+  thread_id: "C123:1710000000.000100"
+)
+```
+
+## Inbound webhook
+
+```ruby
+message = OpenWire::Webhook.verify_and_parse!(
+  secret: ENV["OPEN_WIRE_WEBHOOK_SECRET"],
+  body: request.raw_post,
+  headers: request.headers
+)
+```
+
+See [protocol docs](https://openwire.rails-agent.com/docs/protocol) for the full envelope shape.

data/lib/open-wire.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# open-wire Ruby SDK — protocol client + webhook helpers.
+# Used by rails-agent-stack as a channel adapter; publishable on RubyGems later.
+
+require "open_wire"

data/lib/open_wire/client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module OpenWire
+  # HTTP client for the Open-Wire gateway (outbound message.send).
+  class Client
+    def initialize(base_url: nil, api_key: nil)
+      @base_url = (base_url || OpenWire.configuration.base_url).to_s.sub(%r{/+\z}, "")
+      @api_key = api_key || OpenWire.configuration.api_key
+      raise ConfigurationError, "OPEN_WIRE_API_KEY / api_key is required" if @api_key.to_s.empty?
+    end
+
+    # Send a message through an installation.
+    #
+    #   client.send_message(
+    #     installation_id: "inst_…",
+    #     to: { id: "C123", kind: "channel" },
+    #     text: "Hello",
+    #     thread_id: "C123:1710000000.000100"
+    #   )
+    def send_message(installation_id:, to:, text: nil, body: nil, thread_id: nil, blocks: nil)
+      payload_body = body || {}
+      payload_body = payload_body.merge("text" => text) if text
+      payload_body = payload_body.merge("blocks" => blocks) if blocks
+
+      envelope = {
+        "protocol" => OpenWire::PROTOCOL,
+        "type" => "message.send",
+        "installation_id" => installation_id,
+        "to" => stringify_keys(to),
+        "body" => stringify_keys(payload_body)
+      }
+      if thread_id
+        envelope["thread"] = { "id" => thread_id }
+      end
+
+      request_json(:post, "/api/v1/messages", envelope)
+    end
+
+    def health
+      uri = URI("#{@base_url}/api/v1/health")
+      res = Net::HTTP.get_response(uri)
+      JSON.parse(res.body)
+    end
+
+    private
+
+    def request_json(method, path, body = nil)
+      uri = URI("#{@base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = OpenWire.configuration.open_timeout
+      http.read_timeout = OpenWire.configuration.read_timeout
+
+      req =
+        case method
+        when :post then Net::HTTP::Post.new(uri)
+        when :get then Net::HTTP::Get.new(uri)
+        else
+          raise ArgumentError, "unsupported method #{method}"
+        end
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["Content-Type"] = "application/json"
+      req["Accept"] = "application/json"
+      req.body = JSON.generate(body) if body
+
+      res = http.request(req)
+      parsed = JSON.parse(res.body) rescue {}
+      unless res.is_a?(Net::HTTPSuccess)
+        message = parsed.dig("error", "message") || "Open-Wire error #{res.code}"
+        raise ApiError, message
+      end
+      parsed
+    end
+
+    def stringify_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify_keys(v) }
+      when Array
+        obj.map { |v| stringify_keys(v) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/open_wire/configuration.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OpenWire
+  class Configuration
+    attr_accessor :base_url, :api_key, :open_timeout, :read_timeout
+
+    def initialize
+      @base_url = ENV.fetch("OPEN_WIRE_URL", "https://openwire.rails-agent.com")
+      @api_key = ENV["OPEN_WIRE_API_KEY"]
+      @open_timeout = 3
+      @read_timeout = 15
+    end
+  end
+end

data/lib/open_wire/envelope.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module OpenWire
+  # Parsed open-wire/1 inbound envelope.
+  class InboundMessage
+    attr_reader :raw, :id, :channel, :installation_id, :created_at,
+                :thread_id, :from_id, :from_kind, :to_id, :to_kind, :text, :body
+
+    def initialize(payload)
+      @raw = payload.is_a?(Hash) ? payload : {}
+      @id = @raw["id"]
+      @channel = @raw["channel"]
+      @installation_id = @raw["installation_id"]
+      @created_at = @raw["created_at"]
+      thread = @raw["thread"] || {}
+      @thread_id = thread["id"]
+      from = @raw["from"] || {}
+      @from_id = from["id"]
+      @from_kind = from["kind"]
+      to = @raw["to"] || {}
+      @to_id = to["id"]
+      @to_kind = to["kind"]
+      @body = @raw["body"] || {}
+      @text = (@body["text"] || "").to_s
+    end
+
+    def dm?
+      to_kind.to_s == "dm"
+    end
+
+    def protocol
+      @raw["protocol"]
+    end
+
+    def type
+      @raw["type"]
+    end
+
+    def to_h
+      @raw
+    end
+  end
+
+  module Envelope
+    module_function
+
+    def inbound?(payload)
+      payload.is_a?(Hash) &&
+        payload["protocol"].to_s == OpenWire::PROTOCOL &&
+        payload["type"].to_s == "message.inbound"
+    end
+
+    def parse_inbound(payload)
+      data =
+        case payload
+        when String
+          JSON.parse(payload)
+        when Hash
+          payload
+        else
+          raise WebhookError, "Inbound payload must be JSON object or string"
+        end
+
+      raise WebhookError, "Not an open-wire/1 message.inbound envelope" unless inbound?(data)
+
+      InboundMessage.new(data)
+    rescue JSON::ParserError => e
+      raise WebhookError, "Invalid JSON: #{e.message}"
+    end
+  end
+end

data/lib/open_wire/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OpenWire
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class AuthError < Error; end
+  class ApiError < Error; end
+  class WebhookError < Error; end
+end

data/lib/open_wire/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenWire
+  VERSION = "0.1.0"
+end

data/lib/open_wire/webhook.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OpenWire
+  # Verify and parse inbound POSTs from the Open-Wire gateway.
+  module Webhook
+    module_function
+
+    HEADER_PROTOCOL = "X-Open-Wire-Protocol"
+    HEADER_INSTALLATION = "X-Open-Wire-Installation"
+    HEADER_SECRET = "X-Open-Wire-Secret"
+
+    # opts:
+    #   secret: expected webhook secret (required unless allow_missing_secret)
+    #   body: raw request body string OR already-parsed Hash
+    #   headers: Hash-like (Rack env or ActionDispatch headers)
+    def verify_and_parse!(opts)
+      secret = opts.fetch(:secret)
+      body = opts.fetch(:body)
+      headers = normalize_headers(opts[:headers] || {})
+
+      provided = headers[HEADER_SECRET.downcase] || headers[HEADER_SECRET] || ""
+      raise AuthError, "Missing X-Open-Wire-Secret" if provided.to_s.empty?
+      raise AuthError, "Invalid Open-Wire webhook secret" unless secure_compare(provided.to_s, secret.to_s)
+
+      protocol = headers[HEADER_PROTOCOL.downcase] || headers[HEADER_PROTOCOL]
+      if protocol && protocol.to_s != OpenWire::PROTOCOL
+        raise WebhookError, "Unsupported protocol #{protocol}"
+      end
+
+      Envelope.parse_inbound(body)
+    end
+
+    def normalize_headers(headers)
+      out = {}
+      headers.each do |key, value|
+        name = key.to_s
+        name = name.sub(/\AHTTP_/, "").tr("_", "-") if name.start_with?("HTTP_")
+        out[name.downcase] = value.to_s
+        out[name] = value.to_s
+      end
+      # ActionDispatch::Http::Headers style
+      if headers.respond_to?(:[])
+        [HEADER_SECRET, HEADER_PROTOCOL, HEADER_INSTALLATION].each do |h|
+          val = headers[h] || headers[h.downcase]
+          out[h.downcase] = val.to_s if val
+          out[h] = val.to_s if val
+        end
+      end
+      out
+    end
+
+    def secure_compare(a, b)
+      return false if a.bytesize != b.bytesize
+
+      l = a.unpack("C*")
+      r = 0
+      b.each_byte.with_index { |byte, i| r |= byte ^ l[i] }
+      r.zero?
+    end
+  end
+end

data/lib/open_wire.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "securerandom"
+require "open_wire/version"
+require "open_wire/errors"
+require "open_wire/envelope"
+require "open_wire/webhook"
+require "open_wire/client"
+require "open_wire/configuration"
+
+module OpenWire
+  PROTOCOL = "open-wire/1"
+
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset!
+      @configuration = Configuration.new
+    end
+  end
+end

data/open-wire.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/open_wire/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "open-wire"
+  spec.version       = OpenWire::VERSION
+  spec.authors       = ["Kannan Reghu", "Tiny Bubble Company"]
+  spec.email         = ["kannan@rails-agent.com"]
+
+  spec.summary       = "open-wire/1 client and webhook helpers for agent↔channel transport"
+  spec.description   = "Ruby SDK for the Open-Wire protocol: send messages via the gateway " \
+                       "and verify/parse inbound message.inbound webhooks from Slack and other channels."
+  spec.homepage      = "https://openwire.rails-agent.com"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/Tiny-Bubble-Company/open-wire"
+  spec.metadata["documentation_uri"] = "https://openwire.rails-agent.com/docs/protocol"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir["{lib}/**/*", "*.gemspec", "README.md", "MIT-LICENSE"].select { |f| File.file?(f) }
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "json", "~> 2.0"
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: open-wire
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kannan Reghu
+- Tiny Bubble Company
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 'Ruby SDK for the Open-Wire protocol: send messages via the gateway and
+  verify/parse inbound message.inbound webhooks from Slack and other channels.'
+email:
+- kannan@rails-agent.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/open-wire.rb
+- lib/open_wire.rb
+- lib/open_wire/client.rb
+- lib/open_wire/configuration.rb
+- lib/open_wire/envelope.rb
+- lib/open_wire/errors.rb
+- lib/open_wire/version.rb
+- lib/open_wire/webhook.rb
+- open-wire.gemspec
+homepage: https://openwire.rails-agent.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://openwire.rails-agent.com
+  source_code_uri: https://github.com/Tiny-Bubble-Company/open-wire
+  documentation_uri: https://openwire.rails-agent.com/docs/protocol
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: open-wire/1 client and webhook helpers for agent↔channel transport
+test_files: []