nahook 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06f9b63028d18b1d6b6c6c1c89a1c2583c3407faf379e66cc21f8a15a4558829
-  data.tar.gz: 96c50392e9d71244838c5726168117481310e8f48b269ecb4305b97bd253e057
+  metadata.gz: f3bd344552a65f2ef26b92e4578433a42c3681a8a9f524391cf062973273a416
+  data.tar.gz: 73d4cfa42d44d9beaafdf4c94fabad2f4dba8c5224194d73c5af64d6e799ae01
 SHA512:
-  metadata.gz: 32e6ce367ebaa16276a0580ef1caea905e0926cf312223b7fdd6e2c0ce9628ba4498c4d15e040e336600d7d88c204c1d595ee5e12d34491b821b6bd875a859bf
-  data.tar.gz: 3fd57195f0019f5bfe8347a60fc0a317a0fc15e5b29525b55cf2de7e628ceb7205720df0d1dc940ee749756ef7901ad981a69325312bfd23ba05438fa22c6375
+  metadata.gz: f6ae693721c3e083de6eb51e11ac1da781f5478549c73a723c23a235d1534f3c1b6108e17c43151988d54429aea5cc5e9b4aabb94ebea2fcdac1f54c942e629c
+  data.tar.gz: 1d4570d3add3fd70744c8e03469d02ffe60612b96a59879ef86a0016c053fb25b7ee2be06730c9e4047dfa4bd8d502eb7d2f88e7ad3c2a8af0fcce380c7b13aa

data/README.md

@@ -88,6 +88,56 @@ session = mgmt.portal_sessions.create("ws_abc123", "app_jkl012")
 puts session["url"] # Redirect your customer here
 ```
 
+### Deliveries
+
+Read access to a workspace's webhook deliveries. There is no create/update/delete on this resource — deliveries are produced by the ingestion path and observed through these methods.
+
+```ruby
+# List deliveries for an endpoint, newest-first, cursor-paginated.
+# `next_cursor` is OPAQUE — pass it back verbatim to fetch the next page.
+page = mgmt.deliveries.list("ws_abc123", "ep_def456", limit: 50)
+page.data.each { |d| puts "#{d['id']} #{d['status']}" }
+
+while page.next_cursor
+  page = mgmt.deliveries.list("ws_abc123", "ep_def456", cursor: page.next_cursor)
+  page.data.each { |d| puts "#{d['id']} #{d['status']}" }
+end
+
+# Filter by status. Valid values: "pending", "delivering", "delivered",
+# "scheduled_retry", "failed", "dead_letter".
+failed = mgmt.deliveries.list("ws_abc123", "ep_def456", status: "failed")
+
+# Fetch a single delivery (metadata only).
+delivery = mgmt.deliveries.get("ws_abc123", "del_xyz")
+puts delivery["status"]         # => "delivered"
+puts delivery["totalAttempts"]  # => 1
+puts delivery["hasPayload"]     # => true
+
+# Fetch with the payload envelope. The envelope is a tagged hash whose
+# "status" is one of: "available", "forbidden", "processing", "not_found",
+# "error". The endpoint stays HTTP 200 for all 5 -- the envelope status
+# carries access-level reality, so do NOT rescue on the non-"available" ones.
+delivery = mgmt.deliveries.get("ws_abc123", "del_xyz", include_payload: true)
+case delivery["payload"]["status"]
+when "available"
+  body         = delivery["payload"]["data"]          # decoded JSON
+  content_type = delivery["payload"]["contentType"]   # "application/json"
+when "forbidden"
+  # Workspace plan does not include payload storage.
+when "processing"
+  # Delivery still in flight; payload may be racing the read.
+when "not_found"
+  # Terminal delivery without stored payload (older row, or plan was lower at ingest).
+when "error"
+  # Transient infrastructure failure -- safe to retry.
+end
+
+# List attempts for a delivery in chronological order (oldest first).
+# The attempt "status" is an opaque string, not an enum.
+attempts = mgmt.deliveries.get_attempts("ws_abc123", "del_xyz")
+attempts.each { |a| puts "##{a['attemptNumber']} #{a['status']} #{a['responseStatusCode']}" }
+```
+
 ## Client Options
 
 ### Nahook::Client
@@ -111,6 +161,40 @@ 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.
 
+### Custom HTTP adapter / Faraday connection
+
+The SDK ships with the `:net_http_persistent` Faraday adapter by default, which keeps a per-thread TCP/TLS pool — back-to-back `send` / `trigger` calls reuse the same connection and skip the DNS + TCP + TLS handshake. For most apps that's all you need.
+
+Two escape hatches when you want more control:
+
+**Swap the adapter.** Useful for high-throughput workloads on `:typhoeus` (curl-multi) without building a full Faraday connection:
+
+```ruby
+require "faraday/typhoeus"  # add the gem to your Gemfile
+
+client = Nahook::Client.new("nhk_us_...", adapter: :typhoeus)
+```
+
+Whatever adapter you name must be available — Faraday 2 split adapters into separate gems (`faraday-typhoeus`, `faraday-net_http`, etc.).
+
+**Supply a fully-configured Faraday connection.** When you need middleware (Datadog / OpenTelemetry instrumentation), a custom proxy, mTLS, request retries beyond what the SDK ships, etc.:
+
+```ruby
+conn = Faraday.new(url: "https://us.api.nahook.com") do |f|
+  f.options.timeout      = 15
+  f.options.open_timeout = 5
+  # Plug in your tracing/observability middleware. The exact symbol/class
+  # depends on the gem — e.g. `Datadog::Tracing::Contrib::Faraday::Middleware`
+  # from `ddtrace`, or `OpenTelemetry::Instrumentation::Faraday::Middlewares::TracerMiddleware`.
+  # f.use SomeTracingMiddleware
+  f.adapter :net_http_persistent
+end
+
+client = Nahook::Client.new("nhk_us_...", connection: conn)
+```
+
+When `connection:` is supplied, `base_url`, `timeout_ms`, and `adapter` are ignored — the connection you pass in is used verbatim. The same `adapter:` and `connection:` kwargs are accepted by `Nahook::Management.new`.
+
 ### Nahook::Management
 
 ```ruby

