volley-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 940af3ec50cfcfc56d2893bade22ebbbb44c7cc5144e300501f2b58d1d3191b9
+  data.tar.gz: ea237641f9c32ec904746ae2c19594eeba3027190974aa5fa5292df6f565c898
+SHA512:
+  metadata.gz: 348df765bfee9e5532d372313e1d53a922608de93da701e02520cc94d596edbf6162c3736fdbfdaade08952ce2385c93eca4f3202d6f60f7331015e6a6dea998
+  data.tar.gz: 47bb9e624a10a3cf375cd3e726b373179788bcf9f8b01ab497d9e08ad3af5317e067fc430c82d9f9f48b8b8932ca6675b90fd2d8e9ef1424818330b401df262d

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to the Volley Ruby SDK 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).
+
+## [1.0.0] - 2025-01-16
+
+### Added
+- Initial release of the Volley Ruby SDK
+- Full API coverage for all Volley endpoints:
+  - Organizations (list, get, create)
+  - Projects (list, create, update, delete)
+  - Sources (list, create, get, update, delete)
+  - Destinations (list, create, get, update, delete)
+  - Connections (create, get, update, delete)
+  - Events (list, get, replay)
+  - Delivery Attempts (list with filters)
+  - Webhooks (send)
+- Type-safe models for all API request/response structures
+- Custom exception class (`VolleyException`) with HTTP status code tracking
+- Organization context management
+- Comprehensive unit tests with mocked HTTP responses
+- Integration tests for real API calls
+- Full documentation (README, TESTING, RELEASING)
+- Example code demonstrating SDK usage
+- Ruby 2.7.0+ support
+- Gem package ready for RubyGems
+
+[1.0.0]: https://github.com/volleyhq/volley-ruby/releases/tag/v1.0.0
+

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Volley
+
+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.
+

data/README.md

