tillbell 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72c52a2e210cb60ee2fa3173935075173b3c90a1e30574c7d0b381210c8374f2
-  data.tar.gz: d7d9d6f30c25c140ee124e8de0f567995a57b31a8a211ca76905859f6c78d875
+  metadata.gz: 0a61824e3e025f8e1614137ca1139ed6d76aff9d201a40960704824618926e05
+  data.tar.gz: ac1bdc03f6ef383c121b02ff4b03c8d725f65e3b8184a3c058c65e0aa5c24a12
 SHA512:
-  metadata.gz: 6b9e6e9f84d106ed21019f130acc49913a6dea88014d0c3eaa4b5bcb777d957eafe2173b5ea7892bba9f7eacfbe4421415eb5787c0b47eb696db0fcc2c0d0681
-  data.tar.gz: 9f8314103d9234e46279cd3625fe2603c340e42889435d0adfbd6ef245eca82b7dd354cef6513a78aa3f3363dbf06586beeb9e1f28778a948a364c17450a8f26
+  metadata.gz: 0ca823bfe9a3749f16d0af8103f580cc19cc547eb3c1f9ff1c6f9a76d81de686342bfc3b1656cb245ad3fdf4d37a5febe3a4b82526aa8ba7fe1f4e06febae0a0
+  data.tar.gz: 833739c0d7431f22a909c83e3b48e19365163554165d3c5b73b2ef538d8fd96cedd753de6311697f260feae454bb1b04e171c7f8fd524be83cb0ff8272625593

data/CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-30
+
+### Added
+
+- `Tillbell.native?(user_agent)` and the `tillbell_native?` view helper: tell whether the
+  app showing the page registered the `tillbell` component, to choose between the paywall
+  and another way to pay.
+- Details of a `Pay::GooglePlay::Subscription` read from Google's last answer:
+  `price_amount` and `price_currency`, `replacement?`, `linked_purchase_token`, `replaced?`,
+  `plan_change_pending?`, `deferred_product_id` and `manage_url`.
+- `Tillbell::GooglePlay.manage_url(product_id = nil)`: the Play Store page of a
+  subscription, for web pages and emails.
+- README: detecting the native app, plan changes (replacement modes, `DEFERRED`
+  downgrades), subscription details, several processors per customer, closing an account,
+  and events during a plan change.
+
+### Changed
+
+- A replaced subscription remembers the purchase token that replaced it (`data["replaced_by"]`)
+  and keeps its ended state: a later read of the old token no longer brings it back.
+- `cancel` decides whether to ask Google from its subscription state (canceled or expired)
+  instead of `auto_renewing`, which is false while a deferred plan change waits for the renewal
+  though the subscription will renew.
+
+### Fixed
+
+- `cancel` (and `cancel_now!`) on a subscription Google answers 410 for (a purchase token
+  expired for more than 60 days) no longer raises: it made closing an account or deleting an
+  owner fail for a customer who left long ago, including for a row still stored as active
+  because a notification was missed. The subscription is recorded as ended and
+  `subscription_expired` is emitted once. Other errors still raise.
+
 ## [0.1.1] - 2026-10-30
 
 ### Changed

data/README.md

@@ -211,16 +211,46 @@ Prices always come from Google Play, never from your app.
 
 **Without the native component** (a browser, or an old app version), the Stimulus controller does not connect. The buttons stay disabled, the fallback stays visible, and no purchase can start.
 
+**Detecting the native app.** Hotwire Native lists the components an app registered in its user agent (`bridge-components: [haptic tillbell]`). To choose between the paywall and another way to pay, ask Tillbell instead of parsing it yourself:
+
+```erb
+<% if tillbell_native? %>
+  <%= tillbell_paywall success_url: dashboard_path do |paywall| %> ... <% end %>
+<% else %>
+  <%= link_to "Subscribe on the web", checkout_path %>
+<% end %>
+```
+
+In a controller, use `Tillbell.native?(request.user_agent)`. It only picks which page to show: a purchase is always verified with Google, so a forged user agent gains nothing. It answers `true` for any native app (Android today, iOS later) that registered the component, and `false` for browsers and for app versions without it.
+
 **Plan changes.** Pass the current subscription and Google's [replacement mode](https://developer.android.com/google/play/billing/subscriptions#replacement-modes). Tillbell passes the mode through and never decides proration:
 
 ```erb
-<%= paywall.plan_option product_id: "family", base_plan_id: "monthly",
-      replacing: current_user.pay_subscriptions.active.first,
-      replacement_mode: "CHARGE_PRORATED_PRICE" do %>
-  Switch to Family, <%= paywall.price %>
+<%= tillbell_paywall success_url: settings_path do |paywall| %>
+  <%= paywall.plan_option product_id: "family", base_plan_id: "monthly", checked: true,
+        replacing: current_user.pay_subscriptions.google_play.active.first,   # the current Pay::GooglePlay::Subscription
+        replacement_mode: "CHARGE_PRORATED_PRICE" do %>
+    Switch to Family, <%= paywall.price %>
+  <% end %>
+  <%= paywall.submit "Switch to Family" %>
+  <%= paywall.status %>
 <% end %>
 ```
 
