openreceive 0.4.3 → 0.4.5

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.3.
+These directions describe OpenReceive 0.4.5.
 
 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
@@ -14,6 +14,13 @@ models (`ShopOrder`, `ShopUser`, a signed-cookie visitor) over tables that
 already exist. Find this application's order, product, and user models — whatever
 they are actually named — and map the three hooks onto those.
 
+Keep this application's view layer, its Devise/session authentication and its
+database. Pick the frontend package that matches what already renders here
+(`@openreceive/elements` for ERB/Hotwire; `/react`, `/vue`, `/svelte` or
+`/angular` for an existing SPA) — do not add React to a Hotwire app. Reuse the
+app's existing session or `current_user` in `config.authorize`; the engine's
+migration adds only its own two tables to the app's database.
+
 ## What OpenReceive is
 
 A payment library that runs inside YOUR server. It mounts HTTP routes in the
@@ -217,8 +224,12 @@ built on `@openreceive/browser/headless`. Read that before writing components.
   "switch payment method".
 - No "Open wallet" button on desktop.
 - Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Host the icons with
-  `asset-base-url`. The registry answers ~37 wallets: pass
+  `createWizardRouteDisplays`. Lightning only. Every image ships inside
+  the JavaScript — logos as data URIs, tutorials once `loadPayTutorialImages()`
+  resolves (`image` is `undefined` until then) — so serve nothing and set no
+  asset option. When it works, the logos and payment icons render; a missing
+  image means a CSP `img-src` that blocks `data:`, and the console names it.
+  The registry answers ~37 wallets: pass
   `providerPreviewLimit` and build "show all" from `display.providerCount`,
   or they push the QR off the screen.
 
@@ -233,10 +244,9 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/frontend-checkout.md — the drop-in's props, attributes and slots
 - https://openreceive.org/guides/checkout-ux.md — read before building any custom UI
 - https://openreceive.org/guides/headless-checkout.md — the controller, the display models, refunds
-- https://openreceive.org/guides/provider-registry.md — where the packaged icons and pay
-  tutorials come from, and how to serve them. The asset rule is the one a custom
-  UI is most likely to get wrong; this is the page that owns it, not the summary
-  in checkout-ux.md
+- https://openreceive.org/guides/provider-registry.md — where the wallet logos and pay
+  tutorials come from: inside the JavaScript, nothing to serve. This is the page
+  that owns the image rule, not the summary in checkout-ux.md
 - https://openreceive.org/guides/automated-swaps.md — only if `LSC_URI_PRIMARY` is set
 - https://openreceive.org/guides/swap-refunds.md — the refund flow, and the route back to it. Read it before you turn swaps on
 - https://openreceive.org/guides/lightning-swap-connect.md — what an `LSC_URI_*` code actually is
@@ -261,7 +271,7 @@ passes. The page it comes from is https://openreceive.org/guides/quickstart-rail
 
 ## Rails quickstart
 
-Requires Ruby ≥ 3.2.
+Requires Ruby ≥ 3.2 and Rails ≥ 8.0.
 
 Add the Rails engine gem to your `Gemfile`:
 
@@ -356,6 +366,13 @@ config.on_paid = lambda do |settlement|
 end
 ```
 
+**Unlocking a download works the same way.** If what the payer bought is a
+file, do not unlock it in the browser: gate the download route on the paid
+order row — `Order.find_by(id: params[:id], user: current_user, state: "paid")`
+or a 404 — and serve the file only then. The `state: "paid"` written above is
+the unlock; the client never decides an order was fulfilled, it re-reads the
+row. Buy a Button's `ShopController#download` is this in twenty lines.
+
 Both shapes are idempotent, and both are correct. They differ only in whether
 your model layer gets to run: `update_all` skips it and is the right default;
 the row lock holds the row for the duration of the block and is what you want
