nahook 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dff420cf119a0ff62244803d4fb0897bc403a42172a27f187efecbd2b79d9eb6
+  data.tar.gz: 2eb2ee2daa42e790da927002db9adb91b2034804fd8fd71b64bf9123766fc97e
+SHA512:
+  metadata.gz: a30168ab2246994559832746f45bb714b3f7d120ee0a00d4c646983a19a0a92237bf4db7307c53504ef81e76977e83fb8dab615414e83218757ae861ec445005
+  data.tar.gz: b9a956794a9710d356e09efb57f0fc2d12ed22f0c95e515c1f992983be72c58be3816bb6fefdee21d0a183a4d56a809d701a039910a69c3ff069e0421d6f9dc0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nahook
+
+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,189 @@
+# Nahook Ruby SDK
+
+Official Ruby SDK for the [Nahook](https://nahook.com) webhook platform. Send webhooks, fan-out by event type, and manage resources programmatically.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "nahook"
+```
+
+Or install directly:
+
+```bash
+gem install nahook
+```
+
+**Requirements:** Ruby 3.0+
+
+## Quick Start
+
+### Sending Webhooks (Client)
+
+```ruby
+require "nahook"
+
+client = Nahook::Client.new("nhk_us_your_api_key")
+
+# Send to a specific endpoint
+result = client.send("ep_abc123", payload: { order_id: "12345", status: "paid" })
+puts result["deliveryId"] # => "del_..."
+
+# Fan-out by event type (delivers to all subscribed endpoints)
+result = client.trigger("order.paid", payload: { order_id: "12345" })
+puts result["deliveryIds"] # => ["del_1", "del_2"]
+
+# With metadata
+client.trigger("order.paid",
+  payload: { order_id: "12345" },
+  metadata: { "source" => "checkout" }
+)
+```
+
+### Managing Resources (Management)
+
+```ruby
+mgmt = Nahook::Management.new("nhm_your_management_token")
+
+# Endpoints
+endpoints = mgmt.endpoints.list("ws_abc123")
+endpoint  = mgmt.endpoints.create("ws_abc123",
+  url: "https://example.com/webhook",
+  type: "webhook",
+  description: "Production webhook"
+)
+mgmt.endpoints.update("ws_abc123", endpoint["id"], is_active: false)
+mgmt.endpoints.delete("ws_abc123", endpoint["id"])
+
+# Event Types
+mgmt.event_types.create("ws_abc123", name: "order.paid", description: "Fired when an order is paid")
+types = mgmt.event_types.list("ws_abc123")
+
+# Applications
+app = mgmt.applications.create("ws_abc123", name: "Acme Corp", external_id: "acme_123")
+mgmt.applications.list("ws_abc123", limit: 10, offset: 0)
+mgmt.applications.list_endpoints("ws_abc123", app["id"])
+mgmt.applications.create_endpoint("ws_abc123", app["id"], url: "https://acme.com/hook")
+
+# Subscriptions
+mgmt.subscriptions.create("ws_abc123", "ep_def456", event_type_ids: ["evt_ghi789"])
+mgmt.subscriptions.list("ws_abc123", "ep_def456")
+mgmt.subscriptions.delete("ws_abc123", "ep_def456", "evt_ghi789")
+
+# Environments
+env = mgmt.environments.create("ws_abc123", name: "Staging", slug: "staging")
+mgmt.environments.list("ws_abc123")
+mgmt.environments.get("ws_abc123", env["id"])
+mgmt.environments.update("ws_abc123", env["id"], name: "Pre-production")
+mgmt.environments.delete("ws_abc123", env["id"])
+
+# Event Type Visibility
+mgmt.environments.list_event_type_visibility("ws_abc123", "env_abc123")
+mgmt.environments.set_event_type_visibility("ws_abc123", "env_abc123", "evt_abc123", published: true)
+
+# Portal Sessions
+session = mgmt.portal_sessions.create("ws_abc123", "app_jkl012")
+puts session["url"] # Redirect your customer here
+```
+
+## Client Options
+
+### Nahook::Client
+
+```ruby
+client = Nahook::Client.new("nhk_us_...",
+  timeout_ms: 30_000,                   # milliseconds, default
+  retries: 3                            # retry on 5xx/429/network errors
+)
+```
+
+### Configuration
+
+The SDK automatically routes requests to the correct regional API based on your API key prefix (`nhk_us_...` -> US, `nhk_eu_...` -> EU, `nhk_ap_...` -> Asia Pacific). No configuration needed.
+
+To override the base URL (for testing or local development):
+
+```ruby
+client = Nahook::Client.new("nhk_us_...", base_url: "http://localhost:3001")
+```
+
+For unit tests, mock the SDK client at the dependency injection boundary. For integration tests, override the base URL to point at a local server.
+
+### Nahook::Management
+
+```ruby
+mgmt = Nahook::Management.new("nhm_...",
+  timeout_ms: 30_000                    # milliseconds, default
+)
+# Note: Management does not support retries
+```
+
+## Batch Operations
+
+```ruby
+# Send to multiple endpoints (max 20)
+result = client.send_batch([
+  { endpoint_id: "ep_abc", payload: { order: 1 } },
+  { endpoint_id: "ep_def", payload: { order: 2 }, idempotency_key: "key-2" }
+])
+
+# Fan-out multiple event types (max 20)
+result = client.trigger_batch([
+  { event_type: "order.paid", payload: { order_id: "123" } },
+  { event_type: "user.created", payload: { user_id: "456" }, metadata: { "source" => "api" } }
+])
+```
+
+## Idempotency
+
+The `send` method auto-generates a UUID idempotency key if you don't provide one:
+
+```ruby
+# Auto-generated idempotency key
+client.send("ep_abc", payload: { order: 1 })
+
+# Explicit idempotency key
+client.send("ep_abc", payload: { order: 1 }, idempotency_key: "order-1-v1")
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.send("ep_abc", payload: { test: true })
+rescue Nahook::APIError => e
+  puts e.message       # Human-readable message
+  puts e.status        # HTTP status code
+  puts e.code          # Machine-readable error code
+  puts e.retryable?    # true for 5xx and 429
+  puts e.auth_error?   # true for 401, or 403 with token_disabled
+  puts e.not_found?    # true for 404
+  puts e.rate_limited? # true for 429
+  puts e.retry_after   # Retry-After header value (seconds), if present
+rescue Nahook::NetworkError => e
+  puts e.message       # "Network error: ..."
+  puts e.original_error # Original exception
+rescue Nahook::TimeoutError => e
+  puts e.message       # "Request timed out after 30000ms"
+  puts e.timeout_ms    # Timeout in milliseconds
+rescue Nahook::Error => e
+  # Catch-all for any SDK error
+end
+```
+
+## Retry Logic
+
+When `retries` is configured on `Nahook::Client`, the SDK automatically retries on:
+
+- HTTP 5xx responses
+- HTTP 429 (rate limited) -- respects `Retry-After` header
+- Network connection failures
+- Request timeouts
+
+Retry delay uses exponential backoff with full jitter (base 500ms, max 10s).
+
+## License
+
+MIT

data/lib/nahook/client.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Nahook
+  # Client for sending webhook payloads through the Nahook ingestion API.
+  #
+  # Supports sending to specific endpoints, fan-out by event type,
+  # and batch operations. Includes configurable retry with exponential backoff.
+  #
+  # @example Basic usage
+  #   client = Nahook::Client.new("nhk_us_your_api_key")
+  #   client.send("ep_abc123", payload: { order_id: "12345" })
+  #
+  # @example With options
+  #   client = Nahook::Client.new("nhk_us_your_api_key",
+  #     base_url: "https://custom.nahook.com",
+  #     timeout_ms: 15_000,
+  #     retries: 3
+  #   )
+  class Client
+    # @param api_key [String] API key (must start with "nhk_")
+    # @param base_url [String] API base URL
+    # @param timeout_ms [Integer] request timeout in milliseconds (default: 30000)
+    # @param retries [Integer] number of retry attempts for retryable errors
+    # @raise [ArgumentError] if the API key does not start with "nhk_"
+    def initialize(api_key, base_url: nil, timeout_ms: HttpClient::DEFAULT_TIMEOUT_MS, retries: 0)
+      unless api_key.start_with?("nhk_")
+        raise ArgumentError, "Invalid API key: must start with 'nhk_'"
+      end
+
+      resolved_url = base_url || HttpClient.resolve_base_url(api_key)
+
+      @http = HttpClient.new(
+        token: api_key,
+        base_url: resolved_url,
+        timeout_ms: timeout_ms,
+        retries: retries
+      )
+    end
+
+    # Send a payload to a specific endpoint.
+    #
+    # @param endpoint_id [String] the endpoint public ID (e.g. "ep_abc123")
+    # @param payload [Hash] the webhook payload
+    # @param idempotency_key [String, nil] optional idempotency key (auto-generated if omitted)
+    # @return [Hash] response with "deliveryId", "idempotencyKey", and "status" keys
+    # @raise [APIError] on API error responses
+    # @raise [NetworkError] on connection failures
+    # @raise [TimeoutError] on request timeout
+    def send(endpoint_id, payload:, idempotency_key: nil)
+      key = idempotency_key || SecureRandom.uuid
+
+      @http.request(
+        method: :post,
+        path: "/api/ingest/#{CGI.escape(endpoint_id)}",
+        body: {
+          "payload" => payload,
+          "idempotencyKey" => key
+        }
+      )
+    end
+
+    # Fan-out a payload by event type to all subscribed endpoints.
+    #
+    # @param event_type [String] the event type name (e.g. "order.paid")
+    # @param payload [Hash] the webhook payload
+    # @param metadata [Hash, nil] optional metadata key-value pairs
+    # @return [Hash] response with "eventTypeId", "deliveryIds", and "status" keys
+    # @raise [APIError] on API error responses
+    def trigger(event_type, payload:, metadata: nil)
+      body = { "payload" => payload }
+      body["metadata"] = metadata if metadata
+
+      @http.request(
+        method: :post,
+        path: "/api/ingest/event/#{CGI.escape(event_type)}",
+        body: body
+      )
+    end
+
+    # Batch send to multiple specific endpoints (max 20 items).
+    #
+    # @param items [Array<Hash>] list of items, each with :endpoint_id, :payload, and optional :idempotency_key
+    # @return [Hash] response with "items" key containing per-item results
+    # @raise [APIError] on API error responses
+    #
+    # @example
+    #   client.send_batch([
+    #     { endpoint_id: "ep_abc", payload: { order: 1 } },
+    #     { endpoint_id: "ep_def", payload: { order: 2 }, idempotency_key: "key-2" }
+    #   ])
+    def send_batch(items)
+      mapped = items.map do |item|
+        entry = {
+          "endpointId" => item[:endpoint_id] || item["endpoint_id"],
+          "payload" => item[:payload] || item["payload"]
+        }
+        key = item[:idempotency_key] || item["idempotency_key"]
+        entry["idempotencyKey"] = key if key
+        entry
+      end
+
+      @http.request(
+        method: :post,
+        path: "/api/ingest/batch",
+        body: { "items" => mapped }
+      )
+    end
+
+    # Batch fan-out by event types (max 20 items).
+    #
+    # @param items [Array<Hash>] list of items, each with :event_type, :payload, and optional :metadata
+    # @return [Hash] response with "items" key containing per-item results
+    # @raise [APIError] on API error responses
+    #
+    # @example
+    #   client.trigger_batch([
+    #     { event_type: "order.paid", payload: { order_id: "123" } },
+    #     { event_type: "user.created", payload: { user_id: "456" } }
+    #   ])
+    def trigger_batch(items)
+      mapped = items.map do |item|
+        entry = {
+          "eventType" => item[:event_type] || item["event_type"],
+          "payload" => item[:payload] || item["payload"]
+        }
+        meta = item[:metadata] || item["metadata"]
+        entry["metadata"] = meta if meta
+        entry
+      end
+
+      @http.request(
+        method: :post,
+        path: "/api/ingest/event/batch",
+        body: { "items" => mapped }
+      )
+    end
+  end
+end

data/lib/nahook/errors.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Nahook
+  # Base error for all Nahook SDK errors.
+  class Error < StandardError; end
+
+  # Raised when the Nahook API returns an error response (4xx/5xx).
+  #
+  # @example Handling an API error
+  #   begin
+  #     client.send("ep_123", payload: { order: 1 })
+  #   rescue Nahook::APIError => e
+  #     puts e.status     # => 404
+  #     puts e.code       # => "not_found"
+  #     puts e.retryable? # => false
+  #   end
+  class APIError < Error
+    # @return [Integer] HTTP status code
+    attr_reader :status
+
+    # @return [String] machine-readable error code from the API
+    attr_reader :code
+
+    # @return [Integer, nil] seconds the client should wait before retrying
+    attr_reader :retry_after
+
+    # @param status [Integer] HTTP status code
+    # @param code [String] machine-readable error code
+    # @param message [String] human-readable error message
+    # @param retry_after [Integer, nil] Retry-After header value in seconds
+    def initialize(status, code, message, retry_after = nil)
+      @status = status
+      @code = code
+      @retry_after = retry_after
+      super(message)
+    end
+
+    # Whether this error is safe to retry (5xx or 429).
+    #
+    # @return [Boolean]
+    def retryable?
+      status >= 500 || status == 429
+    end
+
+    # Whether this is an authentication or authorization error.
+    #
+    # @return [Boolean]
+    def auth_error?
+      status == 401 || (status == 403 && code == "token_disabled")
+    end
+
+    # Whether the requested resource was not found.
+    #
+    # @return [Boolean]
+    def not_found?
+      status == 404
+    end
+
+    # Whether the request was rate limited.
+    #
+    # @return [Boolean]
+    def rate_limited?
+      status == 429
+    end
+
+    # Whether the request failed validation.
+    #
+    # @return [Boolean]
+    def validation_error?
+      status == 400
+    end
+  end
+
+  # Raised when a network-level failure occurs (no HTTP response received).
+  class NetworkError < Error
+    # @return [Exception] the underlying error that caused this failure
+    attr_reader :original_error
+
+    # @param original_error [Exception] the original exception
+    def initialize(original_error)
+      @original_error = original_error
+      super("Network error: #{original_error.message}")
+    end
+  end
+
+  # Raised when a request exceeds the configured timeout.
+  class TimeoutError < Error
+    # @return [Integer] the timeout in milliseconds
+    attr_reader :timeout_ms
+
+    # @param timeout_ms [Integer] the configured timeout in milliseconds
+    def initialize(timeout_ms)
+      @timeout_ms = timeout_ms
+      super("Request timed out after #{timeout_ms}ms")
+    end
+  end
+end

data/lib/nahook/http_client.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "cgi"
+
+module Nahook
+  # Low-level HTTP client used by both {Client} and {Management}.
+  #
+  # Handles request execution, retry logic with exponential backoff,
+  # and error parsing. Not intended for direct use.
+  #
+  # @api private
+  class HttpClient
+    DEFAULT_BASE_URL  = "https://api.nahook.com"
+    DEFAULT_TIMEOUT_MS = 30_000
+    BASE_DELAY_MS     = 500
+    MAX_DELAY_MS      = 10_000
+
+    REGION_BASE_URLS = {
+      "us" => "https://us.api.nahook.com",
+      "eu" => "https://eu.api.nahook.com",
+      "ap" => "https://ap.api.nahook.com",
+    }.freeze
+
+    # @api private
+    def self.resolve_base_url(token)
+      if (m = token.match(/\Anhk_([a-z]{2})_/))
+        REGION_BASE_URLS[m[1]] || DEFAULT_BASE_URL
+      else
+        DEFAULT_BASE_URL
+      end
+    end
+
+    # @param token [String] bearer token for authentication
+    # @param base_url [String] API base URL
+    # @param timeout_ms [Integer] request timeout in milliseconds (default: 30000)
+    # @param retries [Integer] number of retry attempts for retryable errors
+    def initialize(token:, base_url: DEFAULT_BASE_URL, timeout_ms: DEFAULT_TIMEOUT_MS, retries: 0)
+      @token      = token
+      @retries    = retries
+      @timeout_ms = timeout_ms
+
+      timeout_secs = timeout_ms / 1000.0
+      @conn = Faraday.new(url: base_url.chomp("/")) do |f|
+        f.options.timeout      = timeout_secs
+        f.options.open_timeout = timeout_secs
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    # Execute an HTTP request with optional retry logic.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :patch, :delete)
+    # @param path [String] request path (will be appended to base URL)
+    # @param body [Hash, nil] request body (will be JSON-encoded)
+    # @param query [Hash, nil] query parameters
+    # @return [Hash, nil] parsed JSON response, or nil for 204
+    # @raise [APIError] on 4xx/5xx responses
+    # @raise [NetworkError] on connection failures
+    # @raise [TimeoutError] on request timeout
+    def request(method:, path:, body: nil, query: nil)
+      execute_with_retry(method, path, body, query)
+    end
+
+    private
+
+    def execute_with_retry(method, path, body, query)
+      last_error = nil
+
+      (0..@retries).each do |attempt|
+        if attempt > 0
+          retry_after_ms = last_error.is_a?(APIError) ? (last_error.retry_after || 0) * 1000 : nil
+          delay = calculate_delay(attempt - 1, retry_after_ms)
+          sleep(delay / 1000.0)
+        end
+
+        begin
+          response = perform_request(method, path, body, query)
+
+          unless response.success?
+            error = parse_error(response)
+            if attempt < @retries && retryable?(error)
+              last_error = error
+              next
+            end
+            raise error
+          end
+
+          return nil if response.status == 204
+          return JSON.parse(response.body)
+
+        rescue APIError
+          raise
+
+        rescue Faraday::TimeoutError => e
+          last_error = TimeoutError.new(@timeout_ms)
+          raise last_error unless attempt < @retries && retryable?(last_error)
+
+        rescue Faraday::ConnectionFailed => e
+          last_error = NetworkError.new(e)
+          raise last_error unless attempt < @retries && retryable?(last_error)
+        end
+      end
+
+      raise last_error
+    end
+
+    def perform_request(method, path, body, query)
+      @conn.run_request(method, path, nil, request_headers(body)) do |req|
+        req.body = JSON.generate(body) if body
+        if query
+          query.each do |key, value|
+            req.params[key.to_s] = value.to_s unless value.nil?
+          end
+        end
+      end
+    end
+
+    def request_headers(body)
+      headers = {
+        "Authorization" => "Bearer #{@token}",
+        "Accept"        => "application/json",
+        "User-Agent"    => "nahook-ruby/#{Nahook::VERSION}"
+      }
+      headers["Content-Type"] = "application/json" if body
+      headers
+    end
+
+    def parse_error(response)
+      retry_after = response.headers["retry-after"]
+      retry_after_secs = retry_after ? retry_after.to_i : nil
+
+      begin
+        body = JSON.parse(response.body)
+        code    = body.dig("error", "code") || "unknown"
+        message = body.dig("error", "message") || response.reason_phrase || "Unknown error"
+      rescue JSON::ParserError
+        code    = "unknown"
+        message = response.reason_phrase || "Unknown error"
+      end
+
+      APIError.new(response.status, code, message, retry_after_secs)
+    end
+
+    def calculate_delay(attempt, retry_after_ms = nil)
+      if retry_after_ms && retry_after_ms > 0
+        return retry_after_ms
+      end
+
+      exponential = [MAX_DELAY_MS, BASE_DELAY_MS * (2**attempt)].min
+      exponential * rand
+    end
+
+    def retryable?(error)
+      case error
+      when APIError     then error.retryable?
+      when NetworkError then true
+      when TimeoutError then true
+      else false
+      end
+    end
+  end
+end

data/lib/nahook/management.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Nahook
+  # Client for the Nahook Management API.
+  #
+  # Provides programmatic access to manage workspaces, endpoints, event types,
+  # applications, subscriptions, and portal sessions. Intended for server-side
+  # use with a management token.
+  #
+  # Unlike {Client}, the Management client does not support retries --
+  # management operations are not idempotent by default.
+  #
+  # @example
+  #   mgmt = Nahook::Management.new("nhm_your_token")
+  #
+  #   # List endpoints
+  #   result = mgmt.endpoints.list("ws_abc123")
+  #   result["data"].each { |ep| puts ep["url"] }
+  #
+  #   # Create an endpoint
+  #   endpoint = mgmt.endpoints.create("ws_abc123",
+  #     url: "https://example.com/webhook",
+  #     description: "Production webhook"
+  #   )
+  class Management
+    # @return [Resources::Endpoints]
+    attr_reader :endpoints
+
+    # @return [Resources::EventTypes]
+    attr_reader :event_types
+
+    # @return [Resources::Applications]
+    attr_reader :applications
+
+    # @return [Resources::Subscriptions]
+    attr_reader :subscriptions
+
+    # @return [Resources::PortalSessions]
+    attr_reader :portal_sessions
+
+    # @return [Resources::Environments]
+    attr_reader :environments
+
+    # @param token [String] management token (must start with "nhm_")
+    # @param base_url [String] API base URL
+    # @param timeout_ms [Integer] request timeout in milliseconds (default: 30000)
+    # @raise [ArgumentError] if the token does not start with "nhm_"
+    def initialize(token, base_url: HttpClient::DEFAULT_BASE_URL, timeout_ms: HttpClient::DEFAULT_TIMEOUT_MS)
+      unless token.start_with?("nhm_")
+        raise ArgumentError, "Invalid management token: must start with 'nhm_'"
+      end
+
+      http = HttpClient.new(token: token, base_url: base_url, timeout_ms: timeout_ms)
+
+      @endpoints       = Resources::Endpoints.new(http)
+      @event_types     = Resources::EventTypes.new(http)
+      @applications    = Resources::Applications.new(http)
+      @subscriptions   = Resources::Subscriptions.new(http)
+      @portal_sessions = Resources::PortalSessions.new(http)
+      @environments    = Resources::Environments.new(http)
+    end
+  end
+end