tillbell 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a61824e3e025f8e1614137ca1139ed6d76aff9d201a40960704824618926e05
-  data.tar.gz: ac1bdc03f6ef383c121b02ff4b03c8d725f65e3b8184a3c058c65e0aa5c24a12
+  metadata.gz: 3e2e56c0874935103736d6f90d868ec525033d4abe32437269b39ea2772d224b
+  data.tar.gz: dde35b5c71bee8fee12aef4ba5fd99c5870d034da7150a8fbcaea55d4dfc5a6c
 SHA512:
-  metadata.gz: 0ca823bfe9a3749f16d0af8103f580cc19cc547eb3c1f9ff1c6f9a76d81de686342bfc3b1656cb245ad3fdf4d37a5febe3a4b82526aa8ba7fe1f4e06febae0a0
-  data.tar.gz: 833739c0d7431f22a909c83e3b48e19365163554165d3c5b73b2ef538d8fd96cedd753de6311697f260feae454bb1b04e171c7f8fd524be83cb0ff8272625593
+  metadata.gz: c951a6879b9603ae4202f731714c2568381f7761d5a86b96fe7566df3e79e7d9c334faf82936582e7f27bb9151f4d614e875c65f725fc99f72f9b133296e3e0d
+  data.tar.gz: fe33d1a43adf91d7a8efdfdad0bbd5acba86536cdcaab1fdf265f6b22491eb3963f9e1029094adc639bf40add424afa360ac6b7666deeda9059a64f43b0ea90e

data/CHANGELOG.md

@@ -6,6 +6,49 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-30
+
+### Added
+
+- `Tillbell::Owner`, to include in the model that declares `pay_customer`: `google_play_subscription`,
+  `google_play_on_hold?`, `current_subscription` (the best subscription across processors),
+  `billing_subscriptions` and `cancel_billing_subscriptions!` (for closing or deleting an account).
+- `billing?` on every Pay subscription: still billed, retried after a failed payment, or paused.
+- Events `subscription_renewed`, `payment_failed`, `payment_recovered` and `plan_changed`. They are
+  emitted next to the existing events, which are unchanged.
+- `config.plans`, `Tillbell.plan`, `Tillbell.replacement_mode(from:, to:)` and `subscription.plan`:
+  a catalog of the plans you sell. `tillbell:check` verifies them without `PLANS`.
+- `paywall.plan_change(to:, from:)`: the option of a plan change, with the replacement mode chosen
+  from the order of the catalog.
+- `subscription.replaced_subscription` and `subscription.token_digest` (a purchase identifier that
+  is safe to send to analytics).
+- Paywall texts in French, Spanish and German (formal address). Their locales become available
+  in the host app unless it sets `config.i18n.available_locales`.
+
+### Changed
+
+- `cancel` and `cancel_now!` raise a `Tillbell::Error` (a `Pay::Error`, with Google's error as its
+  `cause`) instead of a `Google::Apis::Error` or a `Signet::AuthorizationError`, so a host app
+  rescues Pay's error only. Code that rescued the Google errors from `cancel` must rescue
+  `Pay::Error` too.
+
+## [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

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. |
@@ -174,6 +178,7 @@ end
 | `google.pubsub_audience` | endpoint URL | Audience of the Pub/Sub OIDC token. Set it when a proxy changes the URL Rails sees. |
 | `current_owner` | `-> { current_user }` | Returns who is buying. Evaluated in the controller and in the view, so any helper available there works (`Current.user`, `current_account`, ...). |
 | `parent_controller` | `"ApplicationController"` | Controller the purchase endpoint inherits from, to reuse your authentication, CSRF protection and error handling. |
+| `plans` | `[]` | The plans you sell, lowest first: `[{ name: :solo, product_id: "app_solo", base_plan_id: "monthly" }, ...]`. `tillbell:check` verifies them, `subscription.plan` finds the one a subscription is on, and `Tillbell.replacement_mode` and `paywall.plan_change` use their order to tell an upgrade from a downgrade. |
 | `subscription_name` | `->(product_id:, base_plan_id:) { Pay.default_product_name }` | Pay subscription `name` of a Google Play product, as used by `subscribed?(name:)`. |
 
 ## The paywall
