tillbell 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e2e56c0874935103736d6f90d868ec525033d4abe32437269b39ea2772d224b
-  data.tar.gz: dde35b5c71bee8fee12aef4ba5fd99c5870d034da7150a8fbcaea55d4dfc5a6c
+  metadata.gz: 74b959f39549f19cfaad92af9562bd42d373435241e4d3062ec587b8a3fdae69
+  data.tar.gz: c4ed0fcb129893703dbdb273716edb439f312bd88af66062b53eebdaca22bfb9
 SHA512:
-  metadata.gz: c951a6879b9603ae4202f731714c2568381f7761d5a86b96fe7566df3e79e7d9c334faf82936582e7f27bb9151f4d614e875c65f725fc99f72f9b133296e3e0d
-  data.tar.gz: fe33d1a43adf91d7a8efdfdad0bbd5acba86536cdcaab1fdf265f6b22491eb3963f9e1029094adc639bf40add424afa360ac6b7666deeda9059a64f43b0ea90e
+  metadata.gz: cffefbca74044761044ef78a5b1f8dddea337106f14a23e5fd61c9339c1ce1de023c092f57b9ec27359f32efd0a8daf7598a4c2be4bc5ee43e7fa23256bca38d
+  data.tar.gz: ec89c1e8edfd610c70510e51b8b9dc5a20e52f5d0c78c58541dafc5c601b3f49a43072f214a9f60e1b71067aae8d510ac7216935793543adbd6bdf8ed019e274

data/CHANGELOG.md

@@ -6,6 +6,23 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-11-02
+
+### Added
+
+- `grants_access?` on every Pay subscription: it bills and is not paused, and a Google Play
+  subscription on hold gives no access (Google requires it), while a Stripe payment being
+  retried does.
+- `Pay::GooglePlay::Subscription#owned?`: Google still counts the purchase as the customer's
+  (a paused subscription and a pending purchase included), so a new purchase would be answered
+  `ALREADY_OWNED`.
+- `Tillbell::GooglePlay.store_url`: the Play Store page of the app.
+
+### Changed
+
+- README: an "Upgrading" section, starting with 0.4. Documentation comments on `google_play?` (subscriptions),
+  `Tillbell::GooglePlay.package_name` and `reset!`.
+
 ## [0.4.0] - 2026-10-30
 
 ### Added

data/README.md

