purchasekit 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3aead88093b6325a3d7c6530a49999c88870fd7ce8c377923eafb3f42c14d490
+  data.tar.gz: 94921560fdf9ac5f393b0931a9c8f6b396ebea604c2c59bda694732bc90b0d4d
+SHA512:
+  metadata.gz: ce11f8ab3f94e75c62d843adc274dcc5d898ce08ffbd4cfc554d25a6150278fc2eb71f60ee1131d2d0e9756ab5a560805585dbc9a8be49c2e6c8f620dfefa9c7
+  data.tar.gz: eb6d567280bcfd93fe8dc07585acb0159a86b95b564be6f112f7368532fdaaeae349cd2d61608db783bddf966855bcf610e7adcccf0c9474e32567ee1f54a389

data/LICENSE

@@ -0,0 +1,31 @@
+PurchaseKit License
+
+Copyright (c) 2025 Joe Masilotti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and distribute the Software, subject to the following conditions:
+
+1. The Software may only be used in applications that actively integrate with
+   the official PurchaseKit service operated by the copyright holder
+   (https://purchasekit.dev or successor URLs). Use of the Software requires
+   a valid PurchaseKit account and active data transmission to PurchaseKit.
+
+2. The Software may not be used:
+   a. In any application that does not integrate with PurchaseKit, including
+      internal tools, personal projects, or proprietary systems.
+   b. To build, operate, or integrate with any competing in-app purchase
+      management service.
+   c. To create a self-hosted, forked, or alternative version of PurchaseKit.
+   d. As a standalone library independent of PurchaseKit.
+
+3. The above copyright notice and this permission notice shall be included
+   in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+# PurchaseKit
+
+In-app purchase webhooks for Rails. Receive normalized Apple and Google subscription events with a simple callback interface.
+
+## How it works
+
+```
+Native app (iOS/Android)
+    ↓ StoreKit/Play Billing
+App Store / Play Store
+    ↓ Server-to-server notifications
+PurchaseKit SaaS (normalizes Apple/Google data)
+    ↓ Webhooks
+Your Rails app (via this gem)
+    ↓ Callbacks or Pay::Subscription
+Your business logic
+```
+
+PurchaseKit handles the complexity of Apple and Google's different webhook formats, delivering you a consistent event payload regardless of which store the purchase came from.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "purchasekit"
+```
+
+Create an initializer:
+
+```ruby
+# config/initializers/purchasekit.rb
+PurchaseKit.configure do |config|
+  config.api_key = Rails.application.credentials.dig(:purchasekit, :api_key)
+  config.app_id = Rails.application.credentials.dig(:purchasekit, :app_id)
+  config.webhook_secret = Rails.application.credentials.dig(:purchasekit, :webhook_secret)
+end
+```
+
+Mount the engine in your routes:
+
+```ruby
+# config/routes.rb
+mount PurchaseKit::Engine, at: "/purchasekit"
+```
+
+Import the JavaScript:
+
+```javascript
+// app/javascript/application.js
+import "purchasekit/turbo_actions"
+
+// app/javascript/controllers/index.js
+eagerLoadControllersFrom("purchasekit", application)
+```
+
+## Pay gem integration
+
+If you use the [Pay gem](https://github.com/pay-rails/pay), PurchaseKit automatically detects it and handles everything:
+
+```ruby
+gem "pay"
+gem "purchasekit"
+```
+
+When Pay is detected, webhooks automatically create and update `Pay::Subscription` records and broadcast Turbo Stream redirects. No event callbacks needed.
+
+## Event callbacks (without Pay)
+
+If you're not using Pay, register callbacks to handle subscription events:
+
+```ruby
+# config/initializers/purchasekit.rb
+PurchaseKit.configure do |config|
+  # ... credentials ...
+
+  config.on(:subscription_created) do |event|
+    user = User.find(event.customer_id)
+    user.subscriptions.create!(
+      processor_id: event.subscription_id,
+      store: event.store,
+      status: event.status
+    )
+  end
+
+  config.on(:subscription_canceled) do |event|
+    subscription = Subscription.find_by(processor_id: event.subscription_id)
+    subscription&.update!(status: "canceled")
+  end
+
+  config.on(:subscription_expired) do |event|
+    subscription = Subscription.find_by(processor_id: event.subscription_id)
+    subscription&.update!(status: "expired")
+  end
+end
+```
+
+### Available events
+
+| Event | Description |
+|-------|-------------|
+| `:subscription_created` | New subscription started |
+| `:subscription_updated` | Subscription renewed or plan changed |
+| `:subscription_canceled` | User canceled (still active until `ends_at`) |
+| `:subscription_expired` | Subscription ended |
+
+### Event payload
+
+| Method | Description |
+|--------|-------------|
+| `event.customer_id` | Your user ID |
+| `event.subscription_id` | Store's subscription ID |
+| `event.store` | `"apple"` or `"google"` |
+| `event.store_product_id` | e.g., `"com.example.pro.annual"` |
+| `event.status` | `"active"`, `"canceled"`, `"expired"` |
+| `event.current_period_start` | Start of billing period |
+| `event.current_period_end` | End of billing period |
+| `event.ends_at` | When subscription will end |
+| `event.success_path` | Redirect path after purchase |
+
+## Paywall helper
+
+Build a paywall using the included helper:
+
+```erb
+<%= purchasekit_paywall customer_id: current_user.id, success_path: dashboard_path do |paywall| %>
+  <%= paywall.plan_option product: @annual, selected: true do %>
+    Annual - <%= paywall.price %>/year
+  <% end %>
+
+  <%= paywall.plan_option product: @monthly do %>
+    Monthly - <%= paywall.price %>/month
+  <% end %>
+
+  <%= paywall.submit "Subscribe" %>
+  <%= paywall.restore_link %>
+<% end %>
+```
+
+Products are fetched from the PurchaseKit API:
+
+```ruby
+@annual = PurchaseKit::Product.find("prod_XXXXXXXX")
+@monthly = PurchaseKit::Product.find("prod_YYYYYYYY")
+```
+
+## Demo mode
+
+For local development without a PurchaseKit account:
+
+```ruby
+PurchaseKit.configure do |config|
+  config.demo_mode = true
+  config.demo_products = {
+    "prod_annual" => { apple_product_id: "com.example.pro.annual" },
+    "prod_monthly" => { apple_product_id: "com.example.pro.monthly" }
+  }
+end
+```
+
+Works with Xcode's StoreKit local testing.
+
+## License
+
+This software is licensed under a custom PurchaseKit License. The gem may only be used in applications that actively integrate with the official PurchaseKit service at https://purchasekit.dev. See LICENSE for full details.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/app/controllers/purchase_kit/application_controller.rb

@@ -0,0 +1,5 @@
+module PurchaseKit
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end

data/app/controllers/purchase_kit/pay/application_controller.rb

@@ -0,0 +1,2 @@
+class PurchaseKit::Pay::ApplicationController < ActionController::Base
+end

data/app/controllers/purchase_kit/pay/purchase/completions_controller.rb

@@ -0,0 +1,32 @@
+class PurchaseKit::Pay::Purchase::CompletionsController < PurchaseKit::Pay::ApplicationController
+  include ActionView::RecordIdentifier
+  include Turbo::Streams::ActionHelper
+
+  skip_before_action :verify_authenticity_token
+
+  def create
+    unless PurchaseKit::Pay.config.demo_mode?
+      head :not_found
+      return
+    end
+
+    intent = PurchaseKit::Purchase::Intent::Demo.find(params[:intent_uuid])
+    customer = ::Pay::Customer.find(intent.customer_id)
+
+    customer.subscriptions.create!(
+      name: "default",
+      processor_id: "demo_#{SecureRandom.hex(12)}",
+      processor_plan: intent.product.apple_product_id,
+      status: "active",
+      quantity: 1
+    )
+
+    redirect_path = intent.success_path || "/"
+    Turbo::StreamsChannel.broadcast_stream_to(
+      dom_id(customer),
+      content: turbo_stream_action_tag(:redirect, url: redirect_path)
+    )
+
+    head :ok
+  end
+end

data/app/controllers/purchase_kit/pay/purchases_controller.rb

@@ -0,0 +1,34 @@
+class PurchaseKit::Pay::PurchasesController < PurchaseKit::Pay::ApplicationController
+  rescue_from PurchaseKit::Pay::SubscriptionRequiredError, with: :subscription_required
+
+  def create
+    @customer = ::Pay::Customer.find(params[:customer_id])
+
+    @intent = PurchaseKit::Purchase::Intent.create(
+      product_id: params[:product_id],
+      customer_id: @customer.id,
+      success_path: params[:success_path],
+      environment: params[:environment]
+    )
+
+    @xcode_completion_url = PurchaseKit::Pay.config.xcode_completion_url(intent_uuid: @intent.uuid, host: request.base_url)
+
+    respond_to do |format|
+      format.turbo_stream
+    end
+  end
+
+  private
+
+  def subscription_required(exception)
+    respond_to do |format|
+      format.turbo_stream do
+        render turbo_stream: turbo_stream.replace(
+          "purchasekit_paywall",
+          partial: "purchase_kit/pay/purchases/subscription_required",
+          locals: {message: exception.message}
+        )
+      end
+    end
+  end
+end

data/app/controllers/purchase_kit/pay/webhooks_controller.rb

@@ -0,0 +1,35 @@
+class PurchaseKit::Pay::WebhooksController < PurchaseKit::Pay::ApplicationController
+  skip_forgery_protection
+
+  def create
+    PurchaseKit::Pay::Webhook.queue(verified_event)
+    head :ok
+  rescue SignatureVerificationError => e
+    Rails.logger.error "[PurchaseKit] Webhook signature error: #{e.message}"
+    head :bad_request
+  end
+
+  private
+
+  def verified_event
+    payload = request.raw_post
+    signature = request.headers["X-PurchaseKit-Signature"]
+    secret = PurchaseKit::Pay.config.webhook_secret
+
+    if secret.blank?
+      raise SignatureVerificationError, "webhook_secret must be configured" if Rails.env.production?
+      return JSON.parse(payload, symbolize_names: true)
+    end
+
+    raise SignatureVerificationError, "Missing signature" if signature.blank?
+
+    expected = OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+    unless ActiveSupport::SecurityUtils.secure_compare(signature, expected)
+      raise SignatureVerificationError, "Invalid signature"
+    end
+
+    JSON.parse(payload, symbolize_names: true)
+  end
+
+  class SignatureVerificationError < StandardError; end
+end

data/app/controllers/purchase_kit/purchase/completions_controller.rb

@@ -0,0 +1,39 @@
+module PurchaseKit
+  module Purchase
+    # Demo mode only - simulates purchase completion for Xcode StoreKit testing
+    class CompletionsController < ApplicationController
+      skip_forgery_protection
+
+      def create
+        return head :not_found unless PurchaseKit.config.demo_mode?
+
+        intent = Intent::Demo.find(params[:id])
+
+        # Simulate a subscription.created webhook
+        event = {
+          type: "subscription.created",
+          customer_id: intent.customer_id.to_s,
+          subscription_id: "sub_#{SecureRandom.hex(12)}",
+          store: "apple",
+          store_product_id: intent.product.apple_product_id,
+          subscription_name: "Demo Subscription",
+          status: "active",
+          current_period_start: Time.current.iso8601,
+          current_period_end: 1.year.from_now.iso8601,
+          ends_at: nil,
+          success_path: intent.success_path
+        }
+
+        # Publish the event (triggers callbacks and Pay integration if available)
+        PurchaseKit::Events.publish(:subscription_created, event)
+
+        # Queue for Pay if available
+        PurchaseKit::Pay::Webhook.queue(event) if PurchaseKit.pay_enabled?
+
+        redirect_to intent.success_path || main_app.root_path, notice: "Purchase completed!"
+      rescue PurchaseKit::NotFoundError
+        head :not_found
+      end
+    end
+  end
+end

data/app/controllers/purchase_kit/purchases_controller.rb

@@ -0,0 +1,37 @@
+module PurchaseKit
+  class PurchasesController < ApplicationController
+    def create
+      intent = PurchaseKit::Purchase::Intent.create(
+        product_id: params[:product_id],
+        customer_id: params[:customer_id],
+        success_path: params[:success_path],
+        environment: params[:environment]
+      )
+
+      respond_to do |format|
+        format.turbo_stream do
+          render turbo_stream: turbo_stream.append(
+            "purchasekit_paywall",
+            partial: "purchase_kit/purchases/intent",
+            locals: {intent: intent}
+          )
+        end
+        format.json { render json: intent_json(intent) }
+      end
+    end
+
+    private
+
+    def intent_json(intent)
+      {
+        id: intent.id,
+        uuid: intent.uuid,
+        product: {
+          id: intent.product.id,
+          apple_product_id: intent.product.apple_product_id,
+          google_product_id: intent.product.google_product_id
+        }
+      }
+    end
+  end
+end

data/app/controllers/purchase_kit/webhooks_controller.rb

@@ -0,0 +1,42 @@
+module PurchaseKit
+  class WebhooksController < ApplicationController
+    skip_forgery_protection
+
+    def create
+      event = verified_event
+      event_type = event[:type].to_s.tr(".", "_").to_sym
+
+      # Publish to event system (fires registered callbacks)
+      PurchaseKit::Events.publish(event_type, event)
+
+      # Queue for Pay's webhook processing if Pay is available
+      PurchaseKit.queue_pay_webhook(event) if PurchaseKit.pay_enabled?
+
+      head :ok
+    rescue PurchaseKit::SignatureVerificationError => e
+      Rails.logger.error "[PurchaseKit] Webhook signature error: #{e.message}"
+      head :bad_request
+    end
+
+    private
+
+    def verified_event
+      payload = request.raw_post
+      signature = request.headers["X-PurchaseKit-Signature"]
+      secret = PurchaseKit.config.webhook_secret
+
+      if secret.blank?
+        if Rails.env.production?
+          raise PurchaseKit::SignatureVerificationError, "webhook_secret must be configured"
+        end
+        return JSON.parse(payload, symbolize_names: true)
+      end
+
+      PurchaseKit::WebhookSignature.verified_payload(
+        payload: payload,
+        signature: signature,
+        secret: secret
+      )
+    end
+  end
+end

data/app/helpers/purchase_kit/pay/paywall_helper.rb

@@ -0,0 +1,85 @@
+module PurchaseKit::Pay::PaywallHelper
+  # Wrapper for paywall with bridge controller
+  # Renders a form that posts to the purchases endpoint
+  # Yields a builder for plan options and buttons
+  # Requires a Pay::Customer - call user.set_payment_processor(:purchasekit) first
+  def purchasekit_paywall(customer:, success_path: main_app.root_path, **options)
+    raise ArgumentError, "Must provide customer: parameter. Call user.set_payment_processor(:purchasekit) first." unless customer
+
+    builder = PurchaseKit::Pay::PaywallBuilder.new(self, customer)
+
+    form_data = (options.delete(:data) || {}).merge(
+      controller: "purchasekit-pay--paywall",
+      purchasekit_pay__paywall_customer_id_value: customer.id
+    )
+
+    form_with(url: purchasekit_pay.purchases_path, id: "purchasekit_paywall", data: form_data, **options) do |form|
+      hidden = hidden_field_tag(:customer_id, customer.id)
+      hidden += hidden_field_tag(:success_path, success_path)
+      hidden += hidden_field_tag(:environment, "sandbox", data: {purchasekit_pay__paywall_target: "environment"})
+      hidden + capture { yield builder }
+    end
+  end
+end
+
+class PurchaseKit::Pay::PaywallBuilder
+  def initialize(template, customer)
+    @template = template
+    @customer = customer
+    @current_product = nil
+  end
+
+  def plan_option(product:, selected: false, input_class: nil, **options, &block)
+    input_id = "purchasekit_plan_#{product.id.parameterize.underscore}"
+
+    radio = @template.radio_button_tag(
+      :product_id,
+      product.id,
+      selected,
+      id: input_id,
+      class: input_class,
+      autocomplete: "off",
+      data: {
+        purchasekit_pay__paywall_target: "planRadio",
+        apple_store_product_id: product.apple_product_id,
+        google_store_product_id: product.google_product_id
+      }
+    )
+
+    @current_product = product
+    label = @template.label_tag(input_id, **options) { @template.capture(&block) }
+    @current_product = nil
+
+    radio + label
+  end
+
+  def price(**options, &block)
+    raise "price must be called within a plan_option block" unless @current_product
+
+    data = (options.delete(:data) || {}).merge(
+      purchasekit_pay__paywall_target: "price",
+      apple_store_product_id: @current_product.apple_product_id,
+      google_store_product_id: @current_product.google_product_id
+    )
+
+    loading_content = block ? @template.capture(&block) : "Loading..."
+    @template.content_tag(:span, loading_content, data: data, **options)
+  end
+
+  def submit(text = "Subscribe", **options)
+    data = (options.delete(:data) || {}).merge(
+      purchasekit_pay__paywall_target: "submitButton",
+      turbo_submits_with: text
+    )
+
+    @template.submit_tag(text, disabled: true, data: data, **options)
+  end
+
+  def restore_link(text: "Restore purchases", **options)
+    data = (options.delete(:data) || {}).merge(
+      action: "click->purchasekit-pay--paywall#restore"
+    )
+
+    @template.link_to(text, "#", data: data, **options)
+  end
+end

data/app/helpers/purchase_kit/paywall_helper.rb

@@ -0,0 +1,96 @@
+module PurchaseKit
+  module PaywallHelper
+    # Renders a paywall form that triggers native in-app purchases
+    #
+    # @param customer_id [String, Integer] Your user/customer identifier
+    # @param success_path [String] Where to redirect after successful purchase
+    # @yield [PaywallBuilder] Builder for plan options and buttons
+    #
+    # Example:
+    #   <%= purchasekit_paywall customer_id: current_user.id, success_path: dashboard_path do |paywall| %>
+    #     <%= paywall.plan_option product: @annual, selected: true do %>
+    #       Annual - <%= paywall.price %>
+    #     <% end %>
+    #     <%= paywall.submit "Subscribe" %>
+    #   <% end %>
+    #
+    def purchasekit_paywall(customer_id:, success_path: main_app.root_path, **options)
+      raise ArgumentError, "customer_id is required" if customer_id.blank?
+
+      builder = PaywallBuilder.new(self)
+
+      form_data = (options.delete(:data) || {}).merge(
+        controller: "purchasekit--paywall",
+        purchasekit__paywall_customer_id_value: customer_id
+      )
+
+      form_with(url: purchasekit.purchases_path, id: "purchasekit_paywall", data: form_data, **options) do |form|
+        hidden = hidden_field_tag(:customer_id, customer_id)
+        hidden += hidden_field_tag(:success_path, success_path)
+        hidden += hidden_field_tag(:environment, "sandbox", data: {purchasekit__paywall_target: "environment"})
+        hidden + capture { yield builder }
+      end
+    end
+  end
+
+  class PaywallBuilder
+    def initialize(template)
+      @template = template
+      @current_product = nil
+    end
+
+    def plan_option(product:, selected: false, input_class: nil, **options, &block)
+      input_id = "purchasekit_plan_#{product.id.to_s.parameterize.underscore}"
+
+      radio = @template.radio_button_tag(
+        :product_id,
+        product.id,
+        selected,
+        id: input_id,
+        class: input_class,
+        autocomplete: "off",
+        data: {
+          purchasekit__paywall_target: "planRadio",
+          apple_store_product_id: product.apple_product_id,
+          google_store_product_id: product.google_product_id
+        }
+      )
+
+      @current_product = product
+      label = @template.label_tag(input_id, **options) { @template.capture(&block) }
+      @current_product = nil
+
+      radio + label
+    end
+
+    def price(**options, &block)
+      raise "price must be called within a plan_option block" unless @current_product
+
+      data = (options.delete(:data) || {}).merge(
+        purchasekit__paywall_target: "price",
+        apple_store_product_id: @current_product.apple_product_id,
+        google_store_product_id: @current_product.google_product_id
+      )
+
+      loading_content = block ? @template.capture(&block) : "Loading..."
+      @template.content_tag(:span, loading_content, data: data, **options)
+    end
+
+    def submit(text = "Subscribe", **options)
+      data = (options.delete(:data) || {}).merge(
+        purchasekit__paywall_target: "submitButton",
+        turbo_submits_with: text
+      )
+
+      @template.submit_tag(text, disabled: true, data: data, **options)
+    end
+
+    def restore_link(text: "Restore purchases", **options)
+      data = (options.delete(:data) || {}).merge(
+        action: "click->purchasekit--paywall#restore"
+      )
+
+      @template.link_to(text, "#", data: data, **options)
+    end
+  end
+end