tillbell 0.1.0

data/contract/restore.reply.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/pmakerhq/tillbell-rails/blob/main/contract/restore.reply.json",
+  "title": "restore (native to page)",
+  "description": "Subscription purchases of the device's Google account. The page posts each token to the server.",
+  "type": "object",
+  "required": [
+    "result"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "result": {
+      "enum": [
+        "ok",
+        "unavailable",
+        "error"
+      ]
+    },
+    "purchases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "productId",
+          "purchaseToken"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "productId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Google Play product id (subscription id)."
+          },
+          "purchaseToken": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "message": {
+      "type": "string",
+      "description": "Developer-facing detail, never shown to the customer."
+    }
+  },
+  "if": {
+    "properties": {
+      "result": {
+        "const": "ok"
+      }
+    }
+  },
+  "then": {
+    "required": [
+      "purchases"
+    ]
+  }
+}

data/contract/restore.request.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/pmakerhq/tillbell-rails/blob/main/contract/restore.request.json",
+  "title": "restore (page to native)",
+  "description": "Asks the native app for the subscriptions Google Play reports for the device's Google account (queryPurchasesAsync).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "description": "Added by @hotwired/hotwire-native-bridge to every message sent by the page.",
+      "properties": {
+        "url": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

data/lib/generators/tillbell/install/install_generator.rb

@@ -0,0 +1,34 @@
+module Tillbell
+  module Generators
+    # Sets Tillbell up in a Rails app: +rails generate tillbell:install+.
+    #
+    # Tillbell stores everything in Pay's tables, so there is no migration to copy.
+    # Run Pay's own installation first if the app does not use Pay yet.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the Tillbell initializer, mounts the engine and copies the paywall Stimulus controller."
+
+      def create_initializer
+        copy_file "initializer.rb", "config/initializers/tillbell.rb"
+      end
+
+      def mount_engine
+        route 'mount Tillbell::Engine, at: "/tillbell"'
+      end
+
+      def copy_stimulus_controller
+        copy_file "tillbell_controller.js", "app/javascript/controllers/tillbell_controller.js"
+      end
+
+      def install_bridge_package
+        if File.exist?(File.join(destination_root, "config/importmap.rb"))
+          run "bin/importmap pin @hotwired/hotwire-native-bridge"
+        else
+          say "Add the Hotwire Native bridge to your JavaScript dependencies: " \
+            "npm install @hotwired/hotwire-native-bridge", :yellow
+        end
+      end
+    end
+  end
+end

data/lib/generators/tillbell/install/templates/initializer.rb

@@ -0,0 +1,33 @@
+# Tillbell: Google Play subscriptions stored as Pay subscriptions.
+# See https://github.com/pmakerhq/tillbell-rails#configuration
+Tillbell.configure do |config|
+  # Application id of the Android app.
+  config.google.package_name = "com.example.app"
+
+  # JSON key of a Google Cloud service account invited in the Play Console with the
+  # "View financial data" and "Manage orders and subscriptions" permissions.
+  config.google.service_account_json = Rails.application.credentials.dig(:tillbell, :google_service_account)
+
+  # Service account the Pub/Sub push subscription authenticates with.
+  config.google.pubsub_service_account_email = Rails.application.credentials.dig(:tillbell, :pubsub_service_account_email)
+
+  # Audience of the Pub/Sub OIDC token, if it is not the notification endpoint URL.
+  # config.google.pubsub_audience = "https://example.com/tillbell/notifications/google_play"
+
+  # Who is buying. Evaluated in the controller and the view of the paywall.
+  # config.current_owner = -> { current_user }
+
+  # Controller the purchase endpoint inherits from (authentication, CSRF, ...).
+  # config.parent_controller = "ApplicationController"
+
+  # Pay subscription name of a Google Play product, as used by `subscribed?(name:)`.
+  # config.subscription_name = ->(product_id:, base_plan_id:) { Pay.default_product_name }
+
+  # React to subscription changes. Each block receives the Pay::GooglePlay::Subscription.
+  # config.on(:subscription_created) { |subscription| }
+  # config.on(:subscription_updated) { |subscription| }
+  # config.on(:subscription_canceled) { |subscription| }
+  # config.on(:subscription_expired) { |subscription| }
+  # config.on(:subscription_revoked) { |subscription| }
+  # config.on(:purchase_rejected) { |details| } # a token posted by another account
+end

data/lib/generators/tillbell/install/templates/tillbell_controller.js

@@ -0,0 +1,147 @@
+// Tillbell paywall controller, copied into your app by `rails generate tillbell:install`.
+// It is yours now: change it as you like. The messages it exchanges with the native app
+// are documented in docs/bridge-contract.md of the tillbell gem.
+//
+// The controller only connects inside a Hotwire Native app that registers the
+// "tillbell" bridge component. Everywhere else the paywall keeps its buttons disabled
+// and shows its fallback, so a purchase can never start without the native app.
+//
+// Events dispatched on the paywall element, for your own code to listen to:
+//   tillbell:verified  the purchase grants access. Cancel the event to stay on the page
+//                      instead of going to the success URL.
+//   tillbell:status    a status message is shown (detail: { key, message }).
+import { BridgeComponent } from "@hotwired/hotwire-native-bridge"
+
+export default class extends BridgeComponent {
+  static component = "tillbell"
+  static targets = ["plan", "price", "action", "status", "fallback"]
+  static values = { accountId: String, purchaseUrl: String, successUrl: String, messages: Object }
+
+  connect() {
+    super.connect()
+    this.fallbackTargets.forEach((element) => element.hidden = true)
+    this.loadPrices()
+  }
+
+  // Asks Google Play for the localized price of every plan, then enables the paywall.
+  loadPrices() {
+    const products = this.planTargets.map((plan) => this.#productOf(plan))
+
+    this.send("products", { products }, ({ data }) => {
+      if (data.result !== "ok") return this.#showStatus(data.result === "unavailable" ? "unavailable" : "error")
+
+      this.planTargets.forEach((plan) => {
+        const { productId, basePlanId } = this.#productOf(plan)
+        const product = data.products.find((p) => p.productId === productId && (p.basePlanId ?? null) === basePlanId)
+        const price = plan.closest("label")?.querySelector("[data-tillbell-target~='price']")
+
+        if (price && product) price.textContent = product.formattedPrice
+        plan.disabled = !product
+      })
+      this.#setBusy(false)
+    })
+  }
+
+  // Opens the Google Play purchase sheet for the checked plan.
+  purchase() {
+    const plan = this.planTargets.find((plan) => plan.checked && !plan.disabled)
+    if (!plan) return
+
+    const { oldPurchaseToken, replacementMode } = plan.dataset
+    const message = { ...this.#productOf(plan), obfuscatedAccountId: this.accountIdValue }
+    if (oldPurchaseToken) Object.assign(message, { oldPurchaseToken, replacementMode })
+
+    this.#setBusy(true)
+    this.send("purchase", message, ({ data }) => this.#handlePurchase(data))
+  }
+
+  // Records again the purchases Google Play knows for this device's account.
+  restorePurchases() {
+    this.#setBusy(true)
+    this.send("restore", {}, async ({ data }) => {
+      if (data.result !== "ok") return this.#fail(data.result === "unavailable" ? "unavailable" : "error")
+      if (data.purchases.length === 0) return this.#fail("nothing_to_restore")
+
+      const results = []
+      for (const { purchaseToken } of data.purchases) results.push(await this.#record(purchaseToken))
+      this.#finish(results.find((result) => result.active) ?? results[0])
+    })
+  }
+
+  // Opens the Play Store page where the customer manages the subscription.
+  manage() {
+    const plan = this.planTargets.find((plan) => plan.checked) ?? this.planTargets[0]
+    this.send("manage", { productId: plan ? plan.dataset.productId : null })
+  }
+
+  async #handlePurchase({ result, purchaseToken }) {
+    switch (result) {
+      case "purchased":
+      case "pending":
+        return this.#finish(await this.#record(purchaseToken))
+      case "already_owned":
+        return this.restorePurchases()
+      case "canceled":
+        return this.#setBusy(false)
+      case "unavailable":
+        return this.#fail("unavailable")
+      default:
+        return this.#fail("error")
+    }
+  }
+
+  // Sends the purchase token to Rails, which verifies it with Google.
+  async #record(purchaseToken) {
+    this.#showStatus("verifying")
+    try {
+      const response = await fetch(this.purchaseUrlValue, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Accept": "application/json",
+          "X-CSRF-Token": document.querySelector("meta[name='csrf-token']")?.content
+        },
+        body: JSON.stringify({ purchase_token: purchaseToken })
+      })
+      return await response.json()
+    } catch {
+      return { status: "error" }
+    }
+  }
+
+  #finish(body) {
+    if (body.status === "verified" && body.active) {
+      const event = this.dispatch("verified", { detail: body, cancelable: true })
+      event.defaultPrevented ? this.#setBusy(false) : this.#visit(this.successUrlValue)
+    } else if (body.status === "verified") {
+      this.#fail("pending")
+    } else if (body.status === "verifying" || body.status === "rejected") {
+      this.#fail(body.status)
+    } else {
+      this.#fail("error")
+    }
+  }
+
+  #fail(key) {
+    this.#showStatus(key)
+    this.#setBusy(false)
+  }
+
+  #showStatus(key) {
+    const message = this.messagesValue[key] ?? key
+    this.statusTargets.forEach((element) => element.textContent = message)
+    this.dispatch("status", { detail: { key, message } })
+  }
+
+  #setBusy(busy) {
+    this.actionTargets.forEach((element) => element.disabled = busy)
+  }
+
+  #productOf(plan) {
+    return { productId: plan.dataset.productId, basePlanId: plan.dataset.basePlanId ?? null }
+  }
+
+  #visit(url) {
+    window.Turbo ? window.Turbo.visit(url) : window.location.assign(url)
+  }
+}

