polar-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e57f786b73e94872a77124c5865633c7a31b1b88b1e94bfe0bb0e01a1cfe7dec
+  data.tar.gz: b046f3c91cedef35d450d9e8029575e10a9b23a6447b8bab2be6d38feaf2afa4
+SHA512:
+  metadata.gz: 3cbed2cb510eaf3febbdad873e228692452599abf9755768f1499ea56f66fce9778502e8d281c0aa92998ddc5e6884469a6c1ee63f6af6a9321f75138d28fb41
+  data.tar.gz: 4169e320b9884fa6e4308edc3ffc6168869f67225aa13508f178e2a3e7751dd78ac4848e144c0ef65eb77d49404ecc5c7b8466ea026160e2137b95aa64a5ed3d

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-10-12
+
+### Added
+- Initial release of Polar Ruby SDK
+- Complete API coverage for Polar.sh API
+- Organization Access Token (OAT) authentication
+- Customer session authentication
+- Core API resources:
+  - Organizations
+  - Products
+  - Customers
+  - Orders
+  - Payments
+  - Subscriptions
+  - Checkouts
+  - Benefits
+  - License Keys
+  - Files
+  - Metrics
+  - Events
+  - Webhooks
+  - OAuth2
+- Customer Portal API resources:
+  - Customer management
+  - Order management
+  - Subscription management
+  - Benefit grants
+  - License key operations
+- Comprehensive error handling with specific error classes
+- Automatic pagination support with iterator pattern
+- Webhook signature verification
+- HTTP client with retry logic and exponential backoff
+- Production and sandbox environment support
+- Configurable timeouts and retry policies
+- Debug logging support
+- Ruby 2.7+ compatibility
+
+### Security
+- Secure webhook signature verification using HMAC-SHA256
+- Automatic token validation and format checking
+- Safe string comparison to prevent timing attacks

data/DEVELOPMENT.md