@@ -450,10 +467,32 @@ end
 settlement transaction, only for the first settled attempt for a reference.
 → [OpenReceive.configure](https://openreceive.org/guides/api-reference.md#openreceiveconfigure)
 
-The engine inherits your application's `protect_from_forgery`. Keep
+The engine's controllers inherit from `config.parent_controller` — the
+generated initializer sets it to `"ApplicationController"`. That is how the
+engine picks up your application's `protect_from_forgery`. Keep
 `csrf_meta_tags` in the layout that renders the checkout; the checkout client
 sends `X-CSRF-Token` from it automatically.
 
+The same inheritance brings every global `before_action` your
+`ApplicationController` declares. A filter that redirects signed-out users to
+a login page will redirect the engine's JSON routes too, and a guest checkout
+then never gets an invoice. The engine reads nothing from the parent except
+that forgery protection — `config.authorize` receives the request and your
+policy reads its own session from it — so if your `ApplicationController`
+carries such filters, either point `config.parent_controller` at a slimmer
+controller that still calls `protect_from_forgery`, or skip the filter for
+the engine only:
+
+```ruby
+# config/initializers/openreceive.rb (after OpenReceive.configure)
+Rails.application.config.to_prepare do
+  OpenReceive::ApplicationController.skip_before_action :require_login
+end
+```
+
+Filters your authorize policy depends on (a tenant resolver, `Current`
+attributes) should stay: they run before `config.authorize`.
+
 The generated initializer ships
 `config.on_paid = OpenReceive::LOGGING_ON_PAID` — a placeholder that only logs
 the settlement and fulfills nothing. Replace it with your real fulfillment (as
@@ -506,27 +545,33 @@ import "@openreceive/elements/styles.css"; // or link the compiled styles.css
 defineElements();
 ```
 
-Bundling with esbuild (jsbundling-rails)? Two things:
-
-1. Build ESM and load it as a module. esbuild's default IIFE output evaluates
-   a dependency's Node fallback in the browser and throws
-   `ReferenceError: __filename is not defined`:
+Bundling with esbuild (jsbundling-rails)? Build ESM and load it as a module.
+esbuild's default IIFE output evaluates a dependency's Node fallback in the
+browser and throws `ReferenceError: __filename is not defined`:
 
-   ```sh
-   esbuild app/javascript/application.js --bundle --format=esm --outdir=app/assets/builds
-   ```
+```sh
+esbuild app/javascript/application.js --bundle --format=esm --outdir=app/assets/builds
+```
 
-   ```erb
-   <%= javascript_include_tag "application", type: "module" %>
-   ```
+```erb
+<%= javascript_include_tag "application", type: "module" %>
+```
 
-2. Serve the provider images. The payment-method icons are compiled into
-   `@openreceive/browser` and need nothing, but the wallet logos and pay
-   tutorials are files shipped in `@openreceive/provider-data`, and only
-   Vite-style bundlers resolve them from the import. Copy that package's
-   `dist/assets` tree to `public/openreceive-assets/assets/` and set
-   `asset-base-url="/openreceive-assets"` on the element
-   ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
+Everything the checkout draws ships inside the JavaScript: the payment-method
+icons, the wallet logos and the pay tutorials. There is no image file to copy
+or serve and no asset option to set. Deploy your normal JavaScript and CSS
+build output, including any generated JavaScript chunks. Bundlers with code
+splitting can defer tutorial screenshots until first open; single-file builds
+(including the standalone checkout) include them upfront. If your
+Content-Security-Policy has a strict `img-src`, allow `data:`
+([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
+
+Then open the checkout in a browser, confirm the payment-method icons and
+wallet logos render, and open a wallet's pay tutorial to check its screenshots.
+If an image is missing, inspect the console for CSP violations and the Network
+panel for failed JavaScript chunks. Allow `data:` in `img-src` and deploy the
+complete build output. Do not add image routes, copy package source images, or
+use registry `icon_path` / tutorial `path` keys as browser URLs.
 
 The element creates the checkout for `reference`, then renders and polls
 itself. React/Vue/Svelte/Angular apps use the matching wrapper package

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

@@ -0,0 +1,153 @@
+# OpenReceive agent directions (WordPress + WooCommerce)
+
+These directions describe OpenReceive 0.4.5.
+
+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.
+
+### 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.3
+  version: 0.4.5
 platform: ruby
 authors:
 - OpenReceive
@@ -35,6 +35,7 @@ files:
 - README.md
 - lib/openreceive.rb
 - lib/openreceive/core.rb
+- lib/openreceive/generated/tables.rb
 - lib/openreceive/keccak256.rb
 - lib/openreceive/nwc_ruby.rb
 - lib/openreceive/rates.rb
@@ -42,8 +43,16 @@ files:
 - lib/openreceive/version.rb
 - skills/debug-openreceive-payment/SKILL.md
 - skills/integrate-openreceive/SKILL.md
+- skills/integrate-openreceive/references/btcpay.md
+- skills/integrate-openreceive/references/django.md
+- skills/integrate-openreceive/references/fastapi.md
+- skills/integrate-openreceive/references/fastify.md
+- skills/integrate-openreceive/references/laravel.md
+- skills/integrate-openreceive/references/next.md
 - 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