@@ -195,7 +200,7 @@ end
 <% end %>
 ```
 
-The markup is unstyled and every builder method accepts HTML attributes (`class:`, `data:`, ...). Texts default to the `tillbell.paywall` translations in [config/locales/en.yml](config/locales/en.yml). Override them in your locale files, or pass the text as the first argument (`paywall.submit "Go premium"`). A locale without translations falls back to English.
+The markup is unstyled and every builder method accepts HTML attributes (`class:`, `data:`, ...). Texts default to the `tillbell.paywall` translations in [config/locales/en.yml](config/locales/en.yml). Override them in your locale files, or pass the text as the first argument (`paywall.submit "Go premium"`). English, French, Spanish and German are included (their locales become available in an app that does not set `config.i18n.available_locales`). A locale without translations falls back to English.
 
 | Builder method | Renders |
 |---|---|
@@ -293,6 +298,42 @@ A `Pay::GooglePlay::Subscription` stores:
 | `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. |
 
+**Plans.** Declare what you sell in `config.plans` and Tillbell knows the rest:
+
+```ruby
+config.plans = [
+  { name: :solo, product_id: "app_solo", base_plan_id: "monthly" },
+  { name: :family, product_id: "app_family", base_plan_id: "monthly" }
+]
+
+subscription.plan                                     # => #<data Tillbell::Plan name=:family, ...>, or nil if it is not in the catalog
+Tillbell.plan(:family)                                # by name, or Tillbell.plan(product_id: "app_family", base_plan_id: "monthly")
+Tillbell.replacement_mode(from: :solo, to: :family)   # => "CHARGE_PRORATED_PRICE" (upgrade); a downgrade gives "DEFERRED"
+```
+
+A plan change from the settings page is then one option in a paywall:
+
+```erb
+<%= tillbell_paywall(success_url: settings_path) do |paywall| %>
+  <%= paywall.plan_change(to: :family, from: current_user.google_play_subscription) { "Switch to Family" } %>
+  <%= paywall.submit %>
+  <%= paywall.status %>
+  <%= paywall.fallback %>
+<% end %>
+```
+
+`token_digest` is a stable identifier of a purchase that is safe to send to an analytics or advertising service (an event id that deduplicates); the purchase token itself must never leave your server.
+
+**Owners with several processors.** `include Tillbell::Owner` in the model that declares `pay_customer`:
+
+| Method | Returns |
+|---|---|
+| `google_play_subscription` | The Google Play subscription, whatever the default processor. |
+| `google_play_on_hold?` | True when Google suspended the subscription for a failed payment: send the customer to `manage_url` rather than to a second subscription, which would bill twice if Google's retry succeeds. |
+| `current_subscription` | The subscription to show and decide access from: the one that renews, then one that is canceled but running, then one whose payment is retried or that is paused; the most recent breaks a tie. |
+| `billing_subscriptions` | What still bills or resumes by itself (`subscription.billing?`), Google Play first. |
+| `cancel_billing_subscriptions!` | Cancels them: call it before closing or deleting an account. |
+
 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`).
@@ -302,10 +343,10 @@ Pay only knows its own processors, so Tillbell adds `google_play?` to customers
 **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!)
+user.cancel_billing_subscriptions!   # with Tillbell::Owner: what `billing?` says still bills, Google Play first
 ```
 
-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.
+`billing?` is true for an active subscription (a canceled one that has not ended included), one whose payment is retried (`past_due`, `unpaid`) and a paused one, which resumes by itself, a Stripe pause (status `active`) included. A Google Play purchase still pending (a cash payment) is not: Google cannot cancel it until it completes. Google can fail (API error, revoked service account key): `cancel` raises a `Tillbell::Error`, a `Pay::Error` whose `cause` is Google's error, so rescuing `Pay::Error` next to your other processors' errors is enough. Tell the customer to try again.
 
 ## Events
 
@@ -313,6 +354,10 @@ Google can fail (API error, revoked service account key), so rescue `Pay::Error`
 Tillbell.configure do |config|
   config.on(:subscription_created)  { |subscription| WelcomeMailer.with(user: subscription.owner).premium.deliver_later }
   config.on(:subscription_updated)  { |subscription| }  # renewal, grace period, hold, recovery, plan change
+  config.on(:subscription_renewed)  { |subscription| }  # a new period started (also fires subscription_updated)
+  config.on(:payment_failed)        { |subscription| }  # a payment failed: the grace period or the hold started (also fires subscription_updated)
+  config.on(:payment_recovered)     { |subscription| }  # the payment went through after a failure
+  config.on(:plan_changed)          { |subscription| }  # the customer is now on another product or base plan; subscription.replaced_subscription is the previous purchase, if any
   config.on(:subscription_canceled) { |subscription| }  # will not renew; access until ends_at
   config.on(:subscription_expired)  { |subscription| }
   config.on(:subscription_revoked)  { |subscription| }  # refunded or charged back
