hookbridge 1.0.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b629a213046fab3d1fb2ea9eaffcf09de4cb12315b121865ced6e369d536d0e
-  data.tar.gz: b3e7b81b1bf0464f6f127eb065e572f3372159902d1931cc84e02cde7321abd4
+  metadata.gz: 21217d26b8b60f7f11e90921ec65c85886cb9db5083201c54271ab3b73af67c3
+  data.tar.gz: 5c35bcaced137cce82f7763a4c9d338155a4b3324f9ce12ba56455a6586ada29
 SHA512:
-  metadata.gz: 4240c5f2e367dedf09c0af5c628cc29e5f7522ef27c81b23fc9cb8e45fddd699a4c4d04490a132ff702ef8ea4b393e996ad627d7e906370157ec012e0ed21af5
-  data.tar.gz: 9868337d7c0b46efcb8ab17b22833c40d5a8f86c348c2ba3430be617737d9309ef25d3bb445b7265a7bb6deed294844a388f62ee3febee42bb52ea38509c11fb
+  metadata.gz: bb9042d203744bdc6714a8385aa22eb4bc4df4633f5394c56b9cf11165c7abe4c8da7d49a89e24f32a30238575eb06e1afed085ea388128ffde9a00f0e15b72e
+  data.tar.gz: 7a0e7be1de066280224cc326218ee8fe5a88d141f2d500e78b24eabe413e961a2272cfdd3c47ffea9cd51815a9310096b0b263c2b5c66bde4ddbee713b34b38c

data/README.md

@@ -1,254 +1,127 @@
 # 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.
+Official Ruby SDK for HookBridge. Send webhooks with guaranteed delivery, automatic retries, and inbound/outbound observability.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add the gem to your `Gemfile`:
 
 ```ruby
-gem 'hookbridge'
+gem "hookbridge"
 ```
 
-And then execute:
+Then install dependencies:
 
 ```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
+require "hookbridge"
 
-### Sending Webhooks
+client = HookBridge.new(api_key: "hb_live_xxxxxxxxxxxxxxxxxxxx")
 
-```ruby
-# Basic send
-response = client.send(
-  endpoint: 'my-endpoint',
-  payload: { event: 'order.completed', order_id: 456 }
+endpoint = client.create_endpoint(
+  url: "https://customer.app/webhooks",
+  description: "Customer production webhook"
 )
 
-# With idempotency key to prevent duplicates
-response = client.send(
-  endpoint: 'my-endpoint',
-  payload: { event: 'payment.processed' },
-  idempotency_key: 'payment_789'
+result = client.send(
+  endpoint_id: endpoint.id,
+  payload: { event: "order.created" }
 )
 
-# With custom content type
-response = client.send(
-  endpoint: 'my-endpoint',
-  payload: '<xml>data</xml>',
-  content_type: 'application/xml'
-)
+puts result.message_id
 ```
 
-### Checking Message Status
+## Outbound Endpoints
 
 ```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')
+endpoint = client.create_endpoint(
+  url: "https://customer.app/webhooks",
+  description: "Main production webhook",
+  rate_limit_rps: 10,
+  burst: 20
+)
 
-# Cancel a pending retry
-client.cancel_retry('msg_01234567890abcdef')
+details = client.get_endpoint(endpoint.id)
+list = client.list_endpoints(limit: 50)
+rotated = client.rotate_endpoint_secret(endpoint.id)
+client.delete_endpoint(endpoint.id)
 ```
 
-### Querying Delivery Logs
+## Sending and Observability
 
 ```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
+result = client.send(
+  endpoint_id: endpoint.id,
+  payload: { event: "user.created", user_id: "usr_123" },
+  idempotency_key: "user-123-created"
 )
 
-# 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)
+message = client.get_message(result.message_id)
+logs = client.get_logs(limit: 100)
 metrics = client.get_metrics
+timeseries = client.get_timeseries_metrics(endpoint_id: endpoint.id)
 
-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)
+client.replay(message.id)
+client.replay_all_messages(status: "failed_permanent", endpoint_id: endpoint.id, limit: 50)
 ```
 
-### Dead Letter Queue
+## Inbound Webhooks
 
 ```ruby
-# List failed messages
-dlq = client.get_dlq_messages
-
-dlq.messages.each do |msg|
-  puts "#{msg.message_id} failed: #{msg.reason}"
-end
+inbound = client.create_inbound_endpoint(
+  url: "https://myapp.com/webhooks/inbound",
+  name: "Stripe inbound",
+  description: "Receives Stripe events through HookBridge",
+  verify_static_token: true,
+  token_header_name: "X-Webhook-Token",
+  token_value: "my-shared-secret",
+  signing_enabled: true,
+  idempotency_header_names: ["X-Idempotency-Key"],
+  ingest_response_code: 202
+)
 
-# Replay from DLQ
-response = client.replay_from_dlq('msg_01234567890abcdef')
-```
+puts inbound.ingest_url   # Save this
+puts inbound.secret_token # Only shown once
 
-### API Key Management
+details = client.get_inbound_endpoint(inbound.id)
+client.pause_inbound_endpoint(inbound.id)
+client.resume_inbound_endpoint(inbound.id)
 
-```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')
+client.update_inbound_endpoint(
+  inbound.id,
+  verify_hmac: true,
+  hmac_header_name: "X-Signature",
+  hmac_secret: "whsec_inbound_secret"
+)
 ```
 
-## Error Handling
-
-The SDK raises specific exceptions for different error conditions:
+## Inbound Observability
 
 ```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
+inbound_endpoints = client.list_inbound_endpoints(limit: 50)
+inbound_logs = client.get_inbound_logs(inbound_endpoint_id: inbound.id, limit: 50)
+inbound_metrics = client.get_inbound_metrics(inbound_endpoint_id: inbound.id)
+inbound_timeseries = client.get_inbound_timeseries_metrics(inbound_endpoint_id: inbound.id)
+rejections = client.list_inbound_rejections(inbound_endpoint_id: inbound.id, limit: 25)
 ```
 
-## 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:
+## Billing and Exports
 
 ```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.
+subscription = client.get_subscription
+usage = client.get_usage_history(limit: 12, offset: 0)
+invoices = client.get_invoices(limit: 12)
+
+export = client.create_export(
+  start_time: Time.now.utc - 86_400,
+  end_time: Time.now.utc,
+  endpoint_id: endpoint.id
+)
 
-```bash
-bundle install
-bundle exec rspec
-bundle exec rubocop
+download_url = client.download_export(export.id)
 ```
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).