@@ -0,0 +1,329 @@
+# Polar Ruby SDK Development Guide
+
+This guide covers development setup, testing, and contribution guidelines for the Polar Ruby SDK.
+
+## Development Setup
+
+### Prerequisites
+
+- Ruby 2.7 or higher
+- Bundler 2.0+
+- Git
+
+### Initial Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/polarsource/polar-ruby.git
+cd polar-ruby
+```
+
+2. Install dependencies:
+```bash
+bundle install
+```
+
+3. Set up environment variables (optional):
+```bash
+cp .env.example .env
+# Edit .env with your test API keys
+```
+
+4. Run tests to verify setup:
+```bash
+bundle exec rake spec
+```
+
+## Project Structure
+
+```
+polar-ruby/
+├── lib/
+│   └── polar/
+│       ├── resources/           # Core API resource classes
+│       ├── customer_portal/     # Customer portal API classes
+│       ├── authentication.rb   # Authentication classes
+│       ├── client.rb           # Main client class
+│       ├── configuration.rb    # Configuration management
+│       ├── errors.rb           # Error classes
+│       ├── http_client.rb      # HTTP client with retry logic
+│       ├── pagination.rb       # Pagination support
+│       ├── webhooks.rb         # Webhook verification
+│       └── version.rb          # Version constant
+├── spec/                       # Test files
+├── examples/                   # Usage examples
+├── polar-ruby.gemspec         # Gem specification
+├── Gemfile                    # Development dependencies
+├── Rakefile                   # Rake tasks
+└── README.md                  # Main documentation
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake spec
+
+# Run specific test file
+bundle exec rspec spec/polar/client_spec.rb
+
+# Run tests with coverage
+bundle exec rake test_with_coverage
+
+# Run quality checks (tests + rubocop)
+bundle exec rake quality
+```
+
+### Test Structure
+
+Tests are organized using RSpec with the following conventions:
+
+- Unit tests for each class in `spec/polar/`
+- Integration tests in `spec/integration/`
+- VCR cassettes for HTTP request recording in `spec/vcr_cassettes/`
+- Test helpers and shared examples in `spec/support/`
+
+### Writing Tests
+
+Example test structure:
+
+```ruby
+# spec/polar/resources/customers_spec.rb
+RSpec.describe Polar::Resources::Customers do
+  let(:client) { create_test_client }
+  let(:customers) { client.customers }
+
+  describe "#list" do
+    it "returns paginated customers", :vcr do
+      stub_polar_request(:get, "/customers", response_body: {
+        data: [{ id: "cust_123", email: "test@example.com" }]
+      })
+
+      result = customers.list
+      expect(result).to be_a(Polar::PaginatedResponse)
+    end
+  end
+
+  describe "#create" do
+    it "creates a customer", :vcr do
+      customer_data = {
+        email: "new@example.com",
+        name: "New Customer",
+        organization_id: "org_123"
+      }
+
+      stub_polar_request(:post, "/customers",
+        response_body: { id: "cust_456" }.merge(customer_data)
+      )
+
+      result = customers.create(customer_data)
+      expect(result["id"]).to eq("cust_456")
+      expect(result["email"]).to eq("new@example.com")
+    end
+  end
+end
+```
+
+### Test Helpers
+
+Common test helpers are available in `spec_helper.rb`:
+
+- `create_test_client(options = {})` - Creates a test client instance
+- `stub_polar_request(method, path, ...)` - Stubs HTTP requests to Polar API
+
+### VCR Cassettes
+
+For integration tests that make real HTTP requests:
+
+1. Set up test API credentials
+2. Use `:vcr` metadata on test examples
+3. Run tests to generate cassettes
+4. Commit cassettes to version control
+
+```ruby
+it "creates real customer", :vcr do
+  # This will record actual HTTP request/response
+  customer = client.customers.create(email: "test@example.com")
+  expect(customer["id"]).to start_with("cust_")
+end
+```
+
+## Code Style
+
+### RuboCop
+
+The project uses RuboCop for code style enforcement:
+
+```bash
+# Check code style
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -A
+
+# Check specific files
+bundle exec rubocop lib/polar/client.rb
+```
+
+### Style Guidelines
+
+- Follow standard Ruby conventions
+- Use 2 spaces for indentation
+- Prefer double quotes for strings
+- Add frozen string literal comment to all files
+- Document public methods with YARD format
+- Keep line length under 120 characters
+
+### Documentation
+
+Document public methods using YARD syntax:
+
+```ruby
+# Get a customer by ID
+# @param id [String] Customer ID
+# @return [Hash] Customer data
+# @raise [Polar::NotFoundError] If customer doesn't exist
+def get(id)
+  response = get("/customers/#{id}")
+  response.body
+end
+```
+
+## Release Process
+
+### Version Management
+
+1. Update version in `lib/polar/version.rb`
+2. Update `CHANGELOG.md` with changes
+3. Commit changes
+4. Create git tag: `git tag v0.1.1`
+5. Push tag: `git push origin v0.1.1`
+
+### Publishing to RubyGems
+
+```bash
+# Build gem
+bundle exec rake build
+
+# Publish to RubyGems (requires credentials)
+bundle exec rake release
+```
+
+## Contributing
+
+### Pull Request Process
+
+1. Fork the repository
+2. Create feature branch: `git checkout -b feature/new-feature`
+3. Make changes with tests
+4. Run quality checks: `bundle exec rake quality`
+5. Commit changes with descriptive messages
+6. Push branch and create pull request
+
+### Commit Messages
+
+Use conventional commit format:
+
+- `feat: add customer portal support`
+- `fix: handle rate limiting in HTTP client`
+- `docs: update README examples`
+- `test: add webhook verification tests`
+- `refactor: simplify pagination logic`
+
+### Code Review Guidelines
+
+- All code must have tests
+- Maintain backward compatibility
+- Follow existing patterns and conventions
+- Update documentation for public API changes
+- Ensure CI passes before merging
+
+## Debugging
+
+### Debug Logging
+
+Enable debug logging to see HTTP requests/responses:
+
+```ruby
+client = Polar.new(
+  access_token: "your_token",
+  debug: true,
+  logger: Logger.new(STDOUT)
+)
+```
+
+### Common Issues
+
+**Authentication Errors:**
+- Verify token format starts with `polar_oat_`
+- Check token permissions and expiration
+- Ensure correct environment (production vs sandbox)
+
+**Network Errors:**
+- Check internet connection
+- Verify API endpoint URLs
+- Review timeout and retry settings
+
+**Rate Limiting:**
+- Implement exponential backoff
+- Reduce request frequency
+- Contact Polar for rate limit increases
+
+### Development Tools
+
+Useful development tools:
+
+```bash
+# Interactive console
+bin/console
+
+# Generate documentation
+bundle exec yard doc
+
+# Check gem dependencies
+bundle outdated
+
+# Security audit
+bundle audit
+```
+
+## Architecture Notes
+
+### HTTP Client Design
+
+The HTTP client uses Faraday with:
+- JSON request/response handling
+- Automatic retries with exponential backoff
+- Timeout configuration
+- Rate limiting respect
+- Comprehensive error handling
+
+### Pagination Strategy
+
+Pagination follows the iterator pattern:
+- Lazy loading of pages
+- Support for auto-pagination
+- Memory efficient streaming
+- Configurable page sizes
+
+### Error Handling Philosophy
+
+- Specific error classes for different scenarios
+- Preserve original HTTP response data
+- Meaningful error messages
+- Consistent error interface
+
+### Security Considerations
+
+- Secure webhook signature verification
+- Token validation and format checking
+- Safe string comparison for cryptographic operations
+- No sensitive data in logs (when debug disabled)
+
+For questions or help with development, please:
+- Check existing GitHub issues
+- Review documentation
+- Ask in Polar Discord community
+- Create new GitHub issue for bugs/features