polar-ruby 0.1.0

data/EXAMPLES.md

@@ -0,0 +1,385 @@
+# Polar Ruby SDK Examples
+
+This directory contains examples demonstrating how to use the Polar Ruby SDK for various use cases.
+
+## Basic Usage
+
+### Simple E-commerce Checkout
+
+```ruby
+require 'polar'
+
+# Initialize client
+client = Polar.new(access_token: ENV['POLAR_ACCESS_TOKEN'])
+
+# Create a product
+product = client.products.create({
+  name: "Digital Course",
+  description: "Learn Ruby programming",
+  organization_id: "org_123"
+})
+
+# Create checkout session
+checkout = client.checkouts.create({
+  product_price_id: "price_123",
+  success_url: "https://mysite.com/success",
+  cancel_url: "https://mysite.com/cancel",
+  customer_data: {
+    email: "customer@example.com",
+    name: "John Doe"
+  }
+})
+
+puts "Checkout URL: #{checkout['url']}"
+```
+
+### Subscription Management
+
+```ruby
+require 'polar'
+
+client = Polar.new(access_token: ENV['POLAR_ACCESS_TOKEN'])
+
+# List active subscriptions
+subscriptions = client.subscriptions.list(
+  organization_id: 'org_123',
+  status: 'active'
+).auto_paginate
+
+subscriptions.each do |subscription|
+  puts "Subscription #{subscription['id']}: #{subscription['customer']['email']}"
+end
+
+# Update subscription metadata
+updated = client.subscriptions.update('sub_123', {
+  metadata: {
+    tier: 'premium',
+    support_level: 'priority'
+  }
+})
+```
+
+### License Key Validation
+
+```ruby
+require 'polar'
+
+class LicenseValidator
+  def initialize
+    @client = Polar.new(access_token: ENV['POLAR_ACCESS_TOKEN'])
+  end
+
+  def validate_key(license_key)
+    result = @client.customer_portal.license_keys.validate(license_key)
+
+    if result['valid']
+      {
+        valid: true,
+        customer: result['customer']['email'],
+        product: result['benefit']['description'],
+        expires_at: result['expires_at']
+      }
+    else
+      { valid: false, reason: result['error'] }
+    end
+  rescue Polar::Error => e
+    { valid: false, error: e.message }
+  end
+end
+
+# Usage
+validator = LicenseValidator.new
+result = validator.validate_key('license_key_123')
+puts result
+```
+
+### Webhook Handler
+
+```ruby
+require 'polar'
+require 'sinatra'
+require 'json'
+
+# Sinatra webhook endpoint
+post '/webhooks/polar' do
+  payload = request.body.read
+  headers = request.env.select { |k,v| k.start_with? 'HTTP_' }
+  secret = ENV['POLAR_WEBHOOK_SECRET']
+
+  begin
+    event = Polar::Webhooks.validate_event(payload, headers, secret)
+
+    case event['type']
+    when 'order.created'
+      handle_order_created(event['data'])
+    when 'subscription.created'
+      handle_subscription_created(event['data'])
+    when 'subscription.cancelled'
+      handle_subscription_cancelled(event['data'])
+    when 'payment.succeeded'
+      handle_payment_succeeded(event['data'])
+    end
+
+    status 200
+    { status: 'processed' }.to_json
+  rescue Polar::WebhookVerificationError
+    status 403
+    { error: 'Invalid signature' }.to_json
+  end
+end
+
+def handle_order_created(order)
+  puts "New order: #{order['id']} for #{order['amount']} #{order['currency']}"
+  # Send confirmation email, update inventory, etc.
+end
+
+def handle_subscription_created(subscription)
+  puts "New subscription: #{subscription['id']}"
+  # Provision access, send welcome email, etc.
+end
+
+def handle_subscription_cancelled(subscription)
+  puts "Cancelled subscription: #{subscription['id']}"
+  # Revoke access, send cancellation email, etc.
+end
+
+def handle_payment_succeeded(payment)
+  puts "Payment succeeded: #{payment['id']}"
+  # Update payment status, trigger fulfillment, etc.
+end
+```
+
+## Advanced Examples
+
+### Customer Portal Integration
+
+```ruby
+class CustomerPortal
+  def initialize(customer_session)
+    @customer_session = customer_session
+    @client = Polar.new
+  end
+
+  def dashboard_data
+    {
+      customer: get_customer_info,
+      orders: get_recent_orders,
+      subscriptions: get_active_subscriptions,
+      license_keys: get_license_keys
+    }
+  end
+
+  private
+
+  def get_customer_info
+    @client.customer_portal.customers.get(customer_session: @customer_session)
+  end
+
+  def get_recent_orders(limit: 10)
+    @client.customer_portal.orders.list(
+      { limit: limit },
+      customer_session: @customer_session
+    ).auto_paginate
+  end
+
+  def get_active_subscriptions
+    @client.customer_portal.subscriptions.list(
+      customer_session: @customer_session
+    ).auto_paginate.select { |sub| sub['status'] == 'active' }
+  end
+
+  def get_license_keys
+    @client.customer_portal.license_keys.list(
+      customer_session: @customer_session
+    ).auto_paginate
+  end
+end
+```
+
+### Batch Operations
+
+```ruby
+class BatchProcessor
+  def initialize
+    @client = Polar.new(access_token: ENV['POLAR_ACCESS_TOKEN'])
+  end
+
+  def process_customers_in_batches(organization_id, batch_size: 100)
+    customers = @client.customers.list(
+      organization_id: organization_id,
+      limit: batch_size
+    )
+
+    customers.each do |customer|
+      process_customer(customer)
+      sleep(0.1) # Rate limiting
+    end
+  end
+
+  def export_subscription_data(organization_id)
+    export_job = @client.subscriptions.export({
+      organization_id: organization_id,
+      format: 'csv'
+    })
+
+    puts "Export started: #{export_job['id']}"
+    export_job
+  end
+
+  private
+
+  def process_customer(customer)
+    # Example: Update customer metadata
+    @client.customers.update(customer['id'], {
+      metadata: {
+        last_processed: Time.now.iso8601,
+        processor: 'batch_job'
+      }
+    })
+  rescue Polar::Error => e
+    puts "Failed to process customer #{customer['id']}: #{e.message}"
+  end
+end
+```
+
+### Error Handling Patterns
+
+```ruby
+class RobustPolarClient
+  def initialize
+    @client = Polar.new(access_token: ENV['POLAR_ACCESS_TOKEN'])
+    @logger = Logger.new(STDOUT)
+  end
+
+  def safe_get_customer(customer_id)
+    @client.customers.get(customer_id)
+  rescue Polar::NotFoundError
+    @logger.warn("Customer #{customer_id} not found")
+    nil
+  rescue Polar::UnauthorizedError => e
+    @logger.error("Authentication failed: #{e.message}")
+    raise
+  rescue Polar::TooManyRequestsError => e
+    @logger.warn("Rate limited, retrying after delay")
+    sleep(5)
+    retry
+  rescue Polar::HTTPError => e
+    @logger.error("HTTP error #{e.status_code}: #{e.message}")
+    nil
+  end
+
+  def create_customer_with_retry(customer_data, max_retries: 3)
+    retries = 0
+
+    begin
+      @client.customers.create(customer_data)
+    rescue Polar::ValidationError => e
+      @logger.error("Validation failed: #{e.message}")
+      raise
+    rescue Polar::ConnectionError, Polar::TimeoutError => e
+      retries += 1
+      if retries <= max_retries
+        @logger.warn("Connection failed, retry #{retries}/#{max_retries}")
+        sleep(2 ** retries)
+        retry
+      else
+        @logger.error("Max retries exceeded: #{e.message}")
+        raise
+      end
+    end
+  end
+end
+```
+
+### Rails Integration
+
+```ruby
+# app/services/polar_service.rb
+class PolarService
+  include Singleton
+
+  def initialize
+    @client = Polar.new(
+      access_token: Rails.application.credentials.polar_access_token,
+      server: Rails.env.production? ? :production : :sandbox,
+      logger: Rails.logger
+    )
+  end
+
+  def create_checkout_for_user(user, product_price_id)
+    @client.checkouts.create({
+      product_price_id: product_price_id,
+      success_url: Rails.application.routes.url_helpers.checkout_success_url,
+      cancel_url: Rails.application.routes.url_helpers.checkout_cancel_url,
+      customer_data: {
+        email: user.email,
+        name: user.full_name,
+        external_id: user.id.to_s
+      },
+      metadata: {
+        user_id: user.id,
+        created_via: 'rails_app'
+      }
+    })
+  end
+
+  def sync_customer(user)
+    polar_customer = find_or_create_customer(user)
+    user.update!(polar_customer_id: polar_customer['id'])
+    polar_customer
+  end
+
+  private
+
+  def find_or_create_customer(user)
+    @client.customers.get_external(
+      user.id.to_s,
+      organization_id: organization_id
+    )
+  rescue Polar::NotFoundError
+    @client.customers.create({
+      email: user.email,
+      name: user.full_name,
+      external_id: user.id.to_s,
+      organization_id: organization_id
+    })
+  end
+
+  def organization_id
+    Rails.application.credentials.polar_organization_id
+  end
+end
+
+# app/controllers/checkouts_controller.rb
+class CheckoutsController < ApplicationController
+  before_action :authenticate_user!
+
+  def create
+    checkout = PolarService.instance.create_checkout_for_user(
+      current_user,
+      params[:product_price_id]
+    )
+
+    redirect_to checkout['url']
+  rescue Polar::Error => e
+    flash[:error] = "Checkout failed: #{e.message}"
+    redirect_back(fallback_location: root_path)
+  end
+
+  def success
+    # Handle successful checkout
+    flash[:success] = "Payment successful!"
+    redirect_to dashboard_path
+  end
+
+  def cancel
+    # Handle cancelled checkout
+    flash[:info] = "Checkout cancelled"
+    redirect_to pricing_path
+  end
+end
+```
+
+For more examples and detailed documentation, visit:
+- [Polar.sh Documentation](https://polar.sh/docs)
+- [API Reference](https://polar.sh/docs/api-reference)

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in polar-ruby.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'rubocop', '~> 1.21'
+gem 'simplecov', '~> 0.21'
+gem 'vcr', '~> 6.0'
+gem 'webmock', '~> 3.0'
+gem 'yard', '~> 0.9'

data/Gemfile.lock

@@ -0,0 +1,115 @@
+PATH
+  remote: .
+  specs:
+    polar-ruby (0.1.0)
+      faraday (~> 2.0)
+      faraday-multipart (~> 1.0)
+      faraday-retry (~> 2.0)
+      jwt (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (3.3.1)
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-multipart (1.1.1)
+      multipart-post (~> 2.0)
+    faraday-net_http (3.4.1)
+      net-http (>= 0.5.0)
+    faraday-retry (2.3.2)
+      faraday (~> 2.0)
+    hashdiff (1.2.1)
+    json (2.15.1)
+    jwt (2.10.2)
+      base64
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    multipart-post (2.4.1)
+    net-http (0.6.0)
+      uri
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.5.2)
+    public_suffix (6.0.2)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.81.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.47.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    uri (1.0.4)
+    vcr (6.3.1)
+      base64
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.37)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  polar-ruby!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+  simplecov (~> 0.21)
+  vcr (~> 6.0)
+  webmock (~> 3.0)
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.6.7

data/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2024 Polar Ruby SDK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This project is not an official SDK from Polar.sh and is not affiliated with or endorsed by Polar.sh. It is a community-driven. See the README for details.