better_auth-stripe 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19c8cba9e5f67da8b742ec37f48ef758124d373812879ae8af0a49e950962fc5
-  data.tar.gz: c848c8261f7376eb71d2c75d7e2a5fd3b3ef6ba384b92c2891e75de41be4a75b
+  metadata.gz: cd6fea79b678b06d713919a087366ca4d6e0e160e5623e0e2b4c788e5041e7ae
+  data.tar.gz: 96fdab018ed1cdce8beb551052b36ebdea06d832daf178ea54727472ebd604a6
 SHA512:
-  metadata.gz: 75dd173be79173cc0a40596f120b54f1160dfce41c98fa9ce2c60a9de13a91860e17b1f6d42840e798dbe44a9b8f50a3fdc31e8bc95c8c3b972955bd2c38c199
-  data.tar.gz: be8037299688f25db5354ff51fdec3ba1925a0afa023116d3f054da294f4a8db16f1c2ceafb19c3e41c9e9110b00fa5cfa6cd7d617ce73243394df8ea927ba7a
+  metadata.gz: f8b8e916a57096cca616e465cdf4d5ab2688b4ed4592c794a8309f4c71523c8550750a8360b2e76e357743cb52258e214ddf04a28bb232e371302926a3af328d
+  data.tar.gz: 3b2f8193888d31bb65992147081a022c8952a152b3d5642b80364ad0c18e6c9a5e6cdce8c36c09287ba5823f3ffd95e65a82b92ced1f290024b0c69635bee93d

data/CHANGELOG.md

@@ -2,4 +2,11 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-29
+
+- Aligned Stripe subscription, checkout, portal, webhook, customer, and organization flows with upstream Better Auth behavior.
+- Expanded Stripe documentation and tests for subscription lifecycle and organization billing parity.
+
+## [0.1.0] - 2026-04-28
+
 - Initial external Stripe package extracted from `better_auth`.

data/README.md

