rerout 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78cf1ae4573eccdeed6874c837565ea69f415c928c23def1fe506e674be53ec3
-  data.tar.gz: aa23cc62bcd1c3f2f80ee460fe691d0241027020e5d7f5d3bfacb2e909263286
+  metadata.gz: 6f212d64e3f65e342bc6034aa992c270a2322534dc127e18fa4b7defbd6e0b08
+  data.tar.gz: bb2fd2083df69c90e884769fe5aad80b40d11dde7ba7696d96bc04ac73393833
 SHA512:
-  metadata.gz: 4f1e411e4301abfd0009626920e3e974ca4f2b7db05de0d930e2eb9d432b3d71e8c51b5185875c04fdc8edd97cf1cc756e93215cc24e82103086f475714732e0
-  data.tar.gz: 1722814f198aca44eded94a7f5c983a7f30a9437a75652046ad61226cd454d005b248fe500a68080c4aa5b98fc0089274fe610089a3ac8f5b2a68832fcfb723b
+  metadata.gz: a86ed8c18689fa52099e11a1fc1bedec3ddd2aa5897ff2d9c694290260892712591bccc61b1aee0129e24e7f2182b5d5dc7657126dfb9960e9cfb6ad3229b79d
+  data.tar.gz: 812e84cfb86041e00b6798bd149176818162d7c25f56267dc1be12a7a7c4f5c1c8e816a0744194c0b9ce752619bc090deef52f7742a594a8f6e3ae77f55feb07

data/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to the `rerout` gem are documented in this file. The
 format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-06-03
+
+### Added
+
+- Webhook endpoint management via a new `webhooks` namespace — `create`, `list`,
+  and `delete` against `/v1/projects/me/webhooks` (API-key auth). The signing
+  secret returned by `create` is shown once.
+
 ## [0.2.0] - 2026-06-02
 
 ### Added
@@ -40,5 +48,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Rerout::Error` with stable `code`, `status`, `path`, `timestamp`, `details`
   plus `rate_limited?` and `server_error?` convenience flags.
 
+[0.3.0]: https://github.com/ModestNerds-Co/rerout-sdks/releases/tag/ruby/v0.3.0
 [0.2.0]: https://github.com/ModestNerds-Co/rerout-sdks/releases/tag/ruby-v0.2.0
 [0.1.0]: https://github.com/ModestNerds-Co/rerout-sdks/releases/tag/ruby-v0.1.0

data/README.md

@@ -64,7 +64,7 @@ rerout = Rerout::Client.new(
 A blank or missing `api_key` raises `Rerout::Error` with code `missing_api_key`
 before any network call.
 
-The client exposes three namespaces: `links`, `project`, and `qr`.
+The client exposes four namespaces: `links`, `project`, `qr`, and `webhooks`.
 
 ## Links
 
@@ -147,6 +147,38 @@ File.write('q4.svg', svg)
 QR options: `size` (1–32), `margin` (0–16), `ecc` (`L`/`M`/`Q`/`H`), `domain`,
 and `refresh` (`true` is serialized as `1`; a string is sent verbatim).
 
+## Webhook management
+
+Manage the webhook endpoints that receive event deliveries for the project that
+owns the API key. (This is the `webhooks` namespace — distinct from
+`Rerout::Webhooks`, which verifies inbound signatures below.)
+
+```ruby
+# Create — name, url, and events are required.
+created = rerout.webhooks.create(
+  Rerout::CreateWebhookInput.new(
+    name: 'prod listener',
+    url: 'https://hooks.brand.com/rerout',
+    events: ['link.created'],
+    payload_format: 'json' # optional: "json" (default) or "slack"
+  )
+)
+
+created.endpoint.id      # => "wh_..."
+created.signing_secret   # => "whsec_..." — shown ONCE; persist it now.
+
+# List endpoints plus the event types the server can deliver.
+result = rerout.webhooks.list
+result.endpoints   # => [Rerout::Models::Webhook, ...]
+result.event_types # => ["link.created", ...]
+
+# Delete (soft delete) — idempotent.
+rerout.webhooks.delete('wh_...') # => { "deleted" => true }
+```
+
+The `signing_secret` returned by `create` is the value you pass as `secret:` to
+`verify_signature` below — store it securely, as it cannot be retrieved again.
+
 ## Webhook signature verification
 
 Rerout signs every webhook delivery with an `X-Rerout-Signature` header. Verify

data/lib/rerout/client.rb

@@ -7,12 +7,14 @@ require_relative 'version'
 require_relative 'error'
 require_relative 'create_link_input'
 require_relative 'update_link_input'
+require_relative 'create_webhook_input'
 require_relative 'qr_options'
 require_relative 'webhooks'
 require_relative 'models'
 require_relative 'links'
 require_relative 'project'
 require_relative 'qr'
+require_relative 'webhooks_resource'
 
 module Rerout
   # Default production API base URL.
@@ -36,6 +38,8 @@ module Rerout
     attr_reader :project
     # @return [Resources::Qr] QR namespace.
     attr_reader :qr
+    # @return [Resources::Webhooks] webhook endpoint management namespace.
+    attr_reader :webhooks
 
     # @param api_key [String] project API key (`rrk_…`). Required.
     # @param base_url [String, nil] override base URL. Defaults to `https://api.rerout.co`.