@@ -320,7 +365,7 @@ 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:
+A plan change fires `subscription_created` for the new purchase (`replacement?` is true), `subscription_expired` for the old one (`replaced?` is true) and then `plan_changed` once. `subscription_updated` fires for every change, a renewal included; `subscription_renewed`, `payment_failed`, `payment_recovered` and `plan_changed` say which one happened (`payment_failed` fires on the first failure only, not again when the grace period turns into a hold), so you rarely need to filter it yourself. If you do, for example in a Slack or analytics subscriber:
 
 ```ruby
 Tillbell.on(:subscription_updated) do |subscription|
@@ -337,14 +382,183 @@ Events go through Pay's webhook delegator, so `Pay::Webhooks.delegator.subscribe
 
 ## 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
 
@@ -358,6 +572,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_builder.rb

@@ -26,6 +26,19 @@ module Tillbell
       tag.label(**html_options) { radio + @template.capture(&block) }
     end
 
+    # The plan option for moving from the Google Play subscription +from+ to the plan +to+ of
+    # +Tillbell.plans+ (a name or a plan), checked, with the replacement mode Google needs:
+    # prorated for an upgrade, deferred to the next renewal for a downgrade (see
+    # +Tillbell.replacement_mode+). Use it in a paywall that offers this one plan.
+    def plan_change(to:, from:, **html_options, &block)
+      raise ArgumentError, "plan_change needs the current Google Play subscription (from:)" if from.nil?
+
+      current = from.plan || raise(ArgumentError, "the current subscription (#{from.processor_plan}:#{from.base_plan_id}) is not in Tillbell.plans")
+      target = to.is_a?(Tillbell::Plan) ? to : Tillbell.plan(to) || raise(ArgumentError, "#{to.inspect} is not in Tillbell.plans")
+      plan_option(product_id: target.product_id, base_plan_id: target.base_plan_id, checked: true, replacing: from,
+                  replacement_mode: Tillbell.replacement_mode(from: current, to: target), **html_options, &block)
+    end
+
     # Placeholder for the localized price, filled in from Google Play. Use it inside a
     # +plan_option+ block.
     def price(placeholder = "", **html_options)

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

@@ -40,6 +40,11 @@ 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
 
+      ACTIVE_STATE = "SUBSCRIPTION_STATE_ACTIVE".freeze
+
+      # Google states of a payment that failed and is being retried.
+      PAYMENT_PROBLEM_STATES = %w[SUBSCRIPTION_STATE_IN_GRACE_PERIOD SUBSCRIPTION_STATE_ON_HOLD].freeze
+
       store_accessor :data, :subscription_state, :base_plan_id, :auto_renewing, :revoked_at, :replaced_by
 
       class << self
@@ -62,10 +67,13 @@ module Pay
             return
           end
 
-          subscription, event = save_from_google(pay_customer, purchase_token, attributes_from(object, revoked: revoked))
-          Tillbell.instrument(event, subscription) if event
+          subscription, events = save_from_google(pay_customer, purchase_token, attributes_from(object, revoked: revoked))
+          events.each { |event| Tillbell.instrument(event, subscription) }
 
-          retire(object[:linked_purchase_token], replaced_by: purchase_token)
+          retire(object[:linked_purchase_token], replaced_by: purchase_token).each do |old, expired|
+            Tillbell.instrument(:subscription_expired, old) if expired
+            Tillbell.instrument(:plan_changed, subscription) if [ old.processor_plan, old.base_plan_id ] != [ subscription.processor_plan, subscription.base_plan_id ]
+          end
           acknowledge(subscription, object)
           subscription
         end
@@ -95,7 +103,7 @@ module Pay
 
         private
           # Saves the attributes under a row lock and returns the subscription with the
-          # event its changes call for. Concurrent syncs of the same token (purchase
+          # events its changes call for. Concurrent syncs of the same token (purchase
           # request and notification) serialize on the lock, so only one emits the event.
           def save_from_google(pay_customer, purchase_token, attributes)
             attempts = 0
@@ -110,9 +118,9 @@ module Pay
                 # 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
