hookd-client 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e020dd2f4705d56fdc57c2a7da6daba65231a9676a534037104d98cd401bcdaa
-  data.tar.gz: 505b0f7151a9b7dfc02638b7b6c5978be6ef9832987c85b2b6b27ca7262cf8d5
+  metadata.gz: eeded85d2f08978163e752d64342ca5e52fd1cf1fcaade7da0305caeb53e03b5
+  data.tar.gz: 966b9eaf4f9d25549f0473471e446628af82c8ea160e5ebbefef518aa1a6fa08
 SHA512:
-  metadata.gz: 32da3c04302a2e04ce0d1ea42b05f438d80e12fadfcae77de8720d1e5894d56ada4ab8b5db77d934b3bec64378d8140b747b761996931c39bd1f9b70656f94e9
-  data.tar.gz: 78080b0c8e32c86d7634e8d137bfa8a9471e03351a4449ec6f969f12d452ffbd912d6e9ad91ef9ce832853dcd8d3c102ad567d6d3d706e1f49349158c1ebebb4
+  metadata.gz: 0224226f06a4996e6034caabb6182f31d9a7848262a44bd8ed0571fe898a7706f4b95c46bdb0e5617c0bc04f948fc5dc8e5bffbb46cd20de04d9bdcacbe0b2fe
+  data.tar.gz: 88e85eab06e2d351b6231f2769104b6d6a3320ae1cb2ccf68f432dad732a689ee5f50386ca69199534a76fb09425ddfd70f7d711b03b8e4d836e2b25415784ad

data/README.md

@@ -130,8 +130,20 @@ hooks = client.register(count: 5)
 # => [#<Hookd::Hook id="abc123" ...>, #<Hookd::Hook id="def456" ...>, ...]
 ```
 
+**Long-lived hook (survives restarts, for stored-XSS style detection):**
+```ruby
+hook = client.register(ttl: '7d', metadata: { target: 'acme', field: 'profile.bio' })
+# => #<Hookd::Hook id="abc123" ...>
+hook.expires_at # => "2025-10-08T10:30:00Z"
+hook.metadata   # => {"target"=>"acme", "field"=>"profile.bio"}
+```
+
 Parameters:
 - `count` (Integer, optional) - Number of hooks to create (default: 1)
+- `ttl` (String, optional) - Lifetime as a Go duration (`"168h"`) or day count
+  (`"7d"`); a value above the server's ephemeral `hook_ttl` registers a durable
+  long-lived hook. Omit for an ephemeral hook.
+- `metadata` (Hash, optional) - Stored with the hook and echoed back on poll
 
 Returns:
 - `Hookd::Hook` object when `count` is 1 or not specified
@@ -143,6 +155,21 @@ Raises:
 - `Hookd::ServerError` - Server error (5xx)
 - `Hookd::ConnectionError` - Connection failed
 
+##### `#activity`
+
+List the long-lived hooks that currently have pending interactions, so you can
+discover which fired without polling each one; drain the details with `#poll`.
+
+```ruby
+client.activity.each do |a|
+  puts "#{a.hook.id} fired #{a.pending_count} time(s), meta=#{a.hook.metadata}"
+  client.poll(a.hook.id)
+end
+# => [#<Hookd::HookActivity hook=abc123 pending=3>, ...]
+```
+
+Returns: Array of `Hookd::HookActivity` (empty when none fired or long-lived is disabled)
+
 ##### `#poll(hook_id)`
 
 Poll for interactions captured by a single hook.
@@ -233,6 +260,17 @@ Attributes:
 - `http` (String) - HTTP endpoint
 - `https` (String) - HTTPS endpoint
 - `created_at` (String) - Creation timestamp
+- `expires_at` (String, nil) - Expiry timestamp (long-lived hooks)
+- `metadata` (Hash, nil) - Metadata attached at registration
+
+#### `Hookd::HookActivity`
+
+Represents a long-lived hook that has pending interactions (returned by `#activity`).
+
+Attributes:
+- `hook` (`Hookd::Hook`) - The long-lived hook that fired
+- `pending_count` (Integer) - Number of interactions awaiting poll
+- `last_interaction_at` (String) - Timestamp of the most recent interaction
 
 #### `Hookd::Interaction`
 

data/lib/hookd/client.rb

@@ -22,25 +22,20 @@ module Hookd
 
     # Register one or more hooks
     # @param count [Integer, nil] number of hooks to register (default: 1)
+    # @param ttl [String, nil] lifetime as a Go duration ("168h") or day count
+    #   ("7d"); a value above the server's ephemeral hook_ttl registers a durable
+    #   long-lived hook. Omit for an ephemeral hook.
+    # @param metadata [Hash, nil] arbitrary data stored with the hook and echoed
+    #   back on poll
     # @return [Hookd::Hook, Array<Hookd::Hook>] single hook or array of hooks
     # @raise [Hookd::AuthenticationError] if authentication fails
     # @raise [Hookd::ServerError] if server returns 5xx
     # @raise [Hookd::ConnectionError] if connection fails
     # @raise [ArgumentError] if count is invalid