@@ -61,6 +65,7 @@ module Rerout
       @links = Resources::Links.new(self)
       @project = Resources::Project.new(self)
       @qr = Resources::Qr.new(self)
+      @webhooks = Resources::Webhooks.new(self)
     end
 
     # Perform a JSON request against the Rerout API.

data/lib/rerout/create_webhook_input.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Rerout
+  # Request body for `POST /v1/projects/me/webhooks`. `name`, `url`, and
+  # `events` are required; `is_active` and `payload_format` are optional and
+  # omitted from the payload when not set (server defaults apply).
+  class CreateWebhookInput
+    attr_reader :name, :url, :events, :is_active, :payload_format
+
+    # @param name [String] required, human-readable label for the endpoint.
+    # @param url [String] required, public https:// URL that receives deliveries.
+    # @param events [Array<String>] required, non-empty list of event types
+    #   to subscribe to (e.g. `link.created`).
+    # @param is_active [Boolean, nil] whether the endpoint starts active.
+    #   Server default: `true`.
+    # @param payload_format [String, nil] payload encoding — `"json"` or
+    #   `"slack"`. Server default: `"json"`.
+    def initialize(name:, url:, events:, is_active: nil, payload_format: nil)
+      raise ArgumentError, 'name is required' if name.nil? || name.to_s.empty?
+      raise ArgumentError, 'url is required' if url.nil? || url.to_s.empty?
+      if events.nil? || !events.is_a?(Array) || events.empty?
+        raise ArgumentError, 'events is required and must be a non-empty Array'
+      end
+
+      @name = name
+      @url = url
+      @events = events
+      @is_active = is_active
+      @payload_format = payload_format
+      freeze
+    end
+
+    # Serialize for the wire. Optional fields are only included when set.
+    def to_h
+      hash = { 'name' => name, 'url' => url, 'events' => events }
+      hash['is_active'] = is_active unless is_active.nil?
+      hash['payload_format'] = payload_format unless payload_format.nil?
+      hash
+    end
+  end
+end

data/lib/rerout/models.rb

@@ -301,5 +301,115 @@ module Rerout
         [self.class, id, name, slug].hash
       end
     end
+
+    # A webhook endpoint registered to the project. Mirrors the server-side
+    # `WebhookEndpointResponse`.
+    class Webhook
+      ATTRS = %i[
+        id project_id name url events is_active payload_format
+        created_at updated_at last_delivery_at last_success_at last_failure_at
+      ].freeze
+
+      attr_reader(*ATTRS)
+
+      def initialize(**attrs)
+        ATTRS.each { |k| instance_variable_set(:"@#{k}", attrs[k]) }
+        @events = (@events || []).freeze
+        freeze
+      end
+
+      def self.from_hash(hash)
+        new(
+          id: hash['id'],
+          project_id: hash['project_id'],
+          name: hash['name'],
+          url: hash['url'],
+          events: hash['events'] || [],
+          is_active: hash['is_active'],
+          payload_format: hash['payload_format'],
+          created_at: hash['created_at'],
+          updated_at: hash['updated_at'],
+          last_delivery_at: hash['last_delivery_at'],
+          last_success_at: hash['last_success_at'],
+          last_failure_at: hash['last_failure_at']
+        )
+      end
+
+      def to_h
+        ATTRS.to_h { |k| [k, public_send(k)] }
+      end
+
+      def ==(other)
+        other.is_a?(Webhook) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+    end
+
+    # Result of creating a webhook. The `signing_secret` (`whsec_…`) is
+    # returned **once** — store it now; it is never shown again.
+    class CreatedWebhook
+      attr_reader :endpoint, :signing_secret
+
+      def initialize(endpoint:, signing_secret:)
+        @endpoint = endpoint
+        @signing_secret = signing_secret
+        freeze
+      end
+
+      def self.from_hash(hash)
+        new(
+          endpoint: Webhook.from_hash(hash['endpoint'] || {}),
+          signing_secret: hash['signing_secret']
+        )
+      end
+
+      def to_h
+        { endpoint: endpoint.to_h, signing_secret: signing_secret }
+      end
+
+      def ==(other)
+        other.is_a?(CreatedWebhook) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+    end
+
+    # List of webhook endpoints plus every event type the server can deliver.
+    class ListWebhooksResult
+      attr_reader :endpoints, :event_types
+
+      def initialize(endpoints:, event_types:)
+        @endpoints = endpoints.freeze
+        @event_types = event_types.freeze
+        freeze
+      end
+
+      def self.from_hash(hash)
+        new(
+          endpoints: (hash['endpoints'] || []).map { |e| Webhook.from_hash(e) },
+          event_types: hash['event_types'] || []
+        )
+      end
+
+      def to_h
+        { endpoints: endpoints.map(&:to_h), event_types: event_types }
+      end
+
+      def ==(other)
+        other.is_a?(ListWebhooksResult) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+    end
   end
 end

data/lib/rerout/version.rb

@@ -2,5 +2,5 @@
 
 module Rerout
   # Library version. Follows semantic versioning.
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/rerout/webhooks_resource.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module Rerout
+  module Resources
+    # Webhook endpoint management namespace — create, list, delete endpoints
+    # for the project that owns the API key.
+    #
+    # This is distinct from {Rerout::Webhooks}, which verifies *inbound*
+    # delivery signatures. Reach it via `client.webhooks`.
+    class Webhooks
+      # @param client [Rerout::Client]
+      def initialize(client)
+        @client = client
+      end
+
+      # Create a webhook endpoint. The returned `signing_secret` (`whsec_…`) is
+      # shown once — persist it to verify future deliveries.
+      #
+      # @param input [Rerout::CreateWebhookInput, Hash] the request body.
+      # @return [Rerout::Models::CreatedWebhook]
+      def create(input)
+        body = coerce_input(input)
+        response = @client.request(method: :post, path: '/v1/projects/me/webhooks', body: body)
+        Models::CreatedWebhook.from_hash(response)
+      end
+
+      # List webhook endpoints and the event types the server can deliver.
+      #
+      # @return [Rerout::Models::ListWebhooksResult]
+      def list
+        response = @client.request(method: :get, path: '/v1/projects/me/webhooks')
+        Models::ListWebhooksResult.from_hash(response)
+      end
+
+      # Soft-delete an endpoint and abandon its pending deliveries. Idempotent.
+      #
+      # @param endpoint_id [String] the endpoint id (`wh_…`).
+      # @return [Hash] `{ "deleted" => true }`
+      def delete(endpoint_id)
+        @client.request(method: :delete, path: webhook_path(endpoint_id))
+      end
+
+      private
+
+      def webhook_path(endpoint_id)
+        raise ArgumentError, 'endpoint_id is required' if endpoint_id.nil? || endpoint_id.to_s.empty?
+
+        "/v1/projects/me/webhooks/#{ERB::Util.url_encode(endpoint_id.to_s)}"
+      end
+
+      def coerce_input(input)
+        case input
+        when CreateWebhookInput then input.to_h
+        when Hash then input
+        else
+          raise ArgumentError, 'input must be a Rerout::CreateWebhookInput or Hash'
+        end
+      end
+    end
+  end
+end

data/lib/rerout.rb

@@ -5,11 +5,13 @@ require_relative 'rerout/error'
 require_relative 'rerout/models'
 require_relative 'rerout/create_link_input'
 require_relative 'rerout/update_link_input'
+require_relative 'rerout/create_webhook_input'
 require_relative 'rerout/qr_options'
 require_relative 'rerout/webhooks'
 require_relative 'rerout/links'
 require_relative 'rerout/project'
 require_relative 'rerout/qr'
+require_relative 'rerout/webhooks_resource'
 require_relative 'rerout/client'
 
 # Official Ruby SDK for the Rerout branded-link API.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rerout
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Codecraft Solutions
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-02 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -110,6 +110,7 @@ files:
 - lib/rerout.rb
 - lib/rerout/client.rb
 - lib/rerout/create_link_input.rb
+- lib/rerout/create_webhook_input.rb
 - lib/rerout/error.rb
 - lib/rerout/links.rb
 - lib/rerout/models.rb
@@ -119,6 +120,7 @@ files:
 - lib/rerout/update_link_input.rb
 - lib/rerout/version.rb
 - lib/rerout/webhooks.rb
+- lib/rerout/webhooks_resource.rb
 homepage: https://github.com/ModestNerds-Co/rerout-sdks
 licenses:
 - MIT