+                events = subscription.events_for_changes
                 subscription.save!
-                [ subscription, event ]
+                [ subscription, events ]
               end
             rescue ActiveRecord::RecordNotUnique
               # Another process inserted the row first; a second attempt finds it and locks it.
@@ -125,12 +133,21 @@ module Pay
           # 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.
+          #
+          # Returns +[subscription, expired]+ pairs for the subscriptions it marked as replaced,
+          # +expired+ telling whether this call ended them: a notification about the old token
+          # may have ended it first (and emitted +subscription_expired+, before the replacement
+          # was known). Rows are locked and skipped once replaced, so two syncs of the same new
+          # token (purchase request and notification) retire the old one, and report it, once.
           def retire(linked_purchase_token, replaced_by:)
-            return if linked_purchase_token.blank?
+            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, replaced_by: replaced_by)
-              Tillbell.instrument(:subscription_expired, subscription)
+            transaction(requires_new: true) do
+              where(processor_id: linked_purchase_token).lock.reject(&:replaced?).map do |subscription|
+                expired = subscription.status != "canceled"
+                subscription.update!(status: "canceled", ends_at: expired ? Time.current : subscription.ends_at, replaced_by: replaced_by)
+                [ subscription, expired ]
+              end
             end
           end
 
@@ -154,6 +171,15 @@ module Pay
         :subscription_updated
       end
 
+      # Every event the pending changes call for, the generic one first (see
+      # +event_for_changes+) then the detailed ones the host app would otherwise have to
+      # deduce from +saved_changes+. Called before saving.
+      def events_for_changes
+        events = [ event_for_changes ]
+        events.push(*detail_events) if persisted? && !revoked? && !replaced?
+        events.compact
+      end
+
       # True while Google retries a failed payment and the customer keeps access.
       def in_grace_period?
         subscription_state == "SUBSCRIPTION_STATE_IN_GRACE_PERIOD"
@@ -233,6 +259,24 @@ module Pay
         deferred_product_id.present?
       end
 
+      # The subscription this purchase replaces (see +replacement?+), or nil.
+      def replaced_subscription
+        self.class.find_by(processor_id: linked_purchase_token) if replacement?
+      end
+
+      # The plan of +Tillbell.plans+ this subscription is on, or nil when it is not in the
+      # catalog.
+      def plan
+        Tillbell.plan(product_id: processor_plan, base_plan_id: base_plan_id)
+      end
+
+      # A stable identifier of the purchase that is safe to send to a third party (an analytics
+      # or advertising event id): the purchase token itself grants access to the subscription
+      # and must never leave the server.
+      def token_digest
+        Digest::SHA256.hexdigest(processor_id).first(16)
+      end
+
       # Stops the renewal with Google; access continues until the end of the period.
       # 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
@@ -241,15 +285,16 @@ module Pay
       # 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.
+      # error (a 404 or 400 from a wrong package name, a 403, a revoked service account key) is
+      # raised as a +Tillbell::Error+ (a +Pay::Error+), whose +cause+ is Google's error: the
+      # subscription may still be billing, and the host app only has to rescue Pay's error.
       def cancel(**)
         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
+      rescue *Tillbell::GooglePlay::API_ERRORS => error
+        raise Tillbell::Error, "Google Play refused to stop the renewal: #{error.message}" unless error.try(:status_code) == 410
 
         update!(status: "canceled", ends_at: [ current_period_end, Time.current ].compact.min, auto_renewing: false)
         Tillbell.instrument(:subscription_expired, self)
@@ -272,6 +317,33 @@ module Pay
       end
 
       private
+        # Events that say what happened to an existing subscription, deduced from its pending
+        # changes: +:plan_changed+ (the product or base plan changed on the same purchase, e.g. a
+        # deferred downgrade that took effect), +:subscription_renewed+, +:payment_failed+ (the
+        # first failure only: the move from the grace period to the hold is not a second one) and
+        # +:payment_recovered+. A replacement purchase is announced by +Subscription.sync+.
+        def detail_events
+          events = []
+          events << :plan_changed if processor_plan_changed? || base_plan_id_changed?
+          events << :subscription_renewed if renewed?
+          events << :payment_failed if PAYMENT_PROBLEM_STATES.include?(subscription_state) && !PAYMENT_PROBLEM_STATES.include?(previous_state)
+          events << :payment_recovered if subscription_state == ACTIVE_STATE && PAYMENT_PROBLEM_STATES.include?(previous_state)
+          events
+        end
+
+        # A new period started: the expiry moved on while the subscription was in good standing
+        # or recovering. Not the first activation of a pending purchase.
+        def renewed?
+          subscription_state == ACTIVE_STATE && current_period_end_changed? && current_period_end_was.present? &&
+            [ ACTIVE_STATE, *PAYMENT_PROBLEM_STATES ].include?(previous_state)
+        end
+
+        # The state before the pending changes. The store accessor's +_was+ answers nil for a
+        # state that did not change.
+        def previous_state
+          subscription_state_changed? ? subscription_state_was : subscription_state
+        end
+
         # 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.

