invoq 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4394aa795d6674da3055ce51a03de79b19602bc50139dc19bd00488b0bcc267
-  data.tar.gz: 4bba9c3d77bf88951e393097b7b9e47301f42d668acdae4b93ac24adbcf9254b
+  metadata.gz: d6735a9a9a69b7d895e5195f2c996067a5e6abc84535da30bb9c1994b235b15d
+  data.tar.gz: 8882cfaa9d72e9beda66de5bf69a213058164e2b0043aeb2681351f0838a9ad6
 SHA512:
-  metadata.gz: e6606f9c4a3f0043e1353f007da072d9cae06edf823e3f695e9aac80938010baa38bd98bbbeb24d12adb164bbfea2f25f38db62f2a8e14267282d3876bb9fd21
-  data.tar.gz: 6beee35201584d88936d0d289301436eac266f87e0ef0a03889207fce892e72f36a50885314a365f63d93ca8ca714acf0889046150da1069f138469f63ccc48d
+  metadata.gz: a3ae2327b5bfed2af09db878361a2a15028f4943e905ec610884c1e36dc5cdacd75d2aa9385eda9f61dff1382739a58553a449f9233c2e4e160bf1136803f610
+  data.tar.gz: 43efaca949a9c6e2d9ddaf8d34a4381baf70a9a59eaf07902b32616269a57ec4b1aa7371bfdf49c99decaf0f0b2140ab641c8f4ebc9ef1cd5fca43e247fd013e

data/README.md

@@ -1,6 +1,6 @@
 # invoq Ruby SDK
 
-**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)
+**English** · [Bahasa Indonesia](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.id.md) · [Español](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.es-419.md) · [Français](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.fr.md) · [Português](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.pt-BR.md) · [Tiếng Việt](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.vi.md) · [Türkçe](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.tr.md) · [ไทย](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.th.md) · [简体中文](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.zh-Hans.md) · [繁體中文](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.zh-Hant.md)
 
 Accept stablecoin payments with invoq from Ruby server code. This SDK wraps
 invoq server APIs and verifies signed webhooks.
@@ -8,6 +8,12 @@ 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.
 
+**Coding with AI? Paste this.**
+
+```
+Add stablecoin payments to my project with invoq. Start in test mode. Read the docs before you write any code: https://invoq.money/llms.txt
+```
+
 ## 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.
@@ -49,6 +55,9 @@ Requires Ruby 2.6 or newer.
 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.
+4. Set up your **Receiving wallet** before going live. Test invoices don't need
+   one; a live invoice with nowhere to settle fails with
+   `409 no_payment_options_available`.
 
 Add both to your server environment:
 
@@ -97,7 +106,6 @@ 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"
@@ -110,9 +118,9 @@ 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"`.
+- `amount` is a decimal USD string from `"0.01"` to `"1000000.00"` with up
+  to 2 decimal places, such as `"129"` or `"129.99"`. Currency is always USD,
+  and test or live comes from the key — neither is a request field.
 - 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
@@ -131,12 +139,10 @@ Get an invoice:
 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`.
+`invoices.get` returns the public invoice shape used by hosted checkout: the
+create shape plus `amount_paid`, `project`, and `transfers`, minus
+`reference_id`. Use the create response or the `invoice.paid` webhook when you
+need your merchant `reference_id`.
 
 Create a test payment:
 
@@ -161,8 +167,7 @@ webhook URL.
 
 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.
+URL in the dashboard.
 
 Each invoice method returns the response `data` object directly as a Ruby hash.
 
@@ -179,22 +184,40 @@ 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.
+strings before sending requests. The invoq API validates the amount format and
+range.
 
 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`.
+`nil`. Any other key in the hash is dropped rather than sent, because the API
+rejects unknown body keys.
 
 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.