data/lib/tillbell/engine.rb

@@ -0,0 +1,42 @@
+module Tillbell
+  # Mountable engine providing the purchase and notification endpoints, the paywall
+  # helper and the Pay processor models.
+  #
+  # Mount it in the host app's routes:
+  #
+  #   mount Tillbell::Engine, at: "/tillbell"
+  class Engine < ::Rails::Engine
+    isolate_namespace Tillbell
+
+    # Real-time developer notifications are verified, stored and queued by Pay (see
+    # Tillbell::NotificationsController). Once Pay's job processes one, Tillbell re-reads
+    # the subscription from Google.
+    initializer "tillbell.notifications" do
+      Pay::Webhooks.delegator.subscribe "google_play", ->(event) { Tillbell::GooglePlay.handle_notification(event) }
+    end
+
+    # Pay defines +stripe?+, +paddle_billing?+ and the matching scopes for its own
+    # processors only; this adds the same pair for Google Play.
+    initializer "tillbell.processor_helpers" do
+      ActiveSupport.on_load(:pay_customer) do
+        scope :google_play, -> { where(processor: "google_play") }
+
+        def google_play?
+          processor == "google_play"
+        end
+      end
+
+      ActiveSupport.on_load(:pay_subscription) do
+        scope :google_play, -> { joins(:customer).where(pay_customers: { processor: "google_play" }) }
+
+        def google_play?
+          customer.processor == "google_play"
+        end
+      end
+    end
+
+    initializer "tillbell.helpers" do
+      ActiveSupport.on_load(:action_view) { include Tillbell::PaywallHelper }
+    end
+  end
+end

