tillbell 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72c52a2e210cb60ee2fa3173935075173b3c90a1e30574c7d0b381210c8374f2
-  data.tar.gz: d7d9d6f30c25c140ee124e8de0f567995a57b31a8a211ca76905859f6c78d875
+  metadata.gz: 12dfa4c6d7a3864417897be9a747fefbe25e4b1507665cea18427357bde1d6e6
+  data.tar.gz: 30ad262de35244e9262452acce2734ee92245274bd66f6f74205f798d5e01695
 SHA512:
-  metadata.gz: 6b9e6e9f84d106ed21019f130acc49913a6dea88014d0c3eaa4b5bcb777d957eafe2173b5ea7892bba9f7eacfbe4421415eb5787c0b47eb696db0fcc2c0d0681
-  data.tar.gz: 9f8314103d9234e46279cd3625fe2603c340e42889435d0adfbd6ef245eca82b7dd354cef6513a78aa3f3363dbf06586beeb9e1f28778a948a364c17450a8f26
+  metadata.gz: 5d140d39754930be99c4c93de83e51b2947e609e3bff3b0629bad2a95421e806c83e14ce08df900bb78049e869f23802e6d0692506c012feaa58d36649a56de2
+  data.tar.gz: e8118449e7d79da14d3c6b7fc40b0e23aaf20c342343e8f1e77928b15ad4d3ed2a4a6bd14b3915ebb5aa9af1616e5fdc38dcbb1f2fc70f2c423eb7d399599257

data/CHANGELOG.md

@@ -6,6 +6,55 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-30
+
+### Added
+
+- `bin/rails tillbell:check` (`Tillbell::Check`): checks the package name, the service account
+  key, that the engine is mounted and the notification sender, without printing a secret.
+  `ONLINE=1` also asks Google (the key, its rights, the subscriptions of the Play Console);
+  `PLANS=premium:monthly,premium:yearly` checks the plans the app sells exist and are active.
+- The install generator prints the credentials template and the next steps.
+
+### Changed
+
+- README, "Google Play setup": rewritten for someone who has never touched Google Play's
+  consoles. What Google needs and why, a credentials template to fill in, a checklist, every
+  step in the Play Console and the Cloud Console, the check, a test purchase and a
+  troubleshooting table.
+
+## [0.2.0] - 2026-10-30
+
+### Added
+
+- `Tillbell.native?(user_agent)` and the `tillbell_native?` view helper: tell whether the
+  app showing the page registered the `tillbell` component, to choose between the paywall
+  and another way to pay.
+- Details of a `Pay::GooglePlay::Subscription` read from Google's last answer:
+  `price_amount` and `price_currency`, `replacement?`, `linked_purchase_token`, `replaced?`,
+  `plan_change_pending?`, `deferred_product_id` and `manage_url`.
+- `Tillbell::GooglePlay.manage_url(product_id = nil)`: the Play Store page of a
+  subscription, for web pages and emails.
+- README: detecting the native app, plan changes (replacement modes, `DEFERRED`
+  downgrades), subscription details, several processors per customer, closing an account,
+  and events during a plan change.
+
+### Changed
+
+- A replaced subscription remembers the purchase token that replaced it (`data["replaced_by"]`)
+  and keeps its ended state: a later read of the old token no longer brings it back.
+- `cancel` decides whether to ask Google from its subscription state (canceled or expired)
+  instead of `auto_renewing`, which is false while a deferred plan change waits for the renewal
+  though the subscription will renew.
+
+### Fixed
+
+- `cancel` (and `cancel_now!`) on a subscription Google answers 410 for (a purchase token
+  expired for more than 60 days) no longer raises: it made closing an account or deleting an
+  owner fail for a customer who left long ago, including for a row still stored as active
+  because a notification was missed. The subscription is recorded as ended and
+  `subscription_expired` is emitted once. Other errors still raise.
+
 ## [0.1.1] - 2026-10-30
 
 ### Changed

data/README.md

@@ -64,16 +64,18 @@ Assuming a Rails 8 app with a `User` model and Pay installed:
    end
    ```
 
-3. Fill in `config/initializers/tillbell.rb`:
+3. Fill in `config/initializers/tillbell.rb`, and put the two values Google gives you in your credentials (the [Google Play setup](#google-play-setup) below has the template and every click):
 
    ```ruby
    Tillbell.configure do |config|
      config.google.package_name = "com.example.app"
      config.google.service_account_json = Rails.application.credentials.dig(:tillbell, :google_service_account)
-     config.google.pubsub_service_account_email = "pubsub-push@my-project.iam.gserviceaccount.com"
+     config.google.pubsub_service_account_email = Rails.application.credentials.dig(:tillbell, :pubsub_service_account_email)
    end
    ```
 
+   Then `bin/rails tillbell:check` tells you what is still missing.
+
 4. Render a paywall:
 
    ```erb
@@ -92,7 +94,7 @@ Assuming a Rails 8 app with a `User` model and Pay installed:
    current_user.pay_subscriptions.active.any?
    ```
 
-Then add [tillbell-android](https://github.com/pmakerhq/tillbell-android) to your Hotwire Native app and follow the [Google Play setup](#google-play-setup).
+Then add [tillbell-android](https://github.com/pmakerhq/tillbell-android) to your Hotwire Native app, and do the [Google Play setup](#google-play-setup) if you have not yet: it is the part that happens on Google's side.
 
 ## How it works
 
@@ -162,10 +164,12 @@ end
 Tillbell.configure do |config|
   config.google.package_name = "com.example.app"
   config.google.service_account_json = Rails.application.credentials.dig(:tillbell, :google_service_account)
-  config.google.pubsub_service_account_email = "pubsub-push@my-project.iam.gserviceaccount.com"
+  config.google.pubsub_service_account_email = Rails.application.credentials.dig(:tillbell, :pubsub_service_account_email)
 end
 ```
 