data/lib/nahook/client.rb

@@ -23,20 +23,33 @@ module Nahook
     # @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
+    # @param adapter [Symbol, nil] Faraday adapter to use (defaults to
+    #   `:net_http_persistent` for keep-alive). Useful for swapping to e.g.
+    #   `:typhoeus` for high-throughput workloads without building a full
+    #   Faraday connection.
+    # @param connection [Faraday::Connection, nil] a fully-configured Faraday
+    #   connection. When supplied, `base_url`, `timeout_ms`, and `adapter`
+    #   are ignored — the caller owns connection configuration (custom
+    #   middleware, instrumentation, proxies, mTLS, etc.).
     # @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)
+    def initialize(api_key, base_url: nil, timeout_ms: HttpClient::DEFAULT_TIMEOUT_MS,
+                   retries: 0, adapter: nil, connection: nil)
       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(
+      http_kwargs = {
         token: api_key,
         base_url: resolved_url,
         timeout_ms: timeout_ms,
-        retries: retries
-      )
+        retries: retries,
+      }
+      http_kwargs[:adapter]    = adapter    if adapter
+      http_kwargs[:connection] = connection if connection
+
+      @http = HttpClient.new(**http_kwargs)
     end
 
     # Send a payload to a specific endpoint.

data/lib/nahook/http_client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "faraday/net_http_persistent"
 require "json"
 require "cgi"
 
@@ -17,6 +18,12 @@ module Nahook
     BASE_DELAY_MS     = 500
     MAX_DELAY_MS      = 10_000
 
+    # The default Faraday adapter. `net_http_persistent` keeps a per-thread
+    # TCP/TLS pool so back-to-back requests skip the full handshake. Callers
+    # can override via the `adapter:` kwarg, or bypass adapter selection
+    # entirely by passing a pre-built `connection:`.
+    DEFAULT_ADAPTER = :net_http_persistent
+
     REGION_BASE_URLS = {
       "us" => "https://us.api.nahook.com",
       "eu" => "https://eu.api.nahook.com",
@@ -36,16 +43,30 @@ module Nahook
     # @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
+    # @param adapter [Symbol] Faraday adapter to use when no custom connection
+    #   is supplied. Defaults to `:net_http_persistent` (keep-alive). Other
+    #   options the caller can pass: `:net_http`, `:typhoeus`, `:patron`, etc.
+    #   Whatever adapter is named must be available — Faraday 2 split adapters
+    #   into separate gems, so e.g. `:typhoeus` requires `gem "faraday-typhoeus"`.
+    # @param connection [Faraday::Connection, nil] a fully-configured Faraday
+    #   connection to use verbatim. When supplied, `base_url`, `timeout_ms`,
+    #   and `adapter` are ignored — the caller owns connection configuration
+    #   (custom middleware, instrumentation, proxies, mTLS, etc.).
+    def initialize(token:, base_url: DEFAULT_BASE_URL, timeout_ms: DEFAULT_TIMEOUT_MS,
+                   retries: 0, adapter: DEFAULT_ADAPTER, connection: nil)
+      @token   = token
+      @retries = retries
+
+      if connection
+        @conn = connection
+        # Prefer the supplied connection's own timeout so `TimeoutError` reports
+        # the value the caller actually configured. Faraday options.timeout is
+        # in seconds — convert. Fall back to the constructor kwarg if unset.
+        conn_timeout_secs = connection.options.timeout
+        @timeout_ms = conn_timeout_secs ? (conn_timeout_secs * 1000).to_i : timeout_ms
+      else
+        @timeout_ms = timeout_ms
+        @conn = build_default_connection(base_url, timeout_ms, adapter)
       end
     end
 
@@ -160,5 +181,14 @@ module Nahook
       else false
       end
     end
+
+    def build_default_connection(base_url, timeout_ms, adapter)
+      timeout_secs = timeout_ms / 1000.0
+      Faraday.new(url: base_url.chomp("/")) do |f|
+        f.options.timeout      = timeout_secs
+        f.options.open_timeout = timeout_secs
+        f.adapter adapter
+      end
+    end
   end
 end

data/lib/nahook/management.rb

@@ -41,16 +41,29 @@ module Nahook
     # @return [Resources::Environments]
     attr_reader :environments
 
+    # @return [Resources::Deliveries]
+    attr_reader :deliveries
+
     # @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)
+    # @param adapter [Symbol, nil] Faraday adapter to use (defaults to
+    #   `:net_http_persistent` for keep-alive). See {Client#initialize}.
+    # @param connection [Faraday::Connection, nil] a fully-configured Faraday
+    #   connection. When supplied, `base_url`, `timeout_ms`, and `adapter`
+    #   are ignored.
     # @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)
+    def initialize(token, base_url: HttpClient::DEFAULT_BASE_URL, timeout_ms: HttpClient::DEFAULT_TIMEOUT_MS,
+                   adapter: nil, connection: nil)
       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)
+      http_kwargs = { token: token, base_url: base_url, timeout_ms: timeout_ms }
+      http_kwargs[:adapter]    = adapter    if adapter
+      http_kwargs[:connection] = connection if connection
+
+      http = HttpClient.new(**http_kwargs)
 
       @endpoints       = Resources::Endpoints.new(http)
       @event_types     = Resources::EventTypes.new(http)
@@ -58,6 +71,7 @@ module Nahook
       @subscriptions   = Resources::Subscriptions.new(http)
       @portal_sessions = Resources::PortalSessions.new(http)
       @environments    = Resources::Environments.new(http)
+      @deliveries      = Resources::Deliveries.new(http)
     end
   end
 end