data/config/locales/de.yml

@@ -0,0 +1,15 @@
+# Paywall-Texte auf Deutsch. Jeder Text lässt sich in den Sprachdateien der Anwendung überschreiben.
+de:
+  tillbell:
+    paywall:
+      submit: "Abonnieren"
+      restore: "Käufe wiederherstellen"
+      manage: "Abo verwalten"
+      fallback: "Abos sind in der neuesten Version der Android-App verfügbar."
+      messages:
+        verifying: "Wir prüfen Ihren Kauf. Das kann einige Minuten dauern."
+        pending: "Ihre Zahlung steht noch aus. Ihr Abo beginnt, sobald sie bestätigt ist."
+        unavailable: "Google Play Billing ist auf diesem Gerät nicht verfügbar."
+        nothing_to_restore: "Keine Käufe zum Wiederherstellen."
+        rejected: "Dieser Kauf gehört zu einem anderen Konto."
+        error: "Etwas ist schiefgelaufen. Bitte versuchen Sie es erneut."

data/config/locales/es.yml

@@ -0,0 +1,15 @@
+# Textos del paywall en español. Cada texto puede sustituirse en los archivos de idioma de la aplicación.
+es:
+  tillbell:
+    paywall:
+      submit: "Suscribirse"
+      restore: "Restaurar compras"
+      manage: "Gestionar suscripción"
+      fallback: "Las suscripciones están disponibles en la última versión de la aplicación Android."
+      messages:
+        verifying: "Estamos comprobando su compra. Puede tardar unos minutos."
+        pending: "Su pago está pendiente. Su suscripción empieza en cuanto se confirme."
+        unavailable: "La facturación de Google Play no está disponible en este dispositivo."
+        nothing_to_restore: "No hay compras que restaurar."
+        rejected: "Esta compra pertenece a otra cuenta."
+        error: "Algo ha salido mal. Inténtelo de nuevo."

data/config/locales/fr.yml

