tillbell 0.1.0

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

@@ -0,0 +1,52 @@
+module Pay
+  module GooglePlay
+    # The Pay customer behind every Google Play purchase of an owner.
+    #
+    # Its +processor_id+ is a random UUID sent to Google as +obfuscatedAccountId+ when a
+    # purchase starts. Google returns it with every purchase, which is how Tillbell knows
+    # which owner a purchase token belongs to. It never contains an e-mail or a database
+    # id, and the same value can later be reused as an App Store +appAccountToken+.
+    #
+    # The customer is added next to the owner's other Pay customers (Stripe, ...) without
+    # becoming their default payment processor.
+    class Customer < Pay::Customer
+      has_many :subscriptions, dependent: :destroy, class_name: "Pay::GooglePlay::Subscription"
+
+      before_validation :generate_processor_id, on: :create
+
+      # Returns the Google Play customer of +owner+, creating it on first use.
+      # +owner+ is any model declaring +pay_customer+.
+      def self.for(owner)
+        owner.add_payment_processor(:google_play)
+      end
+
+      # Google Play customers exist only in this database.
+      def api_record
+        self
+      end
+
+      def update_api_record(**)
+        self
+      end
+
+      # Store purchases always start in the native app, never on the server.
+      def subscribe(**)
+        raise Tillbell::Error, "Google Play subscriptions are purchased in the Android app, through the Tillbell paywall"
+      end
+
+      def charge(*)
+        raise Tillbell::Error, "Google Play does not support server-side charges"
+      end
+
+      def add_payment_method(*, **)
+        raise Tillbell::Error, "Google Play manages payment methods in the Play Store"
+      end
+
+      private
+        def generate_processor_id
+          self.processor ||= "google_play"
+          self.processor_id ||= SecureRandom.uuid
+        end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+module Pay
+  module GooglePlay
+    # A Google Play subscription, stored as a Pay subscription.
+    #
+    # Columns hold the same meaning as for any other Pay processor:
+    #
+    # [processor_id] The Google purchase token.
+    # [processor_plan] The Google product id (the subscription id in the Play Console).
+    # [status] A Pay status, mapped from Google's state by STATUSES.
+    # [ends_at] Set once the subscription is canceled, expired or revoked.
+    # [object] The last response of the Google Play Developer API, for debugging.
+    #
+    # Google-specific details live in +data+: the raw +subscription_state+, the
+    # +base_plan_id+, +auto_renewing+ and +revoked_at+.
+    #
+    # Because statuses use Pay's vocabulary, Pay helpers behave exactly as they do for
+    # Stripe: +active?+, +past_due?+, +on_grace_period?+, +Pay::Subscription.active+, ...
+    class Subscription < Pay::Subscription
+      # Google +subscriptionState+ => Pay status.
+      #
+      # * In grace period, Google requires the customer to keep access, so it maps to
+      #   "active". Use +in_grace_period?+ to show a "fix your payment" banner.
+      # * Canceled means "will not renew": access continues until +ends_at+, which is how
+      #   Pay represents a canceled subscription that is still valid.
+      # * On hold means the payment failed after the grace period; access is suspended
+      #   while Google retries, like a Stripe "past_due" subscription.
+      #
+      # See https://developer.android.com/google/play/billing/lifecycle/subscriptions
+      STATUSES = {
+        "SUBSCRIPTION_STATE_PENDING" => "incomplete",
+        "SUBSCRIPTION_STATE_ACTIVE" => "active",
+        "SUBSCRIPTION_STATE_IN_GRACE_PERIOD" => "active",
+        "SUBSCRIPTION_STATE_ON_HOLD" => "past_due",
+        "SUBSCRIPTION_STATE_PAUSED" => "paused",
+        "SUBSCRIPTION_STATE_CANCELED" => "active",
+        "SUBSCRIPTION_STATE_EXPIRED" => "canceled",
+        "SUBSCRIPTION_STATE_PENDING_PURCHASE_CANCELED" => "incomplete_expired"
+      }.freeze
+
+      # 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
+
+      class << self
+        # Reads a purchase from Google (unless +object+ is given), saves it and emits the
+        # matching Tillbell event. Safe to call any number of times, in any order: the
+        # result only depends on Google's current state, and an event fires only when
+        # something changed.
+        #
+        # +revoked+ tells that Google refunded the purchase, which the API response alone
+        # does not distinguish from a normal expiry.
+        #
+        # Returns the subscription, or nil when the purchase was not made through Tillbell
+        # (no known +obfuscatedAccountId+).
+        def sync(purchase_token, object: nil, revoked: false)
+          object ||= Tillbell::GooglePlay.subscription(purchase_token)
+
+          pay_customer = Pay::GooglePlay::Customer.find_by(processor_id: Tillbell::GooglePlay.account_id(object))
+          if pay_customer.nil?
+            Rails.logger.warn "[Tillbell] Ignoring Google Play purchase #{Tillbell.redact(purchase_token)}: unknown account"
+            return
+          end
+
+          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])
+          acknowledge(subscription, object)
+          subscription
+        end
+
+        # Maps a +subscriptionsv2+ response to subscription attributes. Pure function, no I/O.
+        def attributes_from(object, revoked: false)
+          state = object[:subscription_state]
+          line_item = object[:line_items].max_by { |item| item[:expiry_time].to_s }
+          product_id = line_item[:product_id]
+          base_plan_id = line_item.dig(:offer_details, :base_plan_id)
+          expires_at = line_item[:expiry_time]&.then { |time| Time.zone.parse(time) }
+
+          attributes = {
+            name: Tillbell.subscription_name.call(product_id: product_id, base_plan_id: base_plan_id),
+            processor_plan: product_id,
+            status: STATUSES.fetch(state) { raise Tillbell::Error, "Unknown Google Play subscription state #{state.inspect}" },
+            current_period_end: expires_at,
+            ends_at: (expires_at if ENDING_STATES.include?(state)),
+            object: object,
+            subscription_state: state,
+            base_plan_id: base_plan_id,
+            auto_renewing: line_item.dig(:auto_renewing_plan, :auto_renew_enabled) || false
+          }
+          attributes.merge!(status: "canceled", ends_at: Time.current, revoked_at: Time.current.iso8601) if revoked
+          attributes
+        end
+
+        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
+          # request and notification) serialize on the lock, so only one emits the event.
+          def save_from_google(pay_customer, purchase_token, attributes)
+            attempts = 0
+            begin
+              # A savepoint, so a failed insert never breaks a transaction the caller opened.
+              transaction(requires_new: true) do
+                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)
+
+                event = subscription.event_for_changes
+                subscription.save!
+                [ subscription, event ]
+              end
+            rescue ActiveRecord::RecordNotUnique
+              # Another process inserted the row first; a second attempt finds it and locks it.
+              attempts += 1
+              attempts == 1 ? retry : raise
+            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)
+            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)
+              Tillbell.instrument(:subscription_expired, subscription)
+            end
+          end
+
+          # Acknowledges the purchase once it grants access. The native app never does it.
+          def acknowledge(subscription, object)
+            return unless object[:acknowledgement_state] == "ACKNOWLEDGEMENT_STATE_PENDING" && subscription.active?
+
+            Tillbell::GooglePlay.acknowledge(subscription.processor_plan, subscription.processor_id)
+          end
+      end
+
+      # The Tillbell event that describes the pending changes, or nil when nothing a host
+      # app cares about changed. Called before saving.
+      def event_for_changes
+        return :subscription_created if new_record?
+        return if (changed - %w[object updated_at]).none?
+        return :subscription_revoked if revoked_at_changed?
+        return :subscription_expired if status_changed? && status == "canceled"
+        return :subscription_canceled if ends_at_changed? && ends_at.present? && status == "active"
+
+        :subscription_updated
+      end
+
+      # True while Google retries a failed payment and the customer keeps access.
+      def in_grace_period?
+        subscription_state == "SUBSCRIPTION_STATE_IN_GRACE_PERIOD"
+      end
+
+      # True when the payment failed after the grace period and access is suspended.
+      def on_hold?
+        subscription_state == "SUBSCRIPTION_STATE_ON_HOLD"
+      end
+
+      # True when Google refunded the purchase.
+      def revoked?
+        revoked_at.present?
+      end
+
+      def paused?
+        status == "paused"
+      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.
+      def cancel(**)
+        Tillbell::GooglePlay.cancel(processor_plan, processor_id) if auto_renewing
+        sync!
+      end
+
+      # Google can only end a subscription immediately by refunding it, which Tillbell
+      # never does on its own. This stops the renewal instead, so deleting an owner (Pay
+      # calls +cancel_now!+ then) never leaves a subscription billing forever.
+      def cancel_now!(**)
+        cancel
+      end
+
+      # Plan changes, pauses and resumes happen in the app (plan change through the
+      # paywall) or in the Play Store.
+      %i[swap pause resume change_quantity].each do |method_name|
+        define_method(method_name) do |*, **|
+          raise Tillbell::Error, "Google Play subscriptions cannot #{method_name} from the server; use the app or the Play Store"
+        end
+      end
+    end
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,16 @@
+# Texts of the paywall. Override any of them in your app's locale files.
+en:
+  tillbell:
+    paywall:
+      submit: "Subscribe"
+      restore: "Restore purchases"
+      manage: "Manage subscription"
+      fallback: "Subscriptions are available in the latest version of the Android app."
+      # Status messages shown by the Stimulus controller.
+      messages:
+        verifying: "We are checking your purchase. This can take a few minutes."
+        pending: "Your payment is pending. Your subscription starts as soon as it is confirmed."
+        unavailable: "Google Play billing is not available on this device."
+        nothing_to_restore: "No purchase to restore."
+        rejected: "This purchase belongs to another account."
+        error: "Something went wrong. Please try again."