data/lib/nahook/resources/deliveries.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Nahook
+  # Generic paginated result returned by cursor-paginated list endpoints.
+  #
+  # @!attribute [rw] data
+  #   @return [Array<Hash>] the page of results
+  # @!attribute [rw] next_cursor
+  #   @return [String, nil] opaque cursor for the next page, or nil if this is
+  #     the last page. Pass back verbatim into the next list call.
+  PaginatedResult = Struct.new(:data, :next_cursor)
+
+  module Resources
+    # Read access to a workspace's webhook deliveries via the Management API.
+    #
+    # All methods are paginated or single-resource reads -- this resource has
+    # no create/update/delete operations. Deliveries are produced by the
+    # ingestion path and consumed by the worker; the Management API exposes
+    # only their observable state.
+    #
+    # @example
+    #   mgmt = Nahook::Management.new("nhm_token")
+    #
+    #   # List a page of deliveries for an endpoint
+    #   page = mgmt.deliveries.list("ws_abc123", "ep_def456", limit: 50)
+    #   page.data.each { |d| puts d["id"] }
+    #   next_page = mgmt.deliveries.list("ws_abc123", "ep_def456", cursor: page.next_cursor)
+    #
+    #   # Fetch a single delivery (metadata only)
+    #   delivery = mgmt.deliveries.get("ws_abc123", "del_xyz")
+    #
+    #   # Fetch with payload envelope
+    #   delivery = mgmt.deliveries.get("ws_abc123", "del_xyz", include_payload: true)
+    #
+    #   # List attempts (chronological order)
+    #   attempts = mgmt.deliveries.get_attempts("ws_abc123", "del_xyz")
+    class Deliveries
+      # @api private
+      # @param http [Nahook::HttpClient]
+      def initialize(http)
+        @http = http
+      end
+
+      # List deliveries for an endpoint, newest-first, with opaque cursor pagination.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param endpoint_id [String] the endpoint public ID
+      # @param limit [Integer, nil] page size, server-capped (default 50, max 100)
+      # @param cursor [String, nil] opaque cursor from a previous response's
+      #   {PaginatedResult#next_cursor}. Pass through unchanged.
+      # @param status [String, nil] filter by delivery status. One of:
+      #   "pending", "delivering", "delivered", "scheduled_retry", "failed",
+      #   "dead_letter".
+      # @return [PaginatedResult] paginated result whose +data+ is an array of
+      #   delivery hashes and +next_cursor+ is a String or nil.
+      def list(workspace_id, endpoint_id, limit: nil, cursor: nil, status: nil)
+        raw = @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/endpoints/#{e(endpoint_id)}/deliveries",
+          query: { "limit" => limit, "cursor" => cursor, "status" => status }
+        )
+        PaginatedResult.new(raw["deliveries"] || [], raw["nextCursor"])
+      end
+
+      # Get a single delivery's metadata, optionally including the payload envelope.
+      #
+      # When +include_payload+ is true, the response includes a "payload"
+      # envelope whose "status" is one of: "available", "forbidden",
+      # "processing", "not_found", "error". The endpoint stays 200 for all 5 --
+      # the envelope status carries access-level reality. This method does NOT
+      # raise on "forbidden"/"processing"/"not_found"/"error".
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param delivery_id [String] the delivery public ID (starts with "del_")
+      # @param include_payload [Boolean] if true, sends ?include=payload and
+      #   the response includes a "payload" envelope (default false).
+      # @return [Hash] the delivery; includes a "payload" envelope when
+      #   +include_payload+ is true.
+      def get(workspace_id, delivery_id, include_payload: false)
+        query = include_payload ? { "include" => "payload" } : nil
+        @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/deliveries/#{e(delivery_id)}",
+          query: query
+        )
+      end
+
+      # List delivery attempts for a single delivery, in chronological order
+      # (oldest first).
+      #
+      # The attempt "status" field is an opaque string ("failed", "success",
+      # etc.) -- treat it as a string, not an enum.
+      #
+      # @param workspace_id [String] the workspace public ID
+      # @param delivery_id [String] the delivery public ID (starts with "del_")
+      # @return [Array<Hash>] attempts in chronological order
+      def get_attempts(workspace_id, delivery_id)
+        @http.request(
+          method: :get,
+          path: "/management/v1/workspaces/#{e(workspace_id)}/deliveries/#{e(delivery_id)}/attempts"
+        )
+      end
+
+      private
+
+      def e(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/nahook/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nahook
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/nahook.rb

@@ -11,6 +11,7 @@ require_relative "nahook/resources/applications"
 require_relative "nahook/resources/subscriptions"
 require_relative "nahook/resources/portal_sessions"
 require_relative "nahook/resources/environments"
+require_relative "nahook/resources/deliveries"
 
 # Official Ruby SDK for the Nahook webhook platform.
 #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nahook
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Nahook
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-25 00:00:00.000000000 Z
+date: 2026-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http_persistent
+  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 client for sending webhooks and managing resources through the Nahook
   API. Supports direct endpoint delivery, fan-out by event type, batch operations,
   and full management API access.
@@ -41,6 +55,7 @@ files:
 - lib/nahook/http_client.rb
 - lib/nahook/management.rb
 - lib/nahook/resources/applications.rb
+- lib/nahook/resources/deliveries.rb
 - lib/nahook/resources/endpoints.rb
 - lib/nahook/resources/environments.rb
 - lib/nahook/resources/event_types.rb