data/lib/tillbell/google_play.rb

@@ -0,0 +1,110 @@
+require "google/apis/androidpublisher_v3"
+require "googleauth"
+
+module Tillbell
+  # Thin client over the Google Play Developer API (Android Publisher v3).
+  #
+  # Every method returns plain hashes with snake_case symbol keys, so the rest of the
+  # gem (and its specs) never deal with the Google client classes.
+  module GooglePlay
+    SCOPE = "https://www.googleapis.com/auth/androidpublisher".freeze
+
+    # Errors worth retrying later: rate limiting, Google server errors and network failures.
+    TRANSIENT_ERRORS = [ Google::Apis::RateLimitError, Google::Apis::ServerError, Google::Apis::TransmissionError ].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
+    # problems and must not be mistaken for an invalid purchase.
+    INVALID_TOKEN_STATUSES = [ 400, 404, 410 ].freeze
+
+    # +notificationType+ of a subscription notification sent when a purchase is refunded.
+    # See https://developer.android.com/google/play/billing/rtdn-reference
+    SUBSCRIPTION_REVOKED = 12
+
+    class << self
+      # Handles a real-time developer notification (the decoded Pub/Sub message).
+      #
+      # A notification is a trigger, never a source of truth: it only says which purchase
+      # changed, and the job reads the actual state from Google. This keeps duplicated or
+      # out-of-order notifications harmless.
+      def handle_notification(notification)
+        if (subscription = notification["subscriptionNotification"])
+          revoked = subscription["notificationType"] == SUBSCRIPTION_REVOKED
+          Tillbell::SyncJob.perform_later(subscription["purchaseToken"], revoked: revoked)
+        elsif (voided = notification["voidedPurchaseNotification"])
+          Tillbell::SyncJob.perform_later(voided["purchaseToken"], revoked: true)
+        end
+      end
+
+      # Fetches the current state of a subscription purchase (+purchases.subscriptionsv2.get+).
+      def subscription(purchase_token)
+        service.get_purchase_subscriptionsv2(package_name, purchase_token).to_h
+      end
+
+      # Acknowledges a subscription purchase. Google refunds purchases that are not
+      # acknowledged within three days.
+      def acknowledge(product_id, purchase_token)
+        service.acknowledge_purchase_subscription(package_name, product_id, purchase_token)
+      end
+
+      # Stops the renewal of a subscription. The customer keeps access until the end of
+      # the current period.
+      def cancel(product_id, purchase_token)
+        service.cancel_purchase_subscription(package_name, product_id, purchase_token)
+      end
+
+      # Verifies the OIDC token Pub/Sub sends with a push request and returns its claims.
+      # Raises +Tillbell::Error+ unless Google signed it for +audience+ on behalf of the
+      # configured service account.
+      def verify_pubsub_token!(token, audience:)
+        claims = Google::Auth::IDTokens.verify_oidc(token.to_s, aud: audience)
+        expected = Tillbell.google.pubsub_service_account_email
+        unless expected.present? && claims["email"] == expected && claims["email_verified"]
+          raise Error, "Pub/Sub token was not issued for the configured service account"
+        end
+
+        claims
+      rescue Google::Auth::IDTokens::VerificationError => error
+        raise Error, error.message
+      end
+
+      # True when +error+ means that the purchase token itself is invalid.
+      def invalid_token?(error)
+        error.is_a?(Google::Apis::ClientError) && INVALID_TOKEN_STATUSES.include?(error.status_code)
+      end
+
+      # The +obfuscatedAccountId+ the purchase was made with, i.e. the +processor_id+ of
+      # the Pay::GooglePlay::Customer it belongs to.
+      def account_id(subscription_purchase)
+        subscription_purchase.dig(:external_account_identifiers, :obfuscated_external_account_id)
+      end
+
+      def package_name
+        Tillbell.google.package_name.presence || raise(Error, "Tillbell.google.package_name is not set")
+      end
+
+      # Memoized API client. Clear it with +reset!+ after changing credentials.
+      def service
+        @service ||= Google::Apis::AndroidpublisherV3::AndroidPublisherService.new.tap do |service|
+          service.authorization = Google::Auth::ServiceAccountCredentials.make_creds(
+            json_key_io: StringIO.new(service_account_json), scope: SCOPE
+          )
+        end
+      end
+
+      def reset!
+        @service = nil
+      end
+
+      private
+        # Accepts the key as a JSON string or as a hash (e.g. from Rails credentials).
+        def service_account_json
+          json = Tillbell.google.service_account_json
+          raise Error, "Tillbell.google.service_account_json is not set" if json.blank?
+
+          json.is_a?(String) ? json : json.to_json
+        end
+    end
+  end
+end

