polar-ruby 0.1.0

data/lib/polar/errors.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Polar
+  # Base error class for all Polar SDK errors
+  class Error < StandardError
+    attr_reader :status_code, :headers, :body
+
+    def initialize(message, status_code: nil, headers: {}, body: nil)
+      super(message)
+      @status_code = status_code
+      @headers = headers || {}
+      @body = body
+    end
+  end
+
+  # HTTP error base class
+  class HTTPError < Error
+    def initialize(response)
+      @status_code = response.status
+      @headers = response.headers
+      @body = response.body
+
+      message = parse_error_message(response)
+      super(message, status_code: @status_code, headers: @headers, body: @body)
+    end
+
+    private
+
+    def parse_error_message(response)
+      return "HTTP #{response.status}" unless response.body
+
+      begin
+        # Handle both already parsed JSON (Hash) and raw JSON string
+        parsed = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body)
+        parsed['detail'] || parsed['message'] || "HTTP #{response.status}"
+      rescue JSON::ParserError, TypeError
+        "HTTP #{response.status}"
+      end
+    end
+  end
+
+  # Specific HTTP error classes matching Polar API responses
+  class BadRequestError < HTTPError; end
+  class UnauthorizedError < HTTPError; end
+  class ForbiddenError < HTTPError; end
+  class NotFoundError < HTTPError; end
+  class MethodNotAllowedError < HTTPError; end
+  class UnprocessableEntityError < HTTPError; end
+  class TooManyRequestsError < HTTPError; end
+  class InternalServerError < HTTPError; end
+  class BadGatewayError < HTTPError; end
+  class ServiceUnavailableError < HTTPError; end
+  class GatewayTimeoutError < HTTPError; end
+
+  # Specific Polar API errors
+  class ValidationError < UnprocessableEntityError; end
+  class ResourceNotFoundError < NotFoundError; end
+  class NotPermittedError < ForbiddenError; end
+  class AlreadyCanceledSubscriptionError < ForbiddenError; end
+  class AlreadyActiveSubscriptionError < ForbiddenError; end
+
+  # Connection and timeout errors
+  class ConnectionError < Error; end
+  class TimeoutError < Error; end
+  class RetryExhaustedError < Error; end
+
+  # Authentication errors
+  class AuthenticationError < Error; end
+  class InvalidTokenError < AuthenticationError; end
+
+  # Webhook errors
+  class WebhookError < Error; end
+  class WebhookVerificationError < WebhookError; end
+
+  class << self
+    # Map HTTP status codes to error classes
+    STATUS_CODE_TO_ERROR = {
+      400 => BadRequestError,
+      401 => UnauthorizedError,
+      403 => ForbiddenError,
+      404 => NotFoundError,
+      405 => MethodNotAllowedError,
+      422 => UnprocessableEntityError,
+      429 => TooManyRequestsError,
+      500 => InternalServerError,
+      502 => BadGatewayError,
+      503 => ServiceUnavailableError,
+      504 => GatewayTimeoutError
+    }.freeze
+
+    def error_for_status(response)
+      error_class = STATUS_CODE_TO_ERROR[response.status] || HTTPError
+      error_class.new(response)
+    end
+  end
+end

data/lib/polar/http_client.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Polar
+  class HTTPClient
+    attr_reader :configuration, :auth
+
+    def initialize(configuration, auth = nil)
+      @configuration = configuration
+      @auth = auth
+    end
+
+    def get(path, params = {}, headers = {})
+      request(:get, path, params: params, headers: headers)
+    end
+
+    def post(path, body = nil, headers = {})
+      request(:post, path, body: body, headers: headers)
+    end
+
+    def put(path, body = nil, headers = {})
+      request(:put, path, body: body, headers: headers)
+    end
+
+    def patch(path, body = nil, headers = {})
+      request(:patch, path, body: body, headers: headers)
+    end
+
+    def delete(path, headers = {})
+      request(:delete, path, headers: headers)
+    end
+
+    private
+
+    def request(method, path, params: nil, body: nil, headers: {})
+      url = build_url(path)
+      request_headers = build_headers(headers)
+
+      log_request(method, url, body) if configuration.debug
+
+      response = connection.public_send(method) do |req|
+        req.url url
+        req.headers.update(request_headers)
+        params.each { |key, value| req.params[key.to_s] = value } if params && method == :get
+        req.body = prepare_body(body) if body && %i[post put patch].include?(method)
+      end
+
+      log_response(response) if configuration.debug
+
+      handle_response(response)
+    rescue Faraday::Error => e
+      handle_faraday_error(e)
+    end
+
+    def connection
+      @connection ||= Faraday.new do |conn|
+        conn.request :json
+        conn.request :multipart
+        conn.request :retry, retry_options
+        conn.response :json, content_type: /\bjson$/
+        conn.options.timeout = configuration.timeout
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def retry_options
+      {
+        max: configuration.retries,
+        interval: 0.5,
+        interval_randomness: 0.5,
+        backoff_factor: 2,
+        exceptions: [
+          Faraday::ConnectionFailed,
+          Faraday::TimeoutError,
+          Faraday::RetriableResponse
+        ],
+        retry_statuses: [429, 500, 502, 503, 504],
+        retry_if: ->(env, _exception) { env.method != :post || retriable_post?(env) }
+      }
+    end
+
+    def retriable_post?(env)
+      # Only retry POST requests that are idempotent (like searches)
+      env.url.path.include?('/search') || env.url.path.include?('/validate')
+    end
+
+    def build_url(path)
+      path.start_with?('http') ? path : "#{configuration.base_url}#{path}"
+    end
+
+    def build_headers(headers)
+      default_headers = {
+        'User-Agent' => "polar-ruby/#{Polar::VERSION}",
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+
+      default_headers.merge!(auth.headers) if auth
+      default_headers.merge(headers)
+    end
+
+    def prepare_body(body)
+      case body
+      when Hash, Array
+        body.to_json
+      when String
+        body
+      else
+        body.to_s
+      end
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response
+      when 400..499, 500..599
+        raise Polar.error_for_status(response)
+      else
+        raise HTTPError.new(response)
+      end
+    end
+
+    def handle_faraday_error(error)
+      case error
+      when Faraday::ConnectionFailed
+        raise ConnectionError, "Failed to connect to Polar API: #{error.message}"
+      when Faraday::TimeoutError
+        raise TimeoutError, "Request timed out: #{error.message}"
+      when Faraday::RetriableResponse
+        raise RetryExhaustedError, "Request failed after #{configuration.retries} retries: #{error.message}"
+      else
+        raise Error, "Network error: #{error.message}"
+      end
+    end
+
+    def log_request(method, url, body)
+      return unless configuration.logger
+
+      configuration.logger.debug("Polar API Request: #{method.upcase} #{url}")
+      configuration.logger.debug("Request Body: #{body}") if body
+    end
+
+    def log_response(response)
+      return unless configuration.logger
+
+      configuration.logger.debug("Polar API Response: #{response.status}")
+      configuration.logger.debug("Response Body: #{response.body}") if response.body
+    end
+  end
+end

data/lib/polar/pagination.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Polar
+  class PaginatedResponse
+    include Enumerable
+
+    attr_reader :client, :path, :params, :headers, :current_page, :total_count
+
+    def initialize(client, path, params = {}, headers = {})
+      @client = client
+      @path = path
+      @params = params.dup
+      @headers = headers
+      @current_page = nil
+      @total_count = nil
+      @items_cache = {}
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      page = 1
+      loop do
+        response_data = fetch_page(page)
+        items = extract_items(response_data)
+
+        break if items.empty?
+
+        items.each(&block)
+
+        # Check if there are more pages
+        break unless has_next_page?(response_data, page)
+
+        page += 1
+      end
+    end
+
+    def auto_paginate
+      all_items = []
+      each { |item| all_items << item }
+      all_items
+    end
+
+    def first_page
+      @first_page ||= fetch_page(1)
+    end
+
+    def page(page_number)
+      fetch_page(page_number)
+    end
+
+    def count
+      first_page['pagination']['total'] if first_page.dig('pagination')
+    end
+
+    def total_pages
+      pagination_info = first_page.dig('pagination')
+      return nil unless pagination_info
+
+      total = pagination_info['total']
+      per_page = pagination_info['per_page'] || pagination_info['limit'] || 20
+      (total.to_f / per_page).ceil
+    end
+
+    private
+
+    def fetch_page(page_number)
+      return @items_cache[page_number] if @items_cache[page_number]
+
+      page_params = @params.merge(page: page_number)
+      response = @client.http_client.get(@path, page_params, @headers)
+
+      response_data = response.body
+      @items_cache[page_number] = response_data
+      @current_page = page_number
+
+      response_data
+    end
+
+    def extract_items(response_data)
+      # The response could have different structures
+      if response_data.is_a?(Hash)
+        # Check for common pagination response structures
+        if response_data.key?('data')
+          response_data['data']
+        elsif response_data.key?('items')
+          response_data['items']
+        elsif response_data.key?('results')
+          response_data['results']
+        else
+          # If it's a hash but no data key, it might be the items themselves
+          []
+        end
+      elsif response_data.is_a?(Array)
+        response_data
+      else
+        []
+      end
+    end
+
+    def has_next_page?(response_data, current_page)
+      return false unless response_data.is_a?(Hash)
+
+      pagination = response_data['pagination']
+      return false unless pagination
+
+      # Check various pagination indicators
+      if pagination.key?('has_next')
+        pagination['has_next']
+      elsif pagination.key?('next_page')
+        !pagination['next_page'].nil?
+      elsif pagination.key?('total')
+        total = pagination['total']
+        per_page = pagination['per_page'] || pagination['limit'] || 20
+        current_page * per_page < total
+      else
+        # If no clear pagination info, check if we got any items
+        items = extract_items(response_data)
+        !items.empty?
+      end
+    end
+  end
+
+  module Pagination
+    def paginate(path, params = {}, headers = {})
+      PaginatedResponse.new(self, path, params, headers)
+    end
+
+    def auto_paginate(path, params = {}, headers = {})
+      paginate(path, params, headers).auto_paginate
+    end
+  end
+end

data/lib/polar/resources/base.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Polar
+  module Resources
+    class Base
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      protected
+
+      def http_client
+        client.http_client
+      end
+
+      def get(path, params = {}, headers = {})
+        http_client.get(path, params, headers)
+      end
+
+      def post(path, body = nil, headers = {})
+        http_client.post(path, body, headers)
+      end
+
+      def put(path, body = nil, headers = {})
+        http_client.put(path, body, headers)
+      end
+
+      def patch(path, body = nil, headers = {})
+        http_client.patch(path, body, headers)
+      end
+
+      def delete(path, headers = {})
+        http_client.delete(path, headers)
+      end
+
+      def paginate(path, params = {}, headers = {})
+        client.paginate(path, params, headers)
+      end
+
+      def auto_paginate(path, params = {}, headers = {})
+        client.auto_paginate(path, params, headers)
+      end
+    end
+  end
+end

data/lib/polar/resources/benefits.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Polar
+  module Resources
+    class Benefits < Base
+      # List benefits
+      # @param params [Hash] Query parameters
+      # @option params [String] :organization_id Filter by organization ID
+      # @option params [String] :type Filter by benefit type
+      # @option params [Integer] :page Page number
+      # @option params [Integer] :limit Items per page
+      # @return [PaginatedResponse] Paginated list of benefits
+      def list(params = {})
+        paginate('/benefits/', params)
+      end
+
+      # Create a benefit
+      # @param attributes [Hash] Benefit attributes
+      # @option attributes [String] :type Benefit type
+      # @option attributes [String] :description Benefit description
+      # @option attributes [String] :organization_id Organization ID
+      # @return [Hash] Created benefit
+      def create(attributes)
+        response = post('/benefits/', attributes)
+        response.body
+      end
+
+      # Get a benefit by ID
+      # @param id [String] Benefit ID
+      # @return [Hash] Benefit data
+      def get(id)
+        response = get("/benefits/#{id}")
+        response.body
+      end
+
+      # Update a benefit
+      # @param id [String] Benefit ID
+      # @param attributes [Hash] Updated attributes
+      # @return [Hash] Updated benefit
+      def update(id, attributes)
+        response = patch("/benefits/#{id}", attributes)
+        response.body
+      end
+
+      # Delete a benefit
+      # @param id [String] Benefit ID
+      # @return [Boolean] Success status
+      def delete(id)
+        delete("/benefits/#{id}")
+        true
+      end
+
+      # List benefit grants
+      # @param id [String] Benefit ID
+      # @param params [Hash] Query parameters
+      # @return [PaginatedResponse] Paginated list of benefit grants
+      def grants(id, params = {})
+        paginate("/benefits/#{id}/grants", params)
+      end
+    end
+  end
+end

data/lib/polar/resources/checkouts.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Polar
+  module Resources
+    class Checkouts < Base
+      # List checkout sessions
+      # @param params [Hash] Query parameters
+      # @option params [String] :organization_id Filter by organization ID
+      # @option params [String] :customer_id Filter by customer ID
+      # @option params [Integer] :page Page number
+      # @option params [Integer] :limit Items per page
+      # @return [PaginatedResponse] Paginated list of checkout sessions
+      def list(params = {})
+        paginate('/checkouts/', params)
+      end
+
+      # Create a checkout session
+      # @param attributes [Hash] Checkout session attributes
+      # @option attributes [String] :product_price_id Product price ID
+      # @option attributes [String] :success_url Success redirect URL
+      # @option attributes [String] :cancel_url Cancel redirect URL
+      # @option attributes [Hash] :customer_data Customer information
+      # @return [Hash] Created checkout session
+      def create(attributes)
+        response = post('/checkouts/', attributes)
+        response.body
+      end
+
+      # Get a checkout session by ID
+      # @param id [String] Checkout session ID
+      # @return [Hash] Checkout session data
+      def get(id)
+        response = get("/checkouts/#{id}")
+        response.body
+      end
+
+      # Update a checkout session
+      # @param id [String] Checkout session ID
+      # @param attributes [Hash] Updated attributes
+      # @return [Hash] Updated checkout session
+      def update(id, attributes)
+        response = patch("/checkouts/#{id}", attributes)
+        response.body
+      end
+
+      # Get checkout session from client (no auth required)
+      # @param id [String] Checkout session ID
+      # @return [Hash] Checkout session data
+      def client_get(id)
+        response = get("/checkouts/#{id}/client")
+        response.body
+      end
+
+      # Update checkout session from client
+      # @param id [String] Checkout session ID
+      # @param attributes [Hash] Updated attributes
+      # @return [Hash] Updated checkout session
+      def client_update(id, attributes)
+        response = patch("/checkouts/#{id}/client", attributes)
+        response.body
+      end
+
+      # Confirm checkout session from client
+      # @param id [String] Checkout session ID
+      # @param confirmation_data [Hash] Confirmation data
+      # @return [Hash] Confirmed checkout session
+      def client_confirm(id, confirmation_data = {})
+        response = post("/checkouts/#{id}/client/confirm", confirmation_data)
+        response.body
+      end
+    end
+  end
+end

data/lib/polar/resources/customers.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Polar
+  module Resources
+    class Customers < Base
+      # List customers
+      # @param params [Hash] Query parameters
+      # @option params [String] :organization_id Filter by organization ID
+      # @option params [String] :query Search query
+      # @option params [Integer] :page Page number
+      # @option params [Integer] :limit Items per page
+      # @return [PaginatedResponse] Paginated list of customers
+      def list(params = {})
+        paginate('/customers/', params)
+      end
+
+      # Create a customer
+      # @param attributes [Hash] Customer attributes
+      # @option attributes [String] :email Customer email
+      # @option attributes [String] :name Customer name
+      # @option attributes [String] :organization_id Organization ID
+      # @return [Hash] Created customer
+      def create(attributes)
+        response = post('/customers/', attributes)
+        response.body
+      end
+
+      # Export customers
+      # @param params [Hash] Export parameters
+      # @return [Hash] Export job details
+      def export(params = {})
+        response = post('/customers/export', params)
+        response.body
+      end
+
+      # Get a customer by ID
+      # @param id [String] Customer ID
+      # @return [Hash] Customer data
+      def get(id)
+        response = get("/customers/#{id}")
+        response.body
+      end
+
+      # Update a customer
+      # @param id [String] Customer ID
+      # @param attributes [Hash] Updated attributes
+      # @return [Hash] Updated customer
+      def update(id, attributes)
+        response = patch("/customers/#{id}", attributes)
+        response.body
+      end
+
+      # Delete a customer
+      # @param id [String] Customer ID
+      # @return [Boolean] Success status
+      def delete(id)
+        delete("/customers/#{id}")
+        true
+      end
+
+      # Get customer by external ID
+      # @param external_id [String] External customer ID
+      # @param organization_id [String] Organization ID
+      # @return [Hash] Customer data
+      def get_external(external_id, organization_id:)
+        params = { organization_id: organization_id }
+        response = get("/customers/external/#{external_id}", params)
+        response.body
+      end
+
+      # Update customer by external ID
+      # @param external_id [String] External customer ID
+      # @param attributes [Hash] Updated attributes
+      # @option attributes [String] :organization_id Organization ID (required)
+      # @return [Hash] Updated customer
+      def update_external(external_id, attributes)
+        response = patch("/customers/external/#{external_id}", attributes)
+        response.body
+      end
+
+      # Delete customer by external ID
+      # @param external_id [String] External customer ID
+      # @param organization_id [String] Organization ID
+      # @return [Boolean] Success status
+      def delete_external(external_id, organization_id:)
+        params = { organization_id: organization_id }
+        delete("/customers/external/#{external_id}", params)
+        true
+      end
+
+      # Get customer state
+      # @param id [String] Customer ID
+      # @return [Hash] Customer state data
+      def get_state(id)
+        response = get("/customers/#{id}/state")
+        response.body
+      end
+
+      # Get customer state by external ID
+      # @param external_id [String] External customer ID
+      # @param organization_id [String] Organization ID
+      # @return [Hash] Customer state data
+      def get_state_external(external_id, organization_id:)
+        params = { organization_id: organization_id }
+        response = get("/customers/external/#{external_id}/state", params)
+        response.body
+      end
+
+      # Get customer balance
+      # @param id [String] Customer ID
+      # @return [Hash] Customer balance data
+      def get_balance(id)
+        response = get("/customers/#{id}/balance")
+        response.body
+      end
+    end
+  end
+end