data/config/routes.rb

@@ -0,0 +1,7 @@
+Tillbell::Engine.routes.draw do
+  # Called by the paywall with the purchase token returned by the native app.
+  resources :purchases, only: :create
+
+  # Pub/Sub push endpoint for Google Play real-time developer notifications.
+  post "notifications/google_play", to: "notifications#create", as: :google_play_notifications
+end

data/contract/examples/manage.request.json

@@ -0,0 +1,3 @@
+{
+  "productId": "premium"
+}

data/contract/examples/products.reply.ok.json

@@ -0,0 +1,15 @@
+{
+  "result": "ok",
+  "products": [
+    {
+      "productId": "premium",
+      "basePlanId": "monthly",
+      "formattedPrice": "€4.99"
+    },
+    {
+      "productId": "premium",
+      "basePlanId": "yearly",
+      "formattedPrice": "€49.99"
+    }
+  ]
+}

data/contract/examples/products.reply.unavailable.json

@@ -0,0 +1,4 @@
+{
+  "result": "unavailable",
+  "message": "BILLING_UNAVAILABLE"
+}

data/contract/examples/products.request.json

@@ -0,0 +1,15 @@
+{
+  "products": [
+    {
+      "productId": "premium",
+      "basePlanId": "monthly"
+    },
+    {
+      "productId": "premium",
+      "basePlanId": "yearly"
+    }
+  ],
+  "metadata": {
+    "url": "https://example.com/paywall"
+  }
+}