@@ -0,0 +1,15 @@
+# Textes du paywall en français. Chaque texte peut être remplacé dans les fichiers de langue de l'application.
+fr:
+  tillbell:
+    paywall:
+      submit: "S'abonner"
+      restore: "Restaurer mes achats"
+      manage: "Gérer l'abonnement"
+      fallback: "Les abonnements sont disponibles dans la dernière version de l'application Android."
+      messages:
+        verifying: "Nous vérifions votre achat. Cela peut prendre quelques minutes."
+        pending: "Votre paiement est en attente. Votre abonnement démarre dès qu'il est confirmé."
+        unavailable: "La facturation Google Play n'est pas disponible sur cet appareil."
+        nothing_to_restore: "Aucun achat à restaurer."
+        rejected: "Cet achat appartient à un autre compte."
+        error: "Une erreur est survenue. Veuillez réessayer."

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.presence || Tillbell.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. Defaults to +Tillbell.plans+; without
+    #         any, +online+ lists what the Play Console has.
+    def initialize(online: false, plans: Tillbell.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.to_h.symbolize_keys.slice(:product_id, :base_plan_id) if plan.respond_to?(:to_h)
+
+      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/engine.rb

@@ -27,6 +27,15 @@ module Tillbell
       end
 
       ActiveSupport.on_load(:pay_subscription) do
+        # True while the processor still bills the subscription, or will resume it by itself:
+        # active (including a canceled one that has not ended), retried after a failed payment
+        # (past_due, unpaid) or paused (a Stripe pause keeps the status "active" and resumes by
+        # itself). These are the ones to cancel before closing an account. A Google Play purchase
+        # still pending (cash payments) is not: Google cannot cancel it until it completes.
+        def billing?
+          !ended? && (active? || past_due? || unpaid? || paused?)
+        end
+
         scope :google_play, -> { joins(:customer).where(pay_customers: { processor: "google_play" }) }
 
         def google_play?

data/lib/tillbell/google_play.rb

@@ -13,6 +13,10 @@ module Tillbell
     # Errors worth retrying later: rate limiting, Google server errors and network failures.
     TRANSIENT_ERRORS = [ Google::Apis::RateLimitError, Google::Apis::ServerError, Google::Apis::TransmissionError ].freeze
 
+    # Everything a call to Google can raise besides a bug: API errors, and the errors of the
+    # request for an access token (a revoked key, Google's token server failing).
+    API_ERRORS = [ Google::Apis::Error, Signet::AuthorizationError, Signet::RemoteServerError, Signet::UnexpectedStatusError ].freeze
+
     # HTTP statuses Google answers for a purchase token it does not know (invented,
     # malformed, or expired for more than 60 days). Other client errors, such as a 403
     # for a service account without access to the Play Console, are configuration

data/lib/tillbell/owner.rb

@@ -0,0 +1,61 @@
+module Tillbell
+  # Subscription helpers for the model that declares +pay_customer+ (usually +User+), for an
+  # owner who may have subscriptions with several Pay processors (Stripe on the web, Google
+  # Play in the app).
+  #
+  #   class User < ApplicationRecord
+  #     pay_customer
+  #     include Tillbell::Owner
+  #   end
+  module Owner
+    # The Google Play subscription of the owner, or nil. Pay's +payment_processor+ is the owner's
+    # default processor, which a Google Play customer never is (see the README).
+    def google_play_subscription
+      customer = pay_customers.active.find_by(processor: "google_play")
+      # Not Pay::Customer#subscription, which only looks at the default subscription name.
+      subscriptions = customer&.subscriptions&.order(created_at: :desc)
+      subscriptions&.active_or_paused&.first || subscriptions&.first
+    end
+
+    # True when the Google Play subscription is on hold: the payment failed after the grace
+    # period and Google requires access to be suspended while it retries. The customer fixes it
+    # in the Play Store (+manage_url+); subscribing again elsewhere would bill twice if the
+    # retry succeeds.
+    def google_play_on_hold?
+      google_play_subscription&.on_hold? || false
+    end
+
+    # The subscription to show and to decide access from, whatever its processor: the one
+    # that renews, then one that is canceled but still running, then one whose payment is
+    # being retried or that is paused; the most recent breaks a tie. Nil without any.
+    def current_subscription
+      pay_subscriptions.includes(:customer).min_by { |subscription| [ subscription_standing(subscription), -subscription.created_at.to_i ] }
+    end
+
+    # The subscriptions that still bill the owner, or will resume by themselves (see
+    # +Pay::Subscription#billing?+), Google Play first: its cancellation can be undone in the
+    # Play Store and Stripe's cannot, so a Google failure must not leave a customer who
+    # already lost the other one.
+    def billing_subscriptions
+      pay_subscriptions.includes(:customer).select(&:billing?).sort_by { |subscription| subscription.google_play? ? 0 : 1 }
+    end
+
+    # Cancels what +billing_subscriptions+ lists, to call before closing or deleting the
+    # account and before changing anything in the database: an error raised afterwards would
+    # leave a closed account that is still billed. Google Play subscriptions only stop
+    # renewing, the customer keeps access until the end of the paid period. Raises +Pay::Error+
+    # (+Tillbell::Error+ for Google Play) when a processor refuses.
+    def cancel_billing_subscriptions!
+      billing_subscriptions.each(&:cancel_now!)
+    end
+
+    private
+      def subscription_standing(subscription)
+        if subscription.active? && !subscription.on_grace_period? then 0
+        elsif subscription.active? then 1
+        elsif subscription.billing? then 2
+        else 3
+        end
+      end
+  end
+end

data/lib/tillbell/version.rb

@@ -1,3 +1,3 @@
 module Tillbell
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/tillbell.rb

@@ -2,6 +2,8 @@ require "pay"
 require "tillbell/version"
 require "tillbell/engine"
 require "tillbell/google_play"
+require "tillbell/check"
+require "tillbell/owner"
 
 # Tillbell adds Google Play subscriptions to Rails apps that use the Pay gem.
 #
@@ -13,8 +15,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
@@ -23,8 +25,17 @@ module Tillbell
   class Error < Pay::Error; end
 
   # The events Tillbell emits, in the order a subscription usually goes through them.
-  EVENTS = %i[subscription_created subscription_updated subscription_canceled subscription_expired subscription_revoked
-              purchase_rejected].freeze
+  # +subscription_updated+ fires for any change; +subscription_renewed+, +payment_failed+,
+  # +payment_recovered+ and +plan_changed+ say which one happened.
+  EVENTS = %i[subscription_created subscription_updated subscription_renewed payment_failed payment_recovered plan_changed
+              subscription_canceled subscription_expired subscription_revoked purchase_rejected].freeze
+
+  # A plan the app sells: a Google Play product and its base plan, under a name of your own.
+  Plan = Data.define(:name, :product_id, :base_plan_id) do
+    def initialize(name:, product_id:, base_plan_id: nil)
+      super(name: name.to_sym, product_id: product_id, base_plan_id: base_plan_id)
+    end
+  end
 
   # Google Play settings, see the README for where each value comes from.
   #
@@ -47,6 +58,18 @@ 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 }
 
