pay-abacatepay 0.1.0.pre.2 → 0.1.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe474c02462ff77be3f7be6764e4d15cc872b3dbede87cb89d82d1953f0c0cb5
-  data.tar.gz: 8d0fcdf3c260ffa42c1e68a0d61fee0d44e38d970f0cd419aad2bd7bfeb1db22
+  metadata.gz: 27f07627d9715f378edc2d9897c43f472dc1894da4ea045e2819f6487251cc36
+  data.tar.gz: b01ce9998ff6a3e72d736ac7f2ae7c4f963c26120936aa64906480bdb03e5c43
 SHA512:
-  metadata.gz: 1b7e2a27e0a2bd70ac20aec7f849b064c6f9320d6aded190a933d7997642a7869861f8278ff5f6d8fb4ce64134d65542bb10e0af29974d91f77ec7dcbdab232c
-  data.tar.gz: fa01c8d9c60a6eee16006540c74b85a4bc0ccc6bce9418ce67b0eecbcee1a2ca2db9e8d37a1c67e3eb2027a9978d78897365c3dfb674f91e89c8f2f7c7af3ee3
+  metadata.gz: a97b59da5e68065a83573fe1b11696542f270e785350fff201928c586fd80b65bd5c0f2ac56ebbd096c33846e177a0c7558ec68de72d6d2de813c940409968fc
+  data.tar.gz: 962f4aad6948fbedcdf9548cb580d08e17c803de98e3c15f3b89e3b7e8476cf3de3e24664b252d3a9a81a5d914a87b5076b11366ecd3e5de9bec5aac4d6c6f9b

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.1.0.pre.3]
+
+### Added
+- `Pay::Abacatepay::Customer#subscribe(name:, plan:, methods:, quantity:, external_id:, metadata:, cycle:)` — creates an AbacatePay subscription and persists a `Pay::Abacatepay::Subscription` eagerly. Status is mapped from the API response: `PENDING` → `"incomplete"` (the typical case, reconciled to `"active"` by the `subscription.completed` webhook on the same `processor_id`); `PAID` → `"active"` already on return. `methods` accepts either an array or a single string (normalized); `quantity` defaults to `1` and must be a positive integer.
+- `Pay::Abacatepay::Frequency` module with `INTERVALS`, `to_interval`, `valid?` — single source of truth shared by `Webhooks::Event#interval` and `Customer#subscribe`.
+- `Pay::Abacatepay::Subscription#checkout_url` (via `store_accessor :data, :checkout_url`) so callers can redirect the payer to the first-payment URL after `subscribe`.
+- Optional `coupons:` kwarg on `Customer#charge`, forwarded to the hosted checkout create call (omitted from the request body when blank).
+
+### Changed
+- `Webhooks::Event#interval` now delegates to `Pay::Abacatepay::Frequency.to_interval` (constant `FREQUENCY_TO_INTERVAL` removed from `Event`).
+
+### Notes
+- `Customer#subscribe(metadata:)` stores values locally only — the upstream SDK's `SubscriptionClient#create` does not include `metadata` in the request body yet. Pending upstream PR.
+- Trial periods unsupported: passing `trial_period_days:` or `trial_end:` raises `Pay::Abacatepay::Error` (fail-fast — silently dropping the trial would charge the customer immediately).
+
+## [0.0.0]
+
 ### Added
 - Initial scaffold with Rails engine structure
 - `Pay::AbacatePay::Customer` with `api_record`, `api_record_attributes`, `update_api_record`

data/README.md

