openreceive 0.4.2 → 0.4.4

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.2.
+These directions describe OpenReceive 0.4.4.
 
 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.4
 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,7 +43,14 @@ 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
 homepage: https://openreceive.org
 licenses: