invoq 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aace348d9c04cd5a80e760fe140730067aa3202152e203ae5541549ced1b73b4
-  data.tar.gz: ff2d61b5b9522f6f9ec2dcc194b89367773db4973aa9b094981a3d276ef4015d
+  metadata.gz: e4394aa795d6674da3055ce51a03de79b19602bc50139dc19bd00488b0bcc267
+  data.tar.gz: 4bba9c3d77bf88951e393097b7b9e47301f42d668acdae4b93ac24adbcf9254b
 SHA512:
-  metadata.gz: 8b7465558d3d32639a49cdfb1fa5a2a043ad154b1138d487afdee592706d8d4d8d84725354308397ff519724b961bd4f06e5c408f249486c5ac95ebda6de99d5
-  data.tar.gz: 8c6e47ed6497d8ebef8a9713a9bd58dc2673368eec45a1e0c9de103790366ed8c1e33ebd80c58f8ae6543dab0ffe48d005c3f27e2889a00a27fd1b9cccd8b935
+  metadata.gz: e6606f9c4a3f0043e1353f007da072d9cae06edf823e3f695e9aac80938010baa38bd98bbbeb24d12adb164bbfea2f25f38db62f2a8e14267282d3876bb9fd21
+  data.tar.gz: 6beee35201584d88936d0d289301436eac266f87e0ef0a03889207fce892e72f36a50885314a365f63d93ca8ca714acf0889046150da1069f138469f63ccc48d

data/LICENSE.txt

@@ -1,6 +1,6 @@
-MIT License
+MIT license
 
-Copyright (c) 2026 Invoq
+Copyright (c) 2026 invoq
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,8 +1,27 @@
-# Invoq Ruby SDK
+# invoq Ruby SDK
 
-Invoq is a stablecoin payment acceptance platform.
+**English** · [Bahasa Indonesia](./docs/README.id.md) · [Español](./docs/README.es-419.md) · [Français](./docs/README.fr.md) · [Português](./docs/README.pt-BR.md) · [Tiếng Việt](./docs/README.vi.md) · [Türkçe](./docs/README.tr.md) · [ไทย](./docs/README.th.md) · [简体中文](./docs/README.zh-Hans.md) · [繁體中文](./docs/README.zh-Hant.md)
 