data/lib/tillbell/version.rb

@@ -0,0 +1,3 @@
+module Tillbell
+  VERSION = "0.1.0"
+end

data/lib/tillbell.rb

@@ -0,0 +1,91 @@
+require "pay"
+require "tillbell/version"
+require "tillbell/engine"
+require "tillbell/google_play"
+
+# Tillbell adds Google Play subscriptions to Rails apps that use the Pay gem.
+#
+# Store subscriptions are regular Pay records (a +Pay::GooglePlay::Customer+ and its
+# +Pay::GooglePlay::Subscription+ rows), so they live next to Stripe or any other Pay
+# processor and every Pay helper (+pay_subscriptions.active+, +subscribed?+, ...) sees them.
+#
+# Configure it in an initializer:
+#
+#   Tillbell.configure do |config|
+#     config.google.package_name = "com.example.app"
+#     config.google.service_account_json = Rails.application.credentials.dig(:tillbell, :google)
+#     config.google.pubsub_service_account_email = "pubsub-push@example.iam.gserviceaccount.com"
+#
+#     config.on(:subscription_created) { |pay_subscription| ... }
+#   end
+module Tillbell
+  # Base class for every error raised by 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
+
+  # Google Play settings, see the README for where each value comes from.
+  #
+  # [package_name] Application id of the Android app, e.g. "com.example.app".
+  # [service_account_json] JSON key of a service account with access to the Play Console.
+  # [pubsub_service_account_email] Service account Pub/Sub signs its push requests with.
+  # [pubsub_audience] Audience of those requests; defaults to the notification endpoint URL.
+  mattr_accessor :google, default: ActiveSupport::OrderedOptions.new
+
+  # Returns the Pay owner (usually a User) the current request acts for, or nil.
+  # Evaluated with +instance_exec+ in the controller and in the view, so any helper
+  # available there (+current_user+, +Current.user+, ...) can be used.
+  mattr_accessor :current_owner, default: -> { current_user }
+
+  # Controller the purchase endpoint inherits from, so it gets the host app's
+  # authentication, CSRF protection and error handling.
+  mattr_accessor :parent_controller, default: "ApplicationController"
+
+  # Returns the Pay subscription +name+ for a Google Play product. Pay helpers such as
+  # +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 }
+
+  class << self
+    # Yields the Tillbell module so settings can be assigned in a block.
+    def configure
+      yield self
+    end
+
+    # Subscribes to a Tillbell event. The block receives the +Pay::GooglePlay::Subscription+
+    # (or, for +:purchase_rejected+, a hash describing the refused purchase).
+    #
+    # Events go through Pay's webhook delegator, so +Pay::Webhooks.delegator.subscribe
+    # "tillbell.subscription_created"+ works too.
+    def on(event, callable = nil, &block)
+      raise ArgumentError, "unknown Tillbell event #{event.inspect}" unless EVENTS.include?(event.to_sym)
+
+      Pay::Webhooks.delegator.subscribe("tillbell.#{event}", callable || block)
+    end
+
+    # Emits a Tillbell event. Errors raised by subscribers are reported to +Rails.error+
+    # instead of propagating: by the time an event fires, the subscription is already
+    # saved, and a failing callback must not turn a recorded purchase into an error.
+    def instrument(event, payload)
+      Pay::Webhooks.instrument(type: "tillbell.#{event}", event: payload)
+    rescue StandardError => error
+      Rails.error.report(error, handled: true, context: { tillbell_event: event })
+    end
+
+    # Paywall text +key+ (see config/locales/en.yml) in the current locale. A locale without
+    # the text, or with only part of the status messages, falls back to English instead of
+    # rendering a "translation missing" marker the Stimulus controller cannot parse.
+    def translate(key)
+      english = I18n.t("tillbell.paywall.#{key}", locale: :en)
+      localized = I18n.t("tillbell.paywall.#{key}", default: english)
+      english.is_a?(Hash) ? english.merge(localized) : localized
+    end
+
+    # Shortens a purchase token for logs: tokens grant access to a subscription and
+    # must never be written in full.
+    def redact(token)
+      token.to_s.first(8) + "..."
+    end
+  end
+end