@@ -12,7 +12,7 @@ AbacatePay processor for the [Pay gem](https://github.com/pay-rails/pay) (Rails
 - [x] Customer creation
 - [x] One-time charges — hosted checkout via `Customer#charge` + `checkout.*` webhooks
 - [ ] Transparent PIX (QR Code inline) — planned (Fase 5)
-- [x] Subscriptions — webhook-driven lifecycle + cancel (gaps below)
+- [x] Subscriptions — `Customer#subscribe` + webhook-driven lifecycle + cancel (gaps below)
 - [x] Webhooks — infrastructure + subscription and checkout handlers
 - [ ] Chargeback/dispute handling — planned (Fase 5)
 - [ ] Payment methods — planned
@@ -88,7 +88,8 @@ result = user.payment_processor.charge(
   methods: ["PIX", "CARD"],                  # defaults shown
   return_url: "https://app.example.com/cart",
   completion_url: "https://app.example.com/thanks",
-  external_id: "order-1234"                  # optional, for your reconciliation
+  external_id: "order-1234",                 # optional, for your reconciliation
+  coupons: ["LANCAMENTO"]                    # optional promo codes; omitted when blank
 )
 
 redirect_to result.url                       # send the user to AbacatePay
@@ -96,6 +97,8 @@ result.id                                    # "chk_xxx" — also result.charge.
 result.charge                                # Pay::Abacatepay::Charge, status: "pending"
 ```
 
+Coupon codes passed via `coupons:` are forwarded to `/checkouts/create`; AbacatePay validates them (existence/eligibility). When the argument is blank, the key is omitted from the request body entirely.
+
 ### Product on-the-fly
 
 AbacatePay's v2 `/checkouts/create` expects pre-registered products in `items[]`. When `product_id:` is omitted, the gem creates an ephemeral product via `POST /products/create` with `name: "Cobrança avulsa"` (overridable via `product_name:`). This costs an extra API call but keeps the host app's code free of product bookkeeping. Pass `product_id:` to skip this step when you manage products yourself.
@@ -148,10 +151,35 @@ bin/rails db:migrate
 
 The migration creates `pay_abacatepay_processed_webhooks`, a permanent table with a unique `(event_type, event_id)` index. It protects against double-processing on AbacatePay retries — `Pay::Webhook` records are destroyed after processing, so without this table a retry that arrives after the original ACK would create a duplicate `Pay::Charge`.
 
+### Creating a subscription
+
+`Customer#subscribe` creates the subscription on AbacatePay and returns a `Pay::Abacatepay::Subscription` persisted with the status mapped from AbacatePay's response. In the typical flow the subscription comes back as `PENDING` (mapped to `"incomplete"`); redirect the payer to `subscription.checkout_url` to complete the first payment, and the `subscription.completed` webhook then flips the local status to `"active"` and fills in `current_period_*`. If AbacatePay responds with `PAID` (e.g., a saved payment method settled immediately), `subscribe` returns the subscription already as `"active"`.
+
+```ruby
+subscription = user.payment_processor.subscribe(
+  name: "Pro",
+  plan: "prod_xxx",                   # AbacatePay product_id (must exist with cycle set)
+  cycle: "MONTHLY",                   # optional; sets an optimistic current_period_end
+  methods: ["PIX", "CARD"],           # defaults shown; a single string is also accepted and normalized
+  quantity: 1,                        # default; positive integer
+  external_id: "order-1234",          # optional
+  metadata: {release_id: order.id}    # local-only, not yet sent to AbacatePay
+)
+
+redirect_to subscription.checkout_url # first payment (when status is "incomplete")
+subscription.processor_id             # "subs_xxx"
+subscription.status                   # usually "incomplete" → flipped to "active" by webhook; can be "active" already if the API returned PAID
+```
+
+`plan` is the AbacatePay `product_id`. Cycle is a Product property, not a Subscription property — pass `cycle:` here purely so the gem can compute `current_period_end` immediately; otherwise it stays `nil` until the webhook arrives.
+
+Trial periods are unsupported: passing `trial_period_days:` or `trial_end:` raises `Pay::Abacatepay::Error`. AbacatePay simply has no trial primitive, and silently dropping it would charge the customer immediately — fail-fast surfaces the divergence.
+
 ### Supported operations
 
 | Operation | Support |
 |---|---|
+| `Customer#subscribe` (create subscription from code) | yes (PIX/CARD; no trial; `cycle:` and `quantity:` optional) |
 | Webhook-driven `Pay::Subscription` create/update | yes |
 | `Pay::Charge` creation per renewal | yes, idempotent via `processor_id = data.payment.id` |
 | `#cancel_now!` (immediate cancellation) | yes (calls `POST /v2/subscriptions/cancel` directly — SDK does not cover) |
@@ -162,10 +190,13 @@ The migration creates `pay_abacatepay_processed_webhooks`, a permanent table wit
 AbacatePay's API is narrower than Stripe's, so several `Pay::Subscription` affordances are intentionally not implemented:
 
 - **No cancel-at-period-end.** AbacatePay cancels immediately. `#cancel` delegates to `#cancel_now!` and logs a warning so code paths that assume Stripe-like grace periods notice the divergence.
-- **No plan swap.** `#swap` raises `NotImplementedError`. Cancel and create a new subscription instead.
+- **No trial periods.** Passing `trial_period_days:` or `trial_end:` to `Customer#subscribe` raises `Pay::Abacatepay::Error`.
+- **Cycle is a Product property.** Pass `cycle:` to `subscribe` for an immediate `current_period_end`; otherwise it stays `nil` until the `subscription.completed` webhook arrives.
+- **`metadata` not yet sent to AbacatePay.** `Customer#subscribe(metadata:)` stores values locally on `Pay::Subscription#metadata` only — the SDK's `SubscriptionClient#create` doesn't include `metadata` in the request body yet. Pending upstream PR.
+- **No plan swap.** `#swap` raises `NotImplementedError`. Cancel and create a new subscription instead. (AbacatePay added `POST /v2/subscriptions/change-plan` on 2026-05-04 — implementation pending.)
 - **No resume.** `#resume` raises `NotImplementedError`. Cancelled subscriptions cannot be reactivated.
 - **No quantity changes.** `#change_quantity` raises `NotImplementedError`.
-- **No `past_due` state.** AbacatePay does not emit payment-failure events, so `#past_due?` always returns `false`.
+- **No `past_due` state.** `#past_due?` always returns `false`. (AbacatePay added `subscription.payment_failed` on 2026-04-29 — handler implementation pending.)
 - **No `Subscriptions.retrieve` / `Subscriptions.cancel` in the SDK (v0.2.x).** Both calls are made via the SDK's Faraday client directly. Filed upstream.
 - **`subscription.trial_started`.** Handler is registered but raises `NotImplementedError` — the event is not listed in `AbacatePay::Enums::Webhooks::EventTypes`, so we fail-loud until it is confirmed.
 

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

@@ -44,7 +44,7 @@ module Pay
 
       CheckoutResult = Struct.new(:id, :url, :charge, keyword_init: true)
 
-      def charge(amount, product_id: nil, methods: ["PIX", "CARD"], return_url: nil, completion_url: nil, external_id: nil, product_name: "Cobrança avulsa", metadata: nil)
+      def charge(amount, product_id: nil, methods: ["PIX", "CARD"], return_url: nil, completion_url: nil, external_id: nil, product_name: "Cobrança avulsa", metadata: nil, coupons: nil)
         api_record unless processor_id?
 
         product_id ||= create_one_time_product(amount, product_name)
@@ -54,7 +54,8 @@ module Pay
           methods: methods,
           return_url: return_url,
           completion_url: completion_url,
-          external_id: external_id
+          external_id: external_id,
+          coupons: coupons
         )
         created = ::AbacatePay.checkouts.create(resource)
 