-This gem is an early placeholder release for the future Invoq Ruby SDK.
+Accept stablecoin payments with invoq from Ruby server code. This SDK wraps
+invoq server APIs and verifies signed webhooks.
+
+Use this gem only on your server. It handles secret keys and should not be
+bundled into browser code.
+
+## Server SDKs
+
+Create invoices and verify webhooks from your backend in any of these languages — same REST API, same webhook signature. This repository is the Ruby SDK.
+
+| Language | Repository |
+| --- | --- |
+| Node.js | [github.com/invoqmoney/sdk-js](https://github.com/invoqmoney/sdk-js) (`@invoq/server`) |
+| Python | [github.com/invoqmoney/sdk-python](https://github.com/invoqmoney/sdk-python) |
+| PHP | [github.com/invoqmoney/sdk-php](https://github.com/invoqmoney/sdk-php) |
+| Go | [github.com/invoqmoney/sdk-go](https://github.com/invoqmoney/sdk-go) |
+| Rust | [github.com/invoqmoney/sdk-rust](https://github.com/invoqmoney/sdk-rust) |
+| Ruby | **this repo** |
+
+The browser side is the same for every backend: **`@invoq/checkout`** (JavaScript, in [github.com/invoqmoney/sdk-js](https://github.com/invoqmoney/sdk-js)) opens the in-page checkout modal for any frontend.
 
 ## Installation
 
@@ -18,12 +37,282 @@ Or add it to a Gemfile:
 gem "invoq"
 ```
 
-## Usage
+Requires Ruby 2.6 or newer.
+
+## Get your keys
+
+1. Sign in to the [invoq dashboard](https://app.invoq.money) and create a
+   project.
+2. On the **API keys** page, create a secret key. Test keys start with
+   `sk_test_`, live keys with `sk_live_`. The key mode determines whether
+   invoices are test or live.
+3. In your project's **webhooks** settings, save your webhook URL. The webhook
+   secret (`whsec_...`) for that mode is shown once, when you first enable the
+   webhook. Store it right away. Webhook URLs must be public HTTPS URLs.
+
+Add both to your server environment:
+
+```sh
+INVOQ_SECRET_KEY=sk_test_...
+INVOQ_WEBHOOK_SECRET=whsec_...
+```
+
+Start with test keys. Switch to the live key and live webhook secret when you
+go to production.
+
+## Create a client
 
 ```ruby
 require "invoq"
 
-Invoq::VERSION
+invoq = Invoq.new(ENV.fetch("INVOQ_SECRET_KEY"))
+```
+
+Default production API origin:
+
+```txt
+https://api.invoq.money
 ```
 
-The public SDK API is not available yet.
+Override the API origin and request timeout during development:
+
+```ruby
+invoq = Invoq.new(
+  ENV.fetch("INVOQ_SECRET_KEY"),
+  api_origin: "http://localhost:8787",
+  timeout_ms: 10_000
+)
+```
+
+`api_origin` must be an absolute `http` or `https` origin with no path, query,
+hash, username, or password. The SDK appends `/v1/...` resource paths.
+
+Requests time out after 10 seconds by default. Pass `timeout_ms` to change the
+timeout. `timeout_ms` must be a positive integer in milliseconds.
+
+## Invoices
+
+Create an invoice:
+
+```ruby
+invoice = invoq.invoices.create(
+  amount: "129",
+  currency: "USD",
+  description: "SaaS boilerplate",
+  reference_id: "order_1234",
+  return_url: "https://merchant.example/thanks"
+)
+
+invoice_id = invoice.fetch("id")
+checkout_url = "https://pay.invoq.money/#{invoice_id}"
+```
+
+Notes:
+
+- Use a server-side amount. Do not trust client-supplied amounts.
+- `amount` is a decimal USD string from `"0.01"` to `"999.99"` with up
+  to 2 decimal places, such as `"129"` or `"129.99"`.
+- `currency` is optional and defaults to `"USD"`.
+- Use a stable, non-empty `reference_id` to map `invoice.paid` webhooks back to
+  your order. Creating again with the same `reference_id` and invoice terms
+  returns the existing invoice; different terms fail with a
+  `409 reference_id_conflict` API error.
+- If you fulfill by invoice ID instead of `reference_id`, store `invoice_id`
+  with your order when you create the invoice.
+- Omit `return_url` to use the project's default return URL. Pass `nil` to send
+  JSON `null` and create the invoice without a return URL. On `reference_id`
+  retries, pass `return_url` explicitly when you need to assert a specific
+  value.
+- `description` and `reference_id` must be strings when present.
+
+Get an invoice:
+
+```ruby
+invoice = invoq.invoices.get("inv_123")
+```
+
+`invoices.get` returns the public invoice shape used by hosted checkout. It
+includes fields such as `amount_paid`, `amount_due`, `amount_overpaid`,
+`payment_status`, `project`, `deposit_address`, `monitoring_ends_at`,
+`monitoring_status`, `transfers`, and `direct_onchain_rails`, but does not
+include `reference_id`. Use the create response or `invoice.paid` webhook when
+you need your merchant `reference_id`.
+
+Create a test payment:
+
+```ruby
+paid_invoice = invoq.invoices.create_test_payment(
+  "inv_123",
+  amount: "129",
+  reference_id: "test_payment_001"
+)
+```
+
+Test invoices cannot receive real funds. Simulate payments from your server
+instead.
+
+`create_test_payment` only works for invoices created with a `sk_test_` key.
+Partial amounts are allowed and produce `partially_paid`; when payments reach
+the invoice amount, invoq sends a signed `invoice.paid` webhook to your test
+webhook URL.
+
+`reference_id` is optional for test payments. Omit it when unset; do not pass
+`nil`.
+
+To receive webhooks on your machine, expose your local server with an HTTPS
+tunnel such as ngrok or cloudflared and save the tunnel URL as your test webhook
+URL in the dashboard. The dashboard can also send a signed `webhook.ping` to
+check connectivity.
+
+Each invoice method returns the response `data` object directly as a Ruby hash.
+
+## Hosted checkout page
+
+Every invoice also has a hosted checkout page at:
+
+```txt
+https://pay.invoq.money/<invoice id>
+```
+
+Share the link or redirect to it when an in-page checkout modal is not a fit.
+
+## Inputs and responses
+
+The SDK checks that `amount` values and `invoice_id` arguments are non-empty
+strings before sending requests. The invoq API validates the amount format,
+range, and currency.
+
+Leave unset optional fields out of the request hash. When you include
+`description` or `reference_id`, pass a string. `return_url` can be a string or
+`nil`.
+
+Amounts in responses are normalized to 4 decimal places: create with `"129"`
+and the invoice returns `amount: "129.0000"`. Compare amounts numerically, not
+as strings. `amount_due` is derived as `max(amount - amount_paid, 0)` and uses
+the same 18-decimal scale as `amount_paid`; `amount_overpaid` is its mirror,
+`max(amount_paid - amount, 0)`, so you never subtract money yourself.
+`monitoring_status` is `"active"` or `"ended"` — once it is `"ended"`, the
+deposit address is no longer watched — and `transfers` is the confirmed
+on-chain receipt trail (each entry has `tx_hash`, `amount`, and
+`explorer_tx_url`). Both are `nil` / `[]` for test invoices.
+
+## Webhooks
+
+Pass the raw request body to `verify_webhook`. Do not parse JSON and encode it
+again before verification.
+
+This Rack example returns `[status, headers, body]`. In Rails, use
+`request.raw_post` and `request.get_header("HTTP_INVOQ_SIGNATURE")`; in Sinatra
+or another Ruby framework, use the framework's raw request body and exposed
+`invoq-signature` or `HTTP_INVOQ_SIGNATURE` header.
+
+```ruby
+def handle_invoq_webhook(env)
+  raw_body = env.fetch("rack.input").read
+
+  begin
+    event = Invoq.verify_webhook(
+      raw_body,
+      { "invoq-signature" => env["HTTP_INVOQ_SIGNATURE"] },
+      ENV.fetch("INVOQ_WEBHOOK_SECRET")
+    )
+  rescue Invoq::SignatureVerificationError
+    return [
+      400,
+      { "content-type" => "application/json" },
+      ['{"error":"invalid signature"}']
+    ]
+  end
+
+  if Invoq.invoice_paid?(event)
+    invoice = event.fetch("data").fetch("invoice")
+    fulfillment_key = invoice["reference_id"] || invoice.fetch("id")
+
+    # Fulfill the order for fulfillment_key idempotently.
+  end
+
+  [
+    200,
+    { "content-type" => "application/json" },
+    ['{"received":true}']
+  ]
+end
+```
+
+Use `invoice.paid` webhooks to fulfill orders on your server. Browser checkout
+results are only for updating the customer experience; do not fulfill orders
+from browser results.
+
+When `Invoq.invoice_paid?(event)` is true, the invoice is ready for automatic
+fulfillment; use the invoice `reference_id` or a stored invoice `id` to find
+and fulfill your order. A `review_required` invoice does not emit an
+`invoice.paid` webhook yet. If checkout reports `review_required`, show a
+pending-review state and wait for a later `invoice.paid` webhook after review
+is approved.
+
+Important:
+
+- Pass the exact raw request body string received by your Ruby framework.
+- Pass the `invoq-signature` header.
+- `verify_webhook` does not require `Invoq.new(...)` or your invoq API secret
+  key.
+- Use your webhook secret (`whsec_...`), not `INVOQ_SECRET_KEY`.
+- Make fulfillment idempotent. Retried webhook deliveries can send the same
+  event more than once.
+- Respond with a 2xx quickly. Any other status counts as a failed delivery.
+  Transient failures such as timeouts, `429`, and `5xx` responses are retried;
+  other `4xx` responses are not.
+
+`Invoq.invoice_paid?` accepts fulfillable `invoice.paid` events whose invoice
+status is `paid`, `settling`, or `settled`; it rejects `review_required`.
+
+Webhook verification failures raise `Invoq::SignatureVerificationError`. The
+SDK allows a 5-minute timestamp tolerance. The signature header is:
+
+```txt
+invoq-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
+```
+
+## Errors
+
+```ruby
+begin
+  invoq.invoices.create(amount: "0.001", currency: "USD")
+rescue Invoq::ApiError => error
+  warn error.status
+  warn error.code
+  warn error.fields
+  warn error.meta
+  warn error.payload
+rescue Invoq::Error
+  raise
+end
+```
+
+Non-2xx API responses raise `Invoq::ApiError` with `status`, `code`, `fields`,
+`meta`, and the raw `payload`.
+
+Connection failures, timeouts, invalid input, and response parse failures raise
+`Invoq::Error`. Timed-out invoice creation is safe to retry with the same
+`reference_id`.
+
+Webhook verification failures raise `Invoq::SignatureVerificationError` with one
+of these codes:
+
+```txt
+missing_signature
+invalid_signature_header
+timestamp_outside_tolerance
+signature_mismatch
+invalid_payload
+```
+
+## Development
+
+```sh
+bundle exec rake test
+```
+
+## License
+
+Licensed under the MIT license.

data/lib/invoq/client.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "uri"
+
+require_relative "errors"
+require_relative "invoices_resource"
+
+module Invoq
+  DEFAULT_API_ORIGIN = "https://api.invoq.money"
+  DEFAULT_TIMEOUT_MS = 10_000
+  MAX_TIMEOUT_MS = 4_294_967_295
+
+  class Client
+    attr_reader :invoices
+
+    def initialize(api_key, api_origin: DEFAULT_API_ORIGIN, timeout_ms: DEFAULT_TIMEOUT_MS)
+      unless api_key.is_a?(String) && !api_key.strip.empty?
+        raise Error, "invoq API key must be a non-empty string."
+      end
+
+      @api_key = api_key
+      @api_origin = Invoq.normalize_api_origin(api_origin)
+      @timeout_ms = Invoq.normalize_timeout_ms(timeout_ms)
+      @invoices = InvoicesResource.new(
+        api_key: @api_key,
+        api_origin: @api_origin,
+        timeout_ms: @timeout_ms
+      )
+    end
+
+    def inspect
+      "#<#{self.class} api_origin=#{@api_origin.inspect} timeout_ms=#{@timeout_ms.inspect}>"
+    end
+  end
+
+  def self.normalize_api_origin(value)
+    unless value.is_a?(String)
+      raise Error, "api_origin must be an absolute http or https origin."
+    end
+
+    uri = URI.parse(value)
+
+    unless uri.is_a?(URI::HTTP) && uri.host && !uri.host.empty?
+      raise Error, "api_origin must be an absolute http or https origin."
+    end
+
+    unless uri.scheme == "http" || uri.scheme == "https"
+      raise Error, "api_origin must be an absolute http or https origin."
+    end
+
+    if uri.user || uri.password
+      raise Error, "api_origin must be an absolute http or https origin."
+    end
+
+    if uri.port < 1 || uri.port > 65_535
+      raise Error, "api_origin must be an absolute http or https origin."
+    end
+
+    if uri.query || uri.fragment
+      raise Error, "api_origin must not include query or hash parts."
+    end
+
+    pathname = uri.path.to_s.sub(%r{/+\z}, "")
+    pathname = "/" if pathname.empty?
+
+    unless pathname == "/"
+      raise Error, "api_origin must not include a path."
+    end
+
+    uri.path = "/"
+    uri.query = nil
+    uri.fragment = nil
+    uri.to_s
+  rescue URI::InvalidURIError
+    raise Error, "api_origin must be an absolute http or https origin."
+  end
+
+  def self.normalize_timeout_ms(value)
+    unless value.is_a?(Integer) && value.positive? && value <= MAX_TIMEOUT_MS
+      raise Error, "timeout_ms must be a positive integer of at most 4294967295."
+    end
+
+    value
+  end
+end

data/lib/invoq/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Invoq
+  class Error < StandardError
+    attr_reader :payload
+
+    def initialize(message = nil, payload: nil)
+      super(message)
+      @payload = payload
+    end
+  end
+
+  class ApiError < Error
+    attr_reader :status, :code, :fields, :meta
+
+    def initialize(message, status:, code: nil, fields: nil, meta: nil, payload: nil)
+      super(message, payload: payload)
+      @status = status
+      @code = code
+      @fields = fields
+      @meta = meta
+    end
+  end
+
+  class SignatureVerificationError < Error
+    attr_reader :code
+
+    def initialize(code, message)
+      super(message)
+      @code = code
+    end
+  end
+end

data/lib/invoq/internal/request.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "timeout"
+require "uri"
+
+require_relative "../errors"
+require_relative "../version"
+
+module Invoq
+  module Internal
+    class Request
+      NO_BODY = Object.new
+      USER_AGENT = "invoq-ruby/#{Invoq::VERSION}"
+
+      def self.json(api_key:, api_origin:, timeout_ms:, path:, method: "POST", body: NO_BODY)
+        url = URI.parse(api_origin + path.sub(%r{\A/+}, ""))
+        request = build_request(url, method)
+        request["Accept"] = "application/json"
+        request["Authorization"] = "Bearer #{api_key}"
+        request["User-Agent"] = USER_AGENT
+
+        unless body.equal?(NO_BODY)
+          request.body = JSON.generate(body)
+          request["Content-Type"] = "application/json"
+        end
+
+        response = perform_request(url, request, timeout_ms)
+        status = response.code.to_i
+        response_text = response.body.to_s
+
+        begin
+          payload = JSON.parse(response_text)
+        rescue JSON::ParserError
+          if status < 200 || status >= 300
+            raise api_error_from_response(status, response_text)
+          end
+
+          raise Error, "Failed to parse invoq API response."
+        end
+
+        if status < 200 || status >= 300
+          raise api_error_from_response(status, payload)
+        end
+
+        unless payload.is_a?(Hash) && payload.key?("data")
+          raise Error.new(
+            "invoq API response did not include a data envelope.",
+            payload: payload
+          )
+        end
+
+        payload["data"]
+      rescue JSON::GeneratorError
+        raise Error, "Failed to encode invoq API request."
+      end
+
+      def self.build_request(url, method)
+        case method
+        when "GET"
+          Net::HTTP::Get.new(url)
+        when "POST"
+          Net::HTTP::Post.new(url)
+        else
+          raise Error, "Unsupported invoq API request method."
+        end
+      end
+      private_class_method :build_request
+
+      def self.perform_request(url, request, timeout_ms)
+        timeout_seconds = timeout_ms / 1000.0
+
+        Timeout.timeout(timeout_seconds) do
+          Net::HTTP.start(
+            url.host,
+            url.port,
+            use_ssl: url.scheme == "https",
+            open_timeout: timeout_seconds,
+            read_timeout: timeout_seconds,
+            write_timeout: timeout_seconds
+          ) do |http|
+            http.request(request)
+          end
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout, Timeout::Error
+        raise Error, "invoq API request timed out."
+      rescue Error
+        raise
+      rescue StandardError
+        raise Error, "Failed to connect to invoq API."
+      end
+      private_class_method :perform_request
+
+      def self.api_error_from_response(status, payload)
+        error = payload.is_a?(Hash) ? payload : nil
+        code = error && error["code"].is_a?(String) ? error["code"] : nil
+        message = error && error["message"].is_a?(String) ? error["message"] : "invoq API request failed."
+        fields = parse_fields(error && error["fields"])
+        meta = error && error["meta"].is_a?(Hash) ? error["meta"] : nil
+
+        ApiError.new(
+          message,
+          status: status,
+          code: code,
+          fields: fields,
+          meta: meta,
+          payload: payload
+        )
+      end
+      private_class_method :api_error_from_response
+
+      def self.parse_fields(value)
+        return nil unless value.is_a?(Array)
+
+        fields = value.each_with_object([]) do |field, result|
+          next unless field.is_a?(Hash)
+
+          location = field["location"]
+          next unless %w[query path body header].include?(location)
+          next unless field["field"].is_a?(String)
+          next unless field["code"].is_a?(String)
+          next unless field["message"].is_a?(String)
+
+          result << {
+            "field" => field["field"],
+            "location" => location,
+            "code" => field["code"],
+            "message" => field["message"]
+          }
+        end
+
+        fields
+      end
+      private_class_method :parse_fields
+    end
+  end
+end

data/lib/invoq/invoices_resource.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "internal/request"
+
+module Invoq
+  class InvoicesResource
+    MISSING = Object.new
+
+    def initialize(api_key:, api_origin:, timeout_ms:)
+      @api_key = api_key
+      @api_origin = api_origin
+      @timeout_ms = timeout_ms
+    end
+
+    def create(input)
+      Internal::Request.json(
+        api_key: @api_key,
+        api_origin: @api_origin,
+        timeout_ms: @timeout_ms,
+        path: "/v1/invoices",
+        body: create_invoice_request_body(input)
+      )
+    end
+
+    def get(invoice_id)
+      id = encode_path_segment(required_request_string(invoice_id, "invoice_id"))
+
+      Internal::Request.json(
+        api_key: @api_key,
+        api_origin: @api_origin,
+        timeout_ms: @timeout_ms,
+        method: "GET",
+        path: "/v1/invoices/#{id}"
+      )
+    end
+
+    def create_test_payment(invoice_id, input)
+      id = encode_path_segment(required_request_string(invoice_id, "invoice_id"))
+
+      Internal::Request.json(
+        api_key: @api_key,
+        api_origin: @api_origin,
+        timeout_ms: @timeout_ms,
+        path: "/v1/invoices/#{id}/test-payments",
+        body: create_test_payment_request_body(input)
+      )
+    end
+
+    private
+
+    def create_invoice_request_body(input)
+      unless input.is_a?(Hash)
+        raise Error, "request body must be a hash."
+      end
+
+      body = {
+        "amount" => required_request_string(input_value(input, "amount"), "amount")
+      }
+      currency = optional_request_value(input, "currency")
+      description = optional_request_string(input, "description")
+      reference_id = optional_request_string(input, "reference_id")
+      return_url = optional_nullable_request_string(input, "return_url")
+
+      body["currency"] = currency unless currency.equal?(MISSING)
+      body["description"] = description unless description.equal?(MISSING)
+      body["reference_id"] = reference_id unless reference_id.equal?(MISSING)
+      body["return_url"] = return_url unless return_url.equal?(MISSING)
+
+      body
+    end
+
+    def create_test_payment_request_body(input)
+      unless input.is_a?(Hash)
+        raise Error, "request body must be a hash."
+      end
+
+      body = {
+        "amount" => required_request_string(input_value(input, "amount"), "amount")
+      }
+      reference_id = optional_request_string(input, "reference_id")
+
+      body["reference_id"] = reference_id unless reference_id.equal?(MISSING)
+
+      body
+    end
+
+    def optional_request_string(input, field)
+      value = optional_request_value(input, field)
+      return MISSING if value.equal?(MISSING)
+
+      unless value.is_a?(String)
+        raise Error, "#{field} must be a string when provided."
+      end
+
+      value
+    end
+
+    def optional_nullable_request_string(input, field)
+      value = optional_request_value(input, field)
+      return MISSING if value.equal?(MISSING)
+
+      unless value.nil? || value.is_a?(String)
+        raise Error, "#{field} must be a string or nil when provided."
+      end
+
+      value
+    end
+
+    def required_request_string(value, field)
+      unless value.is_a?(String) && !value.strip.empty?
+        raise Error, "#{field} must be a non-empty string."
+      end
+
+      value
+    end
+
+    def optional_request_value(input, field)
+      if input.key?(field)
+        input[field]
+      elsif input.key?(field.to_sym)
+        input[field.to_sym]
+      else
+        MISSING
+      end
+    end
+
+    def input_value(input, field)
+      return input[field] if input.key?(field)
+
+      input[field.to_sym]
+    end
+
+    def encode_path_segment(value)
+      value.encode("UTF-8").bytes.map do |byte|
+        if unescaped_path_byte?(byte)
+          byte.chr
+        else
+          format("%%%02X", byte)
+        end
+      end.join
+    end
+
+    def unescaped_path_byte?(byte)
+      case byte
+      when 65..90, 97..122, 48..57, 45, 95, 46, 33, 126, 42, 39, 40, 41
+        true
+      else
+        false
+      end
+    end
+  end
+end

data/lib/invoq/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Invoq
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/invoq/webhooks.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+require_relative "errors"
+
+module Invoq
+  module Webhooks
+    DEFAULT_TOLERANCE_SECONDS = 300
+    SIGNATURE_PATTERN = /\A[a-f0-9]{64}\z/i
+    MISSING = Object.new
+
+    def self.verify_webhook(raw_body, headers, webhook_secret)
+      signature_header = get_signature_header(headers)
+
+      if signature_header.nil? || signature_header.empty?
+        raise signature_error("missing_signature", "Missing invoq-signature header.")
+      end
+
+      unless webhook_secret.is_a?(String) && !webhook_secret.empty?
+        raise signature_error(
+          "invalid_signature_header",
+          "Webhook secret must be a non-empty string."
+        )
+      end
+
+      timestamp, timestamp_seconds, signature = parse_signature_header(signature_header)
+      now_seconds = Time.now.to_i
+
+      if (now_seconds - timestamp_seconds).abs > DEFAULT_TOLERANCE_SECONDS
+        raise signature_error(
+          "timestamp_outside_tolerance",
+          "Webhook timestamp is outside the allowed tolerance."
+        )
+      end
+
+      expected_signature = hmac_sha256_hex(webhook_secret, timestamp, raw_body)
+
+      unless constant_time_equal?(expected_signature, signature)
+        raise signature_error("signature_mismatch", "Webhook signature mismatch.")
+      end
+
+      payload = JSON.parse(body_text(raw_body))
+
+      unless payload.is_a?(Hash) && payload["type"].is_a?(String)
+        raise signature_error(
+          "invalid_payload",
+          "Webhook payload must be an object with a string type."
+        )
+      end
+
+      payload
+    rescue JSON::ParserError
+      raise signature_error("invalid_payload", "Webhook payload is not valid JSON.")
+    end
+
+    def self.invoice_paid?(event)
+      return false unless event.is_a?(Hash)
+      return false unless event["type"] == "invoice.paid"
+      return false unless event["id"].is_a?(String)
+      return false unless invoice_mode?(event["mode"])
+      return false unless event["created_at"].is_a?(String)
+
+      data = event["data"]
+      return false unless data.is_a?(Hash)
+
+      invoice = data["invoice"]
+      return false unless invoice.is_a?(Hash)
+
+      reference_id = invoice.key?("reference_id") ? invoice["reference_id"] : MISSING
+      fully_paid_at = invoice.key?("fully_paid_at") ? invoice["fully_paid_at"] : MISSING
+
+      invoice["id"].is_a?(String) &&
+        invoice_mode?(invoice["mode"]) &&
+        invoice_paid_status?(invoice["status"]) &&
+        invoice["amount"].is_a?(String) &&
+        invoice["currency"] == "USD" &&
+        invoice["amount_paid"].is_a?(String) &&
+        (reference_id.is_a?(String) || reference_id.nil?) &&
+        (fully_paid_at.is_a?(String) || fully_paid_at.nil?)
+    end
+
+    def self.is_invoice_paid(event)
+      invoice_paid?(event)
+    end
+
+    def self.parse_signature_header(signature_header)
+      parts = {}
+
+      signature_header.split(",").each do |part|
+        separator_index = part.index("=")
+
+        unless separator_index
+          raise signature_error(
+            "invalid_signature_header",
+            "Invalid invoq-signature header."
+          )
+        end
+
+        key = part[0...separator_index].strip
+        value = part[(separator_index + 1)..-1].to_s.strip
+        next if key.empty? || value.empty?
+
+        parts[key] = value
+      end
+
+      timestamp = parts["t"]
+      signature = parts["v1"]
+
+      unless timestamp && signature && timestamp.match?(/\A\d+\z/)
+        raise signature_error(
+          "invalid_signature_header",
+          "Invalid invoq-signature header."
+        )
+      end
+
+      unless signature.match?(SIGNATURE_PATTERN)
+        raise signature_error(
+          "invalid_signature_header",
+          "Invalid invoq-signature signature."
+        )
+      end
+
+      [timestamp, timestamp.to_i, signature.downcase]
+    end
+    private_class_method :parse_signature_header
+
+    def self.get_signature_header(headers)
+      return nil if headers.nil?
+      return nil unless headers.respond_to?(:each)
+
+      headers.each do |key, value|
+        next unless key.to_s.downcase == "invoq-signature"
+
+        return nil if value.nil?
+        return value.map(&:to_s).join(",") if value.is_a?(Array)
+
+        return value.to_s
+      end
+
+      nil
+    end
+    private_class_method :get_signature_header
+
+    def self.hmac_sha256_hex(secret, timestamp, raw_body)
+      OpenSSL::HMAC.hexdigest(
+        "SHA256",
+        secret.encode("UTF-8"),
+        "#{timestamp}.".b + body_bytes(raw_body)
+      )
+    end
+    private_class_method :hmac_sha256_hex
+
+    def self.body_text(raw_body)
+      body_bytes(raw_body).force_encoding("UTF-8")
+    end
+    private_class_method :body_text
+
+    def self.body_bytes(raw_body)
+      unless raw_body.is_a?(String)
+        raise signature_error("invalid_payload", "Webhook payload is not valid JSON.")
+      end
+
+      raw_body.b
+    end
+    private_class_method :body_bytes
+
+    def self.constant_time_equal?(left, right)
+      left_bytes = left.b.bytes
+      right_bytes = right.b.bytes
+      max_length = [left_bytes.length, right_bytes.length, 1].max
+      result = left_bytes.length ^ right_bytes.length
+
+      max_length.times do |index|
+        result |= (left_bytes[index] || 0) ^ (right_bytes[index] || 0)
+      end
+
+      result.zero?
+    end
+    private_class_method :constant_time_equal?
+
+    def self.invoice_mode?(value)
+      value == "test" || value == "live"
+    end
+    private_class_method :invoice_mode?
+
+    def self.invoice_paid_status?(value)
+      value == "paid" || value == "settling" || value == "settled"
+    end
+    private_class_method :invoice_paid_status?
+
+    def self.signature_error(code, message)
+      SignatureVerificationError.new(code, message)
+    end
+    private_class_method :signature_error
+  end
+end

data/lib/invoq.rb

@@ -1,7 +1,24 @@
 # frozen_string_literal: true
 
 require_relative "invoq/version"
+require_relative "invoq/errors"
+require_relative "invoq/client"
+require_relative "invoq/webhooks"
 
 module Invoq
-  class Error < StandardError; end
+  def self.new(api_key, api_origin: DEFAULT_API_ORIGIN, timeout_ms: DEFAULT_TIMEOUT_MS)
+    Client.new(api_key, api_origin: api_origin, timeout_ms: timeout_ms)
+  end
+
+  def self.verify_webhook(raw_body, headers, webhook_secret)
+    Webhooks.verify_webhook(raw_body, headers, webhook_secret)
+  end
+
+  def self.invoice_paid?(event)
+    Webhooks.invoice_paid?(event)
+  end
+
+  def self.is_invoice_paid(event)
+    invoice_paid?(event)
+  end
 end

metadata

@@ -1,17 +1,49 @@
 --- !ruby/object:Gem::Specification
 name: invoq
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
-- Invoq
-autorequire: 
+- invoq
 bindir: bin
 cert_chain: []
-date: 2026-06-07 00:00:00.000000000 Z
-dependencies: []
-description: An early placeholder release for the future Invoq Ruby SDK.
-email: 
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14.0'
+description: Ruby SDK for invoq server APIs and webhook verification.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -19,13 +51,17 @@ files:
 - LICENSE.txt
 - README.md
 - lib/invoq.rb
+- lib/invoq/client.rb
+- lib/invoq/errors.rb
+- lib/invoq/internal/request.rb
+- lib/invoq/invoices_resource.rb
 - lib/invoq/version.rb
+- lib/invoq/webhooks.rb
 homepage: https://rubygems.org/gems/invoq
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -40,8 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Ruby SDK for Invoq stablecoin payment acceptance.
+summary: Ruby SDK for invoq stablecoin payment acceptance.
 test_files: []