nombaone 0.1.0

data/lib/nombaone/resources/subscriptions.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Scheduled (next-cycle) changes queued against a subscription
+    # (`nombaone.subscriptions.schedule`).
+    class SubscriptionSchedules < BaseResource
+      # Queue a change for the next cycle boundary — the safe way to switch
+      # billing intervals (mid-cycle interval proration is unsupported).
+      #
+      # @param subscription_id [String] `nbo…sub`
+      # @param price_id [String] the price to switch to at the boundary.
+      # @param quantity [Integer]
+      # @param effective_at [String] defaults to `"next_cycle"` server-side.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ConflictError] 409 `SUBSCRIPTION_SCHEDULE_CONFLICT`
+      def create(subscription_id, price_id:, quantity: OMIT, effective_at: OMIT,
+                 request_options: {})
+        request(:post, "/subscriptions/#{encode(subscription_id)}/schedule",
+                body: { price_id: price_id, quantity: quantity, effective_at: effective_at },
+                options: request_options)
+      end
+
+      # Retrieve the subscription's schedule.
+      #
+      # @param subscription_id [String] `nbo…sub`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::NotFoundError] 404 `SUBSCRIPTION_SCHEDULE_NOT_FOUND`
+      def retrieve(subscription_id, request_options: {})
+        request(:get, "/subscriptions/#{encode(subscription_id)}/schedule",
+                options: request_options)
+      end
+
+      # Cancel the pending schedule before it applies.
+      #
+      # @param subscription_id [String] `nbo…sub`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def release(subscription_id, request_options: {})
+        request(:delete, "/subscriptions/#{encode(subscription_id)}/schedule",
+                options: request_options)
+      end
+    end
+
+    # Read-only view into a subscription's recovery state
+    # (`nombaone.subscriptions.dunning`).
+    class SubscriptionDunning < BaseResource
+      # Where the subscription stands in dunning. Check `grace_access_until`
+      # before cutting access — `past_due` usually means "not yet", not "no".
+      #
+      # @param subscription_id [String] `nbo…sub`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def retrieve(subscription_id, request_options: {})
+        request(:get, "/subscriptions/#{encode(subscription_id)}/dunning", options: request_options)
+      end
+
+      # List every recovery attempt, newest first.
+      #
+      # @param subscription_id [String] `nbo…sub`
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      def list_attempts(subscription_id, limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/subscriptions/#{encode(subscription_id)}/dunning/attempts",
+                     query: { limit: limit, cursor: cursor }, options: request_options)
+      end
+    end
+
+    # Subscriptions — the core object. Create one against a customer and a
+    # price; the engine handles cycles, invoices, retries, and recovery.
+    #
+    # Involuntary churn is `status: "canceled"` with
+    # `cancellation_reason: "involuntary"` (there is no separate `churned`
+    # status; there IS a `subscription.churned` event). `past_due` is **not**
+    # canceled — read {#dunning} and honor `grace_access_until`.
+    #
+    # @example
+    #   subscription = nombaone.subscriptions.create(
+    #     customer_id: customer.id, price_id: price.id, payment_method_id: method.id
+    #   )
+    #   subscription.status # => "active"
+    class Subscriptions < BaseResource
+      # Scheduled (next-cycle) changes.
+      # @return [SubscriptionSchedules]
+      def schedule
+        @schedule ||= SubscriptionSchedules.new(@client)
+      end
+
+      # Recovery/dunning state (read-only).
+      # @return [SubscriptionDunning]
+      def dunning
+        @dunning ||= SubscriptionDunning.new(@client)
+      end
+
+      # Create a subscription. This can move money (the first charge), so the
+      # API requires an `Idempotency-Key`; the SDK sends one automatically and
+      # reuses it across its own retries.
+      #
+      # @param customer_id [String] `nbo…cus`
+      # @param price_id [String] `nbo…prc` — subscriptions reference a price, not a plan.
+      # @param payment_method_id [String] required for `charge_automatically`
+      #   unless `trial_days > 0` (the first charge is deferred to trial end).
+      # @param collection_method [String] `"charge_automatically"` (default) or
+      #   `"send_invoice"`.
+      # @param trial_days [Integer]
+      # @param quantity [Integer] defaults to 1 server-side.
+      # @param metadata [Hash]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ValidationError] 422 — e.g. a missing payment method without a trial.
+      # @raise [Nombaone::ConflictError] 409 `SUBSCRIPTION_PAYMENT_METHOD_REQUIRED`
+      def create(customer_id:, price_id:, payment_method_id: OMIT, collection_method: OMIT,
+                 trial_days: OMIT, quantity: OMIT, metadata: OMIT, request_options: {})
+        request(:post, "/subscriptions",
+                body: {
+                  customer_id: customer_id,
+                  price_id: price_id,
+                  payment_method_id: payment_method_id,
+                  collection_method: collection_method,
+                  trial_days: trial_days,
+                  quantity: quantity,
+                  metadata: metadata,
+                },
+                options: request_options)
+      end
+
+      # Retrieve a subscription by id.
+      #
+      # @param id [String] `nbo…sub`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::NotFoundError] 404 `SUBSCRIPTION_NOT_FOUND`
+      def retrieve(id, request_options: {})
+        request(:get, "/subscriptions/#{encode(id)}", options: request_options)
+      end
+
+      # Edit metadata or the default payment method. For a price, quantity, or
+      # interval change (which prorates), use {#change}. At least one field is required.
+      #
+      # @param id [String] `nbo…sub`
+      # @param default_payment_method_id [String]
+      # @param metadata [Hash]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def update(id, default_payment_method_id: OMIT, metadata: OMIT, request_options: {})
+        request(:patch, "/subscriptions/#{encode(id)}",
+                body: { default_payment_method_id: default_payment_method_id, metadata: metadata },
+                options: request_options)
+      end
+
+      # List subscriptions, newest first.
+      #
+      # @param customer_id [String] filter to one customer (`nbo…cus`).
+      # @param status [String] filter by subscription status.
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      def list(customer_id: OMIT, status: OMIT, limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/subscriptions",
+                     query: { customer_id: customer_id, status: status, limit: limit,
+                              cursor: cursor },
+                     options: request_options)
+      end
+
+      # The subscription's audit trail of domain events, newest first.
+      #
+      # @param id [String] `nbo…sub`
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      def list_events(id, limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/subscriptions/#{encode(id)}/events",
+                     query: { limit: limit, cursor: cursor }, options: request_options)
+      end
+
+      # Pause billing. The subscription keeps its place in the cycle and resumes cleanly.
+      #
+      # @param id [String] `nbo…sub`
+      # @param max_days [Integer] auto-resume after this many days.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ConflictError] 409 `SUBSCRIPTION_ILLEGAL_TRANSITION`
+      def pause(id, max_days: OMIT, request_options: {})
+        request(:post, "/subscriptions/#{encode(id)}/pause",
+                body: { max_days: max_days }, options: request_options)
+      end
+
+      # Resume a paused subscription.
+      #
+      # @param id [String] `nbo…sub`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def resume(id, request_options: {})
+        request(:post, "/subscriptions/#{encode(id)}/resume", body: {}, options: request_options)
+      end
+
+      # Cancel a subscription — immediately (default) or at period end.
+      #
+      # @param id [String] `nbo…sub`
+      # @param mode [String] `"now"` (default) or `"at_period_end"` (keeps
+      #   access until the cycle closes).
+      # @param comment [String]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      #
+      # @example
+      #   nombaone.subscriptions.cancel(subscription.id, mode: "at_period_end")
+      def cancel(id, mode: OMIT, comment: OMIT, request_options: {})
+        request(:post, "/subscriptions/#{encode(id)}/cancel",
+                body: { mode: mode, comment: comment }, options: request_options)
+      end
+
+      # Start a fresh subscription for a canceled one's customer, reusing the
+      # old price/payment method unless overridden. The subscription must be in
+      # a terminal state.
+      #
+      # @param id [String] `nbo…sub`
+      # @param price_id [String] defaults to the previous price.
+      # @param payment_method_id [String] defaults to the previous payment method.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ConflictError] 409 `SUBSCRIPTION_NOT_TERMINAL`
+      def resubscribe(id, price_id: OMIT, payment_method_id: OMIT, request_options: {})
+        request(:post, "/subscriptions/#{encode(id)}/resubscribe",
+                body: { price_id: price_id, payment_method_id: payment_method_id },
+                options: request_options)
+      end
+
+      # Change price or quantity mid-cycle, prorating by default. Switching the
+      # billing interval mid-cycle is unsupported
+      # (`PRORATION_INTERVAL_SWITCH_UNSUPPORTED`) — queue it with {#schedule} instead.
+      #
+      # @param id [String] `nbo…sub`
+      # @param price_id [String]
+      # @param quantity [Integer]
+      # @param interval_switch [Boolean]
+      # @param proration_behavior [String] `"create_prorations"` (default) or `"none"`.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      #
+      # @example
+      #   nombaone.subscriptions.change(subscription.id, price_id: bigger_price.id)
+      def change(id, price_id: OMIT, quantity: OMIT, interval_switch: OMIT,
+                 proration_behavior: OMIT, request_options: {})
+        request(:post, "/subscriptions/#{encode(id)}/change",
+                body: {
+                  price_id: price_id,
+                  quantity: quantity,
+                  interval_switch: interval_switch,
+                  proration_behavior: proration_behavior,
+                },
+                options: request_options)
+      end
+
+      # Swap the payment method that bills this subscription — the card-update
+      # path during dunning. Provide exactly one of `payment_method_reference`
+      # or `checkout_token`.
+      #
+      # @param id [String] `nbo…sub`
+      # @param payment_method_reference [String] an already-captured method (`nbo…pmt`).
+      # @param checkout_token [String] a fresh hosted-checkout token — attaches and swaps atomically.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def update_payment_method(id, payment_method_reference: OMIT, checkout_token: OMIT,
+                                request_options: {})
+        request(:post, "/subscriptions/#{encode(id)}/payment-method",
+                body: {
+                  payment_method_reference: payment_method_reference,
+                  checkout_token: checkout_token,
+                },
+                options: request_options)
+      end
+
+      # Preview the next invoice without charging or storing anything.
+      #
+      # @param id [String] `nbo…sub`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def retrieve_upcoming_invoice(id, request_options: {})
+        request(:get, "/subscriptions/#{encode(id)}/upcoming-invoice", options: request_options)
+      end
+
+      # Apply a coupon to this subscription only.
+      #
+      # @param id [String] `nbo…sub`
+      # @param coupon [String] a coupon id (`nbo…cpn`) or its code.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def apply_discount(id, coupon:, request_options: {})
+        request(:post, "/subscriptions/#{encode(id)}/discount",
+                body: { coupon: coupon }, options: request_options)
+      end
+
+      # Remove the subscription's active discount. Returns the ended discount.
+      #
+      # @param id [String] `nbo…sub`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def remove_discount(id, request_options: {})
+        request(:delete, "/subscriptions/#{encode(id)}/discount", options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/webhook_endpoints.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Deliveries under a webhook endpoint: inspect and replay
+    # (`nombaone.webhook_endpoints.deliveries`).
+    class WebhookEndpointDeliveries < BaseResource
+      # List an endpoint's deliveries, newest first.
+      #
+      # @param endpoint_id [String] `nbo…whk`
+      # @param status [String] `"pending"`, `"succeeded"`, `"failed"`, `"dead"`.
+      # @param event_type [String] filter by catalog event type.
+      # @param endpoint [String] filter by endpoint reference.
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      def list(endpoint_id, status: OMIT, event_type: OMIT, endpoint: OMIT, limit: OMIT,
+               cursor: OMIT, request_options: {})
+        request_page("/webhooks/#{encode(endpoint_id)}/deliveries",
+                     query: {
+                       status: status,
+                       event_type: event_type,
+                       endpoint: endpoint,
+                       limit: limit,
+                       cursor: cursor,
+                     },
+                     options: request_options)
+      end
+
+      # Retrieve one delivery.
+      #
+      # @param endpoint_id [String] `nbo…whk`
+      # @param delivery_id [String] `nbo…whd`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def retrieve(endpoint_id, delivery_id, request_options: {})
+        request(:get, "/webhooks/#{encode(endpoint_id)}/deliveries/#{encode(delivery_id)}",
+                options: request_options)
+      end
+
+      # Redeliver a past delivery. The **original event id is kept**, so a
+      # receiver that dedupes on `event.event.id` correctly treats it as
+      # already-seen.
+      #
+      # @param endpoint_id [String] `nbo…whk`
+      # @param delivery_id [String] `nbo…whd`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def replay(endpoint_id, delivery_id, request_options: {})
+        request(:post, "/webhooks/#{encode(endpoint_id)}/deliveries/#{encode(delivery_id)}/replay",
+                body: {}, options: request_options)
+      end
+    end
+
+    # Webhook endpoints — register and manage the URLs that receive signed
+    # events. To *verify* incoming deliveries in your handler, use
+    # {Nombaone.webhooks} / {Nombaone::Webhooks#construct_event} — the crypto
+    # helper, not this REST resource.
+    class WebhookEndpoints < BaseResource
+      # Deliveries under an endpoint.
+      # @return [WebhookEndpointDeliveries]
+      def deliveries
+        @deliveries ||= WebhookEndpointDeliveries.new(@client)
+      end
+
+      # Register an endpoint. The response includes the full `signing_secret`
+      # **exactly once** — store it in your secret manager immediately.
+      #
+      # @param url [String]
+      # @param enabled_events [Array<String>] event types to fan out; defaults to
+      #   `["*"]` (all events) server-side.
+      # @param request_options [Hash]
+      # @return [NombaObject] the endpoint plus its one-time `signing_secret`.
+      #
+      # @example
+      #   endpoint = nombaone.webhook_endpoints.create(
+      #     url: "https://example.com/nombaone/webhooks",
+      #     enabled_events: ["invoice.paid", "invoice.payment_failed"]
+      #   )
+      #   store_secret(endpoint.signing_secret)
+      def create(url:, enabled_events: OMIT, request_options: {})
+        request(:post, "/webhooks",
+                body: { url: url, enabled_events: enabled_events }, options: request_options)
+      end
+
+      # Retrieve an endpoint by id.
+      #
+      # @param id [String] `nbo…whk`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::NotFoundError] 404 `WEBHOOK_ENDPOINT_NOT_FOUND`
+      def retrieve(id, request_options: {})
+        request(:get, "/webhooks/#{encode(id)}", options: request_options)
+      end
+
+      # Update url, event subscription, or enabled state.
+      #
+      # @param id [String] `nbo…whk`
+      # @param url [String]
+      # @param enabled_events [Array<String>]
+      # @param disabled [Boolean] `true` pauses deliveries; `false` re-enables.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def update(id, url: OMIT, enabled_events: OMIT, disabled: OMIT, request_options: {})
+        request(:patch, "/webhooks/#{encode(id)}",
+                body: { url: url, enabled_events: enabled_events, disabled: disabled },
+                options: request_options)
+      end
+
+      # List your endpoints.
+      #
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      def list(request_options: {})
+        request_page("/webhooks", options: request_options)
+      end
+
+      # Delete an endpoint. Pending deliveries to it are retired.
+      #
+      # @param id [String] `nbo…whk`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def delete(id, request_options: {})
+        request(:delete, "/webhooks/#{encode(id)}", options: request_options)
+      end
+
+      # Rotate the signing secret. The new secret is returned **exactly once**;
+      # the old one is briefly honored so you can roll without dropping in-flight
+      # deliveries.
+      #
+      # @param id [String] `nbo…whk`
+      # @param request_options [Hash]
+      # @return [NombaObject] with the new one-time `signing_secret`.
+      def rotate_secret(id, request_options: {})
+        request(:post, "/webhooks/#{encode(id)}/rotate-secret", body: {}, options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Nombaone
+  # The installed SDK version. Sent on every request as part of the
+  # `User-Agent` (`nombaone-ruby/<version>`) and used for release tooling.
+  VERSION = "0.1.0"
+end

data/lib/nombaone/webhook_event.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Nombaone
+  # Every event type the platform can deliver, as `name = value` constants
+  # (`Nombaone::WebhookEventType::INVOICE_PAID == "invoice.paid"`), plus the
+  # frozen {ALL} list. Branch on {WebhookEvent#type} against these.
+  #
+  # The catalog is **shipped open**: an event type the API adds tomorrow is
+  # still delivered and parsed — it just will not have a named constant here
+  # yet, and never breaks your handler.
+  module WebhookEventType
+    # The public event catalog (scaffold `example.*` events are excluded).
+    ALL = %w[
+      customer.created
+      customer.updated
+      coupon.created
+      discount.created
+      discount.removed
+      plan.created
+      plan.updated
+      plan.archived
+      price.created
+      price.deactivated
+      subscription.created
+      subscription.updated
+      subscription.trial_will_end
+      subscription.activated
+      subscription.paused
+      subscription.resumed
+      subscription.canceled
+      subscription.churned
+      invoice.created
+      invoice.finalized
+      invoice.paid
+      invoice.payment_failed
+      invoice.payment_partially_collected
+      invoice.payment_recovered
+      invoice.action_required
+      invoice.voided
+      payment_method.attached
+      payment_method.updated
+      payment_method.expiring
+      settlement.created
+      settlement.refunded
+      settlement.payout_created
+    ].freeze
+
+    ALL.each { |type| const_set(type.upcase.tr(".", "_"), type) }
+  end
+
+  # A verified webhook delivery. It is a {NombaObject}, so every field reads
+  # idiomatically:
+  #
+  #   event.type              # => "invoice.payment_failed"
+  #   event.event.id          # => "nbo…evt"  — DEDUPE on this
+  #   event.data.reason       # => "insufficient_funds"  (typed payloads narrow with the type)
+  #
+  # Delivery is **at-least-once** — after verification, dedupe on `event.event.id`
+  # before acting. The `event` block is always present: if a delivery arrives in
+  # the older flat shape (top-level `id`/`type`/`created_at`), it is synthesized
+  # so dedupe still works.
+  class WebhookEvent < NombaObject
+  end
+end

data/lib/nombaone/webhooks.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module Nombaone
+  # Verify and parse incoming NombaOne webhook deliveries.
+  #
+  # Available as `nombaone.webhooks` on a client, or standalone via
+  # {Nombaone.webhooks} — verification needs only the endpoint's signing secret,
+  # never an API key, so it works in a receiver that never builds a client.
+  #
+  # **Feed it the raw request body.** Parsing and re-serializing JSON can
+  # reorder keys and change bytes, which breaks the signature. Capture the body
+  # before any middleware parses it (`request.raw_post` in Rack/Rails).
+  #
+  # @example Rails controller
+  #   def receive
+  #     event = Nombaone.webhooks.construct_event(
+  #       request.raw_post,
+  #       request.headers["X-Nombaone-Signature"],
+  #       ENV.fetch("NOMBAONE_WEBHOOK_SECRET"),
+  #     )
+  #     return head(:ok) if already_processed?(event.event.id) # at-least-once ⇒ dedupe
+  #
+  #     unlock(event.data.reference) if event.type == Nombaone::WebhookEventType::INVOICE_PAID
+  #     head :ok # respond 2xx fast; do heavy work async
+  #   rescue Nombaone::WebhookVerificationError
+  #     head :bad_request
+  #   end
+  class Webhooks
+    # Maximum allowed age (seconds) between the delivery's `t` timestamp and now.
+    DEFAULT_TOLERANCE_SECONDS = 300
+
+    # Verify a delivery's signature and timestamp, then parse and return the
+    # typed event. This is the one call your handler needs.
+    #
+    # @param payload [String] the exact raw request body.
+    # @param signature_header [String] the `X-Nombaone-Signature` header value.
+    # @param secret [String] the endpoint's signing secret (shown once at creation).
+    # @param tolerance [Numeric] max timestamp age in seconds (default 300).
+    # @return [WebhookEvent]
+    # @raise [WebhookVerificationError] on a missing/malformed header, a stale
+    #   timestamp, an invalid signature, or a non-JSON body.
+    def construct_event(payload, signature_header, secret, tolerance: DEFAULT_TOLERANCE_SECONDS)
+      verify_signature(payload, signature_header, secret, tolerance: tolerance)
+
+      begin
+        parsed = JSON.parse(payload.to_s)
+      rescue JSON::ParserError
+        raise WebhookVerificationError, "Webhook payload was not valid JSON."
+      end
+      unless parsed.is_a?(Hash)
+        raise WebhookVerificationError, "Webhook payload was not a JSON object."
+      end
+
+      WebhookEvent.new(ensure_event_block(parsed))
+    end
+
+    # Verify a delivery's signature and timestamp only (no parse). Returns true
+    # on success; raises with a distinct message per failure mode.
+    #
+    # @param payload [String] the exact raw request body.
+    # @param signature_header [String] the `X-Nombaone-Signature` header value.
+    # @param secret [String] the endpoint's signing secret.
+    # @param tolerance [Numeric] max timestamp age in seconds (default 300).
+    # @return [true]
+    # @raise [WebhookVerificationError]
+    def verify_signature(payload, signature_header, secret, tolerance: DEFAULT_TOLERANCE_SECONDS)
+      if signature_header.nil? || signature_header.empty?
+        raise WebhookVerificationError,
+              "Missing X-Nombaone-Signature header — is this request really from NombaOne?"
+      end
+      if secret.nil? || secret.empty?
+        raise WebhookVerificationError,
+              "Missing signing secret — pass the secret shown when the endpoint was created."
+      end
+
+      timestamp, signatures = parse_signature_header(signature_header)
+      assert_within_tolerance(timestamp, tolerance)
+
+      expected = compute_signature(secret, timestamp, payload.to_s)
+      return true if signatures.any? { |candidate| secure_compare(candidate, expected) }
+
+      raise WebhookVerificationError,
+            "Webhook signature verification failed — check you are using this endpoint's " \
+            "current signing secret and the exact raw request body (no re-serialization)."
+    end
+
+    # Build a valid `X-Nombaone-Signature` header for a payload — for testing
+    # your own handler without waiting on a real delivery.
+    #
+    # @param payload [String] the raw body you will pass to {#construct_event}.
+    # @param secret [String] the signing secret.
+    # @param timestamp [Integer, nil] unix seconds (defaults to now).
+    # @return [String] a `t=<unix>,v1=<hex>` header value.
+    #
+    # @example
+    #   header = Nombaone.webhooks.generate_test_header(payload: body, secret: secret)
+    #   event = Nombaone.webhooks.construct_event(body, header, secret)
+    def generate_test_header(payload:, secret:, timestamp: nil)
+      timestamp = (timestamp || Time.now.to_i).to_s
+      "t=#{timestamp},v1=#{compute_signature(secret, timestamp, payload.to_s)}"
+    end
+
+    private
+
+    def compute_signature(secret, timestamp, raw_body)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
+    end
+
+    def parse_signature_header(header)
+      timestamp = nil
+      signatures = []
+      header.split(",").each do |pair|
+        eq = pair.index("=")
+        next if eq.nil?
+
+        key = pair[0...eq].strip
+        value = pair[(eq + 1)..].strip
+        timestamp = value if key == "t"
+        # Multiple `v1` entries are legal during secret rotation — any match passes.
+        signatures << value if key == "v1" && !value.empty?
+      end
+
+      if timestamp.nil? || signatures.empty?
+        raise WebhookVerificationError,
+              'Malformed X-Nombaone-Signature header — expected "t=<unix>,v1=<hex>".'
+      end
+      [timestamp, signatures]
+    end
+
+    def assert_within_tolerance(timestamp, tolerance)
+      seconds = Integer(timestamp, exception: false)
+      if seconds.nil?
+        raise WebhookVerificationError,
+              "Malformed X-Nombaone-Signature header — `t` is not a unix timestamp."
+      end
+
+      age = (Time.now.to_i - seconds).abs
+      return if age <= tolerance
+
+      raise WebhookVerificationError,
+            "Webhook timestamp is outside the allowed tolerance (#{age}s old, limit " \
+            "#{tolerance}s) — possible replay, or severe clock skew."
+    end
+
+    def secure_compare(candidate, expected)
+      candidate.bytesize == expected.bytesize &&
+        OpenSSL.fixed_length_secure_compare(candidate, expected)
+    end
+
+    # Guarantee a dedupe-able `event.id` even if a delivery body arrives flat
+    # (older shape) — fall back to top-level fields.
+    def ensure_event_block(body)
+      return body if body["event"].is_a?(Hash)
+
+      body.merge(
+        "event" => {
+          "id" => body["id"].is_a?(String) ? body["id"] : "",
+          "type" => body["type"].is_a?(String) ? body["type"] : "",
+          "createdAt" => body["createdAt"].is_a?(String) ? body["createdAt"] : "",
+        },
+      )
+    end
+  end
+end