@@ -0,0 +1,327 @@
+# Volley Ruby SDK
+
+Official Ruby SDK for the Volley API. This SDK provides a convenient way to interact with the Volley webhook infrastructure API.
+
+[Volley](https://volleyhooks.com) is a webhook infrastructure platform that provides reliable webhook delivery, rate limiting, retries, monitoring, and more.
+
+## Resources
+
+- **Documentation**: [https://docs.volleyhooks.com](https://docs.volleyhooks.com)
+- **Getting Started Guide**: [https://docs.volleyhooks.com/getting-started](https://docs.volleyhooks.com/getting-started)
+- **API Reference**: [https://docs.volleyhooks.com/api](https://docs.volleyhooks.com/api)
+- **Authentication Guide**: [https://docs.volleyhooks.com/authentication](https://docs.volleyhooks.com/authentication)
+- **Security Guide**: [https://docs.volleyhooks.com/security](https://docs.volleyhooks.com/security)
+- **Console**: [https://app.volleyhooks.com](https://app.volleyhooks.com)
+- **Website**: [https://volleyhooks.com](https://volleyhooks.com)
+
+## Requirements
+
+- Ruby 2.7.0 or higher
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'volley-ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install volley-ruby
+```
+
+## Quick Start
+
+```ruby
+require 'volley'
+
+# Create a client with your API token
+client = Volley::VolleyClient.new('your-api-token')
+
+# Optionally set organization context
+client.set_organization_id(123)
+
+# List organizations
+orgs = client.organizations.list
+orgs.each do |org|
+  puts "Organization: #{org.name} (ID: #{org.id})"
+end
+```
+
+## Authentication
+
+Volley uses API tokens for authentication. These are long-lived tokens designed for programmatic access.
+
+### Getting Your API Token
+
+1. Log in to the [Volley Console](https://app.volleyhooks.com)
+2. Navigate to **Settings → Account → API Token**
+3. Click **View Token** (you may need to verify your password)
+4. Copy the token and store it securely
+
+**Important**: API tokens are non-expiring and provide full access to your account. Keep them secure and rotate them if compromised. See the [Security Guide](https://docs.volleyhooks.com/security) for best practices.
+
+```ruby
+client = Volley::VolleyClient.new('your-api-token')
+```
+
+For more details on authentication, API tokens, and security, see the [Authentication Guide](https://docs.volleyhooks.com/authentication) and [Security Guide](https://docs.volleyhooks.com/security).
+
+## Organization Context
+
+When you have multiple organizations, you need to specify which organization context to use for API requests. The API verifies that resources (like projects) belong to the specified organization.
+
+You can set the organization context in two ways:
+
+```ruby
+# Method 1: Set organization ID for all subsequent requests
+client.set_organization_id(123)
+
+# Method 2: Create client with organization ID
+client = Volley::VolleyClient.new('your-api-token', organization_id: 123)
+
+# Clear organization context (uses first accessible organization)
+client.clear_organization_id
+```
+
+**Note**: If you don't set an organization ID, the API uses your first accessible organization by default. For more details, see the [API Reference - Organization Context](https://docs.volleyhooks.com/api#organization-context).
+
+## Examples
+
+### Organizations
+
+```ruby
+# List all organizations
+orgs = client.organizations.list
+
+# Get current organization
+org = client.organizations.get  # nil = use default
+
+# Create organization
+new_org = client.organizations.create(name: 'My Organization')
+```
+
+### Projects
+
+```ruby
+# List projects (requires organization context)
+client.set_organization_id(123)
+projects = client.projects.list
+
+# Create project
+project = client.projects.create(name: 'My Project')
+
+# Update project
+updated = client.projects.update(project_id: project.id, name: 'Updated Name')
+
+# Delete project
+client.projects.delete(project_id: project.id)
+```
+
+### Sources
+
+```ruby
+# List sources for a project
+sources = client.sources.list(project_id: project_id)
+
+# Create source
+source = client.sources.create(
+  project_id: project_id,
+  slug: 'my-source',
+  type: 'webhook',
+  eps: 100,
+  verify_signature: true
+)
+
+# Get source
+source = client.sources.get(project_id: project_id, source_id: source_id)
+
+# Update source
+updated = client.sources.update(
+  project_id: project_id,
+  source_id: source_id,
+  slug: 'new-slug',
+  eps: 200
+)
+
+# Delete source
+client.sources.delete(project_id: project_id, source_id: source_id)
+```
+
+### Destinations
+
+```ruby
+# List destinations for a project
+destinations = client.destinations.list(project_id: project_id)
+
+# Create destination
+destination = client.destinations.create(
+  project_id: project_id,
+  name: 'My Destination',
+  url: 'https://example.com/webhook',
+  eps: 50
+)
+
+# Get destination
+destination = client.destinations.get(project_id: project_id, destination_id: destination_id)
+
+# Update destination
+updated = client.destinations.update(
+  project_id: project_id,
+  destination_id: destination_id,
+  name: 'Updated Name',
+  url: 'https://new.example.com/webhook'
+)
+
+# Delete destination
+client.destinations.delete(project_id: project_id, destination_id: destination_id)
+```
+
+### Connections
+
+```ruby
+# Create connection
+connection = client.connections.create(
+  project_id: project_id,
+  source_id: source_id,
+  destination_id: destination_id,
+  status: 'active',
+  max_retries: 3
+)
+
+# Get connection
+connection = client.connections.get(connection_id: connection_id)
+
+# Update connection
+updated = client.connections.update(
+  connection_id: connection_id,
+  status: 'paused',
+  eps: 100
+)
+
+# Delete connection
+client.connections.delete(connection_id: connection_id)
+```
+
+### Events
+
+```ruby
+# List events with filters
+result = client.events.list(
+  project_id: project_id,
+  limit: 10,
+  offset: 0,
+  source_id: 'src_123',
+  status: 'failed'
+)
+
+result[:events].each do |event|
+  puts "Event ID: #{event.event_id}, Status: #{event.status}"
+end
+
+# Get event by ID
+event = client.events.get(project_id: project_id, event_id: 'evt_abc123xyz')
+
+# Replay a failed event
+message = client.events.replay(event_id: 'evt_abc123xyz')
+```
+
+### Delivery Attempts
+
+```ruby
+# List delivery attempts with filters
+result = client.delivery_attempts.list(
+  project_id: project_id,
+  event_id: 'evt_abc123xyz',
+  status: 'failed',
+  limit: 20
+)
+
+result[:attempts].each do |attempt|
+  puts "Attempt ID: #{attempt.id}, Status: #{attempt.status}"
+end
+```
+
+### Webhooks
+
+```ruby
+# Send a webhook
+message = client.webhooks.send(
+  source_id: source_id,
+  destination_id: destination_id,
+  body: { key: 'value', data: 'test' },
+  headers: { 'X-Custom-Header' => 'value' }
+)
+```
+
+## Error Handling
+
+The SDK raises `VolleyException` for API errors. The exception includes the HTTP status code and error message:
+
+```ruby
+begin
+  org = client.organizations.get(organization_id: 999)
+rescue Volley::VolleyException => e
+  puts "Error: #{e.message}"
+  puts "Status Code: #{e.status_code}"
+
+  # Check specific error types
+  if e.not_found?
+    puts 'Organization not found'
+  elsif e.unauthorized?
+    puts 'Authentication failed'
+  end
+end
+```
+
+## Client Options
+
+You can customize the client with additional options:
+
+```ruby
+require 'faraday'
+
+# Custom base URL (for testing)
+client = Volley::VolleyClient.new(
+  'your-api-token',
+  base_url: 'https://api.staging.volleyhooks.com'
+)
+
+# Custom HTTP client
+http_client = Faraday.new do |f|
+  f.request :retry, { max: 5, interval: 2 }
+end
+client = Volley::VolleyClient.new(
+  'your-api-token',
+  http_client: http_client
+)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/volleyhq/volley-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).
+
+## Support
+
+- **Documentation**: [https://docs.volleyhooks.com](https://docs.volleyhooks.com)
+- **Issues**: [https://github.com/volleyhq/volley-ruby/issues](https://github.com/volleyhq/volley-ruby/issues)
+- **Email**: support@volleyhooks.com
+

data/RELEASING.md

@@ -0,0 +1,131 @@
+# Releasing the Volley Ruby SDK
+
+This document describes the process for releasing a new version of the Volley Ruby SDK.
+
+## Prerequisites
+
+1. Ensure all tests pass:
+```bash
+bundle install
+bundle exec rspec
+```
+
+2. Update version numbers:
+   - Update `VERSION` in `lib/volley/version.rb`
+   - Update version in `volley-ruby.gemspec` (if needed)
+
+3. Update CHANGELOG.md with the new version and changes
+
+4. Ensure code quality:
+```bash
+bundle exec rubocop
+```
+
+## Release Process
+
+### 1. Build the Gem
+
+```bash
+gem build volley-ruby.gemspec
+```
+
+This creates a `.gem` file (e.g., `volley-ruby-1.0.0.gem`).
+
+### 2. Test the Gem Locally
+
+```bash
+gem install ./volley-ruby-1.0.0.gem
+```
+
+Test in a separate directory:
+
+```ruby
+require 'volley'
+client = Volley::VolleyClient.new('test-token')
+# Test basic functionality
+```
+
+### 3. Create a Git Tag
+
+```bash
+git tag -a v1.0.0 -m "Release version 1.0.0"
+git push origin v1.0.0
+```
+
+### 4. Create a GitHub Release
+
+1. Go to the [GitHub repository](https://github.com/volleyhq/volley-ruby)
+2. Click "Releases" → "Draft a new release"
+3. Select the tag you just created
+4. Add release notes (copy from CHANGELOG.md)
+5. Publish the release
+
+### 5. Publish to RubyGems
+
+```bash
+gem push volley-ruby-1.0.0.gem
+```
+
+**Note**: You need to be logged in to RubyGems. If not already logged in:
+
+```bash
+gem signin
+```
+
+Enter your RubyGems credentials.
+
+### 6. Verify Release
+
+1. Verify the gem is available on RubyGems:
+   ```bash
+   gem search volley-ruby
+   ```
+
+2. Test installation:
+   ```bash
+   gem install volley-ruby
+   ```
+
+3. Verify the version:
+   ```ruby
+   require 'volley'
+   puts Volley::VERSION
+   ```
+
+## Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for new functionality in a backward-compatible manner
+- **PATCH** version for backward-compatible bug fixes
+
+## Post-Release Checklist
+
+- [ ] All tests pass
+- [ ] Version numbers updated
+- [ ] CHANGELOG.md updated
+- [ ] Code quality checks pass (RuboCop)
+- [ ] Gem built and tested locally
+- [ ] Git tag created and pushed
+- [ ] GitHub release created
+- [ ] Gem published to RubyGems
+- [ ] Package available on RubyGems.org
+- [ ] Documentation updated (if needed)
+- [ ] Announcement posted (if major release)
+
+## Troubleshooting
+
+### Gem Push Fails
+
+If `gem push` fails with authentication errors:
+1. Check you're logged in: `gem signin`
+2. Verify your credentials are correct
+3. Check if the gem name is already taken (should be `volley-ruby`)
+
+### Version Already Exists
+
+If you get an error that the version already exists:
+1. Check RubyGems.org to see if the version is already published
+2. If it's a mistake, you'll need to yank the version: `gem yank volley-ruby -v 1.0.0`
+3. Then republish with the correct version
+

data/TESTING.md

@@ -0,0 +1,155 @@
+# Testing the Volley Ruby SDK
+
+This document describes how to run tests for the Volley Ruby SDK.
+
+## Prerequisites
+
+1. Install dependencies:
+```bash
+bundle install
+```
+
+2. Ensure RSpec is installed (included in dev dependencies):
+```bash
+bundle exec rspec --version
+```
+
+## Running Tests
+
+### Unit Tests
+
+Unit tests use mocked HTTP responses with WebMock and don't require a real API token:
+
+```bash
+bundle exec rspec spec/
+```
+
+Or run specific test files:
+
+```bash
+bundle exec rspec spec/volley_client_spec.rb
+bundle exec rspec spec/organizations_resource_spec.rb
+```
+
+### Integration Tests
+
+Integration tests make real API calls to the Volley API. These tests are skipped unless `VOLLEY_API_TOKEN` is set.
+
+To run integration tests:
+
+1. Set your API token:
+```bash
+export VOLLEY_API_TOKEN=your-api-token-here
+```
+
+2. Run integration tests:
+```bash
+bundle exec rspec spec/integration_spec.rb
+```
+
+**Note**: Integration tests may create, modify, or delete resources in your account. Use a test account or be prepared to clean up test data.
+
+### Running All Tests
+
+To run all tests (unit and integration):
+
+```bash
+bundle exec rspec
+```
+
+## Test Coverage
+
+To generate a test coverage report, you can use SimpleCov:
+
+1. Add SimpleCov to your Gemfile:
+```ruby
+group :test do
+  gem 'simplecov', require: false
+end
+```
+
+2. Add to `spec/spec_helper.rb`:
+```ruby
+require 'simplecov'
+SimpleCov.start
+```
+
+3. Run tests:
+```bash
+bundle exec rspec
+```
+
+Coverage reports will be generated in the `coverage/` directory.
+
+## Writing Tests
+
+### Unit Tests
+
+Unit tests should mock HTTP responses using WebMock:
+
+```ruby
+require 'webmock/rspec'
+
+RSpec.describe Volley::VolleyClient do
+  it 'makes successful request' do
+    stub_request(:get, 'https://api.volleyhooks.com/api/org')
+      .with(headers: { 'Authorization' => 'Bearer test-token' })
+      .to_return(status: 200, body: '{"id": 1, "name": "Test"}')
+
+    client = Volley::VolleyClient.new('test-token')
+    response = client.request('GET', '/api/org')
+    expect(response['id']).to eq(1)
+  end
+end
+```
+
+### Integration Tests
+
+Integration tests should:
+- Check for `VOLLEY_API_TOKEN` environment variable
+- Skip if not set
+- Clean up any resources created during tests
+- Use descriptive test names
+
+Example:
+
+```ruby
+RSpec.describe 'Integration Tests', type: :integration do
+  let(:api_token) { ENV['VOLLEY_API_TOKEN'] }
+  let(:client) { Volley::VolleyClient.new(api_token) if api_token }
+
+  before do
+    skip 'VOLLEY_API_TOKEN environment variable is not set' unless api_token
+  end
+
+  it 'lists organizations' do
+    orgs = client.organizations.list
+    expect(orgs).to be_a(Array)
+  end
+end
+```
+
+## Continuous Integration
+
+The SDK includes RSpec configuration that can be used in CI/CD pipelines. The configuration:
+
+- Runs all tests in the `spec/` directory
+- Excludes integration tests by default (unless `VOLLEY_API_TOKEN` is set)
+- Uses documentation format for better output
+
+## Code Quality
+
+### RuboCop
+
+To check code style:
+
+```bash
+bundle exec rubocop
+```
+
+To auto-fix issues:
+
+```bash
+bundle exec rubocop -a
+```
+

data/examples/example.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/volley'
+
+# Initialize the client
+client = Volley::VolleyClient.new('your-api-token')
+
+# List organizations
+orgs = client.organizations.list
+orgs.each do |org|
+  puts "Organization: #{org.name} (ID: #{org.id})"
+end
+
+# Get the first organization
+unless orgs.empty?
+  org = client.organizations.get(organization_id: orgs[0].id)
+  puts "Current organization: #{org.name}"
+
+  # Set organization context
+  client.set_organization_id(org.id)
+
+  # List projects
+  projects = client.projects.list
+  projects.each do |project|
+    puts "Project: #{project.name} (ID: #{project.id})"
+  end
+
+  # Create a new project
+  unless projects.empty?
+    project = projects[0]
+
+    # List sources
+    sources = client.sources.list(project_id: project.id)
+    puts "Found #{sources.length} sources"
+
+    # List events
+    events_result = client.events.list(project_id: project.id, limit: 10)
+    puts "Found #{events_result[:total]} events"
+  end
+end
+