+The values marked "credentials" below come from Google: the [Google Play setup](#google-play-setup) says where to find each one, and gives the template to fill in. `bin/rails tillbell:check` verifies them.
+
 | Setting | Default | Description |
 |---|---|---|
 | `google.package_name` | (required) | Application id of the Android app. |
@@ -211,16 +215,46 @@ Prices always come from Google Play, never from your app.
 
 **Without the native component** (a browser, or an old app version), the Stimulus controller does not connect. The buttons stay disabled, the fallback stays visible, and no purchase can start.
 
+**Detecting the native app.** Hotwire Native lists the components an app registered in its user agent (`bridge-components: [haptic tillbell]`). To choose between the paywall and another way to pay, ask Tillbell instead of parsing it yourself:
+
+```erb
+<% if tillbell_native? %>
+  <%= tillbell_paywall success_url: dashboard_path do |paywall| %> ... <% end %>
+<% else %>
+  <%= link_to "Subscribe on the web", checkout_path %>
+<% end %>
+```
+
+In a controller, use `Tillbell.native?(request.user_agent)`. It only picks which page to show: a purchase is always verified with Google, so a forged user agent gains nothing. It answers `true` for any native app (Android today, iOS later) that registered the component, and `false` for browsers and for app versions without it.
+
 **Plan changes.** Pass the current subscription and Google's [replacement mode](https://developer.android.com/google/play/billing/subscriptions#replacement-modes). Tillbell passes the mode through and never decides proration:
 
 ```erb
-<%= paywall.plan_option product_id: "family", base_plan_id: "monthly",
-      replacing: current_user.pay_subscriptions.active.first,
-      replacement_mode: "CHARGE_PRORATED_PRICE" do %>
-  Switch to Family, <%= paywall.price %>
+<%= tillbell_paywall success_url: settings_path do |paywall| %>
+  <%= paywall.plan_option product_id: "family", base_plan_id: "monthly", checked: true,
+        replacing: current_user.pay_subscriptions.google_play.active.first,   # the current Pay::GooglePlay::Subscription
+        replacement_mode: "CHARGE_PRORATED_PRICE" do %>
+    Switch to Family, <%= paywall.price %>
+  <% end %>
+  <%= paywall.submit "Switch to Family" %>
+  <%= paywall.status %>
 <% end %>
 ```
 
+| Replacement mode | Use it for | Effect |
+|---|---|---|
+| `CHARGE_PRORATED_PRICE` | An upgrade to a more expensive plan (upgrades only) | Takes effect now. The customer pays the price difference for the rest of the period, and the billing date does not change. |
+| `WITH_TIME_PRORATION` | An upgrade (Google's default) | Takes effect now. The value of the unused time is credited by pushing the next billing date forward. |
+| `WITHOUT_PRORATION` | An upgrade that keeps a free period | Takes effect now. The new price applies from the next renewal. |
+| `CHARGE_FULL_PRICE` | Switching to a longer billing period | Takes effect now. The customer is charged the full price of the new plan, and the remaining value of the old one is credited. |
+| `DEFERRED` | A downgrade to a cheaper plan | Takes effect at the next renewal: the customer keeps what they paid for until then. |
+
+Google recommends `CHARGE_PRORATED_PRICE` for an upgrade and `DEFERRED` for a downgrade. The server picks the mode, never the app, so a customer cannot choose a cheaper way to upgrade.
+
+A purchase that replaces another (a plan change, or a customer who signs up again for a subscription that was canceled but had not lapsed) gets a new purchase token that points to the old one. Tillbell stores the new subscription, ends the old one, and emits `subscription_created` then `subscription_expired` (see [Events](#events)).
+
+A `DEFERRED` change waits for the renewal. Google reports it on the **new** purchase: one line item for the entitlement that is about to end, carrying the product the customer is moving to, and one for the entitlement that follows. Until the renewal the new subscription keeps the current product as `processor_plan`, and `subscription.plan_change_pending?` and `subscription.deferred_product_id` tell where it is going, so the page can say "Switching to Solo on March 3" (`current_period_end`). After the renewal `processor_plan` is the new product. Only an active subscription that is still renewing can change plan: hide the option for a canceled (`on_grace_period?`) or held (`on_hold?`) one.
+
 **JavaScript events.** The controller dispatches events on the paywall element:
 
 - `tillbell:verified`: the purchase grants access. Call `event.preventDefault()` to stay on the page instead of visiting `success_url`.
@@ -252,9 +286,30 @@ A `Pay::GooglePlay::Subscription` stores:
 - `data`: `base_plan_id`, `subscription_state`, `auto_renewing` and `revoked_at`;
 - `object`: Google's last answer.
 
+**Details from Google.** These read Google's last answer, so they cost no API call:
+
+| Method | Returns |
+|---|---|
+| `price_amount`, `price_currency` | The price of one renewal as a `BigDecimal` in the units of its currency (`12.99`, or `1200` yen) and its ISO currency (`"EUR"`), as Google bills it in the customer's country. For analytics and conversion events (e.g. a Meta or Google Ads purchase, which take a decimal value); show prices to customers from Google Play, as the paywall does. It is the price of the entitlement in force. `nil` when Google gave none. |
+| `replacement?`, `linked_purchase_token` | Whether this purchase replaces an earlier one, and the token of that one. Google sets it for a plan change, for a customer who signs up again for a subscription that was canceled but had not lapsed, and for prepaid plans converted to or topped up as auto-renewing. Compare `processor_plan` with the replaced subscription's to tell a plan change. |
+| `replaced?` | Whether a newer purchase replaced this subscription. Set when the replacement is recorded, so it is already true inside the `subscription_expired` callback; use it to tell a replaced subscription from a customer who left (see [Events](#events)). Subscriptions replaced before this was added are not flagged. |
+| `plan_change_pending?`, `deferred_product_id` | A `DEFERRED` plan change waiting for the next renewal, and the product it goes to. |
+| `manage_url` | The Play Store page where the customer manages this subscription (update the payment method, cancel, resubscribe). Same page as `paywall.manage`, for web pages and emails. `Tillbell::GooglePlay.manage_url(product_id)` gives it for any product, and without one the list of all subscriptions. |
+| `in_grace_period?`, `on_hold?`, `revoked?` | The Google states that Pay statuses merge. |
+
+A customer can have a Stripe subscription and a Google Play one (a web customer who later subscribes in the app, or the reverse). `Pay::GooglePlay::Customer` is never the owner's default payment processor, so `owner.payment_processor` does not see Google Play subscriptions: look at `owner.pay_subscriptions`, or at the Google Play customer (`owner.pay_customers.google_play.first`), to decide who has access.
+
 Pay only knows its own processors, so Tillbell adds `google_play?` to customers and subscriptions, and a `google_play` scope next to Pay's `stripe` one (`Pay::Subscription.google_play`).
 
-`subscription.cancel` stops the renewal through the Google Play Developer API. `swap`, `pause` and `resume` raise `Tillbell::Error`: plan changes go through the paywall, and the rest happens in the Play Store.
+`subscription.cancel` stops the renewal through the Google Play Developer API; the customer keeps access until the end of the paid period. Google can only end a subscription immediately by refunding it, which Tillbell never does on its own, so `cancel_now!` (which Pay calls when an owner is destroyed) also just stops the renewal. Google answers 410 for a purchase token that expired more than 60 days ago: a subscription still stored as active (a missed notification) is then recorded as ended, with a `subscription_expired` event, instead of failing the deletion of its owner. Any other error is raised, a 404 from a wrong package name for example: the subscription may still be billing. A subscription ended or already canceled is left alone, and one that waits for a deferred plan change is cancelled like any other: whether it is renewing comes from Google's subscription state, not from the entitlement about to end. `swap`, `pause` and `resume` raise `Tillbell::Error`: plan changes go through the paywall, and the rest happens in the Play Store.
+
+**Closing or deleting an account.** Cancel what still bills before you close the account, whatever the processor, and before changing anything in your database: an error raised after the account is closed leaves the subscription billing a closed account. Pay's own hook when an owner is destroyed only cancels `active` subscriptions. Google keeps retrying a held payment (`past_due`) and resumes a paused subscription by itself, so include both:
+
+```ruby
+user.pay_subscriptions.where(status: %w[active past_due paused]).reject(&:ended?).each(&:cancel_now!)
+```
+
+Google can fail (API error, revoked service account key), so rescue `Pay::Error` (which includes `Tillbell::Error`, raised when the package name or the service account is not configured), `Google::Apis::Error` and `Signet::AuthorizationError` next to your other processors' errors, and tell the customer to try again.
 
 ## Events
 
@@ -269,18 +324,200 @@ Tillbell.configure do |config|
 end
 ```
 
+A plan change fires `subscription_created` for the new purchase (`replacement?` is true) and `subscription_expired` for the old one (`replaced?` is true). Renewals fire `subscription_updated` too, so filter on what you care about, for example in a Slack or analytics subscriber:
+
+```ruby
+Tillbell.on(:subscription_updated) do |subscription|
+  changes = subscription.saved_changes.keys
+  notify("Payment on hold") if changes.include?("status") && subscription.on_hold?
+end
+
+Tillbell.on(:subscription_expired) do |subscription|
+  notify("Subscription ended") unless subscription.replaced?   # not a plan change
+end
+```
+
 Events go through Pay's webhook delegator, so `Pay::Webhooks.delegator.subscribe "tillbell.subscription_created", MyHandler.new` works too. An event fires once per actual change, after the subscription is saved. An error raised in a callback is reported to `Rails.error` and does not undo the change.
 
 ## Google Play setup
 
-1. **Service account.** In Google Cloud, create a service account and a JSON key, and enable the *Google Play Android Developer API*. In the Play Console, under *Users and permissions*, invite the service account with *View financial data* and *Manage orders and subscriptions*. Store the key in your credentials as `tillbell.google_service_account`.
-2. **Pub/Sub topic.** Create a topic, and grant `google-play-developer-notifications@system.gserviceaccount.com` the *Pub/Sub Publisher* role on it. In the Play Console, under *Monetization setup*, enter the topic name for real-time developer notifications.
-3. **Push subscription.** Create a push subscription on the topic:
-   - endpoint: `https://your-app.example.com/tillbell/notifications/google_play`;
-   - *Enable authentication* turned on, with a service account of your choice. Set its e-mail as `google.pubsub_service_account_email`;
-   - audience: leave it empty (it defaults to the endpoint URL), or set the same value as `google.pubsub_audience`.
-4. **Test.** Click *Send test notification* in the Play Console. The endpoint answers 200 and logs `[Tillbell] Google Play notification test_notification`.
-5. **License testers.** Add your testers in the Play Console, and install the app from a Play testing track to buy with test cards.
+Tillbell needs two things from Google: **permission to read and acknowledge your customers' purchases**, and **a way to hear about renewals, cancellations and refunds**. Setting that up takes about 30 minutes of clicking in two Google websites:
+
+| Website | What lives there | Called here |
+|---|---|---|
+| [Google Play Console](https://play.google.com/console) | Your app, your subscriptions, who may access them | **Play Console** |
+| [Google Cloud Console](https://console.cloud.google.com) | Service accounts (the identities your server uses) and Pub/Sub (the mailbox Google drops notifications in) | **Cloud Console** |
+
+You end up with **two values to give your app**: the JSON key of a service account, and the e-mail address of a second service account.
+
+> [!NOTE]
+> Google's menus move now and then. The names below are the ones to look for; if one has changed, search the console for it.
+
+### Before you start
+
+- A Google Play developer account, with your app created in the Play Console.
+- A payments profile (merchant account) linked to the developer account: Google asks for it when you create a paid product.
+- **A build of your app that includes the Google Play Billing Library, published to a testing track** (the Internal testing track is enough). Google does not let you create subscriptions until it has seen one. [tillbell-android](https://github.com/pmakerhq/tillbell-android) brings the Billing Library, so upload a build of your Hotwire Native app that includes it.
+- Your Rails app deployed on a public HTTPS address (Google must be able to call it).
+
+### The template to fill in
+
+Put the two values in your Rails credentials (`bin/rails credentials:edit`, or `bin/rails credentials:edit --environment production`), under the `tillbell` key. The generated initializer reads them from there. Replace everything between `<` and `>`:
+
+```yaml
+tillbell:
+  # Step 2: the whole JSON key file of the service account that calls Google.
+  # Keep the "|" and the two-space indentation, or the key is unreadable.
+  google_service_account: |
+    {
+      "type": "service_account",
+      "project_id": "<your-cloud-project>",
+      "private_key_id": "...",
+      "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
+      "client_email": "<tillbell-api>@<your-cloud-project>.iam.gserviceaccount.com",
+      "client_id": "...",
+      "token_uri": "https://oauth2.googleapis.com/token"
+    }
+  # Step 4: the e-mail address of the service account Pub/Sub signs its notifications with.
+  pubsub_service_account_email: <tillbell-push>@<your-cloud-project>.iam.gserviceaccount.com
+```
+
+Two more settings live in the initializer, not in the credentials: `config.google.package_name` (the application id of your Android app, for example `com.example.app`) and, only if a proxy changes the address Rails sees, `config.google.pubsub_audience` (see [Configuration](#configuration)).
+
+`rails generate tillbell:install` prints this template when it finishes.
+
+### The checklist
+
+Copy it into your tracker and tick it as you go. Each step is explained below.
+
+```markdown
+- [ ] 0. Developer account, app created, payments profile, a build with the Billing Library on a testing track
+- [ ] 1. Subscriptions created in the Play Console, base plan active (note the product and base plan ids)
+- [ ] 2. Service account "tillbell-api" created, API enabled, JSON key downloaded
+- [ ] 3. That service account invited in the Play Console with the two permissions (then wait, up to a day)
+- [ ] 4. Service account "tillbell-push" created (no role, no key), e-mail copied
+- [ ] 5. Pub/Sub topic created, Google Play allowed to publish to it
+- [ ] 6. Push subscription created: your URL, authentication on, "tillbell-push"
+- [ ] 7. Credentials filled in and deployed, `bin/rails tillbell:check` passes
+- [ ] 8. Topic connected in the Play Console, test message sent and received
+- [ ] 9. License testers added, test purchase made
+```
+
+### 1. Create your subscriptions (Play Console)
+
+*Monetize with Play* → *Products* → *Subscriptions* → *Create subscription*.
+
+- The **product ID** names the subscription (`premium`). You pass it as `product_id:` to `plan_option`.
+- Each subscription has one or more **base plans** (`monthly`, `yearly`), with their own ID, billing period and price. You pass it as `base_plan_id:`. A base plan must be **Active** to be sold.
+- Neither ID can be changed later, so pick them carefully.
+
+### 2. Create the service account that calls Google (Cloud Console)
+
+A *service account* is an identity for a program instead of a person. Your server uses this one to ask Google "what is the state of this purchase?" and to acknowledge it.
+
+1. Pick (or create) a Cloud project. Any project works: what ties the service account to your app is the invitation of step 3.
+2. *APIs & Services* → *Library* → search **Google Play Android Developer API** → *Enable*.
+3. *IAM & Admin* → *Service Accounts* → *Create service account*. Name it `tillbell-api`. Give it **no role** here.
+4. Open it → *Keys* → *Add key* → *Create new key* → **JSON**. A file downloads. **Google shows it only once**: that file is the `google_service_account` of the template. Treat it like a password, and never commit it.
+
+Its e-mail address (`client_email` in the file) is needed in the next step. If *Create new key* is greyed out or refused, an organization policy blocks service account keys: see [If something is off](#if-something-is-off).
+
+### 3. Let that service account into the Play Console
+
+The Cloud Console knows the account exists. The Play Console must also allow it.
+
+*Users and permissions* → *Invite new users* → paste the service account's e-mail address, then open the **App permissions** tab → *Add app* → your app, and tick:
+
+- **View financial data** (the account-level tab calls it *View financial data, orders and cancellation survey responses*);
+- **Manage orders and subscriptions**.
+
+Send the invitation. A service account does not need to accept it, but Google can take **up to a day** to apply the permissions, so a `401` or `403` in step 7 right after this step is normal.
+
+### 4. Create the account that signs notifications (Cloud Console)
+
+When Google tells your server about a renewal, your server must know the call really comes from Google's Pub/Sub. Pub/Sub proves it by signing each call with a service account of your choice. You create that one now, and give your app its e-mail address so it can recognize the signature.
+
+*IAM & Admin* → *Service Accounts* → *Create service account*, named `tillbell-push`. It needs **no role and no key**: it is only a name Pub/Sub signs with. Copy its e-mail address: that is `pubsub_service_account_email` of the template.
+
+### 5. Create the Pub/Sub topic (Cloud Console)
+
+A *topic* is the mailbox Google Play drops notifications in.
+
+1. *Pub/Sub* → *Topics* → *Create topic* (enable the Pub/Sub API if asked). Name it `play-notifications`. Note its full name: `projects/<your-cloud-project>/topics/play-notifications`.
+2. Open the topic → *Permissions* → *Add principal*: `google-play-developer-notifications@system.gserviceaccount.com`, role **Pub/Sub Publisher**. That is Google Play itself, allowed to write in your mailbox.
+
+### 6. Make the topic call your server (Cloud Console)
+
+A *push subscription* forwards each message to a URL.
+
+Open the topic → *Create subscription*:
+
+- **Delivery type**: *Push*.
+- **Endpoint URL**: `https://<your-domain>/tillbell/notifications/google_play` (the path follows where you mounted the engine). It must be public HTTPS, with **no query string and no trailing slash**: the audience below is compared to it exactly. Behind a proxy that terminates TLS, Rails must know the request was HTTPS (`X-Forwarded-Proto`).
+- **Enable authentication**: ticked, with the service account of step 4 (`tillbell-push`).
+- **Audience**: leave empty. It then defaults to the endpoint URL, which is what Tillbell expects.
+
+Two permissions can get in the way:
+
+- If Google refuses to create the subscription with authentication, your own Google account needs the **Service Account User** role on `tillbell-push`.
+- Pub/Sub's own service agent (`service-<project-number>@gcp-sa-pubsub.iam.gserviceaccount.com`) must be allowed to create tokens for `tillbell-push`: give it the **Service Account Token Creator** role on that account. Google's console steps say to check it, and projects that enabled Pub/Sub long ago need it explicitly. Without it, pushes fail silently.
+
+### 7. Fill in the credentials, deploy and check
+
+Put the two values in your credentials (see the template), set `config.google.package_name`, and **deploy**: the next step needs your server to be able to accept Google's notifications. Then run the check where the credentials are available. The simplest is on the server; locally, `RAILS_ENV=production` boots your production environment, which may need its other environment variables (database, `SECRET_KEY_BASE`) and your production key.
+
+```sh
+bin/rails tillbell:check                       # reads your configuration, asks nobody
+ONLINE=1 PLANS=premium:monthly,premium:yearly bin/rails tillbell:check   # also asks Google
+```
+
+`PLANS` lists the `product_id:base_plan_id` pairs your app sells; each must exist in the Play Console with an active base plan. Without `PLANS`, `ONLINE=1` lists the subscriptions Google knows. With `ONLINE=1` the check also asks Google to read a purchase that cannot exist: "unknown purchase" means the service account may read purchases, a permission error means it may not. It changes nothing on Google and never prints a secret.
+
+What it cannot try is acknowledging a purchase, which needs a real one: step 9 does. A healthy run:
+
+```
+OK   Android package name: com.example.app
+OK   Service account key (config.google.service_account_json): tillbell-api@my-project.iam.gserviceaccount.com
+OK   Engine mounted: /tillbell/purchases and /tillbell/notifications/google_play
+OK   Notification sender (config.google.pubsub_service_account_email): tillbell-push@my-project.iam.gserviceaccount.com
+OK   Notification audience: default: the notification URL as Rails sees it
+OK   Reading purchases: allowed (Google answered that the test token is unknown, as expected)
+OK   Subscription premium (base plan monthly): active
+OK   Subscription premium (base plan yearly): active
+
+Everything is in place.
+```
+
+Add `ONLINE=1` to your deploy checklist: it is the quickest way to learn that a key was revoked.
+
+### 8. Connect Google Play to the topic (Play Console)
+
+*Monetize with Play* → *Monetization setup* → *Real-time developer notifications*: tick **Enable real-time notifications**, enter the full topic name from step 5, choose the notification content that covers **subscriptions and all voided purchases** (Tillbell handles both), save, then click **Send test message**.
+
+The Play Console's success message only means the message reached **your topic**. Whether it reached your server is shown by your logs: `[Tillbell] Google Play notification test_notification`, and a 200 answer. A 401 there is the sender or the audience (see below). Without these notifications your app still sells subscriptions, but renewals and cancellations are never seen, and a purchase your server did not acknowledge is refunded by Google after three days.
+
+### 9. Test a purchase
+
+1. Play Console → *Settings* → *License testing*: add the Google accounts of your testers. They buy with test payment methods (pick the test card in the purchase sheet) and are not charged. Test subscriptions renew much faster than real ones, so you can watch a renewal and a cancellation: a monthly subscription renews every 5 minutes, a yearly one every 30, at most 6 times.
+2. Install your app on a device signed in with a tester account. License testers can install a build straight from their computer as long as the package name matches, or from the *Internal testing* opt-in link (a release on a testing track can take a few hours to reach testers).
+3. Open the paywall, buy, and watch `Pay::GooglePlay::Subscription` appear in your database. Then check that Google did not mark the purchase as unacknowledged: it should stay in your database as active after a few minutes.
+
+### If something is off
+
+`bin/rails tillbell:check` names the cause of most problems. The rest:
+
+| What you see | Likely cause | What to do |
+|---|---|---|
+| `not JSON`, or `private_key is missing or unreadable` | The key was pasted with a wrong indentation, or cut | Paste the whole key file again, with the `\|` and two spaces of indentation |
+| `ONLINE=1`: *not authorized (401)* or *not allowed (403)* | Step 3 is missing or not applied yet, the permissions are not the two above, or (403) the API is not enabled in the project of the key | Check the invitation and the API (step 2.2), and wait up to a day |
+| `ONLINE=1`: *not found (404)* | Wrong package name, or no such product in the Play Console | Compare with the Play Console |
+| `ONLINE=1`: *key refused* | The key was deleted or rotated, or belongs to another project | Create a new JSON key and replace it |
+| *Create new key* is greyed out or refused | An organization policy blocks service account keys (common on organizations created recently) | An organization administrator must allow key creation for this project |
+| `Google was not asked` | An offline check failed | Fix the failures above it, then run again |
+| The test message answers 401 in your logs | `pubsub_service_account_email` is not the account of step 4, or the audience differs | Compare the e-mails; if a proxy changes the URL Rails sees, set `config.google.pubsub_audience` to the same value as the subscription's *Audience* |
+| Nothing arrives at your server | The endpoint URL is wrong, not public HTTPS, or the topic is not the one in the Play Console; or Pub/Sub's service agent cannot create tokens (step 6) | Check steps 5 to 8; the subscription's *Unacked messages* graph in the Cloud Console shows whether Google writes |
+| The buy button stays disabled | The app does not register the `tillbell` component, or this is a browser | Use the app with [tillbell-android](https://github.com/pmakerhq/tillbell-android) |
+| A purchase works, then Google refunds it after three days | Your server did not acknowledge it: the purchase endpoint failed | Look at your logs for the purchase request; run `bin/rails tillbell:check` |
 
 ## Security
 
@@ -294,6 +531,8 @@ Found a vulnerability? Please report it privately, as described in [SECURITY.md]
 
 ## Troubleshooting
 
+Problems on Google's side (credentials, permissions, notifications) have their own table at the end of the [Google Play setup](#google-play-setup), and `bin/rails tillbell:check` names the cause of most of them.
+
 **The paywall buttons stay disabled.** The page is not running inside an app that registers the `tillbell` bridge component (a browser, or an app without [tillbell-android](https://github.com/pmakerhq/tillbell-android)). This is expected: the fallback is shown instead.
 
 **`POST /tillbell/purchases` answers 401.** `current_owner` returned `nil`: the request is not signed in, or `current_owner` does not match your authentication.

data/app/helpers/tillbell/paywall_helper.rb

@@ -1,6 +1,18 @@
 module Tillbell
   # View helper rendering the Google Play paywall, available in every view of the host app.
   module PaywallHelper
+    # True when the app showing the page registered the +tillbell+ bridge component, i.e.
+    # when the paywall can start a purchase. Same check as +Tillbell.native?+.
+    #
+    #   <% if tillbell_native? %>
+    #     <%= tillbell_paywall ... %>
+    #   <% else %>
+    #     <%= link_to "Subscribe on the web", checkout_path %>
+    #   <% end %>
+    def tillbell_native?
+      Tillbell.native?(request.user_agent)
+    end
+
     # Renders an unstyled paywall driven by the +tillbell+ Stimulus controller, which
     # talks to the +tillbell+ Hotwire Native bridge component.
     #

data/app/models/pay/google_play/subscription.rb

@@ -40,7 +40,7 @@ module Pay
       # Google states after which the subscription ends at the expiry time of its period.
       ENDING_STATES = %w[SUBSCRIPTION_STATE_CANCELED SUBSCRIPTION_STATE_EXPIRED].freeze
 
-      store_accessor :data, :subscription_state, :base_plan_id, :auto_renewing, :revoked_at
+      store_accessor :data, :subscription_state, :base_plan_id, :auto_renewing, :revoked_at, :replaced_by
 
       class << self
         # Reads a purchase from Google (unless +object+ is given), saves it and emits the
@@ -65,7 +65,7 @@ module Pay
           subscription, event = save_from_google(pay_customer, purchase_token, attributes_from(object, revoked: revoked))
           Tillbell.instrument(event, subscription) if event
 
-          retire(object[:linked_purchase_token])
+          retire(object[:linked_purchase_token], replaced_by: purchase_token)
           acknowledge(subscription, object)
           subscription
         end
@@ -105,8 +105,10 @@ module Pay
                 subscription = pay_customer.subscriptions.lock.find_or_initialize_by(processor_id: purchase_token)
                 # A refund is final: later reads report a normal expiry (or, if Google is
                 # lagging, an active subscription), and a duplicated refund notification
-                # must not emit a second event.
-                subscription.assign_attributes(subscription.revoked? ? attributes.except(:status, :ends_at, :revoked_at) : attributes)
+                # must not emit a second event. So is a replacement: the new purchase carries
+                # the access, and a later read of the old token (a deferred plan change may
+                # still report it as active until the renewal) must not bring it back.
+                subscription.assign_attributes(subscription.revoked? || subscription.replaced? ? attributes.except(:status, :ends_at, :revoked_at) : attributes)
 
                 event = subscription.event_for_changes
                 subscription.save!
@@ -119,13 +121,15 @@ module Pay
             end
           end
 
-          # A plan change creates a new purchase token that points to the old one. The old
-          # subscription ends now; the new one carries the access.
-          def retire(linked_purchase_token)
+          # A purchase that replaces another (a plan change, or a customer who signs up again
+          # for a canceled subscription) gets a new purchase token that points to the old one.
+          # The old subscription ends now, remembers the token that replaced it, and the new
+          # one carries the access.
+          def retire(linked_purchase_token, replaced_by:)
             return if linked_purchase_token.blank?
 
             where(processor_id: linked_purchase_token).where.not(status: "canceled").find_each do |subscription|
-              subscription.update!(status: "canceled", ends_at: Time.current)
+              subscription.update!(status: "canceled", ends_at: Time.current, replaced_by: replaced_by)
               Tillbell.instrument(:subscription_expired, subscription)
             end
           end
@@ -169,13 +173,87 @@ module Pay
         status == "paused"
       end
 
+      # The Play Store page where the customer manages this subscription (update the payment
+      # method, cancel, resubscribe). See Tillbell::GooglePlay.manage_url.
+      def manage_url
+        Tillbell::GooglePlay.manage_url(processor_plan)
+      end
+
+      # Price of one renewal in the units of its currency (a +BigDecimal+: 12.99 euros, 1200
+      # yen), as Google bills it in the customer's country, or nil when Google's answer has
+      # none. Meant for analytics and conversion events; show prices to customers from Google
+      # Play (the paywall does), which knows taxes and promotions. It is the price of the
+      # entitlement in force, so a subscription with add-ons reports the base item only.
+      def price_amount
+        price = recurring_price
+        return unless price
+
+        BigDecimal(price[:units].to_i) + (BigDecimal(price[:nanos].to_i) / 1_000_000_000)
+      end
+
+      # ISO 4217 code of the currency of +price_amount+ ("EUR"), or nil.
+      def price_currency
+        recurring_price&.dig(:currency_code)
+      end
+
+      # The purchase token of the subscription this purchase replaces. Google sets it when a
+      # purchase replaces another: a plan change (upgrade, downgrade, other billing period), a
+      # customer who signs up again for a subscription that was canceled but had not lapsed,
+      # and a prepaid plan converted to or topped up as an auto-renewing one.
+      def linked_purchase_token
+        google_object[:linked_purchase_token].presence
+      end
+
+      # True when this purchase replaces an earlier one: see +linked_purchase_token+ for the
+      # cases. Compare +processor_plan+ with the replaced subscription's to tell a plan change
+      # from a customer who signed up again for the same product.
+      def replacement?
+        linked_purchase_token.present?
+      end
+
+      # True when a newer purchase replaced this subscription (see +replacement?+). Tillbell
+      # ends a replaced subscription on its own and emits +subscription_expired+: check this to
+      # tell it from a customer who left. Set when the replacement is recorded, so it is
+      # already true inside the +subscription_expired+ callback; subscriptions replaced before
+      # this was added are not flagged.
+      def replaced?
+        replaced_by.present?
+      end
+
+      # The product the customer will move to at the next renewal, when a plan change was
+      # asked with the +DEFERRED+ replacement mode (the usual choice for a downgrade), or
+      # nil. Google reports it on the NEW purchase, in the line item of the entitlement that
+      # is about to end; until the renewal +processor_plan+ stays the current product.
+      def deferred_product_id
+        google_object[:line_items].to_a.filter_map { |item| item.dig(:deferred_item_replacement, :product_id).presence }.first
+      end
+
+      # True while a plan change waits for the next renewal. See +deferred_product_id+.
+      def plan_change_pending?
+        deferred_product_id.present?
+      end
+
       # Stops the renewal with Google; access continues until the end of the period.
-      # A subscription that already stopped renewing is only refreshed: Google has nothing
-      # to cancel, and deleting an owner (Pay calls +cancel_now!+ on every subscription
-      # still granting access) must not fail on it.
+      # A subscription that already stopped renewing (or ended) has nothing to stop: it is only
+      # refreshed, or left alone. Deleting an owner (Pay calls +cancel_now!+ on every
+      # subscription still granting access) must not fail on it.
+      #
+      # Google answers 410 for a purchase token that expired more than 60 days ago. A
+      # subscription still stored as active (a missed notification) then has nothing left to
+      # stop: it is recorded as ended, instead of failing the deletion of its owner. Any other
+      # error (a 404 or 400 from a wrong package name, a 403) is raised: the subscription may
+      # still be billing.
       def cancel(**)
-        Tillbell::GooglePlay.cancel(processor_plan, processor_id) if auto_renewing
+        return self if ended?
+
+        Tillbell::GooglePlay.cancel(processor_plan, processor_id) unless renewal_stopped?
         sync!
+      rescue Google::Apis::ClientError => error
+        raise unless error.status_code == 410
+
+        update!(status: "canceled", ends_at: [ current_period_end, Time.current ].compact.min, auto_renewing: false)
+        Tillbell.instrument(:subscription_expired, self)
+        self
       end
 
       # Google can only end a subscription immediately by refunding it, which Tillbell
@@ -192,6 +270,29 @@ module Pay
           raise Tillbell::Error, "Google Play subscriptions cannot #{method_name} from the server; use the app or the Play Store"
         end
       end
+
+      private
+        # True when Google already reports the subscription as canceled or expired. The state,
+        # not +auto_renewing+, which comes from the entitlement about to end and is false while a
+        # deferred plan change waits for the renewal, though the subscription will renew.
+        def renewal_stopped?
+          ENDING_STATES.include?(subscription_state)
+        end
+
+        # Google's last answer with indifferent keys: symbols while the subscription is the
+        # one just synced, strings once it is read back from the database.
+        def google_object
+          ActiveSupport::HashWithIndifferentAccess.new(object || {})
+        end
+
+        # The +recurring_price+ of the line item with the latest known expiry, i.e. the
+        # entitlement in force (Google lists the one about to end and the one that follows during
+        # a deferred plan change; the latter has no expiry yet and sorts first), as a hash with
+        # +units+, +nanos+ and +currency_code+.
+        def recurring_price
+          item = google_object[:line_items].to_a.max_by { |line| line[:expiry_time].to_s }
+          item&.dig(:auto_renewing_plan, :recurring_price)
+        end
     end
   end
 end

data/lib/generators/tillbell/install/install_generator.rb

@@ -7,7 +7,7 @@ module Tillbell
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
-      desc "Creates the Tillbell initializer, mounts the engine and copies the paywall Stimulus controller."
+      desc "Creates the Tillbell initializer, mounts the engine, copies the paywall Stimulus controller and prints the Google Play credentials template."
 
       def create_initializer
         copy_file "initializer.rb", "config/initializers/tillbell.rb"
@@ -29,6 +29,11 @@ module Tillbell
             "npm install @hotwired/hotwire-native-bridge", :yellow
         end
       end
+
+      # The part that happens on Google's side, with the credentials to fill in.
+      def show_next_steps
+        readme "next_steps.txt"
+      end
     end
   end
 end

data/lib/generators/tillbell/install/templates/initializer.rb

@@ -1,5 +1,9 @@
 # Tillbell: Google Play subscriptions stored as Pay subscriptions.
 # See https://github.com/pmakerhq/tillbell-rails#configuration
+#
+# The two values below come from Google: the README's "Google Play setup" has the credentials
+# template and every click. Once they are in your credentials, check everything with
+#   bin/rails tillbell:check          (ONLINE=1 also asks Google)
 Tillbell.configure do |config|
   # Application id of the Android app.
   config.google.package_name = "com.example.app"

data/lib/generators/tillbell/install/templates/next_steps.txt

@@ -0,0 +1,25 @@
+
+Tillbell is installed. What is left happens on Google's side.
+
+1. Put the two values Google gives you in your credentials
+   (bin/rails credentials:edit, or --environment production):
+
+     tillbell:
+       # The whole JSON key file of the service account that calls Google.
+       # Keep the "|" and the two-space indentation.
+       google_service_account: |
+         { "type": "service_account", "client_email": "<tillbell-api>@<project>.iam.gserviceaccount.com", ... }
+       # The service account Pub/Sub signs its notifications with.
+       pubsub_service_account_email: <tillbell-push>@<project>.iam.gserviceaccount.com
+
+2. Set config.google.package_name in config/initializers/tillbell.rb.
+
+3. Follow "Google Play setup" for every click (Play Console, service accounts, Pub/Sub). Allow
+   up to a day for Google to apply the permissions you grant:
+   https://github.com/pmakerhq/tillbell-rails#google-play-setup
+
+4. Check it:
+
+     bin/rails tillbell:check
+     ONLINE=1 PLANS=premium:monthly bin/rails tillbell:check    # also asks Google
+

data/lib/tasks/tillbell.rake

@@ -0,0 +1,17 @@
+namespace :tillbell do
+  desc "Check the Tillbell configuration. ONLINE=1 also asks Google; PLANS=premium:monthly,premium:yearly checks those plans exist."
+  task check: :environment do
+    icons = { ok: "OK  ", warn: "WARN", fail: "FAIL" }
+    online = !%w[0 false no].include?(ENV["ONLINE"].to_s.strip.downcase) && ENV["ONLINE"].present?
+    plans = ENV["PLANS"].to_s.split(",").map(&:strip).reject(&:empty?)
+    check = Tillbell::Check.new(online: online, plans: plans)
+
+    check.call.each do |result|
+      puts "#{icons.fetch(result.status)} #{result.label}#{": #{result.detail}" if result.detail}"
+    end
+    puts "\nGoogle was not asked: run again with ONLINE=1 to check the key, its rights and your subscriptions." unless online
+
+    abort "\nSomething will not work: see the README, \"Google Play setup\"." unless check.ok?
+    puts "\nEverything is in place."
+  end
+end

data/lib/tillbell/check.rb

@@ -0,0 +1,234 @@
+require "openssl"
+
+module Tillbell
+  # Checks that the configuration Tillbell needs is complete, and optionally that Google
+  # accepts it, so an app knows whether purchases and notifications can work before a
+  # customer tries. Run by +bin/rails tillbell:check+ (see the README, "Google Play setup").
+  #
+  # It changes nothing and never shows a secret: only the key names and the e-mail address
+  # of the service accounts.
+  #
+  #   check = Tillbell::Check.new(online: true, plans: [ "premium:monthly", "premium:yearly" ])
+  #   check.call.each { |result| puts "#{result.status} #{result.label} #{result.detail}" }
+  #   check.ok? # false when something will not work
+  class Check
+    # One line of the report. +status+ is +:ok+, +:warn+ (worth a look) or +:fail+ (it will
+    # not work).
+    Result = Data.define(:status, :label, :detail)
+
+    # The shape of a Google Cloud service account e-mail address.
+    SERVICE_ACCOUNT_EMAIL = /\A[^@\s]+@[^@\s]+\.iam\.gserviceaccount\.com\z/
+
+    # [online] Also ask Google (Android Publisher API): the key, its rights and the
+    #          subscriptions of the Play Console.
+    # [plans] Plans the app sells, as +"product_id:base_plan_id"+ strings or
+    #         +{ product_id:, base_plan_id: }+ hashes. With +online+, each must exist in the
+    #         Play Console with an active base plan. Without plans, +online+ lists what the
+    #         Play Console has.
+    def initialize(online: false, plans: [])
+      @online = online
+      @plans = Array(plans).map { |plan| normalize(plan) }
+      @results = []
+    end
+
+    # Runs every check and returns the results, in the order to read them.
+    def call
+      @results = []
+      check_package_name
+      key_email = check_service_account_json
+      check_engine_mount
+      check_pubsub(key_email)
+      if @online && ok?
+        check_online
+      elsif @online
+        add :warn, "Google was not asked", "fix the failures above first, then run again"
+      end
+      @results
+    end
+
+    # True when nothing failed (warnings are fine).
+    def ok? = @results.none? { |result| result.status == :fail }
+
+    private
+
+    def google = Tillbell.google
+
+    def add(status, label, detail = nil)
+      @results << Result.new(status, label, detail)
+      nil
+    end
+
+    def normalize(plan)
+      return plan.symbolize_keys.slice(:product_id, :base_plan_id) if plan.respond_to?(:symbolize_keys)
+
+      product_id, base_plan_id = plan.to_s.split(":", 2)
+      { product_id: product_id, base_plan_id: base_plan_id.presence }
+    end
+
+    def check_package_name
+      if google.package_name.present?
+        add :ok, "Android package name", google.package_name
+      else
+        add :fail, "Android package name", "config.google.package_name is not set"
+      end
+    end
+
+    # Returns the e-mail address of the service account of the key, when it could be read.
+    def check_service_account_json
+      label = "Service account key (config.google.service_account_json)"
+      raw = google.service_account_json
+      return add(:fail, label, "not set: put the key file in your credentials") if raw.blank?
+
+      key = raw.is_a?(String) ? JSON.parse(raw) : raw
+      return add(:fail, label, "not a key file: expected a JSON object") unless key.respond_to?(:to_h) && !key.is_a?(Array)
+
+      key = key.to_h.stringify_keys
+      problems = []
+      problems << "\"type\" is not service_account" unless key["type"] == "service_account"
+      problems << "\"client_email\" is missing" if key["client_email"].blank?
+      problems << "\"private_key\" is missing or unreadable" unless private_key?(key["private_key"])
+      return add(:fail, label, problems.join(", ")) if problems.any?
+
+      add :ok, label, key["client_email"]
+      key["client_email"]
+    rescue JSON::ParserError
+      add :fail, label, "not JSON: paste the whole key file as Google gave it (mind the YAML indentation)"
+    end
+
+    # A key that parses: a mangled one (lost line breaks, truncated) is caught here, offline.
+    def private_key?(pem)
+      OpenSSL::PKey.read(pem.to_s)
+      true
+    rescue OpenSSL::PKey::PKeyError
+      false
+    end
+
+    def check_engine_mount
+      mount = Rails.application.routes.routes.find { |route| route.app.try(:app) == Tillbell::Engine }
+      if mount
+        add :ok, "Engine mounted", "#{mount.path.spec}/purchases and #{mount.path.spec}/notifications/google_play"
+      else
+        add :fail, "Engine mounted", "add `mount Tillbell::Engine, at: \"/tillbell\"` to config/routes.rb"
+      end
+    end
+
+    def check_pubsub(key_email)
+      label = "Notification sender (config.google.pubsub_service_account_email)"
+      email = google.pubsub_service_account_email
+      if email.blank?
+        add :fail, label, "not set: every notification is refused with 401, so renewals and cancellations are never synced"
+      elsif !SERVICE_ACCOUNT_EMAIL.match?(email)
+        add :fail, label, "#{email} does not look like a service account (name@project.iam.gserviceaccount.com)"
+      elsif email == key_email
+        add :warn, label, "#{email} also calls the Google Play API: prefer a dedicated account with no role"
+      else
+        add :ok, label, email
+      end
+
+      add :ok, "Notification audience", google.pubsub_audience.presence || "default: the notification URL as Rails sees it"
+    end
+
+    # Only reads: nothing is created, changed or acknowledged on Google.
+    def check_online
+      service = Tillbell::GooglePlay.service
+      return unless check_purchase_access(service)
+
+      @plans.any? ? @plans.each { |plan| check_plan(service, plan) } : list_subscriptions(service)
+    rescue StandardError => error
+      add :fail, "Google Play API access", describe(error)
+    end
+
+    # What the gem does all day is read a purchase, so ask for one that cannot exist. Google
+    # answers "unknown purchase" when the account may read purchases, and a permission error
+    # when it may not. Acknowledging and cancelling ("Manage orders and subscriptions")
+    # cannot be tried without a real purchase: step 9 of the README does. Returns whether
+    # reading is allowed.
+    def check_purchase_access(service)
+      service.get_purchase_subscriptionsv2(google.package_name, "tillbell-check")
+      add :ok, "Reading purchases", "allowed"
+      true
+    rescue Google::Apis::ClientError => error
+      if Tillbell::GooglePlay::INVALID_TOKEN_STATUSES.include?(error.status_code)
+        add :ok, "Reading purchases", "allowed (Google answered that the test token is unknown, as expected)"
+        true
+      else
+        add :fail, "Reading purchases", describe(error)
+        false
+      end
+    rescue Google::Apis::AuthorizationError, Signet::AuthorizationError => error
+      add :fail, "Reading purchases", describe(error)
+      false
+    end
+
+    def check_plan(service, plan)
+      label = "Subscription #{plan[:product_id]}#{" (base plan #{plan[:base_plan_id]})" if plan[:base_plan_id]}"
+      subscription = service.get_monetization_subscription(google.package_name, plan[:product_id])
+      base_plans = Array(subscription.base_plans)
+      base_plan = if plan[:base_plan_id]
+        base_plans.find { |candidate| candidate.base_plan_id == plan[:base_plan_id] }
+      else
+        base_plans.find { |candidate| candidate.state == "ACTIVE" } || base_plans.first
+      end
+
+      if base_plan.nil?
+        add :fail, label, "the product exists but not this base plan (it has: #{base_plans.map(&:base_plan_id).join(', ').presence || 'none'})"
+      elsif base_plan.state == "ACTIVE"
+        add :ok, label, "active"
+      else
+        add :fail, label, "base plan is #{base_plan.state}: activate it in the Play Console"
+      end
+    rescue Google::Apis::ClientError, Google::Apis::AuthorizationError => error
+      add :fail, label, describe(error, catalog: true)
+    end
+
+    def list_subscriptions(service)
+      subscriptions = []
+      token = nil
+      loop do
+        page = service.list_monetization_subscriptions(google.package_name, page_size: 1000, page_token: token)
+        subscriptions.concat(Array(page.subscriptions))
+        token = page.next_page_token.presence
+        break unless token
+      end
+      return add(:warn, "Subscriptions in the Play Console", "none found: create them under Monetize with Play, Products, Subscriptions") if subscriptions.empty?
+
+      subscriptions.each do |subscription|
+        plans = Array(subscription.base_plans).map { |base_plan| "#{base_plan.base_plan_id} (#{base_plan.state.to_s.downcase})" }
+        add :ok, "Subscription #{subscription.product_id}", plans.join(", ")
+      end
+    rescue Google::Apis::ClientError, Google::Apis::AuthorizationError => error
+      add :fail, "Subscriptions in the Play Console", describe(error, catalog: true)
+    end
+
+    # What to do about an error from Google. +catalog+: the error comes from reading the product
+    # catalog, which may need one more permission than reading purchases.
+    def describe(error, catalog: false)
+      case error
+      when Signet::AuthorizationError
+        "key refused by Google (revoked, deleted, or from another project): create a new JSON key"
+      when Google::Apis::AuthorizationError
+        "not authorized (401): invite the service account in the Play Console with the \"View financial data\" and " \
+          "\"Manage orders and subscriptions\" permissions, and allow up to a day for Google to apply them#{catalog_hint(catalog)}"
+      when Google::Apis::ClientError
+        client_error(error, catalog)
+      else
+        "#{error.class}: #{error.message}"
+      end
+    end
+
+    def client_error(error, catalog)
+      case error.status_code
+      when 403
+        "not allowed (403): enable the Google Play Android Developer API in the Cloud project of the key, and invite the " \
+          "service account in the Play Console with the \"View financial data\" and \"Manage orders and subscriptions\" " \
+          "permissions (Google can take up to a day to apply them)#{catalog_hint(catalog)}"
+      when 404 then "not found (404): wrong package name, or no such product in the Play Console"
+      else "Google answered #{error.status_code}: #{error.message}"
+      end
+    end
+
+    def catalog_hint(catalog)
+      catalog ? "; reading the product catalog may also need \"View app information (read-only)\"" : ""
+    end
+  end
+end

data/lib/tillbell/google_play.rb

@@ -1,5 +1,6 @@
 require "google/apis/androidpublisher_v3"
 require "googleauth"
+require "erb"
 
 module Tillbell
   # Thin client over the Google Play Developer API (Android Publisher v3).
@@ -80,6 +81,17 @@ module Tillbell
         subscription_purchase.dig(:external_account_identifiers, :obfuscated_external_account_id)
       end
 
+      # The Play Store page where a customer manages (updates payment, cancels, resubscribes)
+      # a subscription: the page of +product_id+, or the list of all subscriptions without
+      # it. Same page as the +manage+ message of the native component, for web pages and
+      # emails.
+      def manage_url(product_id = nil)
+        page = "https://play.google.com/store/account/subscriptions"
+        return page if product_id.blank?
+
+        "#{page}?sku=#{ERB::Util.url_encode(product_id)}&package=#{ERB::Util.url_encode(package_name)}"
+      end
+
       def package_name
         Tillbell.google.package_name.presence || raise(Error, "Tillbell.google.package_name is not set")
       end

data/lib/tillbell/version.rb

@@ -1,3 +1,3 @@
 module Tillbell
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/tillbell.rb

@@ -2,6 +2,7 @@ require "pay"
 require "tillbell/version"
 require "tillbell/engine"
 require "tillbell/google_play"
+require "tillbell/check"
 
 # Tillbell adds Google Play subscriptions to Rails apps that use the Pay gem.
 #
@@ -13,8 +14,8 @@ require "tillbell/google_play"
 #
 #   Tillbell.configure do |config|
 #     config.google.package_name = "com.example.app"
-#     config.google.service_account_json = Rails.application.credentials.dig(:tillbell, :google)
-#     config.google.pubsub_service_account_email = "pubsub-push@example.iam.gserviceaccount.com"
+#     config.google.service_account_json = Rails.application.credentials.dig(:tillbell, :google_service_account)
+#     config.google.pubsub_service_account_email = Rails.application.credentials.dig(:tillbell, :pubsub_service_account_email)
 #
 #     config.on(:subscription_created) { |pay_subscription| ... }
 #   end
@@ -47,7 +48,25 @@ module Tillbell
   # +subscribed?(name:)+ look subscriptions up by name, "default" unless you change it.
   mattr_accessor :subscription_name, default: ->(product_id:, base_plan_id:) { Pay.default_product_name }
 
+  # What Hotwire Native writes in the user agent for the bridge components the app
+  # registered, e.g. "bridge-components: [haptic tillbell]". +tillbell+ must be in that
+  # list for the paywall to work.
+  NATIVE_USER_AGENT = /bridge-components: \[(?:[^\]]*\s)?tillbell[\s\]]/
+
   class << self
+    # True when +user_agent+ comes from a native app that registered the +tillbell+ bridge
+    # component (Android today, iOS later), so a Google Play purchase can start from the
+    # page. Use it to choose between the paywall and another way to pay, e.g. a web checkout:
+    #
+    #   Tillbell.native?(request.user_agent)
+    #
+    # An app version without the component, and every browser, answer false. The check
+    # only picks which page to show: purchases are always verified with Google, so a
+    # forged user agent gains nothing.
+    def native?(user_agent)
+      NATIVE_USER_AGENT.match?(user_agent.to_s)
+    end
+
     # Yields the Tillbell module so settings can be assigned in a block.
     def configure
       yield self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tillbell
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Pierre Filstroff
@@ -108,8 +108,11 @@ files:
 - contract/restore.request.json
 - lib/generators/tillbell/install/install_generator.rb
 - lib/generators/tillbell/install/templates/initializer.rb
+- lib/generators/tillbell/install/templates/next_steps.txt
 - lib/generators/tillbell/install/templates/tillbell_controller.js
+- lib/tasks/tillbell.rake
 - lib/tillbell.rb
+- lib/tillbell/check.rb
 - lib/tillbell/engine.rb
 - lib/tillbell/google_play.rb
 - lib/tillbell/version.rb