openreceive 0.4.4 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bd20dc218edcb52926dbb336899f73a4b20312c28469ff8e290a750e9c53e4f
-  data.tar.gz: 4571b97667dfb0d8f19c67439b6005499d92643147b21e6552d426cca9258f5a
+  metadata.gz: 2a58066e78b2dd865b470bda546e371dccea7881c47c0b9d6a98476ffc425ce2
+  data.tar.gz: 1924a2e38066b8b7e52806850029917093805c998e3cfa8ea37656f62ae5ebd9
 SHA512:
-  metadata.gz: 481da5894c2d65c415a6d456763a6550beeea53e1f1a5cce7a79c80994c07e30e80e287a3646d18138fc83fd706e1d62cb44e95018af517fd7c23dd2668b3ced
-  data.tar.gz: '0879af77cfba1eb24cdaab833e551511fb9e0d1508d7a0633df5e4eb6494a346874c1890c465e3c5eb4ccc3bee6d8b9e4bbe6e45afaa5211bb383ebe92f9e19a'
+  metadata.gz: f150f29cf3356647ca2e3c1566e63a8824e62a3af6258586422af5a20193c0447855f39fb819870b5f920543e182f63043bb09d73eba36b5a67feeae61098284
+  data.tar.gz: 0ee1d97ff42aa3d35587c01f44bad5828511599afe373500c01e1b4e445d78ffef3fd672a88329c0e60d1028cd48d5373831bc2abb5554e8c682a5d18c79c908

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.6 - 2026-09-11
+
+Remove obsolete VEF from live price-feed requests, matching the JavaScript,
+Python and PHP engines. Refresh installation and quickstart documentation and
+package metadata. Release in lockstep with the compact checkout and publishing
+fixes in 0.4.6; no Ruby public API change.
+
+## 0.4.5 - 2026-09-07
+
+Release in lockstep with the Python/PHP publishing workflow fixes and complete
+WooCommerce integration documentation. Shared HTTP golden fixtures now use
+the canonical placeholder definitions. No Ruby public API change.
+
 ## 0.4.4 - 2026-09-07
 
 Version lockstep with the 0.4.4 npm release (every checkout image now ships

data/README.md

@@ -1,23 +1,34 @@
 # openreceive
 
-Pure Ruby exact-money, NWC normalization, and settlement-authority primitives
-for [OpenReceive](https://openreceive.org). It has no persistence dependency.
-Settlement requires `settled_at` or state `settled`; a preimage alone does not
-settle a payment.
-
-OpenReceive adds receive-only Bitcoin Lightning payments to a website or app:
-your server creates and verifies BOLT11 invoices through a wallet you control
-via a receive-only Nostr Wallet Connect (NWC / NIP-47) connection. This gem is
-the dependency-free core; most applications want one of the gems built on it:
-
-- [`openreceive-server`](https://rubygems.org/gems/openreceive-server) — the
-  storage-free Service and framework-agnostic Rack app for the shipped HTTP
-  routes.
+**Bitcoin Lightning payments for Ruby. Your app, your wallet.**
+
+[OpenReceive](https://openreceive.org) helps you accept payments directly into
+a wallet you control. Keep your orders, prices, and fulfillment in your own
+application, with receive-only Nostr Wallet Connect (NWC) connecting your
+server to your wallet.
+
+OpenReceive supports optional swaps from **USDT, USDC, SOL, and ETH** through
+a configured swap provider. The provider converts the payment to **BTC over
+Lightning**, which settles into the merchant's connected wallet. Available
+assets and networks depend on the provider; swaps are optional.
+
+This gem is the lightweight Ruby foundation: exact money conversion, exchange
+rates, wallet adapters, and shared settlement rules, with no database
+dependency. Most applications should start with one of the integrations
+built on it:
+
 - [`openreceive-rails`](https://rubygems.org/gems/openreceive-rails) — the
-  mountable Rails engine with host-owned payment scaffolding.
+  complete Rails integration, with payment storage in your existing database,
+  reconciliation, and three application hooks. [Start with Rails](https://github.com/OpenReceive/openreceive/blob/master/docs/guides/quickstart-rails.md).
+- [`openreceive-server`](https://rubygems.org/gems/openreceive-server) — invoice
+  creation, payment checks, and a Rack handler for custom Ruby integrations
+  that provide their own payment persistence. [Explore the server gem](https://github.com/OpenReceive/openreceive/blob/master/packages/ruby/openreceive-server/README.md).
 
 ## Install
 
+Requires Ruby 3.2 or later. Choose this gem directly when you need the payment
+primitives rather than a mounted checkout integration.
+
 ```sh
 gem install openreceive
 ```
@@ -39,6 +50,8 @@ gem "openreceive"
   (`OpenReceive::Nwc.normalize_wallet_error`,
   `OpenReceive::Nwc.normalize_transaction`).
 - Settlement-authority rules: what counts as settled, and what never does.
+  Settlement requires `settled_at` or state `settled`; a preimage alone does
+  not settle a payment.
 - The built-in price feed (`OpenReceive::Rates`): a static provider and the
   cached live feed with primary/fallback failover, fail-closed windows, and
   the shared currency list.
@@ -49,13 +62,14 @@ gem "openreceive"
   (`subscribe_notifications`, forwarded to that gem's
   `subscribe_to_notifications`).
 
-The behavior is pinned to the same test vectors as the Node engine
-(`spec/test-vectors` in the repository), so both engines make identical
-decisions.
+Money, wallet normalization, and settlement rules are tested against shared
+cross-language vectors in `spec/test-vectors`.
 
 ## Links
 
-- Documentation: <https://openreceive.org>
+- Rails quickstart: [Add checkout to your app](https://github.com/OpenReceive/openreceive/blob/master/docs/guides/quickstart-rails.md)
+- API reference: [Ruby and Rails APIs](https://github.com/OpenReceive/openreceive/blob/master/docs/guides/api-reference.md)
+- Website: <https://openreceive.org>
 - Source: <https://github.com/openreceive/openreceive>
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
 

data/lib/openreceive/rates.rb

@@ -40,7 +40,7 @@ module OpenReceive
     # The fixed fiat list both live feeds price Bitcoin against. Hard-coded so
     # the primary and fallback URLs always request the same currencies.
     PRICE_FEED_VS_CURRENCIES =
-      "usd,aed,ars,aud,bdt,bhd,bmd,brl,cad,chf,clp,cny,czk,dkk,eur,gbp,gel,hkd,huf,idr,ils,inr,jpy,krw,kwd,lkr,mmk,mxn,myr,ngn,nok,nzd,php,pkr,pln,rub,sar,sek,sgd,thb,try,twd,uah,vef,vnd,zar"
+      "usd,aed,ars,aud,bdt,bhd,bmd,brl,cad,chf,clp,cny,czk,dkk,eur,gbp,gel,hkd,huf,idr,ils,inr,jpy,krw,kwd,lkr,mmk,mxn,myr,ngn,nok,nzd,php,pkr,pln,rub,sar,sek,sgd,thb,try,twd,uah,vnd,zar"
 
     PRICE_FEED_CURRENCIES = PRICE_FEED_VS_CURRENCIES.split(",").freeze
 

data/lib/openreceive/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenReceive
-  VERSION = "0.4.4"
+  VERSION = "0.4.6"
 end

data/skills/integrate-openreceive/SKILL.md

@@ -30,6 +30,7 @@ code** (`NWC_URI`).
    - Rails: [references/rails.md](references/rails.md)
    - Django: [references/django.md](references/django.md)
    - Laravel: [references/laravel.md](references/laravel.md)
+   - WordPress + WooCommerce: [references/woocommerce.md](references/woocommerce.md) — the packaged gateway and merchant settings.
    - BTCPay Server: [references/btcpay.md](references/btcpay.md) — a plugin,
      configured in BTCPay's store UI or Greenfield API; no application code,
      no npm packages, no gem. The rest of this file is about the library.

data/skills/integrate-openreceive/references/btcpay.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.4.
+These directions describe OpenReceive 0.4.6.
 
 Connect a BTCPay Server store to a receive-only NWC wallet with the OpenReceive
 plugin, and optionally let payers pay BTCPay invoices with USDT, USDC, ETH or

data/skills/integrate-openreceive/references/django.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.4.
+These directions describe OpenReceive 0.4.6.
 
 Add OpenReceive to a Django project — the app you are already working in. You
 do not need a copy of the OpenReceive source: the Python package is on PyPI

data/skills/integrate-openreceive/references/fastapi.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.4.
+These directions describe OpenReceive 0.4.6.
 
 Add OpenReceive to a FastAPI application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the engine is on PyPI

data/skills/integrate-openreceive/references/fastify.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.4.
+These directions describe OpenReceive 0.4.6.
 
 Add OpenReceive to a Fastify application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the packages are on npm, and

data/skills/integrate-openreceive/references/laravel.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.4.
+These directions describe OpenReceive 0.4.6.
 
 Add OpenReceive to a Laravel application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the package is on Packagist

data/skills/integrate-openreceive/references/next.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.4.
+These directions describe OpenReceive 0.4.6.
 
 Add OpenReceive to a Next.js App Router application — the app you are already
 working in. You do not need a copy of the OpenReceive source: the packages are

data/skills/integrate-openreceive/references/node.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.4.
+These directions describe OpenReceive 0.4.6.
 
 Add OpenReceive to a Node application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the packages are on npm, and the

data/skills/integrate-openreceive/references/php.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (PHP)
 
-These directions describe OpenReceive 0.4.4.
+These directions describe OpenReceive 0.4.6.
 
 Add OpenReceive to a PHP application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the engine is on Packagist

data/skills/integrate-openreceive/references/rails.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.4.
+These directions describe OpenReceive 0.4.6.
 
 Add OpenReceive to a Rails application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the gem is on RubyGems, the

data/skills/integrate-openreceive/references/woocommerce.md

@@ -0,0 +1,176 @@
+# OpenReceive agent directions (WordPress + WooCommerce)
+
+These directions describe OpenReceive 0.4.6.
+
+Install and configure the OpenReceive gateway in the existing WooCommerce
+store. Preserve its theme, checkout, customer accounts, order model and prices.
+The plugin bundles the PHP engine and checkout assets; the merchant does not
+install npm or Composer packages on the WordPress server.
+
+## Step 0 — inspect configuration
+
+Check WordPress, WooCommerce and PHP versions, GMP and sodium availability,
+whether the plugin is installed, and whether the Doctor panel reports the
+receive-only NWC credential as set. Never display its value. For a real store,
+ask the merchant to configure a receive-only wallet if none is available.
+For repository development, use the Docker demo's explicit testkit override.
+
+Upload a built plugin archive, not a zip of the source directory. The plugin
+has not yet been accepted into the WordPress.org directory. Configuration and
+the complete quickstart follow below.
+
+The plugin owns only its payment-attempt tables in the WordPress database.
+WooCommerce owns orders, totals, stock and email. Do not add an external
+idempotency store, payment database, browser wallet credentials or custom
+fulfillment implementation. Guest return links use WooCommerce's order key;
+the plugin verifies it before issuing an expiring order-bound cookie.
+
+Run `wp openreceive doctor` after configuration. Use the documented scheduled
+reconciliation or optional notifications command for offline settlement.
+Manual merchant refunds and provider-managed payer swap refunds are separate
+flows; a receive-only NWC wallet cannot send payments.
+
+## Further reading
+
+- [Express Quickstart (Node)](https://openreceive.org/guides/quickstart-node.md)
+- [Fastify Quickstart](https://openreceive.org/guides/quickstart-fastify.md)
+- [FastAPI Quickstart](https://openreceive.org/guides/quickstart-fastapi.md)
+- [Django Quickstart](https://openreceive.org/guides/quickstart-django.md)
+- [Next.js Quickstart](https://openreceive.org/guides/quickstart-next.md)
+- [Rails Quickstart](https://openreceive.org/guides/quickstart-rails.md)
+- [PHP Quickstart (plain PHP)](https://openreceive.org/guides/quickstart-php.md)
+- [Laravel Quickstart](https://openreceive.org/guides/quickstart-laravel.md)
+- [BTCPay Server Quickstart](https://openreceive.org/guides/quickstart-btcpay.md)
+- [BTCPay Plugin Reference](https://openreceive.org/guides/btcpay-reference.md)
+- [Node ORM Recipes](https://openreceive.org/guides/node-orms.md)
+- [Authorization](https://openreceive.org/guides/authorization.md)
+- [Rate Limiting](https://openreceive.org/guides/rate-limiting.md)
+- [Frontend Checkout](https://openreceive.org/guides/frontend-checkout.md)
+- [Checkout UX](https://openreceive.org/guides/checkout-ux.md)
+- [Headless Checkout](https://openreceive.org/guides/headless-checkout.md)
+- [Automated Swaps](https://openreceive.org/guides/automated-swaps.md)
+- [Swap Refunds](https://openreceive.org/guides/swap-refunds.md)
+- [Lightning Swap Connect URI](https://openreceive.org/guides/lightning-swap-connect.md)
+- [Environment Variables](https://openreceive.org/guides/environment-variables.md)
+- [Payment Storage](https://openreceive.org/guides/storage.md)
+- [Deploying OpenReceive](https://openreceive.org/guides/deploying.md)
+- [Testing Your OpenReceive Integration](https://openreceive.org/guides/host-testing.md)
+- [API Reference](https://openreceive.org/guides/api-reference.md)
+- [Security](https://openreceive.org/guides/security.md)
+- [Provider Registry](https://openreceive.org/guides/provider-registry.md)
+- [Price Feeds](https://openreceive.org/guides/price-feeds.md)
+- [React Material UI Recipe](https://openreceive.org/guides/react-material-ui-recipe.md)
+- [Flask Recipe](https://openreceive.org/guides/flask-recipe.md)
+- [Writing Your Own Checkout Route](https://openreceive.org/guides/custom-checkout-route.md)
+- [Agent Directions: Node.js](https://openreceive.org/guides/agent-directions-node.md)
+- [Agent Directions: Fastify](https://openreceive.org/guides/agent-directions-fastify.md)
+- [Agent Directions: FastAPI](https://openreceive.org/guides/agent-directions-fastapi.md)
+- [Agent Directions: Django](https://openreceive.org/guides/agent-directions-django.md)
+- [Agent Directions: Next.js](https://openreceive.org/guides/agent-directions-next.md)
+- [Agent Directions: Rails](https://openreceive.org/guides/agent-directions-rails.md)
+- [Agent Directions: PHP](https://openreceive.org/guides/agent-directions-php.md)
+- [Agent Directions: Laravel](https://openreceive.org/guides/agent-directions-laravel.md)
+- [Agent Directions: BTCPay Server](https://openreceive.org/guides/agent-directions-btcpay.md)
+- [WordPress + WooCommerce Quickstart](https://openreceive.org/guides/quickstart-woocommerce.md)
+
+---
+
+## The quickstart, in full
+
+Inlined verbatim so this file needs no network access — follow it once Step 0
+passes. The page it comes from is https://openreceive.org/guides/quickstart-woocommerce.
+
+## WordPress + WooCommerce quickstart
+
+Install the built OpenReceive plugin zip through **Plugins → Add New → Upload
+Plugin**, with WooCommerce already active. The source directory needs a build;
+it cannot be uploaded as-is. WordPress.org submission is still pending.
+
+Requirements: WordPress 6.6+, WooCommerce 9+, 64-bit PHP 8.2+ with GMP and sodium,
+and MySQL 8 or MariaDB 10.5+. Activation creates payment-attempt tables in the
+existing WordPress database. No separate database or application is required.
+
+### Get the installable archive
+
+Use `openreceive-wordpress-<version>.zip` from the selected
+[OpenReceive GitHub release](https://github.com/OpenReceive/openreceive/releases)
+when that asset is listed. A GitHub source-code zip is not the plugin archive.
+If the release does not yet provide a built zip, build it on a development
+machine with Node 22+, PHP 8.2+, Composer and WP-CLI:
+
+```sh
+git clone https://github.com/OpenReceive/openreceive.git
+cd openreceive
+git checkout <release-tag>
+npm ci
+npm run build:packages
+composer install --working-dir=packages/php/wordpress
+npm run release:wordpress:build
+```
+
+Upload the resulting `dist/openreceive-wordpress-<version>.zip`. WP-CLI must be
+on `PATH`, or set `OPENRECEIVE_WP_CLI` to the absolute path of its phar. The
+WordPress server needs neither Node nor Composer: dependencies and checkout
+assets are bundled inside the built plugin.
+
+### Configure the wallet
+
+Open **WooCommerce → Settings → Payments → OpenReceive**. Enter a receive-only
+NWC code, save, then enable the gateway. Saving verifies receive permissions
+and fails closed on a spend-capable wallet unless the explicit override is set.
+The password fields never show saved credentials. Values are encrypted using
+keys derived from WordPress's authentication keys; re-enter them after rotating
+those keys.
+
+For managed deployments, configure `OPENRECEIVE_NWC_URI` in `wp-config.php` from
+your server's secret environment. It takes precedence over the settings field.
+Optional `OPENRECEIVE_LSC_URI_PRIMARY` and `OPENRECEIVE_LSC_URI_BACKUP` constants
+configure swap providers. Never put these values in browser code or logs.
+
+### Checkout and settlement
+
+Both WooCommerce checkout blocks and classic checkout redirect to the order-pay
+page. The plugin reads the amount from `WC_Order`, serves the bundled checkout,
+and authorizes the customer through their account, checkout session or an
+expiring signed cookie issued after verifying the order-pay key. Keep that
+order-pay URL available to customers returning to a pending payment or swap
+refund. The plugin verifies that each requested payment hash belongs to the order.
+
+Payment attempts persist before invoice instructions appear. Settlement commits
+once in the payment transaction. WooCommerce's `payment_complete` then handles
+status, stock and emails. A durable order marker lets subsequent requests and
+scheduled passes repair an interruption between settlement and order completion.
+
+The checkout polling drives opportunistic reconciliation through the PHP
+engine's shared database gate. Action Scheduler adds a recurring one-minute
+safety net. Configure a system cron to run WordPress scheduled work on stores
+with little traffic; no page visits means WP-Cron alone cannot guarantee prompt
+settlement. Optional process-manager commands:
+
+```sh
+wp openreceive doctor
+wp openreceive reconcile
+wp openreceive notifications
+```
+
+The notifications command runs as a separate process. The Doctor panel in the
+gateway settings reports schema, credential presence, scheduling and attention
+orders. A currency without a usable price feed makes the gateway unavailable.
+
+### Refunds and removal
+
+The receive-only wallet cannot send merchant refunds. Make those manually from
+your wallet. Payer swap refunds use the configured provider through the same
+authorized order-pay page; enabling LSC payments commits the shop to keeping
+that recovery path available. See [swap refunds](https://openreceive.org/guides/swap-refunds.md).
+
+Deactivation preserves payment records. Deleting the plugin drops its two
+tables only if **Remove data on uninstall** was enabled. WooCommerce orders are
+retained.
+
+### Local example
+
+The repository's `examples/wordpress` Docker stack builds the plugin and seeds
+WooCommerce from the shared button catalog. Run `npm run demo wordpress` for
+the real-wallet mode, or use its documented `compose.testkit.yml` override for
+a disposable fake-wallet shop. No testkit routes are registered by default.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.6
 platform: ruby
 authors:
 - OpenReceive
@@ -23,7 +23,19 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Vector-backed Ruby helpers for OpenReceive receive-checkout contracts.
+description: |
+  Build Bitcoin Lightning payments into your Ruby application with OpenReceive.
+  Work with exact money amounts, normalize wallet responses, and apply consistent
+  settlement rules while keeping control of your wallet and application.
+
+  This lightweight core provides money conversion, exchange rates, Nostr Wallet
+  Connect (NWC) adapters, and swap-address validation without a database dependency.
+  For a complete Rails integration, install openreceive-rails. For a custom Ruby
+  or Rack integration, use openreceive-server.
+
+  OpenReceive integrations support optional swaps from USDT, USDC, SOL, and ETH
+  through a configured provider, settling as BTC over Lightning into your wallet.
+  Available assets and networks depend on the provider.
 email:
 - info@openreceive.org
 executables: []
@@ -52,6 +64,7 @@ files:
 - skills/integrate-openreceive/references/node.md
 - skills/integrate-openreceive/references/php.md
 - skills/integrate-openreceive/references/rails.md
+- skills/integrate-openreceive/references/woocommerce.md
 homepage: https://openreceive.org
 licenses:
 - MIT
@@ -60,7 +73,7 @@ metadata:
   source_code_uri: https://github.com/openreceive/openreceive
   changelog_uri: https://github.com/openreceive/openreceive/blob/master/packages/ruby/openreceive/CHANGELOG.md
   bug_tracker_uri: https://github.com/openreceive/openreceive/issues
-  documentation_uri: https://rubydoc.info/gems/openreceive
+  documentation_uri: https://github.com/openreceive/openreceive/blob/master/packages/ruby/openreceive/README.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -78,5 +91,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: OpenReceive Ruby core helpers
+summary: Bitcoin Lightning payment primitives for Ruby. Your app, your wallet.
 test_files: []