-    def register(count: nil)
-      body = count.nil? ? nil : { count: count }
-
+    def register(count: nil, ttl: nil, metadata: nil)
       raise ArgumentError, 'count must be a positive integer' if count && (!count.is_a?(Integer) || count < 1)
 
-      response = post('/register', body)
-
-      # Single hook response (backward compatible)
-      return Hook.from_hash(response) if response.key?('id')
-
-      # Multiple hooks response
-      return [] if response['hooks'].nil? || response['hooks'].empty?
-
-      response['hooks'].map { |h| Hook.from_hash(h) }
+      parse_register_response(post('/register', register_body(count, ttl, metadata)))
     end
 
     # Poll for interactions on a hook
@@ -92,8 +87,45 @@ module Hookd
       get('/metrics')
     end
 
+    # List long-lived hooks that currently have pending interactions, so you can
+    # discover which of your long-lived hooks fired without polling each one.
+    # Drain the details with #poll. Returns an empty array when none have fired
+    # (or the server has long-lived hooks disabled).
+    # @return [Array<Hookd::HookActivity>]
+    # @raise [Hookd::AuthenticationError] if authentication fails
+    # @raise [Hookd::ServerError] if server returns 5xx
+    # @raise [Hookd::ConnectionError] if connection fails
+    def activity
+      response = get('/activity')
+
+      hooks = response['hooks']
+      return [] if hooks.nil? || hooks.empty? || !hooks.is_a?(Array)
+
+      hooks.map { |h| HookActivity.from_hash(h) }
+    rescue NoMethodError => e
+      raise Error, "Invalid response format: #{e.message}"
+    end
+
     private
 
+    def register_body(count, ttl, metadata)
+      body = {}
+      body[:count] = count unless count.nil?
+      body[:ttl] = ttl unless ttl.nil?
+      body[:metadata] = metadata unless metadata.nil?
+      body.empty? ? nil : body
+    end
+
+    def parse_register_response(response)
+      # Single hook response (backward compatible)
+      return Hook.from_hash(response) if response.key?('id')
+
+      # Multiple hooks response
+      return [] if response['hooks'].nil? || response['hooks'].empty?
+
+      response['hooks'].map { |h| Hook.from_hash(h) }
+    end
+
     def get(path)
       url = "#{@server}#{path}"
       response = @http.get(url)

data/lib/hookd/hook.rb

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 
 module Hookd
-  # Represents a registered hook with DNS and HTTP endpoints
+  # Represents a registered hook with DNS and HTTP endpoints. expires_at and
+  # metadata are populated for long-lived hooks (registered with a ttl) and nil
+  # otherwise.
   class Hook
-    attr_reader :id, :dns, :http, :https, :created_at
+    attr_reader :id, :dns, :http, :https, :created_at, :expires_at, :metadata
 
-    def initialize(id:, dns:, http:, https:, created_at:)
+    def initialize(id:, dns:, http:, https:, created_at:, expires_at: nil, metadata: nil)
       @id = id
       @dns = dns
       @http = http
       @https = https
       @created_at = created_at
+      @expires_at = expires_at
+      @metadata = metadata
     end
 
     # Create a Hook from API response hash
@@ -22,7 +26,9 @@ module Hookd
         dns: hash['dns'],
         http: hash['http'],
         https: hash['https'],
-        created_at: hash['created_at']
+        created_at: hash['created_at'],
+        expires_at: hash['expires_at'],
+        metadata: hash['metadata']
       )
     end
 

data/lib/hookd/hook_activity.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Hookd
+  # Summarises a long-lived hook that currently has pending interactions,
+  # returned by Client#activity.
+  class HookActivity
+    attr_reader :hook, :pending_count, :last_interaction_at
+
+    def initialize(hook:, pending_count:, last_interaction_at:)
+      @hook = hook
+      @pending_count = pending_count
+      @last_interaction_at = last_interaction_at
+    end
+
+    # Create a HookActivity from an API response hash
+    def self.from_hash(hash)
+      raise ArgumentError, "Invalid hash: expected Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      new(
+        hook: Hook.from_hash(hash['hook']),
+        pending_count: hash['pending_count'],
+        last_interaction_at: hash['last_interaction_at']
+      )
+    end
+
+    def to_s
+      "#<Hookd::HookActivity hook=#{hook.id} pending=#{pending_count}>"
+    end
+  end
+end

data/lib/hookd/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hookd
-  VERSION = '1.2.2'
+  VERSION = '1.3.0'
 end

data/lib/hookd.rb

@@ -3,6 +3,7 @@
 require_relative 'hookd/version'
 require_relative 'hookd/error'
 require_relative 'hookd/hook'
+require_relative 'hookd/hook_activity'
 require_relative 'hookd/interaction'
 require_relative 'hookd/client'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hookd-client
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Joshua MARTINELLE
@@ -36,6 +36,7 @@ files:
 - lib/hookd/client.rb
 - lib/hookd/error.rb
 - lib/hookd/hook.rb
+- lib/hookd/hook_activity.rb
 - lib/hookd/interaction.rb
 - lib/hookd/version.rb
 homepage: https://github.com/JoshuaMart/Hookd