+  # The plans the app sells, from the lowest to the highest: the order decides whether a plan
+  # change is an upgrade or a downgrade (see +replacement_mode+). Assign hashes:
+  #
+  #   config.plans = [
+  #     { name: :solo, product_id: "app_solo", base_plan_id: "monthly" },
+  #     { name: :family, product_id: "app_family", base_plan_id: "monthly" }
+  #   ]
+  #
+  # +tillbell:check+ checks them with Google, and +Pay::GooglePlay::Subscription#plan+ finds
+  # the one a subscription is on.
+  mattr_reader :plans, default: [].freeze
+
   # 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.
@@ -66,6 +89,41 @@ module Tillbell
       NATIVE_USER_AGENT.match?(user_agent.to_s)
     end
 
+    # Sets the catalog of +plans+ from hashes with +name+, +product_id+ and optionally
+    # +base_plan_id+ (or from +Tillbell::Plan+ objects).
+    def plans=(list)
+      @@plans = list.map do |plan|
+        next plan if plan.is_a?(Plan)
+        raise ArgumentError, "a plan is a hash with :name, :product_id and :base_plan_id, got #{plan.inspect}" unless plan.respond_to?(:to_h) && !plan.nil?
+
+        Plan.new(**plan.to_h.symbolize_keys)
+      end.freeze
+    end
+
+    # Finds a plan of +plans+ by +name+ (a symbol or string) or by Google ids. With a
+    # +base_plan_id+ that no plan has, falls back to the product's plan when it has only one.
+    def plan(name = nil, product_id: nil, base_plan_id: nil)
+      return plans.find { |plan| plan.name == name.to_sym } if name
+
+      matches = plans.select { |plan| plan.product_id == product_id }
+      matches.find { |plan| plan.base_plan_id == base_plan_id } || (matches.first if matches.one?)
+    end
+
+    # The Google replacement mode for moving from plan +from+ to plan +to+ (plans, or their
+    # names): +CHARGE_PRORATED_PRICE+ for an upgrade, charged now for the difference with the
+    # renewal date unchanged, and +DEFERRED+ for a downgrade, which takes effect at the next
+    # renewal because the customer already paid the current period and Google does not
+    # refund it. Raises +ArgumentError+ for a plan that is not in +plans+ or a move to the
+    # same plan.
+    def replacement_mode(from:, to:)
+      ranks = [ from, to ].map do |plan|
+        plans.index { |candidate| candidate == plan || candidate.name == plan.try(:to_sym) } || raise(ArgumentError, "#{plan.inspect} is not in Tillbell.plans")
+      end
+      raise ArgumentError, "#{from.inspect} and #{to.inspect} are the same plan" if ranks.first == ranks.last
+
+      ranks.last > ranks.first ? "CHARGE_PRORATED_PRICE" : "DEFERRED"
+    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.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Pierre Filstroff
@@ -82,7 +82,10 @@ files:
 - app/jobs/tillbell/sync_job.rb
 - app/models/pay/google_play/customer.rb
 - app/models/pay/google_play/subscription.rb
+- config/locales/de.yml
 - config/locales/en.yml
+- config/locales/es.yml
+- config/locales/fr.yml
 - config/routes.rb
 - contract/examples/manage.request.json
 - contract/examples/products.reply.ok.json
@@ -108,10 +111,14 @@ 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/owner.rb
 - lib/tillbell/version.rb
 homepage: https://github.com/pmakerhq/tillbell-rails
 licenses: