metrifox-sdk 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cdf295c1adaab10f96e19c3075c40731a28bb799a1a696ff956abfaf2f0a724
-  data.tar.gz: 5c964c16f80530bd851132092261a09939473c60e53fe9d65ef309a9d354b9e7
+  metadata.gz: 5b50b292611bbf15e93297b499fe95c413bb78742469c7f8fe3c72b828c0c562
+  data.tar.gz: f2927b301e5b5e2f52f3bf900bddb92438ad5e3372c4cddf32e101bf9596ce9e
 SHA512:
-  metadata.gz: 7f391b66aae02c8854acd698a3f4031d0bf8996715367c28187346217b8a6be06fffce582cb42ace51de436e85bf3def974e0100c8364adeaddb5586522ec537
-  data.tar.gz: b8b03fe8d55a00d308b2affb7fc1fe6e8fe8a32a7d50b15cee248e406123690ad579e202331352a83b85bdfb75cff4f90c0b798bf59e924d3d625d2e058f8a15
+  metadata.gz: a17ff50508a89fee40d85b970b6fd51418fb1aff4695c58e9f1c240ebbf2c14f98bc9e12140e2c07999e9b7f4dd51a696f4003fab8a11082484b3d9e7a4089b2
+  data.tar.gz: 26309f0d2ef619f1149f294e487b6dcdca6f10a81f31af5890a13c8035c75bdd9c3a55aac2fb2cd506a583565dbbc764e3c6d0fd3f457ebf41604b09b57795ef

data/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
+
+## [1.3.0]
+- Add `wallets` module with `list`, `list_credit_allocations`, and `get_credit_allocation` methods.
+- Add `customers.archive` and `customers.unarchive`.
+- Add `checkout.card_collection_url(subscription_id:, order_id:)` for generating card-collection URLs.
+- Add `usages.list_events` for listing recorded usage events with optional filters and pagination.
+- Add `usages.quantity_price(customer_key:, feature_key:, quantity:)` for computing the price of a usage quantity.
+- Allow overriding the meter service base URL via `meter_service_base_url` config or `METRIFOX_METER_SERVICE_BASE_URL` env var.
+
+## [1.2.x]
 - Update usage access and recording to call the meter service (`https://api-meter.metrifox.com`).
 
 ## [1.0.3] - 2025-09-01

data/README.md

@@ -36,6 +36,15 @@ METRIFOX_SDK = MetrifoxSDK.init({ api_key: "your-api-key"})
 ENV["METRIFOX_API_KEY"] = "your-api-key"
 METRIFOX_SDK = MetrifoxSDK.init
 
+# Override base URLs (e.g. for staging or self-hosted environments)
+METRIFOX_SDK = MetrifoxSDK.init({
+  api_key: "your-api-key",
+  base_url: "https://api.staging.metrifox.com/api/v1/",
+  meter_service_base_url: "https://api-meter.staging.metrifox.com/"
+})
+
+# The meter service URL can also be set via env var
+ENV["METRIFOX_METER_SERVICE_BASE_URL"] = "https://api-meter.staging.metrifox.com/"
 ```
 
 ### Access Control
@@ -189,6 +198,41 @@ response = METRIFOX_SDK.customers.list({
 # Delete customer
 response = METRIFOX_SDK.customers.delete_customer({ customer_key: "customer_123" })
 
+# Archive customer
+response = METRIFOX_SDK.customers.archive("customer_123")
+
+# Unarchive customer
+response = METRIFOX_SDK.customers.unarchive("customer_123")
+
+```
+
+### Bulk Create Customers
+
+Create multiple customers in a single API call:
+
+```ruby
+result = METRIFOX_SDK.customers.bulk_create({
+  customers: [
+    {
+      customer_key: "customer_001",
+      customer_type: "BUSINESS",
+      primary_email: "contact@acme.com",
+      legal_name: "Acme Corp",
+      display_name: "Acme"
+    },
+    {
+      customer_key: "customer_002",
+      customer_type: "INDIVIDUAL",
+      primary_email: "jane@example.com",
+      first_name: "Jane",
+      last_name: "Doe"
+    }
+  ]
+})
+
+puts result["data"]["total"]
+puts result["data"]["successful_count"]
+puts result["data"]["failed_count"]
 ```
 
 ### CSV Upload