@@ -74,8 +75,33 @@ module Pay
         raise Pay::Abacatepay::Error, e.message
       end
 
-      def subscribe(name: Pay.default_product_name, plan: Pay.default_plan_name, **options)
-        raise NotImplementedError, "Pay::Abacatepay::Customer#subscribe is planned for a future release"
+      def subscribe(name: Pay.default_product_name, plan: nil, methods: ["PIX", "CARD"], quantity: 1, external_id: nil, metadata: nil, cycle: nil, **options)
+        methods = Array(methods).reject(&:blank?)
+        validate_subscribe_args!(plan: plan, methods: methods, quantity: quantity, cycle: cycle, options: options)
+        api_record unless processor_id?
+
+        resource = build_subscription_resource(plan: plan, methods: methods, external_id: external_id, quantity: quantity)
+        created = ::AbacatePay.subscriptions.create(resource)
+
+        period_start = Time.current
+        period_end = cycle ? period_start + Pay::Abacatepay::Frequency.to_interval(cycle) : nil
+
+        pay_subscription = Pay::Abacatepay::Subscription.find_or_initialize_by(customer: self, processor_id: created.id)
+        pay_subscription.assign_attributes(
+          name: name,
+          processor_plan: plan,
+          quantity: quantity,
+          status: Pay::Abacatepay::Subscription::API_STATUS_MAP[created.status&.to_s&.upcase] || "incomplete",
+          current_period_start: period_start,
+          current_period_end: period_end,
+          checkout_url: created.url
+        )
+        pay_subscription.metadata = metadata if metadata.present?
+        pay_subscription.save!
+
+        pay_subscription
+      rescue ::AbacatePay::Error => e
+        raise Pay::Abacatepay::Error, e.message
       end
 
       def add_payment_method(payment_method_id, default: false)
@@ -84,6 +110,34 @@ module Pay
 
       private
 