@@ -23,6 +23,7 @@ subscription.active?                     # same rules as for Stripe
 - [How it works](#how-it-works)
 - [Requirements](#requirements)
 - [Installation](#installation)
+- [Upgrading](#upgrading)
 - [Configuration](#configuration)
 - [The paywall](#the-paywall)
 - [Subscriptions and statuses](#subscriptions-and-statuses)
@@ -157,6 +158,31 @@ class User < ApplicationRecord
 end
 ```
 
+## Upgrading
+
+Every release is listed in the [CHANGELOG](CHANGELOG.md). No release so far has added a migration.
+
+### To 0.4
+
+Nothing is required, but one behavior changes: `cancel` and `cancel_now!` on a Google Play subscription 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`. Code that rescued the Google errors around a cancellation, to close or delete an account for example, must rescue `Pay::Error`, which also covers Stripe:
+
+```ruby
+begin
+  user.cancel_billing_subscriptions!
+rescue Pay::Error => error
+  # Stripe or Google Play refused: keep the account open and say why
+end
+```
+
+Then, to drop the code you wrote around the gem:
+
+- `include Tillbell::Owner` in your Pay customer model for `current_subscription`, `google_play_subscription`, `google_play_on_hold?`, `billing_subscriptions` and `cancel_billing_subscriptions!`;
+- declare the plans you sell in `config.plans`: `tillbell:check` verifies them without `PLANS`, and `paywall.plan_change` chooses the replacement mode from their order;
+- subscribe to `plan_changed`, `payment_failed`, `payment_recovered` and `subscription_renewed` instead of reading `saved_changes` in `subscription_updated`;
+- send `subscription.token_digest` to analytics instead of hashing the purchase token yourself.
+
+The existing events are unchanged. The paywall texts now exist in French, Spanish and German: if your app set `config.i18n.available_locales`, add the ones you want.
+
 ## Configuration
 
 ```ruby
@@ -295,7 +321,8 @@ A `Pay::GooglePlay::Subscription` stores:
 | `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. |
+| `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. `Tillbell::GooglePlay.store_url` is the page of the app itself, for a "Get it on Google Play" link. |
+| `owned?` | Whether Google still counts the purchase as the customer's, even without access: a paused subscription or a pending purchase (a cash payment) too. Buying the same product again would be answered `ALREADY_OWNED`, so show `manage_url` instead of a paywall. False once refunded, replaced or expired. |
 | `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:
@@ -334,6 +361,12 @@ A plan change from the settings page is then one option in a paywall:
 | `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. |
 
+**Who has access.** `subscription.grants_access?`, on every Pay subscription, is true when it bills (`billing?`) and is not paused. A payment the processor retries keeps access, so the customer can reach the page where they fix it, except on Google Play: a subscription on hold comes after Google's grace period, and Google requires access to be suspended until the payment succeeds.
+
+```ruby
+def subscribed? = !!current_user.current_subscription&.grants_access?
+```
+
 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`).

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

@@ -45,6 +45,14 @@ module Pay
       # 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
 
+      # Google states in which the purchase still belongs to the customer (see +owned?+): every
+      # state but an expiry and a pending purchase that was canceled. A whitelist, so an unknown
+      # or missing state (a row older than the state column) never blocks a new purchase.
+      OWNED_STATES = %w[
+        SUBSCRIPTION_STATE_PENDING SUBSCRIPTION_STATE_ACTIVE SUBSCRIPTION_STATE_IN_GRACE_PERIOD
+        SUBSCRIPTION_STATE_ON_HOLD SUBSCRIPTION_STATE_PAUSED SUBSCRIPTION_STATE_CANCELED
+      ].freeze
+
       store_accessor :data, :subscription_state, :base_plan_id, :auto_renewing, :revoked_at, :replaced_by
 
       class << self
@@ -199,6 +207,16 @@ module Pay
         status == "paused"
       end
 
+      # True while Google still counts the purchase as the customer's: buying the same product
+      # again would be answered +ALREADY_OWNED+, so offer +manage_url+ rather than a paywall. It
+      # covers states that give no access (see +grants_access?+): a paused subscription resumes
+      # by itself and a pending purchase (a cash payment) completes or lapses at Google. A
+      # refunded, replaced or expired purchase is no longer owned, whatever Google still reports
+      # for its token.
+      def owned?
+        !revoked? && !replaced? && OWNED_STATES.include?(subscription_state)
+      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

data/lib/tillbell/engine.rb

@@ -36,8 +36,20 @@ module Tillbell
           !ended? && (active? || past_due? || unpaid? || paused?)
         end
 
+        # True when the subscription should give access to what it pays for: it bills
+        # (+billing?+) and is not paused. A payment the processor retries keeps access, so the
+        # customer can still reach the page where they fix it, except on Google Play: a
+        # subscription on hold (past_due) comes after Google's grace period, and Google requires
+        # access to be suspended until the payment succeeds. Combine it with
+        # +Tillbell::Owner#current_subscription+ to decide what an owner may use.
+        def grants_access?
+          billing? && !paused? && !(google_play? && past_due?)
+        end
+
         scope :google_play, -> { joins(:customer).where(pay_customers: { processor: "google_play" }) }
 
+        # True for a subscription bought with Google Play, whatever the owner's default
+        # processor is.
         def google_play?
           customer.processor == "google_play"
         end

data/lib/tillbell/google_play.rb

@@ -96,6 +96,14 @@ module Tillbell
         "#{page}?sku=#{ERB::Util.url_encode(product_id)}&package=#{ERB::Util.url_encode(package_name)}"
       end
 
+      # The Play Store page of the app itself (+config.google.package_name+), for a "Get it on
+      # Google Play" link on the website.
+      def store_url
+        "https://play.google.com/store/apps/details?id=#{ERB::Util.url_encode(package_name)}"
+      end
+
+      # The Android package name Google Play knows the app by, from +config.google.package_name+.
+      # Raises +Tillbell::Error+ when it is not set.
       def package_name
         Tillbell.google.package_name.presence || raise(Error, "Tillbell.google.package_name is not set")
       end
@@ -109,6 +117,7 @@ module Tillbell
         end
       end
 
+      # Forgets the memoized client so the next call builds it from the current credentials.
       def reset!
         @service = nil
       end

data/lib/tillbell/version.rb

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

metadata

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