tillbell 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12dfa4c6d7a3864417897be9a747fefbe25e4b1507665cea18427357bde1d6e6
-  data.tar.gz: 30ad262de35244e9262452acce2734ee92245274bd66f6f74205f798d5e01695
+  metadata.gz: 3e2e56c0874935103736d6f90d868ec525033d4abe32437269b39ea2772d224b
+  data.tar.gz: dde35b5c71bee8fee12aef4ba5fd99c5870d034da7150a8fbcaea55d4dfc5a6c
 SHA512:
-  metadata.gz: 5d140d39754930be99c4c93de83e51b2947e609e3bff3b0629bad2a95421e806c83e14ce08df900bb78049e869f23802e6d0692506c012feaa58d36649a56de2
-  data.tar.gz: e8118449e7d79da14d3c6b7fc40b0e23aaf20c342343e8f1e77928b15ad4d3ed2a4a6bd14b3915ebb5aa9af1616e5fdc38dcbb1f2fc70f2c423eb7d399599257
+  metadata.gz: c951a6879b9603ae4202f731714c2568381f7761d5a86b96fe7566df3e79e7d9c334faf82936582e7f27bb9151f4d614e875c65f725fc99f72f9b133296e3e0d
+  data.tar.gz: fe33d1a43adf91d7a8efdfdad0bbd5acba86536cdcaab1fdf265f6b22491eb3963f9e1029094adc639bf40add424afa360ac6b7666deeda9059a64f43b0ea90e

data/CHANGELOG.md

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

data/README.md

@@ -178,6 +178,7 @@ The values marked "credentials" below come from Google: the [Google Play setup](
 | `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
@@ -199,7 +200,7 @@ The values marked "credentials" below come from Google: the [Google Play setup](
 <% 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 |
 |---|---|
@@ -297,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`).
@@ -306,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
 
@@ -317,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
@@ -324,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|

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/tasks/tillbell.rake

@@ -4,7 +4,7 @@ namespace :tillbell 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 = 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}"

data/lib/tillbell/check.rb

@@ -23,9 +23,9 @@ module Tillbell
     #          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: [])
+    #         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 = []
@@ -59,7 +59,7 @@ module Tillbell
     end
 
     def normalize(plan)
-      return plan.symbolize_keys.slice(:product_id, :base_plan_id) if plan.respond_to?(:symbolize_keys)
+      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 }

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.3.0"
+  VERSION = "0.4.0"
 end

data/lib/tillbell.rb

@@ -3,6 +3,7 @@ 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.
 #
@@ -24,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.
   #
@@ -48,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.
@@ -67,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.3.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
@@ -115,6 +118,7 @@ files:
 - 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: