polar-ruby 0.1.0

data/examples/demo.rb

@@ -0,0 +1,106 @@
+#!/usr/bin/env ruby
+# Demo script showing the Polar Ruby SDK in action
+
+require_relative '../lib/polar'
+
+puts '🐻‍❄️  Polar Ruby SDK Demo'
+puts '=' * 50
+
+# Configuration example
+puts "\n📋 Configuration Examples:"
+puts "- Production client: Polar.new(access_token: 'polar_oat_...') "
+puts "- Sandbox client: Polar.new(access_token: 'polar_oat_...', server: :sandbox)"
+puts "- With customer session: Polar.new(customer_session: 'customer_session_...')"
+
+# Create a demo client (without real credentials)
+puts "\n🔧 Creating client instance..."
+client = Polar.new
+
+puts '✅ Client created successfully!'
+puts 'Available resources:'
+
+# List all available resources
+resources = %w[
+  organizations products customers orders payments subscriptions
+  checkouts benefits license_keys files metrics events webhooks oauth2
+]
+
+resources.each do |resource|
+  puts "  • #{resource}: #{client.send(resource).class.name}"
+end
+
+puts "\n👥 Customer Portal resources:"
+customer_portal_resources = %w[customers orders subscriptions benefit_grants license_keys]
+customer_portal_resources.each do |resource|
+  puts "  • #{resource}: #{client.customer_portal.send(resource).class.name}"
+end
+
+# Configuration demonstration
+puts "\n⚙️  Configuration examples:"
+Polar.configure do |config|
+  config.server = :sandbox
+  config.timeout = 60
+  config.retries = 5
+  config.debug = false
+end
+
+puts 'Global configuration set:'
+puts "  • Server: #{Polar.configuration.server}"
+puts "  • Timeout: #{Polar.configuration.timeout}s"
+puts "  • Retries: #{Polar.configuration.retries}"
+puts "  • Debug: #{Polar.configuration.debug}"
+
+# Error handling demonstration
+puts "\n🚨 Error handling capabilities:"
+error_classes = [
+  Polar::HTTPError, Polar::NotFoundError, Polar::UnauthorizedError,
+  Polar::ValidationError, Polar::WebhookVerificationError, Polar::TimeoutError
+]
+
+error_classes.each do |error_class|
+  puts "  • #{error_class.name}"
+end
+
+# Webhook verification demo
+puts "\n🔐 Webhook verification example:"
+payload = '{"type":"order.created","id":"evt_123","data":{"id":"order_123"}}'
+timestamp = Time.now.to_i.to_s
+secret = 'demo_webhook_secret'
+
+signature = Polar::Webhooks.compute_signature(payload, timestamp, secret)
+puts "  • Computed signature: #{signature[0..20]}..."
+
+# Event parsing
+event = Polar::Webhooks::Event.new(payload)
+puts "  • Event type: #{event.type}"
+puts "  • Event ID: #{event.id}"
+puts "  • Is order event: #{event.order_event?}"
+
+puts "\n🎯 Usage patterns:"
+puts '  • List with pagination: client.customers.list.each { |customer| ... }'
+puts '  • Auto-paginate: client.orders.list.auto_paginate'
+puts "  • Single resource: client.products.get('prod_123')"
+puts "  • Create resource: client.customers.create(email: '...', name: '...')"
+
+puts "\n✨ Key features:"
+puts '  ✅ Complete API coverage'
+puts '  ✅ Type-safe error handling'
+puts '  ✅ Automatic pagination'
+puts '  ✅ Retry logic with backoff'
+puts '  ✅ Webhook verification'
+puts '  ✅ Customer portal support'
+puts '  ✅ Environment switching (prod/sandbox)'
+puts '  ✅ Ruby 2.7+ compatibility'
+
+puts "\n📚 For detailed usage examples, see:"
+puts '  • README.md - Main documentation'
+puts '  • EXAMPLES.md - Comprehensive usage examples'
+puts '  • DEVELOPMENT.md - Development guide'
+
+puts "\n🔗 Resources:"
+puts '  • Polar.sh Documentation: https://polar.sh/docs'
+puts '  • API Reference: https://polar.sh/docs/api-reference'
+puts '  • Discord Community: https://discord.gg/polar'
+
+puts "\n🎉 SDK loaded and validated successfully!"
+puts 'Ready to integrate with Polar.sh payment infrastructure.'

