tillbell 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a61824e3e025f8e1614137ca1139ed6d76aff9d201a40960704824618926e05
-  data.tar.gz: ac1bdc03f6ef383c121b02ff4b03c8d725f65e3b8184a3c058c65e0aa5c24a12
+  metadata.gz: 12dfa4c6d7a3864417897be9a747fefbe25e4b1507665cea18427357bde1d6e6
+  data.tar.gz: 30ad262de35244e9262452acce2734ee92245274bd66f6f74205f798d5e01695
 SHA512:
-  metadata.gz: 0ca823bfe9a3749f16d0af8103f580cc19cc547eb3c1f9ff1c6f9a76d81de686342bfc3b1656cb245ad3fdf4d37a5febe3a4b82526aa8ba7fe1f4e06febae0a0
-  data.tar.gz: 833739c0d7431f22a909c83e3b48e19365163554165d3c5b73b2ef538d8fd96cedd753de6311697f260feae454bb1b04e171c7f8fd524be83cb0ff8272625593
+  metadata.gz: 5d140d39754930be99c4c93de83e51b2947e609e3bff3b0629bad2a95421e806c83e14ce08df900bb78049e869f23802e6d0692506c012feaa58d36649a56de2
+  data.tar.gz: e8118449e7d79da14d3c6b7fc40b0e23aaf20c342343e8f1e77928b15ad4d3ed2a4a6bd14b3915ebb5aa9af1616e5fdc38dcbb1f2fc70f2c423eb7d399599257

data/CHANGELOG.md

@@ -6,6 +6,23 @@ 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

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. |
@@ -337,14 +341,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 +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/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/version.rb

@@ -1,3 +1,3 @@
 module Tillbell
-  VERSION = "0.2.0"
+  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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tillbell
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  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