hookbridge 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b629a213046fab3d1fb2ea9eaffcf09de4cb12315b121865ced6e369d536d0e
+  data.tar.gz: b3e7b81b1bf0464f6f127eb065e572f3372159902d1931cc84e02cde7321abd4
+SHA512:
+  metadata.gz: 4240c5f2e367dedf09c0af5c628cc29e5f7522ef27c81b23fc9cb8e45fddd699a4c4d04490a132ff702ef8ea4b393e996ad627d7e906370157ec012e0ed21af5
+  data.tar.gz: 9868337d7c0b46efcb8ab17b22833c40d5a8f86c348c2ba3430be617737d9309ef25d3bb445b7265a7bb6deed294844a388f62ee3febee42bb52ea38509c11fb

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-01-15
+
+### Added
+
+- Initial release of the HookBridge Ruby SDK
+- `send` - Send webhooks with guaranteed delivery
+- `get_message` - Get detailed message status
+- `replay` - Replay failed messages
+- `cancel_retry` - Cancel pending retries
+- `retry_now` - Trigger immediate retry
+- `get_logs` - Query delivery logs with filtering
+- `get_metrics` - Get aggregated delivery metrics
+- `get_dlq_messages` - List Dead Letter Queue messages
+- `replay_from_dlq` - Replay messages from DLQ
+- `list_api_keys` - List project API keys
+- `create_api_key` - Create new API keys
+- `delete_api_key` - Delete API keys
+- Comprehensive error handling with specific exception types
+- Automatic retries with exponential backoff for transient failures
+- Full type definitions for all API responses

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 HookBridge
+
+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,254 @@
+# HookBridge Ruby SDK
+
+Official Ruby client library for the [HookBridge](https://hookbridge.io) API. Send webhooks with guaranteed delivery, automatic retries, and comprehensive delivery tracking.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hookbridge'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install hookbridge
+```
+
+## Quick Start
+
+```ruby
+require 'hookbridge'
+
+# Initialize the client
+client = HookBridge.new(api_key: 'hb_live_xxxxxxxxxxxxxxxxxxxx')
+
+# Send a webhook
+response = client.send(
+  endpoint: 'my-endpoint',
+  payload: { event: 'user.created', data: { id: 123 } }
+)
+
+puts "Message queued: #{response.message_id}"
+```
+
+## Configuration
+
+```ruby
+client = HookBridge.new(
+  api_key: 'hb_live_xxxxxxxxxxxxxxxxxxxx',
+  base_url: 'https://api.hookbridge.io',  # optional, can also use HOOKBRIDGE_BASE_URL env var
+  timeout: 30,                             # request timeout in seconds (default: 30)
+  retries: 3                               # number of retries for failed requests (default: 3)
+)
+```
+
+## Usage
+
+### Sending Webhooks
+
+```ruby
+# Basic send
+response = client.send(
+  endpoint: 'my-endpoint',
+  payload: { event: 'order.completed', order_id: 456 }
+)
+
+# With idempotency key to prevent duplicates
+response = client.send(
+  endpoint: 'my-endpoint',
+  payload: { event: 'payment.processed' },
+  idempotency_key: 'payment_789'
+)
+
+# With custom content type
+response = client.send(
+  endpoint: 'my-endpoint',
+  payload: '<xml>data</xml>',
+  content_type: 'application/xml'
+)
+```
+
+### Checking Message Status
+
+```ruby
+message = client.get_message('msg_01234567890abcdef')
+
+puts message.status           # => "succeeded"
+puts message.attempt_count    # => 1
+puts message.response_status  # => 200
+puts message.response_latency_ms
+```
+
+### Replaying Messages
+
+```ruby
+# Replay a failed message
+response = client.replay('msg_01234567890abcdef')
+puts "Replayed, attempt #{response.attempt_count}"
+
+# Trigger immediate retry for a pending message
+client.retry_now('msg_01234567890abcdef')
+
+# Cancel a pending retry
+client.cancel_retry('msg_01234567890abcdef')
+```
+
+### Querying Delivery Logs
+
+```ruby
+# Get recent logs
+logs = client.get_logs
+
+logs.messages.each do |msg|
+  puts "#{msg.message_id}: #{msg.status}"
+end
+
+# Filter by status
+logs = client.get_logs(status: HookBridge::MessageStatus::FAILED_PERMANENT)
+
+# Filter by time range
+logs = client.get_logs(
+  start_time: Time.now - 3600,  # last hour
+  end_time: Time.now,
+  limit: 50
+)
+
+# Pagination
+logs = client.get_logs(limit: 20)
+if logs.has_more
+  next_page = client.get_logs(cursor: logs.next_cursor)
+end
+```
+
+### Getting Metrics
+
+```ruby
+# Get 24-hour metrics (default)
+metrics = client.get_metrics
+
+puts "Total: #{metrics.total_messages}"
+puts "Success rate: #{(metrics.success_rate * 100).round(1)}%"
+puts "Avg latency: #{metrics.avg_latency_ms}ms"
+
+# Different time windows
+metrics_1h = client.get_metrics(window: HookBridge::MetricsWindow::ONE_HOUR)
+metrics_7d = client.get_metrics(window: HookBridge::MetricsWindow::SEVEN_DAYS)
+metrics_30d = client.get_metrics(window: HookBridge::MetricsWindow::THIRTY_DAYS)
+```
+
+### Dead Letter Queue
+
+```ruby
+# List failed messages
+dlq = client.get_dlq_messages
+
+dlq.messages.each do |msg|
+  puts "#{msg.message_id} failed: #{msg.reason}"
+end
+
+# Replay from DLQ
+response = client.replay_from_dlq('msg_01234567890abcdef')
+```
+
+### API Key Management
+
+```ruby
+# List all API keys
+keys = client.list_api_keys
+keys.keys.each do |key|
+  puts "#{key.name}: #{key.prefix}... (#{key.mode})"
+end
+
+# Create a new key
+new_key = client.create_api_key(name: 'Production Server', mode: HookBridge::APIKeyMode::LIVE)
+puts "Save this key: #{new_key.key}"  # Only shown once!
+
+# Delete a key
+client.delete_api_key('key_01234567890abcdef')
+```
+
+## Error Handling
+
+The SDK raises specific exceptions for different error conditions:
+
+```ruby
+begin
+  client.send(endpoint: 'my-endpoint', payload: data)
+rescue HookBridge::AuthenticationError => e
+  # Invalid or missing API key (401)
+  puts "Auth failed: #{e.message}"
+rescue HookBridge::ValidationError => e
+  # Invalid request parameters (400)
+  puts "Validation failed: #{e.message}"
+rescue HookBridge::NotFoundError => e
+  # Resource not found (404)
+  puts "Not found: #{e.message}"
+rescue HookBridge::RateLimitError => e
+  # Rate limit exceeded (429)
+  puts "Rate limited, retry after #{e.retry_after} seconds"
+rescue HookBridge::IdempotencyError => e
+  # Idempotency key conflict (409)
+  puts "Duplicate request: #{e.message}"
+rescue HookBridge::ReplayLimitError => e
+  # Replay limit exceeded (409)
+  puts "Replay limit reached: #{e.message}"
+rescue HookBridge::TimeoutError => e
+  # Request timed out
+  puts "Timeout: #{e.message}"
+rescue HookBridge::NetworkError => e
+  # Network/connection error
+  puts "Network error: #{e.message}"
+rescue HookBridge::Error => e
+  # Other API errors
+  puts "Error: #{e.message} (code: #{e.code}, request_id: #{e.request_id})"
+end
+```
+
+## Message Statuses
+
+Messages can be in one of these statuses:
+
+| Status | Description |
+|--------|-------------|
+| `queued` | Message is queued for delivery |
+| `delivering` | Delivery attempt in progress |
+| `succeeded` | Successfully delivered |
+| `pending_retry` | Failed, will retry automatically |
+| `failed_permanent` | Failed permanently (in DLQ) |
+
+Use the constants:
+
+```ruby
+HookBridge::MessageStatus::QUEUED
+HookBridge::MessageStatus::DELIVERING
+HookBridge::MessageStatus::SUCCEEDED
+HookBridge::MessageStatus::PENDING_RETRY
+HookBridge::MessageStatus::FAILED_PERMANENT
+```
+
+## Requirements
+
+- Ruby 3.0 or higher
+- Faraday 2.x
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/hookbridge/client.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module HookBridge
+  # Main client for interacting with the HookBridge API
+  class Client
+    DEFAULT_BASE_URL = "https://api.hookbridge.io"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_RETRIES = 3
+
+    attr_reader :api_key, :base_url, :timeout, :retries
+
+    # Initialize a new HookBridge client
+    #
+    # @param api_key [String] Your HookBridge API key (starts with hb_live_ or hb_test_)
+    # @param base_url [String] API base URL (defaults to https://api.hookbridge.io)
+    # @param timeout [Integer] Request timeout in seconds (defaults to 30)
+    # @param retries [Integer] Number of retries for failed requests (defaults to 3)
+    def initialize(api_key:, base_url: nil, timeout: DEFAULT_TIMEOUT, retries: DEFAULT_RETRIES)
+      raise ValidationError, "API key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = (base_url || ENV.fetch("HOOKBRIDGE_BASE_URL", DEFAULT_BASE_URL)).chomp("/")
+      @timeout = timeout
+      @retries = retries
+      @connection = build_connection
+    end
+
+    # Send a webhook for guaranteed delivery
+    #
+    # @param endpoint [String] The registered endpoint identifier
+    # @param payload [Hash, String] The webhook payload
+    # @param idempotency_key [String, nil] Optional idempotency key to prevent duplicates
+    # @param content_type [String] Content type of the payload (defaults to application/json)
+    # @return [SendResponse] The send response with message_id and status
+    def send(endpoint:, payload:, idempotency_key: nil, content_type: "application/json")
+      body = {
+        endpoint: endpoint,
+        payload: payload,
+        content_type: content_type
+      }
+      body[:idempotency_key] = idempotency_key if idempotency_key
+
+      data = request(:post, "/v1/webhooks/send", body)
+      SendResponse.new(data)
+    end
+
+    # Get detailed status for a specific message
+    #
+    # @param message_id [String] The message ID (UUIDv7)
+    # @return [Message] The message details
+    def get_message(message_id)
+      data = request(:get, "/v1/messages/#{message_id}")
+      Message.new(data)
+    end
+
+    # Manually replay a failed message
+    #
+    # @param message_id [String] The message ID to replay
+    # @return [ReplayResponse] The replay response
+    def replay(message_id)
+      data = request(:post, "/v1/messages/#{message_id}/replay")
+      ReplayResponse.new(data)
+    end
+
+    # Cancel a pending retry
+    #
+    # @param message_id [String] The message ID
+    # @return [Message] The updated message
+    def cancel_retry(message_id)
+      data = request(:post, "/v1/messages/#{message_id}/cancel")
+      Message.new(data)
+    end
+
+    # Trigger immediate retry for a pending message
+    #
+    # @param message_id [String] The message ID
+    # @return [Message] The updated message
+    def retry_now(message_id)
+      data = request(:post, "/v1/messages/#{message_id}/retry-now")
+      Message.new(data)
+    end
+
+    # Query delivery logs with optional filtering
+    #
+    # @param status [String, nil] Filter by message status
+    # @param start_time [Time, String, nil] Filter by start time
+    # @param end_time [Time, String, nil] Filter by end time
+    # @param limit [Integer, nil] Maximum number of results (default 50, max 100)
+    # @param cursor [String, nil] Pagination cursor from previous response
+    # @return [LogsResponse] Paginated list of message summaries
+    def get_logs(status: nil, start_time: nil, end_time: nil, limit: nil, cursor: nil)
+      params = {}
+      params[:status] = status if status
+      params[:start_time] = format_time(start_time) if start_time
+      params[:end_time] = format_time(end_time) if end_time
+      params[:limit] = limit if limit
+      params[:cursor] = cursor if cursor
+
+      data = request(:get, "/v1/logs", nil, params)
+      LogsResponse.new(data)
+    end
+
+    # Retrieve aggregated delivery metrics
+    #
+    # @param window [String] Time window: "1h", "24h", "7d", or "30d"
+    # @return [Metrics] The delivery metrics
+    def get_metrics(window: MetricsWindow::TWENTY_FOUR_HOURS)
+      data = request(:get, "/v1/metrics", nil, { window: window })
+      Metrics.new(data)
+    end
+
+    # List messages in the Dead Letter Queue
+    #
+    # @param limit [Integer, nil] Maximum number of results
+    # @param cursor [String, nil] Pagination cursor
+    # @return [DLQResponse] Paginated list of DLQ messages
+    def get_dlq_messages(limit: nil, cursor: nil)
+      params = {}
+      params[:limit] = limit if limit
+      params[:cursor] = cursor if cursor
+
+      data = request(:get, "/v1/dlq/messages", nil, params)
+      DLQResponse.new(data)
+    end
+
+    # Replay a message from the Dead Letter Queue
+    #
+    # @param message_id [String] The message ID to replay
+    # @return [ReplayResponse] The replay response
+    def replay_from_dlq(message_id)
+      data = request(:post, "/v1/dlq/replay/#{message_id}")
+      ReplayResponse.new(data)
+    end
+
+    # List all API keys for the project
+    #
+    # @return [APIKeysResponse] List of API keys
+    def list_api_keys
+      data = request(:get, "/v1/api-keys")
+      APIKeysResponse.new(data)
+    end
+
+    # Create a new API key
+    #
+    # @param name [String] Name for the API key
+    # @param mode [String] Key mode: "live" or "test"
+    # @return [APIKeyCreated] The created API key (includes full key, only shown once)
+    def create_api_key(label: nil, mode: APIKeyMode::LIVE)
+      body = { mode: mode }
+      body[:label] = label if label
+      data = request(:post, "/v1/api-keys", body)
+      APIKeyCreated.new(data)
+    end
+
+    # Delete an API key
+    #
+    # @param key_id [String] The API key ID to delete
+    # @return [Boolean] true if successful
+    def delete_api_key(key_id)
+      request(:delete, "/v1/api-keys/#{key_id}")
+      true
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(url: @base_url) do |conn|
+        conn.request :retry,
+                     max: @retries,
+                     interval: 0.1,
+                     interval_randomness: 0.5,
+                     backoff_factor: 2,
+                     retry_statuses: [500, 502, 503, 504],
+                     methods: %i[get post put delete],
+                     retry_block: lambda { |env, _options, retries, exception|
+                       # Don't retry client errors
+                       return false if env.status && env.status < 500
+
+                       true
+                     }
+
+        conn.options.timeout = @timeout
+        conn.options.open_timeout = 10
+
+        conn.headers["Authorization"] = "Bearer #{@api_key}"
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["Accept"] = "application/json"
+        conn.headers["User-Agent"] = "hookbridge-ruby/#{VERSION}"
+
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def request(method, path, body = nil, params = nil)
+      response = @connection.run_request(method, path, body&.to_json, nil) do |req|
+        req.params.update(params) if params
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError.new("Request timed out: #{e.message}")
+    rescue Faraday::ConnectionFailed => e
+      raise NetworkError.new("Connection failed: #{e.message}")
+    rescue Faraday::Error => e
+      raise NetworkError.new("Network error: #{e.message}")
+    end
+
+    def handle_response(response)
+      request_id = response.headers["x-request-id"]
+
+      case response.status
+      when 200..299
+        return nil if response.body.nil? || response.body.empty?
+
+        parsed = JSON.parse(response.body)
+        # API wraps responses in { data: ..., meta: ... }
+        # Return data field if present, otherwise return parsed response
+        if parsed.is_a?(Hash) && parsed.key?("data")
+          # For paginated responses, include meta info
+          if parsed["meta"]&.key?("has_more") || parsed["meta"]&.key?("next_cursor")
+            {
+              "data" => parsed["data"],
+              "has_more" => parsed.dig("meta", "has_more"),
+              "next_cursor" => parsed.dig("meta", "next_cursor")
+            }
+          else
+            parsed["data"]
+          end
+        else
+          parsed
+        end
+      when 400
+        error_data = parse_error(response.body)
+        raise ValidationError.new(error_data[:message], request_id: request_id)
+      when 401
+        error_data = parse_error(response.body)
+        raise AuthenticationError.new(error_data[:message], request_id: request_id)
+      when 404
+        error_data = parse_error(response.body)
+        raise NotFoundError.new(error_data[:message], request_id: request_id)
+      when 409
+        error_data = parse_error(response.body)
+        code = error_data[:code]
+        if code == "REPLAY_LIMIT_EXCEEDED"
+          raise ReplayLimitError.new(error_data[:message], request_id: request_id)
+        else
+          raise IdempotencyError.new(error_data[:message], request_id: request_id)
+        end
+      when 429
+        error_data = parse_error(response.body)
+        retry_after = response.headers["retry-after"]&.to_i
+        raise RateLimitError.new(error_data[:message], request_id: request_id, retry_after: retry_after)
+      else
+        error_data = parse_error(response.body)
+        raise Error.new(
+          error_data[:message] || "HTTP #{response.status}",
+          code: error_data[:code],
+          request_id: request_id,
+          status_code: response.status
+        )
+      end
+    end
+
+    def parse_error(body)
+      return { message: "Unknown error", code: nil } if body.nil? || body.empty?
+
+      data = JSON.parse(body)
+      # API wraps errors in { error: { code: ..., message: ... }, meta: ... }
+      if data["error"].is_a?(Hash)
+        {
+          message: data["error"]["message"] || "Unknown error",
+          code: data["error"]["code"]
+        }
+      else
+        {
+          message: data["error"] || data["message"] || "Unknown error",
+          code: data["code"]
+        }
+      end
+    rescue JSON::ParserError
+      { message: body, code: nil }
+    end
+
+    def format_time(time)
+      case time
+      when Time
+        time.utc.iso8601
+      when String
+        time
+      else
+        time.to_s
+      end
+    end
+  end
+end

data/lib/hookbridge/errors.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module HookBridge
+  # Base error class for all HookBridge errors
+  class Error < StandardError
+    attr_reader :code, :request_id, :status_code
+
+    def initialize(message, code: nil, request_id: nil, status_code: nil)
+      @code = code
+      @request_id = request_id
+      @status_code = status_code
+      super(message)
+    end
+  end
+
+  # Raised when authentication fails (401)
+  class AuthenticationError < Error
+    def initialize(message = "Invalid or missing API key", **kwargs)
+      super(message, code: "AUTHENTICATION_ERROR", status_code: 401, **kwargs)
+    end
+  end
+
+  # Raised when a resource is not found (404)
+  class NotFoundError < Error
+    def initialize(message = "Resource not found", **kwargs)
+      super(message, code: "NOT_FOUND", status_code: 404, **kwargs)
+    end
+  end
+
+  # Raised when request validation fails (400)
+  class ValidationError < Error
+    def initialize(message = "Validation failed", **kwargs)
+      super(message, code: "VALIDATION_ERROR", status_code: 400, **kwargs)
+    end
+  end
+
+  # Raised when rate limit is exceeded (429)
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", retry_after: nil, **kwargs)
+      @retry_after = retry_after
+      super(message, code: "RATE_LIMIT_EXCEEDED", status_code: 429, **kwargs)
+    end
+  end
+
+  # Raised when idempotency key conflict occurs (409)
+  class IdempotencyError < Error
+    def initialize(message = "Idempotency key conflict", **kwargs)
+      super(message, code: "IDEMPOTENCY_CONFLICT", status_code: 409, **kwargs)
+    end
+  end
+
+  # Raised when replay limit is exceeded (429)
+  class ReplayLimitError < Error
+    def initialize(message = "Replay limit exceeded", **kwargs)
+      super(message, code: "REPLAY_LIMIT_EXCEEDED", status_code: 429, **kwargs)
+    end
+  end
+
+  # Raised when a network error occurs
+  class NetworkError < Error
+    def initialize(message = "Network error", **kwargs)
+      super(message, code: "NETWORK_ERROR", **kwargs)
+    end
+  end
+
+  # Raised when a request times out
+  class TimeoutError < Error
+    def initialize(message = "Request timed out", **kwargs)
+      super(message, code: "TIMEOUT", **kwargs)
+    end
+  end
+end

data/lib/hookbridge/types.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require "time"
+
+module HookBridge
+  # Message status constants
+  module MessageStatus
+    QUEUED = "queued"
+    DELIVERING = "delivering"
+    SUCCEEDED = "succeeded"
+    PENDING_RETRY = "pending_retry"
+    FAILED_PERMANENT = "failed_permanent"
+
+    ALL = [QUEUED, DELIVERING, SUCCEEDED, PENDING_RETRY, FAILED_PERMANENT].freeze
+  end
+
+  # API key mode constants
+  module APIKeyMode
+    LIVE = "live"
+    TEST = "test"
+
+    ALL = [LIVE, TEST].freeze
+  end
+
+  # Metrics time window constants
+  module MetricsWindow
+    ONE_HOUR = "1h"
+    TWENTY_FOUR_HOURS = "24h"
+    SEVEN_DAYS = "7d"
+    THIRTY_DAYS = "30d"
+
+    ALL = [ONE_HOUR, TWENTY_FOUR_HOURS, SEVEN_DAYS, THIRTY_DAYS].freeze
+  end
+
+  # Full message details
+  class Message
+    attr_reader :id, :status, :project_id, :endpoint_id, :attempt_count, :replay_count,
+                :payload_sha256, :content_type, :size_bytes, :idempotency_key,
+                :next_attempt_at, :last_error, :response_status, :response_latency_ms,
+                :created_at, :updated_at
+
+    def initialize(data)
+      @id = data["id"]
+      @status = data["status"]
+      @project_id = data["project_id"]
+      @endpoint_id = data["endpoint_id"]
+      @attempt_count = data["attempt_count"]
+      @replay_count = data["replay_count"]
+      @payload_sha256 = data["payload_sha256"]
+      @content_type = data["content_type"]
+      @size_bytes = data["size_bytes"]
+      @idempotency_key = data["idempotency_key"]
+      @next_attempt_at = parse_time(data["next_attempt_at"])
+      @last_error = data["last_error"]
+      @response_status = data["response_status"]
+      @response_latency_ms = data["response_latency_ms"]
+      @created_at = parse_time(data["created_at"])
+      @updated_at = parse_time(data["updated_at"])
+    end
+
+    def to_h
+      {
+        id: @id,
+        status: @status,
+        project_id: @project_id,
+        endpoint_id: @endpoint_id,
+        attempt_count: @attempt_count,
+        replay_count: @replay_count,
+        payload_sha256: @payload_sha256,
+        content_type: @content_type,
+        size_bytes: @size_bytes,
+        idempotency_key: @idempotency_key,
+        next_attempt_at: @next_attempt_at,
+        last_error: @last_error,
+        response_status: @response_status,
+        response_latency_ms: @response_latency_ms,
+        created_at: @created_at,
+        updated_at: @updated_at
+      }
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+
+      Time.parse(value)
+    end
+  end
+
+  # Lighter message summary for logs
+  class MessageSummary
+    attr_reader :message_id, :endpoint, :status, :attempt_count, :created_at,
+                :delivered_at, :response_status, :response_latency_ms, :last_error
+
+    def initialize(data)
+      @message_id = data["message_id"]
+      @endpoint = data["endpoint"]
+      @status = data["status"]
+      @attempt_count = data["attempt_count"]
+      @created_at = parse_time(data["created_at"])
+      @delivered_at = parse_time(data["delivered_at"])
+      @response_status = data["response_status"]
+      @response_latency_ms = data["response_latency_ms"]
+      @last_error = data["last_error"]
+    end
+
+    def to_h
+      {
+        message_id: @message_id,
+        endpoint: @endpoint,
+        status: @status,
+        attempt_count: @attempt_count,
+        created_at: @created_at,
+        delivered_at: @delivered_at,
+        response_status: @response_status,
+        response_latency_ms: @response_latency_ms,
+        last_error: @last_error
+      }
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+
+      Time.parse(value)
+    end
+  end
+
+  # Send webhook response
+  class SendResponse
+    attr_reader :message_id, :status
+
+    def initialize(data)
+      @message_id = data["message_id"]
+      @status = data["status"]
+    end
+
+    def to_h
+      { message_id: @message_id, status: @status }
+    end
+  end
+
+  # Replay response
+  class ReplayResponse
+    attr_reader :message_id, :status, :attempt_count
+
+    def initialize(data)
+      @message_id = data["message_id"]
+      @status = data["status"]
+      @attempt_count = data["attempt_count"]
+    end
+
+    def to_h
+      { message_id: @message_id, status: @status, attempt_count: @attempt_count }
+    end
+  end
+
+  # Paginated list of log entries
+  class LogsResponse
+    attr_reader :messages, :has_more, :next_cursor
+
+    def initialize(data)
+      # data is an array directly, pagination info is at top level
+      messages_data = data["data"] || data
+      messages_data = [] unless messages_data.is_a?(Array)
+      @messages = messages_data.map { |m| MessageSummary.new(m) }
+      @has_more = data["has_more"] || false
+      @next_cursor = data["next_cursor"]
+    end
+
+    def to_h
+      {
+        messages: @messages.map(&:to_h),
+        has_more: @has_more,
+        next_cursor: @next_cursor
+      }
+    end
+  end
+
+  # Delivery metrics
+  class Metrics
+    attr_reader :window, :total_messages, :succeeded, :failed, :retries,
+                :success_rate, :avg_latency_ms
+
+    def initialize(data)
+      @window = data["window"]
+      @total_messages = data["total_messages"]
+      @succeeded = data["succeeded"]
+      @failed = data["failed"]
+      @retries = data["retries"]
+      @success_rate = data["success_rate"]
+      @avg_latency_ms = data["avg_latency_ms"]
+    end
+
+    def to_h
+      {
+        window: @window,
+        total_messages: @total_messages,
+        succeeded: @succeeded,
+        failed: @failed,
+        retries: @retries,
+        success_rate: @success_rate,
+        avg_latency_ms: @avg_latency_ms
+      }
+    end
+  end
+
+  # Dead Letter Queue message
+  class DLQMessage
+    attr_reader :message_id, :endpoint, :failed_at, :reason, :attempt_count
+
+    def initialize(data)
+      @message_id = data["message_id"]
+      @endpoint = data["endpoint"]
+      @failed_at = parse_time(data["failed_at"])
+      @reason = data["reason"]
+      @attempt_count = data["attempt_count"]
+    end
+
+    def to_h
+      {
+        message_id: @message_id,
+        endpoint: @endpoint,
+        failed_at: @failed_at,
+        reason: @reason,
+        attempt_count: @attempt_count
+      }
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+
+      Time.parse(value)
+    end
+  end
+
+  # Paginated list of DLQ messages
+  class DLQResponse
+    attr_reader :messages, :has_more, :next_cursor
+
+    def initialize(data)
+      # DLQ response: data can be { messages: [...] } or have messages at top level
+      messages_data = if data.is_a?(Hash) && data["data"].is_a?(Hash)
+                        data.dig("data", "messages") || []
+                      elsif data.is_a?(Hash) && data["messages"]
+                        data["messages"]
+                      elsif data.is_a?(Array)
+                        data
+                      else
+                        []
+                      end
+      @messages = messages_data.map { |m| MessageSummary.new(m) }
+      @has_more = data["has_more"] || false
+      @next_cursor = data["next_cursor"]
+    end
+
+    def to_h
+      {
+        messages: @messages.map(&:to_h),
+        has_more: @has_more,
+        next_cursor: @next_cursor
+      }
+    end
+  end
+
+  # API key information
+  class APIKey
+    attr_reader :key_id, :label, :prefix, :created_at, :last_used_at
+
+    # Aliases for backwards compatibility
+    alias id key_id
+    alias name label
+
+    def initialize(data)
+      @key_id = data["key_id"]
+      @label = data["label"]
+      @prefix = data["prefix"]
+      @created_at = parse_time(data["created_at"])
+      @last_used_at = parse_time(data["last_used_at"])
+    end
+
+    def to_h
+      {
+        key_id: @key_id,
+        label: @label,
+        prefix: @prefix,
+        created_at: @created_at,
+        last_used_at: @last_used_at
+      }
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+
+      Time.parse(value)
+    end
+  end
+
+  # API key creation response (includes full key)
+  class APIKeyCreated
+    attr_reader :key_id, :label, :key, :prefix, :created_at
+
+    # Aliases for backwards compatibility
+    alias id key_id
+    alias name label
+
+    def initialize(data)
+      @key_id = data["key_id"]
+      @label = data["label"]
+      @key = data["key"]
+      @prefix = data["prefix"]
+      @created_at = parse_time(data["created_at"])
+    end
+
+    def to_h
+      {
+        key_id: @key_id,
+        label: @label,
+        key: @key,
+        prefix: @prefix,
+        created_at: @created_at
+      }
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+
+      Time.parse(value)
+    end
+  end
+
+  # List of API keys
+  class APIKeysResponse
+    attr_reader :keys
+
+    def initialize(data)
+      # data is an array directly
+      keys_data = data.is_a?(Array) ? data : (data["data"] || data["keys"] || [])
+      keys_data = [] unless keys_data.is_a?(Array)
+      @keys = keys_data.map { |k| APIKey.new(k) }
+    end
+
+    def to_h
+      { keys: @keys.map(&:to_h) }
+    end
+  end
+end

data/lib/hookbridge/version.rb

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

data/lib/hookbridge.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "hookbridge/version"
+require_relative "hookbridge/errors"
+require_relative "hookbridge/types"
+require_relative "hookbridge/client"
+
+module HookBridge
+  class << self
+    # Create a new HookBridge client
+    #
+    # @param api_key [String] Your HookBridge API key
+    # @param options [Hash] Additional options (base_url, timeout, retries)
+    # @return [Client] A new HookBridge client instance
+    def new(api_key:, **options)
+      Client.new(api_key: api_key, **options)
+    end
+  end
+end

metadata

@@ -0,0 +1,186 @@
+--- !ruby/object:Gem::Specification
+name: hookbridge
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- HookBridge
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  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'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.20'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Official Ruby client library for the HookBridge API. Send webhooks with
+  guaranteed delivery, automatic retries, and comprehensive delivery tracking.
+email:
+- support@hookbridge.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/hookbridge.rb
+- lib/hookbridge/client.rb
+- lib/hookbridge/errors.rb
+- lib/hookbridge/types.rb
+- lib/hookbridge/version.rb
+homepage: https://github.com/hookbridge/hookbridge-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hookbridge/hookbridge-ruby
+  source_code_uri: https://github.com/hookbridge/hookbridge-ruby
+  changelog_uri: https://github.com/hookbridge/hookbridge-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.hookbridge.io
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Ruby SDK for HookBridge - Guaranteed webhook delivery
+test_files: []