+
+Two status fields. `status` is the accounting one — `unpaid`, `partially_paid`,
+`paid`, `settling`, `settled`, `review_required` — where the three paid-like
+values differ only in how far the funds have moved to your wallet.
+`checkout_status` is payer-facing — `open`, `confirming`, `expired`, `paid`,
+`unavailable` — and never authorizes fulfillment. `payment_revision` is a
+non-negative integer that increments whenever the confirmed payment set changes,
+so you can discard a snapshot older than one you already hold.
+
+`payment_options` holds the payment instructions, fixed at creation and `[]` in
+test mode. Entries are discriminated by `status`, then `collection_method`: only
+`"ready"` is payable, `"evm_deposit"` carries `deposit_address` and
+`suggested_amount`, `"direct_exact"` carries `recipient_address` and an
+`exact_amount` the buyer must send to the digit. `transfers` is the confirmed
+receipt trail — `transaction_id`, `event_index`, `amount`,
+`explorer_transaction_url` — and stays `[]` until a payment confirms. Full field
+reference: [REST API docs](https://github.com/invoqmoney/api).
+
+Identify a payment option by `chain_namespace`, `chain_reference`, and
+`token_address`, never by its position in the array. `monitoring_ends_at` is the
+end of the payment window, and is `nil` for test invoices.
 
 ## Webhooks
 
@@ -229,6 +252,11 @@ def handle_invoq_webhook(env)
     fulfillment_key = invoice["reference_id"] || invoice.fetch("id")
 
     # Fulfill the order for fulfillment_key idempotently.
+  elsif Invoq.invoice_payment_reversed?(event)
+    invoice = event.fetch("data").fetch("invoice")
+    fulfillment_key = invoice["reference_id"] || invoice.fetch("id")
+
+    # Hold or reverse the order for fulfillment_key.
   end
 
   [
@@ -245,11 +273,16 @@ 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
+and fulfill your order. A `review_required` invoice emits no `invoice.paid`
+until the review clears. If checkout reports `review_required`, show a
 pending-review state and wait for a later `invoice.paid` webhook after review
 is approved.
 
+invoq also sends `invoice.payment_reversed` when a previously paid invoice drops
+back below its amount — a chain reorg dropping a confirmed transfer, for
+example. Catch it with `Invoq.invoice_payment_reversed?(event)` and hold or
+reverse the fulfillment according to your own policy.
+
 Important:
 
 - Pass the exact raw request body string received by your Ruby framework.
@@ -259,12 +292,19 @@ Important:
 - 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.
+- Respond with a 2xx quickly. Any other status counts as a failed delivery and
+  is retried, including redirects and `4xx`, so a deploy window or a temporarily
+  misrouted path is retried rather than dropped. The ladder is 1 minute,
+  5 minutes, 30 minutes, then 2 hours, for 5 attempts in total.
+- Deliveries can arrive out of order. Keep the snapshot with the highest
+  `payment_revision`.
 
 `Invoq.invoice_paid?` accepts fulfillable `invoice.paid` events whose invoice
 status is `paid`, `settling`, or `settled`; it rejects `review_required`.
+`Invoq.invoice_payment_reversed?` accepts `invoice.payment_reversed` events
+without checking the status at all: a reversal you drop leaves an order
+fulfilled on a payment that no longer exists. An event type this SDK version
+does not model still verifies and is returned as-is.
 
 Webhook verification failures raise `Invoq::SignatureVerificationError`. The
 SDK allows a 5-minute timestamp tolerance. The signature header is:
@@ -277,7 +317,7 @@ invoq-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
 
 ```ruby
 begin
-  invoq.invoices.create(amount: "0.001", currency: "USD")
+  invoq.invoices.create(amount: "0.001")
 rescue Invoq::ApiError => error
   warn error.status
   warn error.code

data/lib/invoq/client.rb

@@ -18,6 +18,12 @@ module Invoq
         raise Error, "invoq API key must be a non-empty string."
       end
 
+      # A control character in a key is either rejected deep in the transport or
+      # silently sent; reject it here so every SDK answers the same way.
+      if api_key.match?(/[\x00-\x1F\x7F]/)
+        raise Error, "invoq API key must not contain control characters."
+      end
+
       @api_key = api_key
       @api_origin = Invoq.normalize_api_origin(api_origin)
       @timeout_ms = Invoq.normalize_timeout_ms(timeout_ms)

data/lib/invoq/internal/request.rb

@@ -51,6 +51,15 @@ module Invoq
           )
         end
 
+        # A non-Hash data is a broken envelope; returning it defers the failure
+        # to the caller's first read.
+        unless payload["data"].is_a?(Hash)
+          raise Error.new(
+            "invoq API response data envelope was not an object.",
+            payload: payload
+          )
+        end
+
         payload["data"]
       rescue JSON::GeneratorError
         raise Error, "Failed to encode invoq API request."
@@ -116,8 +125,11 @@ module Invoq
         fields = value.each_with_object([]) do |field, result|
           next unless field.is_a?(Hash)
 
+          # A location this version does not know is passed through, not
+          # dropped: the caller is already on an error path and needs the code
+          # and message. Only a structurally invalid entry is discarded.
           location = field["location"]
-          next unless %w[query path body header].include?(location)
+          next unless location.is_a?(String)
           next unless field["field"].is_a?(String)
           next unless field["code"].is_a?(String)
           next unless field["message"].is_a?(String)

data/lib/invoq/invoices_resource.rb

@@ -24,7 +24,7 @@ module Invoq
     end
 
     def get(invoice_id)
-      id = encode_path_segment(required_request_string(invoice_id, "invoice_id"))
+      id = encode_path_segment(required_path_segment(invoice_id, "invoice_id"))
 
       Internal::Request.json(
         api_key: @api_key,
@@ -36,7 +36,7 @@ module Invoq
     end
 
     def create_test_payment(invoice_id, input)
-      id = encode_path_segment(required_request_string(invoice_id, "invoice_id"))
+      id = encode_path_segment(required_path_segment(invoice_id, "invoice_id"))
 
       Internal::Request.json(
         api_key: @api_key,
@@ -54,15 +54,16 @@ module Invoq
         raise Error, "request body must be a hash."
       end
 
+      # Only these four fields exist: the API rejects unknown body keys, and
+      # currency (always USD) and mode (from the key) are not request fields,
+      # so anything else in the hash is dropped rather than forwarded.
       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)
@@ -107,6 +108,18 @@ module Invoq
       value
     end
 
+    # A URL resolver pops "." and "..", so an id of either would call a
+    # different endpoint instead of 404ing. Percent-encoding is no help.
+    def required_path_segment(value, field)
+      segment = required_request_string(value, field)
+
+      if segment == "." || segment == ".."
+        raise Error, "#{field} must not be a path segment that resolves ('.' or '..')."
+      end
+
+      segment
+    end
+
     def required_request_string(value, field)
       unless value.is_a?(String) && !value.strip.empty?
         raise Error, "#{field} must be a non-empty string."

data/lib/invoq/version.rb

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

data/lib/invoq/webhooks.rb

@@ -56,39 +56,65 @@ module Invoq
     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)
+      invoice = lifecycle_event_invoice(event, "invoice.paid")
+
+      # Paid-equivalent statuses only: review_required has money against it but
+      # is not cleared for fulfillment.
+      !invoice.nil? && invoice_paid_status?(invoice["status"])
+    end
+
+    def self.is_invoice_paid(event)
+      invoice_paid?(event)
+    end
+
+    def self.invoice_payment_reversed?(event)
+      # No status check, unlike the paid guard: rejecting an unrecognized status
+      # would drop the event and leave the order fulfilled on a payment that no
+      # longer exists.
+      !lifecycle_event_invoice(event, "invoice.payment_reversed").nil?
+    end
+
+    def self.is_invoice_payment_reversed(event)
+      invoice_payment_reversed?(event)
+    end
+
+    # The fields both lifecycle events share, returned so each guard can apply
+    # its own status rule. nil when this is not a well-formed event of that type.
+    def self.lifecycle_event_invoice(event, type)
+      return nil unless event.is_a?(Hash)
+      return nil unless event["type"] == type
+      return nil unless event["id"].is_a?(String)
+      return nil unless invoice_mode?(event["mode"])
+      return nil unless event["created_at"].is_a?(String)
 
       data = event["data"]
-      return false unless data.is_a?(Hash)
+      return nil unless data.is_a?(Hash)
 
       invoice = data["invoice"]
-      return false unless invoice.is_a?(Hash)
+      return nil 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) &&
+      valid = invoice["id"].is_a?(String) &&
         invoice_mode?(invoice["mode"]) &&
-        invoice_paid_status?(invoice["status"]) &&
+        invoice["status"].is_a?(String) &&
         invoice["amount"].is_a?(String) &&
         invoice["currency"] == "USD" &&
         invoice["amount_paid"].is_a?(String) &&
         (reference_id.is_a?(String) || reference_id.nil?) &&
+        invoice["payment_revision"].is_a?(Integer) &&
         (fully_paid_at.is_a?(String) || fully_paid_at.nil?)
-    end
 
-    def self.is_invoice_paid(event)
-      invoice_paid?(event)
+      valid ? invoice : nil
     end
+    private_class_method :lifecycle_event_invoice
 
     def self.parse_signature_header(signature_header)
       parts = {}
 
-      signature_header.split(",").each do |part|
+      # -1 keeps trailing empty fields, so a trailing comma reaches the check below.
+      signature_header.split(",", -1).each do |part|
         separator_index = part.index("=")
 
         unless separator_index
@@ -146,7 +172,7 @@ module Invoq
     def self.hmac_sha256_hex(secret, timestamp, raw_body)
       OpenSSL::HMAC.hexdigest(
         "SHA256",
-        secret.encode("UTF-8"),
+        secret.b,
         "#{timestamp}.".b + body_bytes(raw_body)
       )
     end

data/lib/invoq.rb

@@ -21,4 +21,12 @@ module Invoq
   def self.is_invoice_paid(event)
     invoice_paid?(event)
   end
+
+  def self.invoice_payment_reversed?(event)
+    Webhooks.invoice_payment_reversed?(event)
+  end
+
+  def self.is_invoice_payment_reversed(event)
+    invoice_payment_reversed?(event)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: invoq
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - invoq