@@ -232,6 +276,76 @@ checkout_config = MetrifoxSDK::Types::CheckoutConfig.new(
 checkout_url = METRIFOX_SDK.checkout.url(checkout_config)
 ```
 
+### Card Collection URL
+
+Generate a hosted URL for collecting a payment method against an existing subscription or order:
+
+```ruby
+# For a subscription
+url = METRIFOX_SDK.checkout.card_collection_url(subscription_id: "sub_uuid_123")
+
+# For an order
+url = METRIFOX_SDK.checkout.card_collection_url(order_id: "order_uuid_456")
+```
+
+### Usage Events
+
+```ruby
+# List usage events with optional filters and pagination
+response = METRIFOX_SDK.usages.list_events(
+  customer_key: "customer_123",   # optional
+  feature_key: "feature_seats",   # optional
+  page: 1,                        # optional
+  per_page: 25                    # optional
+)
+
+response["data"].each do |event|
+  puts "#{event['feature_key']}: #{event['quantity']} at #{event['timestamp']}"
+end
+```
+
+### Compute Quantity Price
+
+Compute the price for a given quantity of a feature for a customer, based on their plan. Useful for previewing upgrade costs or showing the cost of additional usage before a customer commits.
+
+```ruby
+response = METRIFOX_SDK.usages.quantity_price(
+  customer_key: "customer_123",
+  feature_key: "feature_interview_booking",
+  quantity: 500
+)
+
+puts "#{response['data']['price']} #{response['data']['unit']}"
+
+# For tiered pricing, inspect the per-tier breakdown
+response["data"]["applied_tiers"].each do |tier|
+  puts "  Tier #{tier['first_unit']}-#{tier['last_unit']}: #{tier['units_consumed']} units -> #{tier['tier_price']}"
+end
+```
+
+> Only available to tenants whose plan includes the finance API feature.
+
+### Wallets
+
+```ruby
+# List wallets for a customer
+response = METRIFOX_SDK.wallets.list("customer_123")
+response["data"].each do |wallet|
+  puts "#{wallet['name']}: #{wallet['balance']} #{wallet['credit_unit_plural']}"
+end
+
+# List credit allocations for a wallet (optionally filtered by status)
+response = METRIFOX_SDK.wallets.list_credit_allocations("wallet_uuid_123")
+response = METRIFOX_SDK.wallets.list_credit_allocations("wallet_uuid_123", status: "active")
+
+# Get a single credit allocation with its transactions
+response = METRIFOX_SDK.wallets.get_credit_allocation("alloc_uuid_123")
+puts response["data"]["amount"]
+response["data"]["transactions"].each do |txn|
+  puts "  #{txn['amount']} at #{txn['created_at']}"
+end
+```
+
 ### Subscriptions
 
 ```ruby
@@ -252,6 +366,26 @@ response = METRIFOX_SDK.subscriptions.get_entitlements_usage("subscription_uuid"
 puts response["data"]
 ```
 
+### Bulk Assign Plan
+
+Assign a plan to multiple customers at once:
+
+```ruby
+result = METRIFOX_SDK.subscriptions.bulk_assign_plan(
+  customer_keys: ["customer_001", "customer_002"],
+  plan_key: "pro-plan",
+  billing_interval: "monthly",          # optional
+  currency_code: "USD",                 # optional
+  items: [                              # optional: credit/feature quantities
+    { credit_key: "api_credits", quantity: 500 }
+  ],
+  skip_invoice: false                   # optional
+)
+
+puts result["data"]["succeeded"]  # Array of successful assignments
+puts result["data"]["failed"]     # Array of failures with error details
+```
+
 ### Using Client Instance
 
 ```ruby

data/lib/metrifox-sdk.rb

@@ -11,6 +11,8 @@ require_relative "metrifox_sdk/checkout/api"
 require_relative "metrifox_sdk/checkout/module"
 require_relative "metrifox_sdk/subscriptions/api"
 require_relative "metrifox_sdk/subscriptions/module"
+require_relative "metrifox_sdk/wallets/api"
+require_relative "metrifox_sdk/wallets/module"
 
 module MetrifoxSDK
   class << self

data/lib/metrifox_sdk/checkout/api.rb

@@ -19,5 +19,13 @@ module MetrifoxSDK::Checkout
       data = parse_response(response, "Failed to generate checkout URL")
       data.dig("data", "checkout_url")
     end
+
+    def generate_card_collection_url(base_url, api_key, query_params)
+      uri = URI.join(base_url, "checkout/generate-card-collection-url")
+      uri.query = URI.encode_www_form(query_params)
+      response = make_request(uri, "GET", api_key)
+      data = parse_response(response, "Failed to generate card collection URL")
+      data.dig("data", "checkout_url")
+    end
   end
 end

data/lib/metrifox_sdk/checkout/module.rb

@@ -26,6 +26,23 @@ module MetrifoxSDK
         checkout_url
       end
 
+      def card_collection_url(subscription_id: nil, order_id: nil)
+        validate_api_key!
+
+        if (subscription_id.nil? || subscription_id.to_s.empty?) && (order_id.nil? || order_id.to_s.empty?)
+          raise ArgumentError, "Either subscription_id or order_id is required"
+        end
+
+        query_params = {}
+        query_params[:subscription_id] = subscription_id if subscription_id && !subscription_id.to_s.empty?
+        query_params[:order_id] = order_id if order_id && !order_id.to_s.empty?
+
+        checkout_url = api.generate_card_collection_url(base_url, api_key, query_params)
+        raise StandardError, "Card collection URL could not be generated" if checkout_url.nil? || checkout_url.empty?
+
+        checkout_url
+      end
+
       private
 
       def get_checkout_key

data/lib/metrifox_sdk/client.rb

@@ -15,7 +15,7 @@ module MetrifoxSDK
       @api_key = config[:api_key] || get_api_key_from_environment
       @base_url = config[:base_url] || DEFAULT_BASE_URL
       @web_app_base_url = config[:web_app_base_url] || DEFAULT_WEB_APP_BASE_URL
-      @meter_service_base_url = METER_SERVICE_BASE_URL
+      @meter_service_base_url = config[:meter_service_base_url] || ENV["METRIFOX_METER_SERVICE_BASE_URL"] || METER_SERVICE_BASE_URL
     end
 
     def customers
@@ -34,6 +34,10 @@ module MetrifoxSDK
       @subscriptions ||= Subscriptions::Module.new(self)
     end
 
+    def wallets
+      @wallets ||= Wallets::Module.new(self)
+    end
+
     private
 
     def get_api_key_from_environment

data/lib/metrifox_sdk/customers/api.rb

@@ -47,6 +47,18 @@ module MetrifoxSDK::Customers
       parse_response(response, "Failed to Check Active Subscription")
     end
 
+    def customer_archive_request(base_url, api_key, customer_key)
+      uri = URI.join(base_url, "customers/#{customer_key}/archive")
+      response = make_request(uri, "POST", api_key)
+      parse_response(response, "Failed to Archive Customer")
+    end
+
+    def customer_unarchive_request(base_url, api_key, customer_key)
+      uri = URI.join(base_url, "customers/#{customer_key}/unarchive")
+      response = make_request(uri, "POST", api_key)
+      parse_response(response, "Failed to Unarchive Customer")
+    end
+
     def customer_list_request(base_url, api_key, request_payload = {})
       uri = URI.join(base_url, "customers")
       
@@ -75,6 +87,13 @@ module MetrifoxSDK::Customers
       parse_response(response, "Failed to upload CSV")
     end
 
+    def bulk_create_request(base_url, api_key, request_payload)
+      uri = URI.join(base_url, "customers/bulk-create")
+      body = serialize_customer_request(request_payload)
+      response = make_request(uri, "POST", api_key, body)
+      parse_response(response, "Failed to Bulk Create Customers")
+    end
+
     private
 
     def serialize_customer_request(request)

data/lib/metrifox_sdk/customers/module.rb

@@ -44,6 +44,16 @@ module MetrifoxSDK
         delete_customer(request_payload)
       end
 
+      def archive(customer_key)
+        validate_api_key!
+        api.customer_archive_request(base_url, api_key, customer_key)
+      end
+
+      def unarchive(customer_key)
+        validate_api_key!
+        api.customer_unarchive_request(base_url, api_key, customer_key)
+      end
+
       def list(request_payload = {})
         validate_api_key!
         api.customer_list_request(base_url, api_key, request_payload)
@@ -54,6 +64,11 @@ module MetrifoxSDK
         api.upload_customers_csv(base_url, api_key, file_path)
       end
 
+      def bulk_create(request_payload)
+        validate_api_key!
+        api.bulk_create_request(base_url, api_key, request_payload)
+      end
+
       private
 
       def api

data/lib/metrifox_sdk/subscriptions/api.rb

@@ -22,5 +22,18 @@ module MetrifoxSDK::Subscriptions
       response = make_request(uri, "GET", api_key)
       parse_response(response, "Failed to Fetch Entitlements Usage")
     end
+
+    def bulk_assign_plan_request(base_url, api_key, request_payload)
+      uri = URI.join(base_url, "subscriptions/bulk-assign-plan")
+      body = if request_payload.respond_to?(:to_h)
+               request_payload.to_h.compact
+             elsif request_payload.is_a?(Hash)
+               request_payload.compact
+             else
+               raise ArgumentError, "Invalid request format"
+             end
+      response = make_request(uri, "POST", api_key, body)
+      parse_response(response, "Failed to Bulk Assign Plan")
+    end
   end
 end

data/lib/metrifox_sdk/subscriptions/module.rb

@@ -19,6 +19,19 @@ module MetrifoxSDK
         api.entitlements_usage_request(base_url, api_key, subscription_id)
       end
 
+      def bulk_assign_plan(customer_keys:, plan_key:, billing_interval: nil, currency_code: nil, items: nil, skip_invoice: nil)
+        validate_api_key!
+        request_payload = {
+          customer_keys: customer_keys,
+          plan_key: plan_key,
+          billing_interval: billing_interval,
+          currency_code: currency_code,
+          items: items,
+          skip_invoice: skip_invoice
+        }.compact
+        api.bulk_assign_plan_request(base_url, api_key, request_payload)
+      end
+
       private
 
       def api

data/lib/metrifox_sdk/usages/api.rb

@@ -52,6 +52,20 @@ module MetrifoxSDK::Usages
       parse_response(response, "Failed to record usage")
     end
 
+    def list_events(base_url, api_key, query_params = {})
+      uri = URI.join(base_url, "usage/events")
+      uri.query = URI.encode_www_form(query_params) unless query_params.empty?
+      response = make_request(uri, "GET", api_key)
+      parse_response(response, "Failed to list usage events")
+    end
+
+    def quantity_price(base_url, api_key, customer_key:, feature_key:, quantity:)
+      uri = URI.join(base_url, "usage/quantity-price")
+      uri.query = URI.encode_www_form(customer_key: customer_key, feature_key: feature_key, quantity: quantity)
+      response = make_request(uri, "GET", api_key)
+      parse_response(response, "Failed to compute quantity price")
+    end
+
     def fetch_tenant_id(base_url, api_key)
       uri = URI.join(base_url, "auth/get-tenant-id")
       response = make_request(uri, "GET", api_key)

data/lib/metrifox_sdk/usages/module.rb

@@ -14,6 +14,21 @@ module MetrifoxSDK
         api.record_usage(meter_service_base_url, api_key, request_payload)
       end
 
+      def list_events(customer_key: nil, feature_key: nil, page: nil, per_page: nil)
+        validate_api_key!
+        query_params = {}
+        query_params[:customer_key] = customer_key if customer_key
+        query_params[:feature_key] = feature_key if feature_key
+        query_params[:page] = page if page
+        query_params[:per_page] = per_page if per_page
+        api.list_events(meter_service_base_url, api_key, query_params)
+      end
+
+      def quantity_price(customer_key:, feature_key:, quantity:)
+        validate_api_key!
+        api.quantity_price(base_url, api_key, customer_key: customer_key, feature_key: feature_key, quantity: quantity)
+      end
+
       def get_tenant_id
         validate_api_key!
         api.fetch_tenant_id(base_url, api_key)

data/lib/metrifox_sdk/version.rb

@@ -1,3 +1,3 @@
 module MetrifoxSDK
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

data/lib/metrifox_sdk/wallets/api.rb

@@ -0,0 +1,28 @@
+require "net/http"
+require "uri"
+require "json"
+require_relative "../base_api"
+
+module MetrifoxSDK::Wallets
+  class API < MetrifoxSDK::BaseApi
+    def list_wallets(base_url, api_key, customer_key)
+      uri = URI.join(base_url, "credit_systems/v2/wallets")
+      uri.query = URI.encode_www_form(customer_key: customer_key)
+      response = make_request(uri, "GET", api_key)
+      parse_response(response, "Failed to list wallets")
+    end
+
+    def list_credit_allocations(base_url, api_key, wallet_id, status: nil)
+      uri = URI.join(base_url, "credit_systems/v2/wallets/#{wallet_id}/credit-allocations")
+      uri.query = URI.encode_www_form(status: status) if status && !status.to_s.empty?
+      response = make_request(uri, "GET", api_key)
+      parse_response(response, "Failed to list credit allocations")
+    end
+
+    def get_credit_allocation(base_url, api_key, allocation_id)
+      uri = URI.join(base_url, "credit_systems/v2/credit-allocations/#{allocation_id}")
+      response = make_request(uri, "GET", api_key)
+      parse_response(response, "Failed to get credit allocation")
+    end
+  end
+end

data/lib/metrifox_sdk/wallets/module.rb

@@ -0,0 +1,29 @@
+require_relative "api"
+require_relative "../base_module"
+
+module MetrifoxSDK
+  module Wallets
+    class Module < BaseModule
+      def list(customer_key)
+        validate_api_key!
+        api.list_wallets(base_url, api_key, customer_key)
+      end
+
+      def list_credit_allocations(wallet_id, status: nil)
+        validate_api_key!
+        api.list_credit_allocations(base_url, api_key, wallet_id, status: status)
+      end
+
+      def get_credit_allocation(allocation_id)
+        validate_api_key!
+        api.get_credit_allocation(base_url, api_key, allocation_id)
+      end
+
+      private
+
+      def api
+        @api ||= API.new
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metrifox-sdk
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Metrifox
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-16 00:00:00.000000000 Z
+date: 2026-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -133,6 +133,8 @@ files:
 - lib/metrifox_sdk/usages/module.rb
 - lib/metrifox_sdk/util_methods.rb
 - lib/metrifox_sdk/version.rb
+- lib/metrifox_sdk/wallets/api.rb
+- lib/metrifox_sdk/wallets/module.rb
 homepage: https://github.com/metrifox/metrifox-ruby
 licenses:
 - MIT