data/contract/examples/purchase.reply.already_owned.json

@@ -0,0 +1,3 @@
+{
+  "result": "already_owned"
+}

data/contract/examples/purchase.reply.canceled.json

@@ -0,0 +1,3 @@
+{
+  "result": "canceled"
+}

data/contract/examples/purchase.reply.error.json

@@ -0,0 +1,4 @@
+{
+  "result": "error",
+  "message": "DEVELOPER_ERROR"
+}

data/contract/examples/purchase.reply.pending.json

@@ -0,0 +1,5 @@
+{
+  "result": "pending",
+  "productId": "premium",
+  "purchaseToken": "purchase-token"
+}

data/contract/examples/purchase.reply.purchased.json

@@ -0,0 +1,5 @@
+{
+  "result": "purchased",
+  "productId": "premium",
+  "purchaseToken": "purchase-token"
+}

data/contract/examples/purchase.reply.unavailable.json

@@ -0,0 +1,3 @@
+{
+  "result": "unavailable"
+}

data/contract/examples/purchase.request.json

@@ -0,0 +1,8 @@
+{
+  "productId": "premium",
+  "basePlanId": "monthly",
+  "obfuscatedAccountId": "6f1c2a8e-3b7d-4e59-9a0c-2d4f8b1e7c35",
+  "metadata": {
+    "url": "https://example.com/paywall"
+  }
+}

data/contract/examples/purchase.request.plan_change.json

@@ -0,0 +1,7 @@
+{
+  "productId": "premium",
+  "basePlanId": "yearly",
+  "obfuscatedAccountId": "6f1c2a8e-3b7d-4e59-9a0c-2d4f8b1e7c35",
+  "oldPurchaseToken": "old-purchase-token",
+  "replacementMode": "CHARGE_PRORATED_PRICE"
+}

data/contract/examples/restore.reply.empty.json

@@ -0,0 +1,4 @@
+{
+  "result": "ok",
+  "purchases": []
+}

data/contract/examples/restore.reply.ok.json

@@ -0,0 +1,9 @@
+{
+  "result": "ok",
+  "purchases": [
+    {
+      "productId": "premium",
+      "purchaseToken": "purchase-token"
+    }
+  ]
+}

data/contract/examples/restore.request.json

@@ -0,0 +1,5 @@
+{
+  "metadata": {
+    "url": "https://example.com/paywall"
+  }
+}