data/lib/polar/authentication.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Polar
+  module Authentication
+    # Organization Access Token authentication
+    class OATAuth
+      attr_reader :access_token
+
+      def initialize(access_token)
+        @access_token = access_token
+        validate_token!
+      end
+
+      def headers
+        {
+          'Authorization' => "Bearer #{access_token}",
+          'Content-Type' => 'application/json',
+          'Accept' => 'application/json'
+        }
+      end
+
+      def valid?
+        !access_token.nil? && !access_token.empty? && access_token.start_with?('polar_oat_')
+      end
+
+      private
+
+      def validate_token!
+        return if valid?
+
+        raise AuthenticationError, 'Access token is required' if access_token.nil? || access_token.empty?
+
+        return if access_token.start_with?('polar_oat_')
+
+        raise AuthenticationError,
+              "Invalid Organization Access Token format. Expected token to start with 'polar_oat_'"
+      end
+    end
+
+    # Customer Access Token authentication
+    class CustomerAuth
+      attr_reader :customer_session
+
+      def initialize(customer_session)
+        @customer_session = customer_session
+        validate_token!
+      end
+
+      def headers
+        {
+          'Authorization' => "Bearer #{customer_session}",
+          'Content-Type' => 'application/json',
+          'Accept' => 'application/json'
+        }
+      end
+
+      def valid?
+        !customer_session.nil? && !customer_session.empty?
+      end
+
+      private
+
+      def validate_token!
+        return if valid?
+
+        raise AuthenticationError, 'Customer session token is required'
+      end
+    end
+
+    # Factory for creating appropriate authentication based on token type
+    class AuthFactory
+      def self.create(token)
+        return nil if token.nil? || token.empty?
+
+        if token.start_with?('polar_oat_')
+          OATAuth.new(token)
+        else
+          CustomerAuth.new(token)
+        end
+      end
+    end
+  end
+end

