billingio 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be246a686bc1dac9b2c0bf75a6f66c5f77b58ba205ad72628a09d72a57d4a9e0
-  data.tar.gz: 610719813172e602cc3b78c4f5b21120d91320a34945fc483c6ecc9743a4f8af
+  metadata.gz: 8be425bd5a196519fc083794cb40c7d6e0aeade7354739867e9221f67e57538a
+  data.tar.gz: 9fe922dc7b07f6af96df71d73dc9a40b008a62cf297e7b2b8b24303dea833a11
 SHA512:
-  metadata.gz: dfce4a65d73b3c03f3a968fe376c4b6ca47d22fa5f693c8134672b94c09972872109b00b5abd3047d22a84f27b7acbb57fbc26860d1f100411cc03cd37b241a3
-  data.tar.gz: a47bdd1a11a97832bb68bb3d0c17baa6f45b6259430106a3e859b7266b39bf75238541c61995f01c6f700b1ddc25ca9cdb1c7e880dcf407d93d39a403cc3c6f5
+  metadata.gz: 716b4c36731a3cffe27fb2342379e1ed75ab83958f1845621b21dee41833f5ace4dc2ab1eb5e64ad0eb8c801ae5f8d86e98c29c497a2b79356d28dc28381b373
+  data.tar.gz: 718ef6e1f6a2ac87710095902585c5eaa2685151109ff0f87217d5cdcd14ed5f5f21da3fd2fd612f815c9bc340c155e60648cffc0f876cef9872e8be245ce7d6

data/README.md

@@ -1,8 +1,12 @@
 # billingio
 