+      def validate_subscribe_args!(plan:, methods:, quantity:, cycle:, options:)
+        raise Pay::Abacatepay::Error, "plan is required (AbacatePay product_id)" if plan.blank?
+        raise Pay::Abacatepay::Error, "methods cannot be empty" if methods.empty?
+
+        unless quantity.is_a?(Integer) && quantity.positive?
+          raise Pay::Abacatepay::Error, "quantity must be a positive integer (got #{quantity.inspect})"
+        end
+
+        if cycle && !Pay::Abacatepay::Frequency.valid?(cycle)
+          raise Pay::Abacatepay::Error,
+            "invalid cycle: #{cycle.inspect}. Use one of: #{Pay::Abacatepay::Frequency::INTERVALS.keys.join(", ")}"
+        end
+
+        if options.key?(:trial_period_days) || options.key?(:trial_end)
+          raise Pay::Abacatepay::Error,
+            "AbacatePay does not support trial periods; remove trial_period_days/trial_end"
+        end
+      end
+
+      def build_subscription_resource(plan:, methods:, external_id:, quantity:)
+        ::AbacatePay::Resources::Subscriptions.new(
+          methods: methods,
+          externalId: external_id,
+          customer: {id: processor_id},
+          products: [{externalId: plan, quantity: quantity}]
+        )
+      end
+
       def create_one_time_product(amount, product_name)
         resource = ::AbacatePay::Resources::Products.new(
           external_id: "pay-abacatepay-#{SecureRandom.hex(8)}",
@@ -95,14 +149,15 @@ module Pay
         created.id
       end
 
-      def build_checkout_resource(product_id:, quantity:, methods:, return_url:, completion_url:, external_id:)
+      def build_checkout_resource(product_id:, quantity:, methods:, return_url:, completion_url:, external_id:, coupons: nil)
         ::AbacatePay::Resources::Checkouts.new(
           frequency: "ONE_TIME",
           methods: methods,
           metadata: {returnUrl: return_url, completionUrl: completion_url}.compact,
           products: [{externalId: product_id, quantity: quantity}],
           customer: {id: processor_id},
-          externalId: external_id
+          externalId: external_id,
+          coupons: coupons.presence
         )
       end
 

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

@@ -7,6 +7,20 @@ module Pay
         "subscription.cancelled" => "canceled"
       }.freeze
 
+      # Maps AbacatePay API checkout-like statuses (Resources::Subscriptions
+      # reuses Enums::Checkouts::Statuses) to local Pay::Subscription statuses.
+      # PENDING is the default on creation: the first payment hasn't settled
+      # yet, mirroring Stripe's "incomplete".
+      API_STATUS_MAP = {
+        "PENDING" => "incomplete",
+        "PAID" => "active",
+        "CANCELLED" => "canceled",
+        "EXPIRED" => "canceled",
+        "REFUNDED" => "canceled"
+      }.freeze
+
+      store_accessor :data, :checkout_url
+
       def self.sync(processor_id, event: nil)
         return if processor_id.blank?
 

data/lib/pay/abacatepay/frequency.rb

@@ -0,0 +1,20 @@
+module Pay
+  module Abacatepay
+    module Frequency
+      INTERVALS = {
+        "WEEKLY" => 1.week,
+        "MONTHLY" => 1.month,
+        "SEMIANNUALLY" => 6.months,
+        "ANNUALLY" => 1.year
+      }.freeze
+
+      def self.to_interval(freq)
+        INTERVALS[freq]
+      end
+
+      def self.valid?(freq)
+        INTERVALS.key?(freq)
+      end
+    end
+  end
+end

data/lib/pay/abacatepay/version.rb

@@ -1,5 +1,5 @@
 module Pay
   module Abacatepay
-    VERSION = "0.1.0.pre.2"
+    VERSION = "0.1.0.pre.3"
   end
 end

data/lib/pay/abacatepay/webhooks/event.rb

@@ -2,13 +2,6 @@ module Pay
   module Abacatepay
     module Webhooks
       class Event
-        FREQUENCY_TO_INTERVAL = {
-          "WEEKLY" => 1.week,
-          "MONTHLY" => 1.month,
-          "SEMIANNUALLY" => 6.months,
-          "ANNUALLY" => 1.year
-        }.freeze
-
         def initialize(raw)
           @raw = raw.is_a?(Hash) ? raw : {}
         end
@@ -80,7 +73,7 @@ module Pay
         def product_id = data.dig("checkout", "items", 0, "id")
 
         def interval
-          FREQUENCY_TO_INTERVAL[frequency]
+          Pay::Abacatepay::Frequency.to_interval(frequency)
         end
 
         private

data/lib/pay/abacatepay.rb

@@ -16,6 +16,7 @@ module Pay
     # live in app/models/pay/abacatepay/ — Zeitwerk autoloads them from the host
     # app, which is required so STI subclasses get reloaded together with their
     # superclass (Pay::Customer/Charge/...) during dev reloads.
+    autoload :Frequency, "pay/abacatepay/frequency"
     autoload :Webhooks, "pay/abacatepay/webhooks"
 
     # Enabled when the processor is registered and the SDK constant is present.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pay-abacatepay
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.2
+  version: 0.1.0.pre.3
 platform: ruby
 authors:
 - Daniel Moreira
@@ -59,6 +59,7 @@ files:
 - lib/pay-abacatepay.rb
 - lib/pay/abacatepay.rb
 - lib/pay/abacatepay/engine.rb
+- lib/pay/abacatepay/frequency.rb
 - lib/pay/abacatepay/version.rb
 - lib/pay/abacatepay/webhooks.rb
 - lib/pay/abacatepay/webhooks/checkout_completed.rb