data/lib/polar/client.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Polar
+  class Client
+    include Pagination
+
+    attr_reader :configuration, :auth, :http_client
+
+    def initialize(options = {})
+      @configuration = build_configuration(options)
+      @auth = build_authentication(options)
+      @http_client = HTTPClient.new(@configuration, @auth)
+    end
+
+    # Core API Resources
+    def organizations
+      @organizations ||= Resources::Organizations.new(self)
+    end
+
+    def products
+      @products ||= Resources::Products.new(self)
+    end
+
+    def customers
+      @customers ||= Resources::Customers.new(self)
+    end
+
+    def orders
+      @orders ||= Resources::Orders.new(self)
+    end
+
+    def payments
+      @payments ||= Resources::Payments.new(self)
+    end
+
+    def subscriptions
+      @subscriptions ||= Resources::Subscriptions.new(self)
+    end
+
+    def checkouts
+      @checkouts ||= Resources::Checkouts.new(self)
+    end
+
+    def benefits
+      @benefits ||= Resources::Benefits.new(self)
+    end
+
+    def license_keys
+      @license_keys ||= Resources::LicenseKeys.new(self)
+    end
+
+    def files
+      @files ||= Resources::Files.new(self)
+    end
+
+    def metrics
+      @metrics ||= Resources::Metrics.new(self)
+    end
+
+    def events
+      @events ||= Resources::Events.new(self)
+    end
+
+    def webhooks
+      @webhooks ||= Resources::Webhooks.new(self)
+    end
+
+    def oauth2
+      @oauth2 ||= Resources::OAuth2.new(self)
+    end
+
+    # Customer Portal API
+    def customer_portal
+      @customer_portal ||= CustomerPortalClient.new(self)
+    end
+
+    private
+
+    def build_configuration(options)
+      config = Configuration.new
+
+      # Set from options
+      config.access_token = options[:access_token] || ENV['POLAR_ACCESS_TOKEN']
+      config.server = options[:server] || :production
+      config.base_url = options[:base_url] if options[:base_url]
+      config.timeout = options[:timeout] if options[:timeout]
+      config.retries = options[:retries] if options[:retries]
+      config.logger = options[:logger] if options[:logger]
+      config.debug = options[:debug] || ENV['POLAR_DEBUG'] == 'true'
+
+      # Apply global configuration
+      global_config = Polar.configuration
+      config.access_token ||= global_config.access_token
+      config.server = global_config.server if global_config.server && !options.key?(:server)
+      config.base_url ||= global_config.base_url
+      config.timeout = global_config.timeout if global_config.timeout && !options.key?(:timeout)
+      config.retries = global_config.retries if global_config.retries && !options.key?(:retries)
+      config.logger ||= global_config.logger
+      config.debug = global_config.debug if global_config.debug && !options.key?(:debug)
+
+      config
+    end
+
+    def build_authentication(options)
+      token = options[:access_token] || @configuration.access_token
+      customer_session = options[:customer_session]
+
+      if customer_session
+        Authentication::CustomerAuth.new(customer_session)
+      elsif token
+        Authentication::AuthFactory.create(token)
+      end
+    end
+  end
+
+  # Customer Portal specific client wrapper
+  class CustomerPortalClient
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    def customers
+      @customers ||= CustomerPortal::Customers.new(@client)
+    end
+
+    def orders
+      @orders ||= CustomerPortal::Orders.new(@client)
+    end
+
+    def subscriptions
+      @subscriptions ||= CustomerPortal::Subscriptions.new(@client)
+    end
+
+    def benefit_grants
+      @benefit_grants ||= CustomerPortal::BenefitGrants.new(@client)
+    end
+
+    def license_keys
+      @license_keys ||= CustomerPortal::LicenseKeys.new(@client)
+    end
+  end
+end

data/lib/polar/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Polar
+  class Configuration
+    attr_accessor :access_token, :server, :base_url, :timeout, :retries, :logger, :debug
+
+    # Server environments
+    PRODUCTION_SERVER = 'https://api.polar.sh/v1'
+    SANDBOX_SERVER = 'https://sandbox-api.polar.sh/v1'
+
+    def initialize
+      @server = :production
+      @timeout = 30
+      @retries = 3
+      @debug = false
+      @logger = nil
+    end
+
+    def base_url
+      @base_url || server_url
+    end
+
+    attr_writer :base_url
+
+    def server=(environment)
+      unless %i[production sandbox].include?(environment.to_sym)
+        raise ArgumentError, 'Invalid server environment. Must be :production or :sandbox'
+      end
+
+      @server = environment.to_sym
+    end
+
+    private
+
+    def server_url
+      case @server
+      when :production
+        PRODUCTION_SERVER
+      when :sandbox
+        SANDBOX_SERVER
+      else
+        raise ArgumentError, "Unknown server environment: #{@server}"
+      end
+    end
+  end
+end