@@ -19,14 +19,35 @@ auth = BetterAuth.auth(
   plugins: [
     BetterAuth::Plugins.stripe(
       stripe_api_key: ENV.fetch("STRIPE_SECRET_KEY"),
-      stripe_webhook_secret: ENV.fetch("STRIPE_WEBHOOK_SECRET")
+      stripe_webhook_secret: ENV.fetch("STRIPE_WEBHOOK_SECRET"),
+      subscription: {
+        enabled: true,
+        plans: [
+          { name: "pro", price_id: "price_monthly", annual_discount_price_id: "price_yearly" },
+          { name: "team", price_id: "price_team", seat_price_id: "price_team_seat" }
+        ]
+      }
     )
   ]
 )
 ```
 
+## Subscription Options
+
+Set `subscription: { enabled: true, plans: [...] }` to enable checkout, portal, restore, list, and webhook subscription handling. Plans support `name`, `price_id`, `lookup_key`, `annual_discount_price_id`, `annual_discount_lookup_key`, `limits`, `free_trial`, `seat_price_id`, `line_items`, and `proration_behavior`.
+
+Organization subscriptions require `organization: { enabled: true }` and an `authorize_reference` callback. When a plan has `seat_price_id`, organization member changes sync the Stripe seat item quantity.
+
 ## Notes
 
 This package depends on the official `stripe` gem. Keeping Stripe outside `better_auth` avoids installing Stripe SDK dependencies for applications that do not use billing.
 
 Pass `stripe_client:` when you need a custom Stripe client, Stripe Connect behavior, or a test double.
+
+## Subscriptions
+
+Configure plans under `subscription: { enabled: true, plans: [...] }`. Ruby accepts upstream-equivalent plan keys including `price_id`, `annual_discount_price_id`, lookup-key variants, `limits`, `free_trial`, and `seat_price_id`.
+
+For organization subscriptions, `seat_price_id` enables upstream-style seat billing. Checkout sends the base plan item with quantity `1` and a separate seat item whose quantity is the current organization member count. Webhooks read the seat item quantity back into the local `subscription.seats` field.
+
+`scheduleAtPeriodEnd` / `schedule_at_period_end` on `/subscription/upgrade` creates a Stripe subscription schedule for active subscriptions, stores `stripeScheduleId`, and returns the configured `returnUrl` instead of opening the billing portal immediately.

data/lib/better_auth/plugins/stripe.rb

@@ -6,7 +6,7 @@ require "stripe"
 module BetterAuth
   module Stripe
     class ClientAdapter
-      attr_reader :customers, :checkout, :billing_portal, :subscriptions, :prices, :webhooks
+      attr_reader :customers, :checkout, :billing_portal, :subscriptions, :prices, :subscription_schedules, :webhooks
 
       def initialize(api_key)
         client = ::Stripe::StripeClient.new(api_key)
@@ -15,6 +15,7 @@ module BetterAuth
         @billing_portal = NamespaceAdapter.new(sessions: ResourceAdapter.new(client.v1.billing_portal.sessions))
         @subscriptions = ResourceAdapter.new(client.v1.subscriptions)
         @prices = ResourceAdapter.new(client.v1.prices)
+        @subscription_schedules = ResourceAdapter.new(client.v1.subscription_schedules)
         @webhooks = WebhooksAdapter.new
       end
     end
@@ -52,6 +53,10 @@ module BetterAuth
       def update(id, params = {})
         @resource.update(id, params || {})
       end
+
+      def release(id)
+        @resource.release(id)
+      end
     end
 
     class WebhooksAdapter
@@ -95,8 +100,10 @@ module BetterAuth
       "STRIPE_WEBHOOK_SECRET_NOT_FOUND" => "Stripe webhook secret not found",
       "FAILED_TO_CONSTRUCT_STRIPE_EVENT" => "Failed to construct Stripe event",
       "STRIPE_WEBHOOK_ERROR" => "Stripe webhook error",
+      "INVALID_CUSTOMER_TYPE" => "Customer type must be either user or organization",
       "INVALID_REQUEST_BODY" => "Invalid request body"
     }.freeze
+    STRIPE_UNSAFE_METADATA_KEYS = %w[__proto__ constructor prototype].freeze
 
     def stripe(options = {})
       config = normalize_hash(options)
@@ -135,6 +142,8 @@ module BetterAuth
             canceledAt: {type: "date", required: false},
             endedAt: {type: "date", required: false},
             seats: {type: "number", required: false},
+            billingInterval: {type: "string", required: false},
+            stripeScheduleId: {type: "string", required: false},
             limits: {type: "json", required: false}
           }
         }
@@ -172,6 +181,8 @@ module BetterAuth
               data["id"] ||= SecureRandom.hex(16)
               customer = stripe_find_or_create_user_customer(config, data, nil, hook_ctx)
               {data: {id: data["id"], stripeCustomerId: stripe_id(customer)}}
+            rescue
+              nil
             end
           },
           update: {
@@ -216,7 +227,10 @@ module BetterAuth
             !%w[canceled incomplete incomplete_expired].include?(stripe_fetch(subscription, "status").to_s)
           end
           raise APIError.new("BAD_REQUEST", message: STRIPE_ERROR_CODES.fetch("ORGANIZATION_HAS_ACTIVE_SUBSCRIPTION")) if active
-        end
+        end,
+        after_add_member: ->(data, ctx) { stripe_sync_organization_seats(config, data, ctx) },
+        after_remove_member: ->(data, ctx) { stripe_sync_organization_seats(config, data, ctx) },
+        after_accept_invitation: ->(data, ctx) { stripe_sync_organization_seats(config, data, ctx) }
       }
     end
 
@@ -225,7 +239,7 @@ module BetterAuth
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         subscription_options = stripe_subscription_options(config)
-        customer_type = (body[:customer_type] || "user").to_s
+        customer_type = stripe_customer_type!(body)
         reference_id = stripe_reference_id!(ctx, session, customer_type, body[:reference_id], config)
         stripe_authorize_reference!(ctx, session, reference_id, "upgrade-subscription", customer_type, subscription_options, explicit: body.key?(:reference_id))
 
@@ -264,11 +278,16 @@ module BetterAuth
 
         price_id = stripe_price_id(config, plan, body[:annual])
         raise APIError.new("BAD_REQUEST", message: "Price ID not found for the selected plan") if price_id.to_s.empty?
+        auto_managed_seats = !!(plan[:seat_price_id] && customer_type == "organization")
+        member_count = auto_managed_seats ? ctx.context.adapter.count(model: "member", where: [{field: "organizationId", value: reference_id}]) : 0
+        requested_seats = auto_managed_seats ? member_count : (body[:seats] || 1)
+        seat_only_plan = auto_managed_seats && plan[:seat_price_id] == price_id
 
-        active_stripe_item = stripe_subscription_item(active_stripe || {})
+        active_resolved = active_stripe && stripe_resolve_plan_item(config, active_stripe)
+        active_stripe_item = active_resolved&.fetch(:item, nil) || stripe_subscription_item(active_stripe || {})
         stripe_price_id_value = stripe_fetch(stripe_fetch(active_stripe_item || {}, "price") || {}, "id")
         same_plan = active_or_trialing && active_or_trialing["plan"].to_s.downcase == body[:plan].to_s.downcase
-        same_seats = active_or_trialing && active_or_trialing["seats"].to_i == (body[:seats] || 1).to_i
+        same_seats = auto_managed_seats || (active_or_trialing && active_or_trialing["seats"].to_i == requested_seats.to_i)
         same_price = !active_stripe || stripe_price_id_value == price_id
         valid_period = !active_or_trialing || !active_or_trialing["periodEnd"] || active_or_trialing["periodEnd"] > Time.now
         if active_or_trialing&.fetch("status", nil) == "active" && same_plan && same_seats && same_price && valid_period
@@ -276,6 +295,17 @@ module BetterAuth
         end
 
         if active_stripe
+          if body[:schedule_at_period_end]
+            url = stripe_schedule_plan_change(ctx, config, active_stripe, active_or_trialing, plan, price_id, requested_seats, seat_only_plan, body)
+            next ctx.json({url: url, redirect: stripe_redirect?(body)})
+          end
+
+          old_plan = active_or_trialing && stripe_plan_by_name(config, active_or_trialing["plan"])
+          if stripe_direct_subscription_update?(old_plan, plan, auto_managed_seats)
+            url = stripe_update_active_subscription_items(ctx, config, active_stripe, active_or_trialing, old_plan, plan, price_id, requested_seats, seat_only_plan, body)
+            next ctx.json({url: url, redirect: stripe_redirect?(body)})
+          end
+
           portal = stripe_client(config).billing_portal.sessions.create(
             customer: customer_id,
             return_url: stripe_url(ctx, body[:return_url] || "/"),
@@ -284,7 +314,7 @@ module BetterAuth
               after_completion: {type: "redirect", redirect: {return_url: stripe_url(ctx, body[:return_url] || "/")}},
               subscription_update_confirm: {
                 subscription: stripe_fetch(active_stripe, "id"),
-                items: [{id: stripe_fetch(active_stripe_item || {}, "id"), quantity: body[:seats] || 1, price: price_id}]
+                items: [stripe_line_item(config, price_id, requested_seats).merge(id: stripe_fetch(active_stripe_item || {}, "id"))]
               }
             }
           )
@@ -294,12 +324,12 @@ module BetterAuth
         incomplete = subscriptions.find { |entry| entry["status"] == "incomplete" }
         subscription = active_or_trialing || incomplete
         if subscription
-          update = {plan: plan[:name].to_s.downcase, seats: body[:seats] || 1}
+          update = {plan: plan[:name].to_s.downcase, seats: requested_seats}
           subscription = ctx.context.adapter.update(model: "subscription", where: [{field: "id", value: subscription.fetch("id")}], update: update) || subscription.merge(update.transform_keys { |key| Schema.storage_key(key) })
         else
           subscription = ctx.context.adapter.create(
             model: "subscription",
-            data: {plan: plan[:name].to_s.downcase, referenceId: reference_id, stripeCustomerId: customer_id, status: "incomplete", seats: body[:seats] || 1, limits: plan[:limits]}
+            data: {plan: plan[:name].to_s.downcase, referenceId: reference_id, stripeCustomerId: customer_id, status: "incomplete", seats: requested_seats, limits: plan[:limits]}
           )
         end
 
@@ -323,9 +353,9 @@ module BetterAuth
           customer: customer_id,
           customer_update: (customer_type == "user") ? {name: "auto", address: "auto"} : {address: "auto"},
           locale: body[:locale],
-          success_url: stripe_url(ctx, "#{ctx.context.base_url}/subscription/success?callbackURL=#{Rack::Utils.escape(body[:success_url] || "/")}&subscriptionId=#{Rack::Utils.escape(subscription.fetch("id"))}"),
+          success_url: stripe_url(ctx, "#{ctx.context.base_url}/subscription/success?callbackURL=#{Rack::Utils.escape(body[:success_url] || "/")}&checkoutSessionId={CHECKOUT_SESSION_ID}"),
           cancel_url: stripe_url(ctx, body[:cancel_url] || "/"),
-          line_items: [{price: price_id, quantity: body[:seats] || 1}],
+          line_items: stripe_checkout_line_items(config, plan, price_id, requested_seats, auto_managed_seats, seat_only_plan),
           subscription_data: free_trial.merge(metadata: subscription_metadata),
           mode: "subscription",
           client_reference_id: reference_id,
@@ -343,7 +373,7 @@ module BetterAuth
       Endpoint.new(path: "/subscription/cancel", method: "POST") do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
-        customer_type = (body[:customer_type] || "user").to_s
+        customer_type = stripe_customer_type!(body)
         reference_id = stripe_reference_id!(ctx, session, customer_type, body[:reference_id], config)
         stripe_authorize_reference!(ctx, session, reference_id, "cancel-subscription", customer_type, stripe_subscription_options(config), explicit: body.key?(:reference_id))
         subscription = stripe_find_subscription_for_action(ctx, reference_id, body[:subscription_id], active_only: true)
@@ -378,12 +408,22 @@ module BetterAuth
       Endpoint.new(path: "/subscription/restore", method: "POST") do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
-        customer_type = (body[:customer_type] || "user").to_s
+        customer_type = stripe_customer_type!(body)
         reference_id = stripe_reference_id!(ctx, session, customer_type, body[:reference_id], config)
         stripe_authorize_reference!(ctx, session, reference_id, "restore-subscription", customer_type, stripe_subscription_options(config), explicit: body.key?(:reference_id))
         subscription = stripe_find_subscription_for_action(ctx, reference_id, body[:subscription_id], active_only: false)
         raise APIError.new("BAD_REQUEST", message: STRIPE_ERROR_CODES.fetch("SUBSCRIPTION_NOT_FOUND")) unless subscription && subscription["stripeCustomerId"]
         raise APIError.new("BAD_REQUEST", message: STRIPE_ERROR_CODES.fetch("SUBSCRIPTION_NOT_ACTIVE")) unless stripe_active_or_trialing?(subscription)
+
+        if subscription["stripeScheduleId"]
+          schedule = stripe_client(config).subscription_schedules.retrieve(subscription["stripeScheduleId"])
+          if stripe_fetch(schedule, "status") == "active"
+            schedule = stripe_client(config).subscription_schedules.release(subscription["stripeScheduleId"])
+          end
+          ctx.context.adapter.update(model: "subscription", where: [{field: "id", value: subscription.fetch("id")}], update: {stripeScheduleId: nil})
+          next ctx.json(stripe_stringify_keys(schedule))
+        end
+
         raise APIError.new("BAD_REQUEST", message: STRIPE_ERROR_CODES.fetch("SUBSCRIPTION_NOT_SCHEDULED_FOR_CANCELLATION")) unless stripe_pending_cancel?(subscription)
 
         active = stripe_active_subscriptions(config, subscription["stripeCustomerId"]).first
@@ -406,14 +446,19 @@ module BetterAuth
       Endpoint.new(path: "/subscription/list", method: "GET") do |ctx|
         session = Routes.current_session(ctx)
         query = normalize_hash(ctx.query)
-        customer_type = (query[:customer_type] || "user").to_s
+        customer_type = stripe_customer_type!(query)
         reference_id = stripe_reference_id!(ctx, session, customer_type, query[:reference_id], config)
         stripe_authorize_reference!(ctx, session, reference_id, "list-subscription", customer_type, stripe_subscription_options(config), explicit: query.key?(:reference_id))
         plans = stripe_plans(config)
         subscriptions = ctx.context.adapter.find_many(model: "subscription", where: [{field: "referenceId", value: reference_id}]).select { |entry| stripe_active_or_trialing?(entry) }
         ctx.json(subscriptions.map do |entry|
           plan = plans.find { |item| item[:name].to_s.downcase == entry["plan"].to_s.downcase }
-          entry.merge("limits" => plan&.fetch(:limits, nil), "priceId" => plan&.fetch(:price_id, nil))
+          price_id = if entry["billingInterval"] == "year"
+            plan&.fetch(:annual_discount_price_id, nil) || plan&.fetch(:price_id, nil)
+          else
+            plan&.fetch(:price_id, nil)
+          end
+          entry.merge("limits" => plan&.fetch(:limits, nil), "priceId" => price_id)
         end)
       end
     end
@@ -422,7 +467,7 @@ module BetterAuth
       Endpoint.new(path: "/subscription/billing-portal", method: "POST") do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
-        customer_type = (body[:customer_type] || "user").to_s
+        customer_type = stripe_customer_type!(body)
         reference_id = stripe_reference_id!(ctx, session, customer_type, body[:reference_id], config)
         stripe_authorize_reference!(ctx, session, reference_id, "billing-portal", customer_type, stripe_subscription_options(config), explicit: body.key?(:reference_id))
         customer_id = if customer_type == "organization"
@@ -468,13 +513,22 @@ module BetterAuth
       Endpoint.new(path: "/subscription/success", method: "GET") do |ctx|
         query = normalize_hash(ctx.query)
         callback = query[:callback_url] || "/"
-        unless query[:subscription_id]
+        checkout_session_id = query[:checkout_session_id]
+        subscription_id = query[:subscription_id]
+        if checkout_session_id
+          callback = callback.to_s.gsub("{CHECKOUT_SESSION_ID}", checkout_session_id.to_s)
+          checkout_session = stripe_client(config || {}).checkout.sessions.retrieve(checkout_session_id)
+          metadata = normalize_hash(stripe_fetch(checkout_session || {}, "metadata") || {})
+          subscription_id = metadata[:subscription_id]
+        end
+
+        unless subscription_id
           raise ctx.redirect(stripe_url(ctx, callback))
         end
         session = Routes.current_session(ctx, allow_nil: true)
         raise ctx.redirect(stripe_url(ctx, callback)) unless session
 
-        subscription = ctx.context.adapter.find_one(model: "subscription", where: [{field: "id", value: query[:subscription_id]}])
+        subscription = ctx.context.adapter.find_one(model: "subscription", where: [{field: "id", value: subscription_id}])
         raise ctx.redirect(stripe_url(ctx, callback)) unless subscription
         raise ctx.redirect(stripe_url(ctx, callback)) if stripe_active_or_trialing?(subscription)
 
@@ -483,15 +537,16 @@ module BetterAuth
 
         stripe_subscription = stripe_active_subscriptions(config || {}, customer_id).first
         if stripe_subscription
-          item = stripe_subscription_item(stripe_subscription)
-          plan = item && stripe_plan_by_price_info(config || {}, stripe_fetch(stripe_fetch(item, "price") || {}, "id"), stripe_fetch(stripe_fetch(item, "price") || {}, "lookup_key"))
+          resolved = stripe_resolve_plan_item(config || {}, stripe_subscription)
+          item = resolved&.fetch(:item, nil)
+          plan = resolved&.fetch(:plan, nil)
           if item && plan
             ctx.context.adapter.update(
               model: "subscription",
               where: [{field: "id", value: subscription.fetch("id")}],
-              update: stripe_subscription_state(stripe_subscription, include_status: true).merge(
+              update: stripe_subscription_state(stripe_subscription, include_status: true, compact: false).merge(
                 plan: plan[:name].to_s.downcase,
-                seats: stripe_fetch(item, "quantity") || 1,
+                seats: stripe_resolve_quantity(stripe_subscription, item, plan),
                 stripeSubscriptionId: stripe_fetch(stripe_subscription, "id")
               )
             )
@@ -508,23 +563,27 @@ module BetterAuth
 
         raise APIError.new("INTERNAL_SERVER_ERROR", message: STRIPE_ERROR_CODES.fetch("STRIPE_WEBHOOK_SECRET_NOT_FOUND")) if config[:stripe_webhook_secret].to_s.empty?
 
-        event = if stripe_client(config).respond_to?(:webhooks)
-          webhooks = stripe_client(config).webhooks
-          if webhooks.respond_to?(:construct_event_async) && (!webhooks.respond_to?(:construct_event) || config[:stripe_async_webhooks] || (webhooks.respond_to?(:async) && webhooks.async))
-            webhooks.construct_event_async(ctx.body, signature, config[:stripe_webhook_secret])
+        event = begin
+          if stripe_client(config).respond_to?(:webhooks)
+            webhooks = stripe_client(config).webhooks
+            if webhooks.respond_to?(:construct_event_async)
+              webhooks.construct_event_async(ctx.body, signature, config[:stripe_webhook_secret])
+            else
+              webhooks.construct_event(ctx.body, signature, config[:stripe_webhook_secret])
+            end
           else
-            webhooks.construct_event(ctx.body, signature, config[:stripe_webhook_secret])
+            ctx.body
           end
-        else
-          ctx.body
+        rescue
+          raise APIError.new("BAD_REQUEST", message: STRIPE_ERROR_CODES.fetch("FAILED_TO_CONSTRUCT_STRIPE_EVENT"))
         end
         raise APIError.new("BAD_REQUEST", message: STRIPE_ERROR_CODES.fetch("FAILED_TO_CONSTRUCT_STRIPE_EVENT")) unless event
-        stripe_handle_event(ctx, event)
+        begin
+          stripe_handle_event(ctx, event)
+        rescue
+          raise APIError.new("BAD_REQUEST", message: STRIPE_ERROR_CODES.fetch("STRIPE_WEBHOOK_ERROR"))
+        end
         ctx.json({success: true})
-      rescue APIError
-        raise
-      rescue => error
-        raise APIError.new("BAD_REQUEST", message: STRIPE_ERROR_CODES.fetch("FAILED_TO_CONSTRUCT_STRIPE_EVENT") || error.message)
       end
     end
 
@@ -551,10 +610,11 @@ module BetterAuth
       return if object[:mode] == "setup" || !config.dig(:subscription, :enabled)
 
       stripe_subscription = stripe_client(config).subscriptions.retrieve(object[:subscription])
-      item = stripe_subscription_item(stripe_subscription)
-      return unless item
+      resolved = stripe_resolve_plan_item(config, stripe_subscription)
+      return unless resolved
 
-      plan = stripe_plan_by_price_info(config, stripe_fetch(stripe_fetch(item, "price") || {}, "id"), stripe_fetch(stripe_fetch(item, "price") || {}, "lookup_key"))
+      item = resolved.fetch(:item)
+      plan = resolved.fetch(:plan)
       metadata = normalize_hash(object[:metadata] || {})
       reference_id = object[:client_reference_id] || metadata[:reference_id]
       subscription_id = metadata[:subscription_id]
@@ -563,7 +623,7 @@ module BetterAuth
       update = stripe_subscription_state(stripe_subscription, include_status: true).merge(
         plan: plan[:name].to_s.downcase,
         stripeSubscriptionId: object[:subscription],
-        seats: stripe_fetch(item, "quantity"),
+        seats: stripe_resolve_quantity(stripe_subscription, item, plan),
         trialStart: stripe_time(stripe_fetch(stripe_subscription, "trial_start")),
         trialEnd: stripe_time(stripe_fetch(stripe_subscription, "trial_end"))
       ).compact
@@ -588,9 +648,10 @@ module BetterAuth
 
       reference = stripe_reference_by_customer(ctx, config, customer_id) || ((metadata[:reference_id] && metadata[:plan]) ? {reference_id: metadata[:reference_id], customer_type: metadata[:customer_type] || "user"} : nil)
       return unless reference
-      item = stripe_subscription_item(object)
-      return unless item
-      plan = stripe_plan_by_price_info(config, stripe_fetch(stripe_fetch(item, "price") || {}, "id"), stripe_fetch(stripe_fetch(item, "price") || {}, "lookup_key")) || (metadata[:plan] && stripe_plan_by_name(config, metadata[:plan]))
+      resolved = stripe_resolve_plan_item(config, object)
+      return unless resolved
+      item = resolved.fetch(:item)
+      plan = resolved[:plan] || (metadata[:plan] && stripe_plan_by_name(config, metadata[:plan]))
       return unless plan
 
       created = ctx.context.adapter.create(
@@ -600,7 +661,7 @@ module BetterAuth
           stripeCustomerId: customer_id,
           stripeSubscriptionId: object[:id],
           plan: plan[:name].to_s.downcase,
-          seats: stripe_fetch(item, "quantity"),
+          seats: stripe_resolve_quantity(object, item, plan),
           limits: plan[:limits]
         ).compact
       )
@@ -610,8 +671,9 @@ module BetterAuth
     def stripe_on_subscription_updated(ctx, event)
       config = ctx.context.options.plugins.find { |plugin| plugin.id == "stripe" }&.options || {}
       object = normalize_hash(event.dig(:data, :object) || {})
-      item = stripe_subscription_item(object)
-      return unless item
+      resolved = stripe_resolve_plan_item(config, object)
+      return unless resolved
+      item = resolved.fetch(:item)
 
       metadata = normalize_hash(object[:metadata] || {})
       subscription = if metadata[:subscription_id]
@@ -629,19 +691,25 @@ module BetterAuth
       end
       return unless subscription
 
-      plan = stripe_plan_by_price_info(config, stripe_fetch(stripe_fetch(item, "price") || {}, "id"), stripe_fetch(stripe_fetch(item, "price") || {}, "lookup_key"))
+      plan = resolved[:plan]
       was_pending = stripe_pending_cancel?(subscription)
-      update = stripe_subscription_state(object, include_status: true).merge(
+      update = stripe_subscription_state(object, include_status: true, compact: false).merge(
         stripeSubscriptionId: object[:id],
-        seats: stripe_fetch(item, "quantity")
+        seats: stripe_resolve_quantity(object, item, plan)
       )
       update[:plan] = plan[:name].to_s.downcase if plan
       update[:limits] = plan[:limits] if plan&.key?(:limits)
-      updated = ctx.context.adapter.update(model: "subscription", where: [{field: "id", value: subscription.fetch("id")}], update: update.compact)
+      updated = ctx.context.adapter.update(model: "subscription", where: [{field: "id", value: subscription.fetch("id")}], update: update)
       if object[:status] == "active" && stripe_stripe_pending_cancel?(object) && !was_pending
         config.dig(:subscription, :on_subscription_cancel)&.call({event: event, subscription: subscription, stripeSubscription: object, stripe_subscription: object, cancellationDetails: object[:cancellation_details], cancellation_details: object[:cancellation_details]})
       end
       config.dig(:subscription, :on_subscription_update)&.call({event: event, subscription: updated || subscription})
+      if plan && subscription["status"] == "trialing" && object[:status] == "active"
+        plan.dig(:free_trial, :on_trial_end)&.call({subscription: subscription}, ctx)
+      end
+      if plan && subscription["status"] == "trialing" && object[:status] == "incomplete_expired"
+        plan.dig(:free_trial, :on_trial_expired)&.call(subscription, ctx)
+      end
     end
 
     def stripe_on_subscription_deleted(ctx, event)
@@ -650,7 +718,7 @@ module BetterAuth
       subscription = ctx.context.adapter.find_one(model: "subscription", where: [{field: "stripeSubscriptionId", value: object[:id]}])
       return unless subscription
 
-      ctx.context.adapter.update(model: "subscription", where: [{field: "id", value: subscription.fetch("id")}], update: stripe_subscription_state(object, include_status: false).merge(status: "canceled"))
+      ctx.context.adapter.update(model: "subscription", where: [{field: "id", value: subscription.fetch("id")}], update: stripe_subscription_state(object, include_status: false, compact: false).merge(status: "canceled", stripeScheduleId: nil))
       config.dig(:subscription, :on_subscription_deleted)&.call({event: event, subscription: subscription, stripeSubscription: object, stripe_subscription: object})
     end
 
@@ -662,8 +730,7 @@ module BetterAuth
     end
 
     def stripe_find_or_create_user_customer(config, user, metadata = nil, ctx = nil)
-      existing = stripe_client(config).customers.search(query: "email:\"#{stripe_escape_search(user["email"])}\" AND -metadata[\"customerType\"]:\"organization\"", limit: 1)
-      customer = Array(stripe_fetch(existing, "data")).first
+      customer = stripe_find_user_customer(config, user["email"])
       if customer
         stripe_notify_customer_created(config, customer, user, ctx)
         return customer
@@ -691,8 +758,7 @@ module BetterAuth
       raise APIError.new("BAD_REQUEST", message: STRIPE_ERROR_CODES.fetch("ORGANIZATION_NOT_FOUND")) unless org
       return org["stripeCustomerId"] if org["stripeCustomerId"]
 
-      existing = stripe_client(config).customers.search(query: "metadata[\"organizationId\"]:\"#{stripe_escape_search(org["id"])}\"", limit: 1)
-      customer = Array(stripe_fetch(existing, "data")).first
+      customer = stripe_find_organization_customer(config, org["id"])
       unless customer
         raw_extra = config.dig(:organization, :get_customer_create_params)&.call(org, ctx) || {}
         extra_metadata = stripe_fetch(raw_extra, "metadata")
@@ -796,6 +862,41 @@ module BetterAuth
       raise APIError.new("UNAUTHORIZED", message: STRIPE_ERROR_CODES.fetch("UNAUTHORIZED")) unless allowed
     end
 
+    def stripe_customer_type!(source)
+      customer_type = (source[:customer_type] || "user").to_s
+      raise APIError.new("BAD_REQUEST", message: STRIPE_ERROR_CODES.fetch("INVALID_CUSTOMER_TYPE")) unless %w[user organization].include?(customer_type)
+
+      customer_type
+    end
+
+    def stripe_find_user_customer(config, email)
+      customers = stripe_client(config).customers
+      begin
+        existing = customers.search(query: "email:\"#{stripe_escape_search(email)}\" AND -metadata[\"customerType\"]:\"organization\"", limit: 1)
+        Array(stripe_fetch(existing, "data")).first
+      rescue
+        listed = customers.list(email: email, limit: 100)
+        Array(stripe_fetch(listed, "data")).find do |customer|
+          stripe_metadata_fetch(stripe_fetch(customer, "metadata") || {}, "customerType") != "organization"
+        end
+      end
+    end
+
+    def stripe_find_organization_customer(config, organization_id)
+      customers = stripe_client(config).customers
+      begin
+        existing = customers.search(query: "metadata[\"organizationId\"]:\"#{stripe_escape_search(organization_id)}\" AND metadata[\"customerType\"]:\"organization\"", limit: 1)
+        Array(stripe_fetch(existing, "data")).first
+      rescue
+        listed = customers.list(limit: 100)
+        Array(stripe_fetch(listed, "data")).find do |customer|
+          metadata = stripe_fetch(customer, "metadata") || {}
+          stripe_metadata_fetch(metadata, "organizationId") == organization_id &&
+            stripe_metadata_fetch(metadata, "customerType") == "organization"
+        end
+      end
+    end
+
     def stripe_find_subscription_for_action(ctx, reference_id, subscription_id, active_only:)
       subscription = if subscription_id
         ctx.context.adapter.find_one(model: "subscription", where: [{field: "stripeSubscriptionId", value: subscription_id}])
@@ -832,8 +933,192 @@ module BetterAuth
       Array(stripe_fetch(stripe_fetch(subscription, "items") || {}, "data")).first
     end
 
-    def stripe_subscription_state(subscription, include_status: true)
+    def stripe_resolve_plan_item(config, subscription)
+      items = Array(stripe_fetch(stripe_fetch(subscription, "items") || {}, "data"))
+      first = items.first
+      return nil unless first
+
+      items.each do |item|
+        price = stripe_fetch(item, "price") || {}
+        plan = stripe_plan_by_price_info(config, stripe_fetch(price, "id"), stripe_fetch(price, "lookup_key"))
+        return {item: item, plan: plan} if plan
+      end
+      {item: first, plan: nil} if items.length == 1
+    end
+
+    def stripe_resolve_quantity(subscription, plan_item, plan = nil)
+      items = Array(stripe_fetch(stripe_fetch(subscription, "items") || {}, "data"))
+      seat_price_id = plan && plan[:seat_price_id]
+      seat_item = seat_price_id && items.find { |item| stripe_fetch(stripe_fetch(item, "price") || {}, "id") == seat_price_id }
+      stripe_fetch(seat_item || plan_item, "quantity") || 1
+    end
+
+    def stripe_line_item(config, price_id, quantity)
+      item = {price: price_id}
+      item[:quantity] = quantity unless stripe_metered_price?(config, price_id)
+      item
+    end
+
+    def stripe_checkout_line_items(config, plan, price_id, quantity, auto_managed_seats, seat_only_plan)
+      items = []
+      items << stripe_line_item(config, price_id, auto_managed_seats ? 1 : quantity) unless seat_only_plan
+      items << {price: plan[:seat_price_id], quantity: quantity} if auto_managed_seats && plan[:seat_price_id]
+      items.concat(stripe_plan_line_items(plan))
+      items
+    end
+
+    def stripe_plan_line_items(plan)
+      Array(plan[:line_items]).map do |item|
+        item.is_a?(Hash) ? normalize_hash(item) : item
+      end
+    end
+
+    def stripe_schedule_plan_change(ctx, config, active_stripe, db_subscription, plan, price_id, quantity, seat_only_plan, body)
+      schedule = stripe_client(config).subscription_schedules.create(from_subscription: stripe_fetch(active_stripe, "id"))
+      current_phase = Array(stripe_fetch(schedule, "phases")).first || {}
+      current_items = Array(stripe_fetch(current_phase, "items"))
+      active_item = stripe_resolve_plan_item(config, active_stripe)&.fetch(:item, nil) || stripe_subscription_item(active_stripe)
+      active_price_id = stripe_fetch(stripe_fetch(active_item || {}, "price") || {}, "id")
+      replaced = false
+      new_items = current_items.filter_map do |item|
+        item_price = stripe_fetch(item, "price")
+        item_price = stripe_fetch(item_price, "id") if item_price.is_a?(Hash)
+        if item_price == active_price_id
+          replaced = true
+          next nil if seat_only_plan
+
+          stripe_line_item(config, price_id, quantity)
+        else
+          {price: item_price, quantity: stripe_fetch(item, "quantity")}.compact
+        end
+      end
+      new_items << stripe_line_item(config, price_id, quantity) unless replaced || seat_only_plan
+      new_items << {price: plan[:seat_price_id], quantity: quantity} if plan[:seat_price_id]
+      new_items.concat(stripe_plan_line_items(plan))
+
+      stripe_client(config).subscription_schedules.update(
+        stripe_fetch(schedule, "id"),
+        metadata: {source: "@better-auth/stripe"},
+        end_behavior: "release",
+        phases: [
+          {
+            items: current_items.map do |item|
+              item_price = stripe_fetch(item, "price")
+              item_price = stripe_fetch(item_price, "id") if item_price.is_a?(Hash)
+              {price: item_price, quantity: stripe_fetch(item, "quantity")}.compact
+            end,
+            start_date: stripe_fetch(current_phase, "start_date"),
+            end_date: stripe_fetch(current_phase, "end_date")
+          },
+          {
+            items: new_items,
+            start_date: stripe_fetch(current_phase, "end_date"),
+            proration_behavior: "none"
+          }
+        ]
+      )
+      if db_subscription
+        ctx.context.adapter.update(model: "subscription", where: [{field: "id", value: db_subscription.fetch("id")}], update: {stripeScheduleId: stripe_fetch(schedule, "id")})
+      end
+      stripe_url(ctx, body[:return_url] || "/")
+    end
+
+    def stripe_direct_subscription_update?(old_plan, plan, auto_managed_seats)
+      return true if auto_managed_seats && old_plan && old_plan[:seat_price_id] != plan[:seat_price_id]
+
+      stripe_plan_line_items(old_plan || {}).map { |item| item[:price] } != stripe_plan_line_items(plan).map { |item| item[:price] }
+    end
+
+    def stripe_update_active_subscription_items(ctx, config, active_stripe, db_subscription, old_plan, plan, price_id, quantity, seat_only_plan, body)
+      active_item = stripe_resolve_plan_item(config, active_stripe)&.fetch(:item, nil) || stripe_subscription_item(active_stripe)
+      active_price_id = stripe_fetch(stripe_fetch(active_item || {}, "price") || {}, "id")
+      old_line_prices = stripe_plan_line_items(old_plan || {}).map { |item| item[:price] }
+      new_line_prices = stripe_plan_line_items(plan).map { |item| item[:price] }
+      added_line_prices = new_line_prices - old_line_prices
+      items = []
+      Array(stripe_fetch(stripe_fetch(active_stripe, "items") || {}, "data")).each do |item|
+        item_price = stripe_fetch(stripe_fetch(item, "price") || {}, "id")
+        if item_price == active_price_id
+          items << stripe_line_item(config, price_id, plan[:seat_price_id] ? 1 : quantity).merge(id: stripe_fetch(item, "id")) unless seat_only_plan
+        elsif old_plan && item_price == old_plan[:seat_price_id] && plan[:seat_price_id]
+          items << {id: stripe_fetch(item, "id"), price: plan[:seat_price_id], quantity: quantity}
+        elsif old_line_prices.include?(item_price)
+          if new_line_prices.include?(item_price)
+            new_line_prices.delete_at(new_line_prices.index(item_price))
+          else
+            items << {id: stripe_fetch(item, "id"), deleted: true}
+          end
+        end
+      end
+      items << {price: plan[:seat_price_id], quantity: quantity} if plan[:seat_price_id] && !items.any? { |item| item[:price] == plan[:seat_price_id] || item[:id] && item[:price] == plan[:seat_price_id] }
+      added_line_prices.each { |price| items << {price: price} }
+      stripe_client(config).subscriptions.update(stripe_fetch(active_stripe, "id"), items: items, proration_behavior: plan[:proration_behavior] || "create_prorations")
+      if db_subscription
+        ctx.context.adapter.update(
+          model: "subscription",
+          where: [{field: "id", value: db_subscription.fetch("id")}],
+          update: {plan: plan[:name].to_s.downcase, seats: quantity, limits: plan[:limits], stripeScheduleId: nil}
+        )
+      end
+      stripe_url(ctx, body[:return_url] || "/")
+    end
+
+    def stripe_sync_organization_seats(config, data, ctx)
+      organization = data[:organization] || data["organization"]
+      return unless config.dig(:subscription, :enabled) && organization && organization["stripeCustomerId"]
+
+      member_count = ctx.context.adapter.count(model: "member", where: [{field: "organizationId", value: organization.fetch("id")}])
+      seat_plans = stripe_plans(config).select { |plan| plan[:seat_price_id] }
+      return if seat_plans.empty?
+
+      subscription = ctx.context.adapter.find_many(model: "subscription", where: [{field: "referenceId", value: organization.fetch("id")}]).find { |entry| stripe_active_or_trialing?(entry) }
+      return unless subscription && subscription["stripeSubscriptionId"]
+
+      plan = seat_plans.find { |entry| entry[:name].to_s.downcase == subscription["plan"].to_s.downcase }
+      return unless plan
+
+      stripe_subscription = stripe_client(config).subscriptions.retrieve(subscription["stripeSubscriptionId"])
+      return unless stripe_active_or_trialing?(stripe_subscription)
+
+      items = Array(stripe_fetch(stripe_fetch(stripe_subscription, "items") || {}, "data"))
+      seat_item = items.find { |item| stripe_fetch(stripe_fetch(item, "price") || {}, "id") == plan[:seat_price_id] }
+      return if seat_item && stripe_fetch(seat_item, "quantity").to_i == member_count.to_i
+
+      update_items = if seat_item
+        [{id: stripe_fetch(seat_item, "id"), quantity: member_count}]
+      else
+        [{price: plan[:seat_price_id], quantity: member_count}]
+      end
+      stripe_client(config).subscriptions.update(subscription["stripeSubscriptionId"], items: update_items, proration_behavior: plan[:proration_behavior] || "create_prorations")
+      ctx.context.adapter.update(model: "subscription", where: [{field: "id", value: subscription.fetch("id")}], update: {seats: member_count})
+    rescue
+      nil
+    end
+
+    def stripe_metered_price?(config, price_id, lookup_key = nil)
+      price = stripe_resolve_stripe_price(config, price_id, lookup_key)
+      recurring = stripe_fetch(price || {}, "recurring") || {}
+      stripe_fetch(recurring, "usage_type") == "metered"
+    end
+
+    def stripe_resolve_stripe_price(config, price_id, lookup_key = nil)
+      return nil unless stripe_client(config).respond_to?(:prices)
+
+      prices = stripe_client(config).prices
+      if lookup_key
+        result = prices.list(lookup_keys: [lookup_key], active: true, limit: 1)
+        Array(stripe_fetch(result, "data")).first
+      elsif price_id && prices.respond_to?(:retrieve)
+        prices.retrieve(price_id)
+      end
+    rescue
+      nil
+    end
+
+    def stripe_subscription_state(subscription, include_status: true, compact: true)
       item = stripe_subscription_item(subscription)
+      price = stripe_fetch(item || {}, "price") || {}
+      recurring = stripe_fetch(price, "recurring") || {}
       state = {
         periodStart: stripe_time(stripe_fetch(item || subscription, "current_period_start")),
         periodEnd: stripe_time(stripe_fetch(item || subscription, "current_period_end")),
@@ -842,10 +1127,20 @@ module BetterAuth
         canceledAt: stripe_time(stripe_fetch(subscription, "canceled_at")),
         endedAt: stripe_time(stripe_fetch(subscription, "ended_at")),
         trialStart: stripe_time(stripe_fetch(subscription, "trial_start")),
-        trialEnd: stripe_time(stripe_fetch(subscription, "trial_end"))
+        trialEnd: stripe_time(stripe_fetch(subscription, "trial_end")),
+        billingInterval: stripe_fetch(recurring, "interval"),
+        stripeScheduleId: stripe_schedule_id(subscription)
       }
       state[:status] = stripe_fetch(subscription, "status") if include_status
-      state.compact
+      compact ? state.compact : state
+    end
+
+    def stripe_schedule_id(subscription)
+      schedule = stripe_fetch(subscription, "schedule")
+      return nil if schedule.nil?
+      return schedule if schedule.is_a?(String)
+
+      stripe_id(schedule) || schedule.to_s
     end
 
     def stripe_reference_by_customer(ctx, config, customer_id)
@@ -864,7 +1159,10 @@ module BetterAuth
         .reduce({}) do |acc, entry|
           next acc unless entry.respond_to?(:each)
 
-          acc.merge(entry.each_with_object({}) { |(key, value), result| result[stripe_metadata_key(key)] = value })
+          acc.merge(entry.each_with_object({}) do |(key, value), result|
+            metadata_key = stripe_metadata_key(key)
+            result[metadata_key] = value unless STRIPE_UNSAFE_METADATA_KEYS.include?(metadata_key)
+          end)
         end
         .merge(internal.transform_keys { |key| stripe_metadata_key(key) })
     end

data/lib/better_auth/stripe/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module Stripe
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_auth-stripe
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sebastian Sala