-Official Ruby SDK for the [billing.io](https://billing.io) crypto checkout API.
+Official Ruby SDK for the [billing.io](https://billing.io) payments platform.
 
+- Manage customers, payment methods, and payment links
 - Create payment checkouts settled in USDT / USDC on Tron or Arbitrum
+- Recurring billing with subscription plans, renewals, and entitlements
+- Payouts and settlement tracking
+- Revenue events, accounting reports, and adjustments
 - Manage webhook endpoints and verify signatures
 - Query event history with cursor-based pagination
 - Zero runtime dependencies (stdlib only)
@@ -57,6 +61,71 @@ puts status.required_confirmations   # => 19
 puts status.polling_interval_ms      # => 2000
 ```
 
+## Customers
+
+```ruby
+# Create a customer
+customer = client.customers.create(
+  email: "user@example.com",
+  name:  "Jane Doe",
+  metadata: { "org" => "acme" }
+)
+puts customer.customer_id  # => "cus_..."
+
+# List customers
+customers = client.customers.list(limit: 10)
+customers.each { |c| puts c.email }
+
+# Retrieve a customer
+customer = client.customers.get("cus_abc123")
+
+# Update a customer
+customer = client.customers.update("cus_abc123", name: "Jane Smith")
+```
+
+## Payment Methods
+
+```ruby
+# Register a payment method
+pm = client.payment_methods.create(
+  customer_id: "cus_abc123",
+  type:        "wallet",
+  chain:       "tron",
+  token:       "USDT",
+  address:     "T..."
+)
+puts pm.payment_method_id  # => "pm_..."
+
+# List payment methods
+methods = client.payment_methods.list(customer_id: "cus_abc123")
+methods.each { |m| puts "#{m.payment_method_id}: #{m.type}" }
+
+# Update a payment method
+client.payment_methods.update("pm_abc123", metadata: { "label" => "primary" })
+
+# Set as default
+client.payment_methods.set_default("pm_abc123")
+
+# Delete a payment method
+client.payment_methods.delete("pm_abc123")
+```
+
+## Payment Links
+
+```ruby
+# Create a payment link
+link = client.payment_links.create(
+  amount_usd: 25.00,
+  chain:      "tron",
+  token:      "USDT"
+)
+puts link.url  # => "https://pay.billing.io/..."
+
+# List payment links
+links = client.payment_links.list
+links.each { |l| puts "#{l.payment_link_id}: #{l.url}" }
+```
+
 ## Checkouts
 
 ```ruby
@@ -79,6 +148,162 @@ list = client.checkouts.list(status: "confirmed", limit: 10)
 list.each { |c| puts c.checkout_id }
 ```
 
+## Subscription Plans
+
+```ruby
+# Create a plan
+plan = client.subscription_plans.create(
+  name:       "Pro Monthly",
+  amount_usd: 29.99,
+  interval:   "monthly"
+)
+puts plan.plan_id  # => "plan_..."
+
+# List plans
+plans = client.subscription_plans.list
+plans.each { |p| puts "#{p.plan_id}: #{p.name} ($#{p.amount_usd})" }
+
+# Update a plan
+client.subscription_plans.update("plan_abc123", name: "Pro Plus Monthly")
+```
+
+## Subscriptions
+
+```ruby
+# Create a subscription
+sub = client.subscriptions.create(
+  customer_id: "cus_abc123",
+  plan_id:     "plan_abc123"
+)
+puts sub.subscription_id  # => "sub_..."
+puts sub.status           # => "active"
+
+# List subscriptions
+subs = client.subscriptions.list(customer_id: "cus_abc123", status: "active")
+subs.each { |s| puts "#{s.subscription_id}: #{s.status}" }
+
+# Cancel a subscription
+client.subscriptions.update("sub_abc123", status: "canceled")
+```
+
+## Subscription Renewals
+
+```ruby
+# List renewals
+renewals = client.subscription_renewals.list(subscription_id: "sub_abc123")
+renewals.each { |r| puts "#{r.renewal_id}: #{r.status}" }
+
+# Retry a failed renewal
+renewal = client.subscription_renewals.retry("ren_abc123")
+puts renewal.status  # => "pending"
+```
+
+## Entitlements
+
+```ruby
+# Create an entitlement
+ent = client.entitlements.create(
+  subscription_id: "sub_abc123",
+  feature_key:     "api_calls",
+  value:           10_000
+)
+puts ent.entitlement_id  # => "ent_..."
+
+# List entitlements
+ents = client.entitlements.list(subscription_id: "sub_abc123")
+ents.each { |e| puts "#{e.feature_key}: #{e.value}" }
+
+# Update an entitlement
+client.entitlements.update("ent_abc123", value: 50_000)
+
+# Check entitlement access
+check = client.entitlements.check(
+  customer_id: "cus_abc123",
+  feature_key: "api_calls"
+)
+puts check.entitled    # => true
+puts check.value       # => 50000
+
+# Delete an entitlement
+client.entitlements.delete("ent_abc123")
+```
+
+## Payout Intents
+
+```ruby
+# Create a payout
+payout = client.payout_intents.create(
+  amount_usd:  500.00,
+  chain:       "tron",
+  token:       "USDT",
+  destination: "T..."
+)
+puts payout.payout_id  # => "po_..."
+puts payout.status     # => "pending"
+
+# List payouts
+payouts = client.payout_intents.list(status: "pending")
+payouts.each { |p| puts "#{p.payout_id}: $#{p.amount_usd}" }
+
+# Update a payout
+client.payout_intents.update("po_abc123", metadata: { "ref" => "inv_001" })
+
+# Execute a payout (trigger on-chain transfer)
+payout = client.payout_intents.execute("po_abc123")
+puts payout.status   # => "executing"
+puts payout.tx_hash  # => "0x..."
+```
+
+## Settlements
+
+```ruby
+# List settlements
+settlements = client.settlements.list
+settlements.each do |s|
+  puts "#{s.settlement_id}: $#{s.net_usd} (fee: $#{s.fee_usd})"
+end
+
+# Filter by payout
+settlements = client.settlements.list(payout_id: "po_abc123")
+```
+
+## Revenue Events
+
+```ruby
+# List revenue events
+events = client.revenue_events.list(type: "payment", customer_id: "cus_abc123")
+events.each do |e|
+  puts "#{e.revenue_event_id}: #{e.type} $#{e.amount_usd}"
+end
+
+# Get accounting summary
+report = client.revenue_events.accounting(
+  period_start: "2025-01-01",
+  period_end:   "2025-01-31"
+)
+puts report.total_revenue       # => 12500.00
+puts report.total_fees          # => 125.00
+puts report.total_net           # => 12375.00
+puts report.transaction_count   # => 340
+```
+
+## Adjustments
+
+```ruby
+# Create a revenue adjustment
+adj = client.adjustments.create(
+  type:        "credit",
+  amount_usd:  10.00,
+  reason:      "Goodwill credit",
+  customer_id: "cus_abc123"
+)
+puts adj.adjustment_id  # => "adj_..."
+
+# List adjustments
+adjustments = client.adjustments.list(customer_id: "cus_abc123")
+adjustments.each { |a| puts "#{a.adjustment_id}: #{a.type} $#{a.amount_usd}" }
+```
+
 ## Webhook Endpoints
 
 ```ruby

data/billingio.gemspec

@@ -8,10 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ["billing.io"]
   spec.email         = ["support@billing.io"]
 
-  spec.summary       = "Ruby SDK for the billing.io crypto checkout API"
+  spec.summary       = "Ruby SDK for the billing.io payments platform"
   spec.description   = "Official Ruby client for billing.io -- non-custodial crypto " \
-                        "payment checkouts with stablecoin settlement. Create checkouts, " \
-                        "manage webhooks, verify signatures, and query event history."
+                        "payments with stablecoin settlement. Manage customers, checkouts, " \
+                        "subscriptions, payouts, revenue tracking, entitlements, webhooks, " \
+                        "and more."
   spec.homepage      = "https://github.com/billingio/billingio-ruby"
   spec.license       = "MIT"
 

data/lib/billingio/client.rb

@@ -40,5 +40,60 @@ module BillingIO
     def health
       @health ||= Health.new(@http)
     end
+
+    # @return [BillingIO::Customers]
+    def customers
+      @customers ||= Customers.new(@http)
+    end
+
+    # @return [BillingIO::PaymentMethods]
+    def payment_methods
+      @payment_methods ||= PaymentMethods.new(@http)
+    end
+
+    # @return [BillingIO::PaymentLinks]
+    def payment_links
+      @payment_links ||= PaymentLinks.new(@http)
+    end
+
+    # @return [BillingIO::SubscriptionPlans]
+    def subscription_plans
+      @subscription_plans ||= SubscriptionPlans.new(@http)
+    end
+
+    # @return [BillingIO::Subscriptions]
+    def subscriptions
+      @subscriptions ||= Subscriptions.new(@http)
+    end
+
+    # @return [BillingIO::SubscriptionRenewals]
+    def subscription_renewals
+      @subscription_renewals ||= SubscriptionRenewals.new(@http)
+    end
+
+    # @return [BillingIO::Entitlements]
+    def entitlements
+      @entitlements ||= Entitlements.new(@http)
+    end
+
+    # @return [BillingIO::PayoutIntents]
+    def payout_intents
+      @payout_intents ||= PayoutIntents.new(@http)
+    end
+
+    # @return [BillingIO::Settlements]
+    def settlements
+      @settlements ||= Settlements.new(@http)
+    end
+
+    # @return [BillingIO::RevenueEvents]
+    def revenue_events
+      @revenue_events ||= RevenueEvents.new(@http)
+    end
+
+    # @return [BillingIO::Adjustments]
+    def adjustments
+      @adjustments ||= Adjustments.new(@http)
+    end
   end
 end

data/lib/billingio/http_client.rb

@@ -37,6 +37,16 @@ module BillingIO
       execute(uri, request)
     end
 
+    def patch(path, body = nil)
+      uri = build_uri(path)
+      request = Net::HTTP::Patch.new(uri)
+      if body
+        request.body = JSON.generate(body)
+        request["Content-Type"] = "application/json"
+      end
+      execute(uri, request)
+    end
+
     def delete(path)
       uri = build_uri(path)
       request = Net::HTTP::Delete.new(uri)

data/lib/billingio/models/accounting_report.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents an accounting summary report.
+  #
+  # @attr_reader period_start    [String]  ISO-8601 period start
+  # @attr_reader period_end      [String]  ISO-8601 period end
+  # @attr_reader total_revenue   [Float]   total revenue in USD
+  # @attr_reader total_fees      [Float]   total fees in USD
+  # @attr_reader total_net       [Float]   total net revenue in USD
+  # @attr_reader transaction_count [Integer] number of transactions
+  # @attr_reader currency        [String]  report currency
+  class AccountingReport
+    ATTRS = %i[
+      period_start period_end total_revenue
+      total_fees total_net transaction_count currency
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::AccountingReport]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::AccountingReport period_start=#{@period_start.inspect} total_revenue=#{@total_revenue.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/adjustment.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a revenue adjustment (credit, debit, or correction).
+  #
+  # @attr_reader adjustment_id [String]      unique identifier (prefixed +adj_+)
+  # @attr_reader type          [String]      adjustment type (e.g. "credit", "debit", "correction")
+  # @attr_reader amount_usd    [Float]       adjustment amount in USD
+  # @attr_reader reason        [String, nil] human-readable reason
+  # @attr_reader customer_id   [String, nil] related customer
+  # @attr_reader metadata      [Hash, nil]   arbitrary key-value pairs
+  # @attr_reader created_at    [String]      ISO-8601 creation timestamp
+  class Adjustment
+    ATTRS = %i[
+      adjustment_id type amount_usd reason
+      customer_id metadata created_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::Adjustment]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::Adjustment adjustment_id=#{@adjustment_id.inspect} type=#{@type.inspect} amount_usd=#{@amount_usd.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/customer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a customer record.
+  #
+  # @attr_reader customer_id [String]      unique identifier (prefixed +cus_+)
+  # @attr_reader email       [String, nil] customer email address
+  # @attr_reader name        [String, nil] customer display name
+  # @attr_reader metadata    [Hash, nil]   arbitrary key-value pairs
+  # @attr_reader status      [String]      customer status
+  # @attr_reader created_at  [String]      ISO-8601 creation timestamp
+  # @attr_reader updated_at  [String]      ISO-8601 last-update timestamp
+  class Customer
+    ATTRS = %i[
+      customer_id email name metadata
+      status created_at updated_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::Customer]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::Customer customer_id=#{@customer_id.inspect} email=#{@email.inspect} status=#{@status.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/entitlement.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a subscription entitlement (feature or access grant).
+  #
+  # @attr_reader entitlement_id  [String]      unique identifier (prefixed +ent_+)
+  # @attr_reader subscription_id [String]      parent subscription
+  # @attr_reader feature_key     [String]      machine-readable feature identifier
+  # @attr_reader value           [Object, nil] entitlement value (boolean, numeric, or string)
+  # @attr_reader metadata        [Hash, nil]   arbitrary key-value pairs
+  # @attr_reader created_at      [String]      ISO-8601 creation timestamp
+  # @attr_reader updated_at      [String]      ISO-8601 last-update timestamp
+  class Entitlement
+    ATTRS = %i[
+      entitlement_id subscription_id feature_key
+      value metadata created_at updated_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::Entitlement]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::Entitlement entitlement_id=#{@entitlement_id.inspect} feature_key=#{@feature_key.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/entitlement_check.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents the result of an entitlement check.
+  #
+  # @attr_reader entitled   [Boolean]     whether the customer has the entitlement
+  # @attr_reader feature_key [String]     the feature key that was checked
+  # @attr_reader value       [Object, nil] entitlement value if entitled
+  class EntitlementCheck
+    ATTRS = %i[entitled feature_key value].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::EntitlementCheck]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::EntitlementCheck feature_key=#{@feature_key.inspect} entitled=#{@entitled.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/payment_link.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a reusable payment link.
+  #
+  # @attr_reader payment_link_id [String]      unique identifier (prefixed +pl_+)
+  # @attr_reader url             [String]      hosted payment URL
+  # @attr_reader amount_usd      [Float, nil]  fixed amount in USD (nil for open-amount)
+  # @attr_reader chain           [String, nil] blockchain network
+  # @attr_reader token           [String, nil] stablecoin token
+  # @attr_reader metadata        [Hash, nil]   arbitrary key-value pairs
+  # @attr_reader status          [String]      link status
+  # @attr_reader created_at      [String]      ISO-8601 creation timestamp
+  class PaymentLink
+    ATTRS = %i[
+      payment_link_id url amount_usd chain token
+      metadata status created_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::PaymentLink]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::PaymentLink payment_link_id=#{@payment_link_id.inspect} url=#{@url.inspect} status=#{@status.inspect}>"
+    end
+  end
+end

data/lib/billingio/models/payment_method.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module BillingIO
+  # Represents a stored payment method (wallet address or card token).
+  #
+  # @attr_reader payment_method_id [String]      unique identifier (prefixed +pm_+)
+  # @attr_reader customer_id       [String]      owning customer
+  # @attr_reader type              [String]      payment method type
+  # @attr_reader chain             [String, nil] blockchain network
+  # @attr_reader token             [String, nil] stablecoin token
+  # @attr_reader address           [String, nil] wallet address
+  # @attr_reader is_default        [Boolean]     whether this is the default method
+  # @attr_reader metadata          [Hash, nil]   arbitrary key-value pairs
+  # @attr_reader status            [String]      method status
+  # @attr_reader created_at        [String]      ISO-8601 creation timestamp
+  # @attr_reader updated_at        [String]      ISO-8601 last-update timestamp
+  class PaymentMethod
+    ATTRS = %i[
+      payment_method_id customer_id type chain token
+      address is_default metadata status
+      created_at updated_at
+    ].freeze
+
+    attr_reader(*ATTRS)
+
+    # @param attrs [Hash{String,Symbol => Object}]
+    def initialize(attrs = {})
+      ATTRS.each do |attr|
+        value = attrs[attr.to_s] || attrs[attr]
+        instance_variable_set(:"@#{attr}", value)
+      end
+    end
+
+    # @param hash [Hash]
+    # @return [BillingIO::PaymentMethod]
+    def self.from_hash(hash)
+      new(hash)
+    end
+
+    # @return [Hash{String => Object}]
+    def to_h
+      ATTRS.each_with_object({}) do |attr, h|
+        h[attr.to_s] = instance_variable_get(:"@#{attr}")
+      end
+    end
+
+    def inspect
+      "#<BillingIO::PaymentMethod payment_method_id=#{@payment_method_id.inspect} type=#{@type.inspect} is_default=#{@is_default.inspect}>"
+    end
+  end
+end