data/contract/manage.request.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/pmakerhq/tillbell-rails/blob/main/contract/manage.request.json",
+  "title": "manage (page to native)",
+  "description": "Opens the Play Store subscription page (https://play.google.com/store/account/subscriptions, with sku and package when productId is set). No reply.",
+  "type": "object",
+  "required": [
+    "productId"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "productId": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Added by @hotwired/hotwire-native-bridge to every message sent by the page.",
+      "properties": {
+        "url": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

data/contract/products.reply.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/pmakerhq/tillbell-rails/blob/main/contract/products.reply.json",
+  "title": "products (native to page)",
+  "description": "Plans known to Google Play, with the price formatted for the customer's locale. Plans missing from the list cannot be bought.",
+  "type": "object",
+  "required": [
+    "result"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "result": {
+      "enum": [
+        "ok",
+        "unavailable",
+        "error"
+      ],
+      "description": "unavailable: Google Play billing cannot be used on this device."
+    },
+    "products": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "productId",
+          "basePlanId",
+          "formattedPrice"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "productId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Google Play product id (subscription id)."
+          },
+          "basePlanId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Google Play base plan id, or null for the product's only base plan."
+          },
+          "formattedPrice": {
+            "type": "string",
+            "minLength": 1,
+            "description": "ProductDetails formattedPrice of the base plan's regular pricing phase, e.g. \"\u20ac4.99\"."
+          }
+        }
+      }
+    },
+    "message": {
+      "type": "string",
+      "description": "Developer-facing detail, never shown to the customer."
+    }
+  },
+  "if": {
+    "properties": {
+      "result": {
+        "const": "ok"
+      }
+    }
+  },
+  "then": {
+    "required": [
+      "products"
+    ]
+  }
+}

data/contract/products.request.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/pmakerhq/tillbell-rails/blob/main/contract/products.request.json",
+  "title": "products (page to native)",
+  "description": "Asks the native app for the localized price of each plan shown by the paywall.",
+  "type": "object",
+  "required": [
+    "products"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "products": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "productId",
+          "basePlanId"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "productId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Google Play product id (subscription id)."
+          },
+          "basePlanId": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Google Play base plan id, or null for the product's only base plan."
+          }
+        }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Added by @hotwired/hotwire-native-bridge to every message sent by the page.",
+      "properties": {
+        "url": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

data/contract/purchase.reply.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/pmakerhq/tillbell-rails/blob/main/contract/purchase.reply.json",
+  "title": "purchase (native to page)",
+  "description": "Outcome of the purchase sheet. The native app never acknowledges the purchase: the server does after verifying it.",
+  "type": "object",
+  "required": [
+    "result"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "result": {
+      "enum": [
+        "purchased",
+        "pending",
+        "canceled",
+        "already_owned",
+        "unavailable",
+        "error"
+      ],
+      "description": "purchased: Purchase.PurchaseState.PURCHASED. pending: PurchaseState.PENDING (e.g. cash payment). canceled: USER_CANCELED. already_owned: ITEM_ALREADY_OWNED. unavailable: BILLING_UNAVAILABLE, SERVICE_UNAVAILABLE or FEATURE_NOT_SUPPORTED. error: anything else."
+    },
+    "productId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Google Play product id (subscription id)."
+    },
+    "purchaseToken": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Purchase.getPurchaseToken()."
+    },
+    "message": {
+      "type": "string",
+      "description": "Developer-facing detail, never shown to the customer."
+    }
+  },
+  "if": {
+    "properties": {
+      "result": {
+        "enum": [
+          "purchased",
+          "pending"
+        ]
+      }
+    }
+  },
+  "then": {
+    "required": [
+      "productId",
+      "purchaseToken"
+    ]
+  }
+}

data/contract/purchase.request.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/pmakerhq/tillbell-rails/blob/main/contract/purchase.request.json",
+  "title": "purchase (page to native)",
+  "description": "Opens the Google Play purchase sheet. With oldPurchaseToken, the purchase replaces an existing subscription (plan change).",
+  "type": "object",
+  "required": [
+    "productId",
+    "basePlanId",
+    "obfuscatedAccountId"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "productId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Google Play product id (subscription id)."
+    },
+    "basePlanId": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Google Play base plan id, or null for the product's only base plan."
+    },
+    "obfuscatedAccountId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Pass unchanged to BillingFlowParams.Builder.setObfuscatedAccountId. Generated by the server; never derive it on the device."
+    },
+    "oldPurchaseToken": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Purchase token of the subscription being replaced (SubscriptionUpdateParams.Builder.setOldPurchaseToken)."
+    },
+    "replacementMode": {
+      "enum": [
+        "WITH_TIME_PRORATION",
+        "CHARGE_PRORATED_PRICE",
+        "WITHOUT_PRORATION",
+        "CHARGE_FULL_PRICE",
+        "DEFERRED"
+      ],
+      "description": "SubscriptionUpdateParams.ReplacementMode, chosen by the server and passed through."
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Added by @hotwired/hotwire-native-bridge to every message sent by the page.",
+      "properties": {
+        "url": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "dependentRequired": {
+    "oldPurchaseToken": [
+      "replacementMode"
+    ],
+    "replacementMode": [
+      "oldPurchaseToken"
+    ]
+  }
+}