+| Replacement mode | Use it for | Effect |
+|---|---|---|
+| `CHARGE_PRORATED_PRICE` | An upgrade to a more expensive plan (upgrades only) | Takes effect now. The customer pays the price difference for the rest of the period, and the billing date does not change. |
+| `WITH_TIME_PRORATION` | An upgrade (Google's default) | Takes effect now. The value of the unused time is credited by pushing the next billing date forward. |
+| `WITHOUT_PRORATION` | An upgrade that keeps a free period | Takes effect now. The new price applies from the next renewal. |
+| `CHARGE_FULL_PRICE` | Switching to a longer billing period | Takes effect now. The customer is charged the full price of the new plan, and the remaining value of the old one is credited. |
+| `DEFERRED` | A downgrade to a cheaper plan | Takes effect at the next renewal: the customer keeps what they paid for until then. |
+
+Google recommends `CHARGE_PRORATED_PRICE` for an upgrade and `DEFERRED` for a downgrade. The server picks the mode, never the app, so a customer cannot choose a cheaper way to upgrade.
+
+A purchase that replaces another (a plan change, or a customer who signs up again for a subscription that was canceled but had not lapsed) gets a new purchase token that points to the old one. Tillbell stores the new subscription, ends the old one, and emits `subscription_created` then `subscription_expired` (see [Events](#events)).
+
+A `DEFERRED` change waits for the renewal. Google reports it on the **new** purchase: one line item for the entitlement that is about to end, carrying the product the customer is moving to, and one for the entitlement that follows. Until the renewal the new subscription keeps the current product as `processor_plan`, and `subscription.plan_change_pending?` and `subscription.deferred_product_id` tell where it is going, so the page can say "Switching to Solo on March 3" (`current_period_end`). After the renewal `processor_plan` is the new product. Only an active subscription that is still renewing can change plan: hide the option for a canceled (`on_grace_period?`) or held (`on_hold?`) one.
+
 **JavaScript events.** The controller dispatches events on the paywall element:
 
 - `tillbell:verified`: the purchase grants access. Call `event.preventDefault()` to stay on the page instead of visiting `success_url`.
@@ -252,9 +282,30 @@ A `Pay::GooglePlay::Subscription` stores:
 - `data`: `base_plan_id`, `subscription_state`, `auto_renewing` and `revoked_at`;
 - `object`: Google's last answer.
 
+**Details from Google.** These read Google's last answer, so they cost no API call:
+
+| Method | Returns |
+|---|---|
+| `price_amount`, `price_currency` | The price of one renewal as a `BigDecimal` in the units of its currency (`12.99`, or `1200` yen) and its ISO currency (`"EUR"`), as Google bills it in the customer's country. For analytics and conversion events (e.g. a Meta or Google Ads purchase, which take a decimal value); show prices to customers from Google Play, as the paywall does. It is the price of the entitlement in force. `nil` when Google gave none. |
+| `replacement?`, `linked_purchase_token` | Whether this purchase replaces an earlier one, and the token of that one. Google sets it for a plan change, for a customer who signs up again for a subscription that was canceled but had not lapsed, and for prepaid plans converted to or topped up as auto-renewing. Compare `processor_plan` with the replaced subscription's to tell a plan change. |
+| `replaced?` | Whether a newer purchase replaced this subscription. Set when the replacement is recorded, so it is already true inside the `subscription_expired` callback; use it to tell a replaced subscription from a customer who left (see [Events](#events)). Subscriptions replaced before this was added are not flagged. |
+| `plan_change_pending?`, `deferred_product_id` | A `DEFERRED` plan change waiting for the next renewal, and the product it goes to. |
+| `manage_url` | The Play Store page where the customer manages this subscription (update the payment method, cancel, resubscribe). Same page as `paywall.manage`, for web pages and emails. `Tillbell::GooglePlay.manage_url(product_id)` gives it for any product, and without one the list of all subscriptions. |
+| `in_grace_period?`, `on_hold?`, `revoked?` | The Google states that Pay statuses merge. |
+
+A customer can have a Stripe subscription and a Google Play one (a web customer who later subscribes in the app, or the reverse). `Pay::GooglePlay::Customer` is never the owner's default payment processor, so `owner.payment_processor` does not see Google Play subscriptions: look at `owner.pay_subscriptions`, or at the Google Play customer (`owner.pay_customers.google_play.first`), to decide who has access.
+
 Pay only knows its own processors, so Tillbell adds `google_play?` to customers and subscriptions, and a `google_play` scope next to Pay's `stripe` one (`Pay::Subscription.google_play`).
 
-`subscription.cancel` stops the renewal through the Google Play Developer API. `swap`, `pause` and `resume` raise `Tillbell::Error`: plan changes go through the paywall, and the rest happens in the Play Store.
+`subscription.cancel` stops the renewal through the Google Play Developer API; the customer keeps access until the end of the paid period. Google can only end a subscription immediately by refunding it, which Tillbell never does on its own, so `cancel_now!` (which Pay calls when an owner is destroyed) also just stops the renewal. Google answers 410 for a purchase token that expired more than 60 days ago: a subscription still stored as active (a missed notification) is then recorded as ended, with a `subscription_expired` event, instead of failing the deletion of its owner. Any other error is raised, a 404 from a wrong package name for example: the subscription may still be billing. A subscription ended or already canceled is left alone, and one that waits for a deferred plan change is cancelled like any other: whether it is renewing comes from Google's subscription state, not from the entitlement about to end. `swap`, `pause` and `resume` raise `Tillbell::Error`: plan changes go through the paywall, and the rest happens in the Play Store.
+
+**Closing or deleting an account.** Cancel what still bills before you close the account, whatever the processor, and before changing anything in your database: an error raised after the account is closed leaves the subscription billing a closed account. Pay's own hook when an owner is destroyed only cancels `active` subscriptions. Google keeps retrying a held payment (`past_due`) and resumes a paused subscription by itself, so include both:
+
+```ruby
+user.pay_subscriptions.where(status: %w[active past_due paused]).reject(&:ended?).each(&:cancel_now!)
+```
+
+Google can fail (API error, revoked service account key), so rescue `Pay::Error` (which includes `Tillbell::Error`, raised when the package name or the service account is not configured), `Google::Apis::Error` and `Signet::AuthorizationError` next to your other processors' errors, and tell the customer to try again.
 
 ## Events
 
@@ -269,6 +320,19 @@ Tillbell.configure do |config|
 end
 ```
 
+A plan change fires `subscription_created` for the new purchase (`replacement?` is true) and `subscription_expired` for the old one (`replaced?` is true). Renewals fire `subscription_updated` too, so filter on what you care about, for example in a Slack or analytics subscriber:
+
+```ruby
+Tillbell.on(:subscription_updated) do |subscription|
+  changes = subscription.saved_changes.keys
+  notify("Payment on hold") if changes.include?("status") && subscription.on_hold?
+end
+
+Tillbell.on(:subscription_expired) do |subscription|
+  notify("Subscription ended") unless subscription.replaced?   # not a plan change
+end
+```
+
 Events go through Pay's webhook delegator, so `Pay::Webhooks.delegator.subscribe "tillbell.subscription_created", MyHandler.new` works too. An event fires once per actual change, after the subscription is saved. An error raised in a callback is reported to `Rails.error` and does not undo the change.
 
 ## Google Play setup

data/app/helpers/tillbell/paywall_helper.rb

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

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

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

data/lib/tillbell/google_play.rb

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

data/lib/tillbell/version.rb

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

data/lib/tillbell.rb

@@ -47,7 +47,25 @@ module Tillbell
   # +subscribed?(name:)+ look subscriptions up by name, "default" unless you change it.
   mattr_accessor :subscription_name, default: ->(product_id:, base_plan_id:) { Pay.default_product_name }
 
+  # What Hotwire Native writes in the user agent for the bridge components the app
+  # registered, e.g. "bridge-components: [haptic tillbell]". +tillbell+ must be in that
+  # list for the paywall to work.
+  NATIVE_USER_AGENT = /bridge-components: \[(?:[^\]]*\s)?tillbell[\s\]]/
+
   class << self
+    # True when +user_agent+ comes from a native app that registered the +tillbell+ bridge
+    # component (Android today, iOS later), so a Google Play purchase can start from the
+    # page. Use it to choose between the paywall and another way to pay, e.g. a web checkout:
+    #
+    #   Tillbell.native?(request.user_agent)
+    #
+    # An app version without the component, and every browser, answer false. The check
+    # only picks which page to show: purchases are always verified with Google, so a
+    # forged user agent gains nothing.
+    def native?(user_agent)
+      NATIVE_USER_AGENT.match?(user_agent.to_s)
+    end
+
     # Yields the Tillbell module so settings can be assigned in a block.
     def configure
       yield self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tillbell
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Pierre Filstroff