data/lib/polar/customer_portal/benefit_grants.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative '../resources/base'
+
+module Polar
+  module CustomerPortal
+    class BenefitGrants < Resources::Base
+      # List customer benefit grants
+      # @param params [Hash] Query parameters
+      # @param customer_session [String] Customer session token
+      # @option params [Integer] :page Page number
+      # @option params [Integer] :limit Items per page
+      # @return [PaginatedResponse] Paginated list of benefit grants
+      def list(params = {}, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        paginate('/customer-portal/benefit-grants', params, headers)
+      end
+
+      # Get customer benefit grant
+      # @param id [String] Benefit grant ID
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Benefit grant data
+      def get(id, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = get("/customer-portal/benefit-grants/#{id}", {}, headers)
+        response.body
+      end
+
+      # Update customer benefit grant
+      # @param id [String] Benefit grant ID
+      # @param attributes [Hash] Updated attributes
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Updated benefit grant
+      def update(id, attributes, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = patch("/customer-portal/benefit-grants/#{id}", attributes, headers)
+        response.body
+      end
+    end
+  end
+end

data/lib/polar/customer_portal/customers.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative '../resources/base'
+
+module Polar
+  module CustomerPortal
+    class Customers < Resources::Base
+      # Get authenticated customer information
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Customer data
+      def get(customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = get('/customer-portal/customers/me', {}, headers)
+        response.body
+      end
+
+      # Update authenticated customer
+      # @param attributes [Hash] Updated customer attributes
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Updated customer
+      def update(attributes, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = patch('/customer-portal/customers/me', attributes, headers)
+        response.body
+      end
+
+      # List customer payment methods
+      # @param customer_session [String] Customer session token
+      # @return [Array] List of payment methods
+      def list_payment_methods(customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = get('/customer-portal/customers/me/payment-methods', {}, headers)
+        response.body
+      end
+
+      # Add customer payment method
+      # @param payment_method_data [Hash] Payment method data
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Payment method creation response
+      def add_payment_method(payment_method_data, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = post('/customer-portal/customers/me/payment-methods', payment_method_data, headers)
+        response.body
+      end
+
+      # Confirm customer payment method
+      # @param payment_method_id [String] Payment method ID
+      # @param confirmation_data [Hash] Confirmation data
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Confirmation response
+      def confirm_payment_method(payment_method_id, confirmation_data, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        path = "/customer-portal/customers/me/payment-methods/#{payment_method_id}/confirm"
+        response = post(path, confirmation_data, headers)
+        response.body
+      end
+
+      # Delete customer payment method
+      # @param payment_method_id [String] Payment method ID
+      # @param customer_session [String] Customer session token
+      # @return [Boolean] Success status
+      def delete_payment_method(payment_method_id, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        delete("/customer-portal/customers/me/payment-methods/#{payment_method_id}", headers)
+        true
+      end
+    end
+  end
+end

data/lib/polar/customer_portal/license_keys.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../resources/base'
+
+module Polar
+  module CustomerPortal
+    class LicenseKeys < Resources::Base
+      # List customer license keys
+      # @param params [Hash] Query parameters
+      # @param customer_session [String] Customer session token
+      # @option params [Integer] :page Page number
+      # @option params [Integer] :limit Items per page
+      # @return [PaginatedResponse] Paginated list of license keys
+      def list(params = {}, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        paginate('/customer-portal/license-keys', params, headers)
+      end
+
+      # Get customer license key
+      # @param id [String] License key ID
+      # @param customer_session [String] Customer session token
+      # @return [Hash] License key data
+      def get(id, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = get("/customer-portal/license-keys/#{id}", {}, headers)
+        response.body
+      end
+
+      # Validate a license key (no authentication required)
+      # @param key [String] License key
+      # @param activation_id [String, nil] Optional activation ID
+      # @return [Hash] Validation result
+      def validate(key, activation_id: nil)
+        body = { key: key }
+        body[:activation_id] = activation_id if activation_id
+
+        response = post('/customer-portal/license-keys/validate', body)
+        response.body
+      end
+
+      # Activate a license key (no authentication required)
+      # @param key [String] License key
+      # @param activation_data [Hash] Activation data
+      # @param customer_session [String, nil] Optional customer session token
+      # @option activation_data [String] :label Activation label
+      # @option activation_data [Hash] :metadata Activation metadata
+      # @return [Hash] Activation result
+      def activate(key, activation_data = {}, customer_session: nil)
+        body = { key: key }.merge(activation_data)
+        headers = customer_session ? { 'Authorization' => "Bearer #{customer_session}" } : {}
+
+        response = post('/customer-portal/license-keys/activate', body, headers)
+        response.body
+      end
+
+      # Deactivate a license key (no authentication required)
+      # @param key [String] License key
+      # @param activation_id [String] Activation ID
+      # @param customer_session [String, nil] Optional customer session token
+      # @return [Boolean] Success status
+      def deactivate(key, activation_id, customer_session: nil)
+        body = { key: key, activation_id: activation_id }
+        headers = customer_session ? { 'Authorization' => "Bearer #{customer_session}" } : {}
+
+        post('/customer-portal/license-keys/deactivate', body, headers)
+        true
+      end
+    end
+  end
+end

data/lib/polar/customer_portal/orders.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative '../resources/base'
+
+module Polar
+  module CustomerPortal
+    class Orders < Resources::Base
+      # List customer orders
+      # @param params [Hash] Query parameters
+      # @param customer_session [String] Customer session token
+      # @option params [Integer] :page Page number
+      # @option params [Integer] :limit Items per page
+      # @return [PaginatedResponse] Paginated list of orders
+      def list(params = {}, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        paginate('/customer-portal/orders', params, headers)
+      end
+
+      # Get customer order
+      # @param id [String] Order ID
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Order data
+      def get(id, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = get("/customer-portal/orders/#{id}", {}, headers)
+        response.body
+      end
+
+      # Update customer order
+      # @param id [String] Order ID
+      # @param attributes [Hash] Updated attributes
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Updated order
+      def update(id, attributes, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = patch("/customer-portal/orders/#{id}", attributes, headers)
+        response.body
+      end
+
+      # Generate invoice for customer order
+      # @param id [String] Order ID
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Invoice generation result
+      def generate_invoice(id, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = post("/customer-portal/orders/#{id}/invoice", {}, headers)
+        response.body
+      end
+
+      # Get customer order invoice
+      # @param id [String] Order ID
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Invoice data
+      def invoice(id, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = get("/customer-portal/orders/#{id}/invoice", {}, headers)
+        response.body
+      end
+
+      # Get order payment status
+      # @param id [String] Order ID
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Payment status
+      def get_payment_status(id, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = get("/customer-portal/orders/#{id}/payment-status", {}, headers)
+        response.body
+      end
+
+      # Confirm retry payment for order
+      # @param id [String] Order ID
+      # @param payment_data [Hash] Payment confirmation data
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Payment confirmation result
+      def confirm_retry_payment(id, payment_data, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = post("/customer-portal/orders/#{id}/confirm-retry-payment", payment_data, headers)
+        response.body
+      end
+    end
+  end
+end

data/lib/polar/customer_portal/subscriptions.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative '../resources/base'
+
+module Polar
+  module CustomerPortal
+    class Subscriptions < Resources::Base
+      # List customer subscriptions
+      # @param params [Hash] Query parameters
+      # @param customer_session [String] Customer session token
+      # @option params [Integer] :page Page number
+      # @option params [Integer] :limit Items per page
+      # @return [PaginatedResponse] Paginated list of subscriptions
+      def list(params = {}, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        paginate('/customer-portal/subscriptions', params, headers)
+      end
+
+      # Get customer subscription
+      # @param id [String] Subscription ID
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Subscription data
+      def get(id, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = get("/customer-portal/subscriptions/#{id}", {}, headers)
+        response.body
+      end
+
+      # Update customer subscription
+      # @param id [String] Subscription ID
+      # @param attributes [Hash] Updated attributes
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Updated subscription
+      def update(id, attributes, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = patch("/customer-portal/subscriptions/#{id}", attributes, headers)
+        response.body
+      end
+
+      # Cancel customer subscription
+      # @param id [String] Subscription ID
+      # @param customer_session [String] Customer session token
+      # @return [Hash] Cancelled subscription
+      def cancel(id, customer_session:)
+        headers = { 'Authorization' => "Bearer #{customer_session}" }
+        response = post("/customer-portal/subscriptions/#{id}/cancel", {}, headers)
+        response.body
+      end
+    end
+  end
+end