basecamp-sdk 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5251d36b00bfd269e7fce1bc324c2c9b491b9d0f0d30296807c0b1b724272adc
+  data.tar.gz: c590cec999d1b5c687456d8cdf1259712df2fcb26260048410ac5edd41dd772b
+SHA512:
+  metadata.gz: 874a76ab2b404c5ad8bada234f9002ba4e50d3ad5e574352d0f6cc53991efa656f0adb0ddd1701df52e66966ed201740b1156c9aaa7a3193422c9ab82fa877ae
+  data.tar.gz: 05570761aa1e7a59823ed614505391415f883b41fcf7ba4b4197f51ad2ad07cf7ce9d7ecd7722ecfe7e60d759fb963638f7bfe621b20406233dcf1b0a1909400

data/.rubocop.yml

@@ -0,0 +1,14 @@
+# 37signals house style
+inherit_gem:
+  rubocop-37signals: rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 3.2
+  Exclude:
+    - "vendor/**/*"
+    - "lib/basecamp/generated/**/*"
+
+# Documentation not required for tests
+Style/Documentation:
+  Exclude:
+    - "test/**/*"

data/.yardopts

@@ -0,0 +1,6 @@
+--output-dir doc
+--protected
+--no-private
+--embed-mixins
+--title "Basecamp Ruby SDK"
+lib/**/*.rb

data/README.md

@@ -0,0 +1,293 @@
+# Basecamp Ruby SDK
+
+Official Ruby SDK for the [Basecamp API](https://github.com/basecamp/bc3-api).
+
+## Requirements
+
+- Ruby 3.2+
+- Faraday HTTP client
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "basecamp-sdk"
+```
+
+Or install directly:
+
+```bash
+gem install basecamp-sdk
+```
+
+## Quick Start
+
+```ruby
+require "basecamp"
+
+# Create client with access token
+client = Basecamp.client(access_token: ENV["BASECAMP_TOKEN"])
+
+# Scope to an account
+account = client.for_account(ENV["BASECAMP_ACCOUNT_ID"])
+
+# List projects
+account.projects.list.each do |project|
+  puts "#{project['id']}: #{project['name']}"
+end
+
+# Get a specific project
+project = account.projects.get(project_id: 12345)
+
+# Create a todo
+todo = account.todos.create(
+  project_id: 12345,
+  todolist_id: 67890,
+  content: "Review PR",
+  due_on: "2024-12-31"
+)
+```
+
+## Configuration
+
+### Basic Configuration
+
+```ruby
+config = Basecamp::Config.new(
+  base_url: "https://3.basecampapi.com",  # Default
+  timeout: 30,                             # Request timeout in seconds
+  max_retries: 3,                          # Max retry attempts for GET requests
+  base_delay: 1.0,                         # Base delay for exponential backoff
+  max_pages: 10_000                         # Max pages for pagination
+)
+
+token_provider = Basecamp::StaticTokenProvider.new(ENV["BASECAMP_TOKEN"])
+client = Basecamp::Client.new(config: config, token_provider: token_provider)
+```
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `base_url` | `https://3.basecampapi.com` | Basecamp API base URL |
+| `timeout` | `30` | HTTP request timeout (seconds) |
+| `max_retries` | `3` | Maximum retry attempts for GET requests |
+| `base_delay` | `1.0` | Base delay for exponential backoff (seconds) |
+| `max_jitter` | `0.1` | Maximum random jitter added to delays |
+| `max_pages` | `10_000` | Maximum pages to fetch during pagination |
+
+## OAuth Authentication
+
+### Token Providers
+
+The SDK supports multiple authentication patterns:
+
+```ruby
+# Static token (simplest)
+token_provider = Basecamp::StaticTokenProvider.new("your-access-token")
+
+# OAuth with refresh
+token_provider = Basecamp::OauthTokenProvider.new(
+  access_token: "access-token",
+  refresh_token: "refresh-token",
+  expires_at: Time.now + 3600,
+  client_id: ENV["BASECAMP_CLIENT_ID"],
+  client_secret: ENV["BASECAMP_CLIENT_SECRET"]
+)
+```
+
+### OAuth Flow Helpers
+
+```ruby
+# 1. Discover OAuth configuration
+config = Basecamp::Oauth.discover_launchpad
+
+# 2. Build authorization URL (redirect user here)
+auth_url = "#{config.authorization_endpoint}?" + URI.encode_www_form(
+  type: "web_server",
+  client_id: ENV["BASECAMP_CLIENT_ID"],
+  redirect_uri: "https://myapp.com/callback"
+)
+
+# 3. Exchange code for tokens (in callback handler)
+token = Basecamp::Oauth.exchange_code(
+  token_endpoint: config.token_endpoint,
+  code: params[:code],
+  redirect_uri: "https://myapp.com/callback",
+  client_id: ENV["BASECAMP_CLIENT_ID"],
+  client_secret: ENV["BASECAMP_CLIENT_SECRET"],
+  use_legacy_format: true  # Required for Launchpad
+)
+
+# 4. Use the token
+client = Basecamp.client(access_token: token.access_token)
+
+# 5. Refresh when needed
+if token.expired?
+  token = Basecamp::Oauth.refresh_token(
+    token_endpoint: config.token_endpoint,
+    refresh_token: token.refresh_token,
+    use_legacy_format: true
+  )
+end
+```
+
+## Services
+
+The SDK provides 37 services covering the complete Basecamp API:
+
+| Service | Description |
+|---------|-------------|
+| `projects` | Project management |
+| `todos` | Todo items |
+| `todolists` | Todo lists |
+| `todosets` | Todo set containers |
+| `todolist_groups` | Todolist grouping/folders |
+| `people` | People/users |
+| `comments` | Comments on recordings |
+| `messages` | Message posts |
+| `message_boards` | Message boards |
+| `message_types` | Message categories |
+| `campfires` | Chat rooms |
+| `schedules` | Calendar schedules |
+| `documents` | Documents |
+| `vaults` | File folders |
+| `uploads` | File uploads |
+| `attachments` | Binary attachments |
+| `recordings` | Generic recordings |
+| `webhooks` | Webhook subscriptions |
+| `subscriptions` | Notification subscriptions |
+| `templates` | Project templates |
+| `events` | Activity events |
+| `checkins` | Automatic check-ins |
+| `forwards` | Email forwards |
+| `cards` | Card table cards |
+| `card_tables` | Card tables (kanban) |
+| `card_columns` | Card table columns |
+| `card_steps` | Card workflow steps |
+| `lineup` | Card lineup view |
+| `tools` | Project dock tools |
+| `search` | Full-text search |
+| `reports` | Activity reports |
+| `timeline` | Activity timeline |
+| `timesheet` | Time tracking reports |
+| `client_approvals` | Client approval workflows |
+| `client_correspondences` | Client communications |
+| `client_replies` | Client replies |
+| `authorization` | Auth info |
+
+## Pagination
+
+All list methods return lazy Enumerators that automatically handle pagination:
+
+```ruby
+# Automatically fetches all pages
+account.projects.list.each do |project|
+  puts project["name"]
+end
+
+# Take only what you need
+first_10 = account.todos.list(todolist_id: 456).take(10)
+
+# Convert to array (fetches all pages)
+all_projects = account.projects.list.to_a
+```
+
+## Retry Behavior
+
+GET requests automatically retry on transient failures with exponential backoff:
+
+- **Retryable errors**: 429 (rate limit), 502, 503, 504 (gateway errors)
+- **Backoff**: Exponential with jitter (1s, 2s, 4s...)
+- **Rate limits**: Respects `Retry-After` header
+
+Mutation operations (POST, PUT, DELETE) do **not** retry to prevent data duplication.
+
+## Error Handling
+
+```ruby
+begin
+  account.projects.get(project_id: 99999)
+rescue Basecamp::NotFoundError => e
+  puts "Project not found: #{e.message}"
+rescue Basecamp::RateLimitError => e
+  puts "Rate limited, retry after: #{e.retry_after} seconds"
+rescue Basecamp::AuthError => e
+  puts "Authentication failed: #{e.message}"
+rescue Basecamp::APIError => e
+  puts "API error (#{e.http_status}): #{e.message}"
+end
+```
+
+### Error Types
+
+| Error | Description |
+|-------|-------------|
+| `APIError` | Base error class for all API errors |
+| `AuthError` | Authentication failures (401) |
+| `ForbiddenError` | Access denied (403) |
+| `NotFoundError` | Resource not found (404) |
+| `ValidationError` | Invalid request data (400, 422) |
+| `RateLimitError` | Rate limit exceeded (429) |
+| `NetworkError` | Connection failures |
+
+## Observability Hooks
+
+Monitor SDK behavior with hooks:
+
+```ruby
+class MyHooks
+  include Basecamp::Hooks
+
+  def on_request_start(info)
+    puts "Starting #{info.method} #{info.url}"
+  end
+
+  def on_request_end(info, result)
+    puts "Completed in #{result.duration}s with status #{result.status_code}"
+  end
+
+  def on_retry(info, attempt, error, delay)
+    puts "Retrying attempt #{attempt} after #{delay}s"
+  end
+
+  def on_paginate(url, page)
+    puts "Fetching page #{page}"
+  end
+end
+
+client = Basecamp::Client.new(
+  config: config,
+  token_provider: token_provider,
+  hooks: MyHooks.new
+)
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `BASECAMP_TOKEN` | OAuth access token |
+| `BASECAMP_ACCOUNT_ID` | Account ID |
+| `BASECAMP_BASE_URL` | API base URL (default: `https://3.basecampapi.com`) |
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rake test
+
+# Run linter
+bundle exec rubocop
+
+# Generate types from OpenAPI
+ruby scripts/generate-types.rb
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+require 'yard'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+RuboCop::RakeTask.new
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = [ 'lib/**/*.rb' ]
+  t.options = [ '--output-dir', 'doc' ]
+end
+
+desc 'Start an interactive console with the SDK loaded'
+task :console do
+  exec 'bin/console'
+end
+
+task default: %i[test rubocop]

data/basecamp-sdk.gemspec

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'lib/basecamp/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'basecamp-sdk'
+  spec.version = Basecamp::VERSION
+  spec.authors = [ 'Basecamp' ]
+  spec.email = [ 'support@basecamp.com' ]
+
+  spec.summary = 'Official Ruby SDK for the Basecamp API'
+  spec.description = 'A Ruby SDK for the Basecamp API with automatic retry, ' \
+                     'exponential backoff, Link header pagination, and observability hooks.'
+  spec.homepage = 'https://github.com/basecamp/basecamp-sdk'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/releases"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.require_paths = [ 'lib' ]
+
+  # Runtime dependencies
+  spec.add_dependency 'faraday', '~> 2.0'
+  spec.add_dependency 'zeitwerk', '~> 2.6'
+
+  # Development dependencies
+  spec.add_development_dependency 'minitest', '~> 6.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rubocop-37signals'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'webmock', '~> 3.24'
+  spec.add_development_dependency 'irb', '~> 1.15'
+  spec.add_development_dependency 'rdoc', '~> 7.1'
+  spec.add_development_dependency 'webrick', '~> 1.9'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end

data/lib/basecamp/auth_strategy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # AuthStrategy controls how authentication is applied to HTTP requests.
+  # The default strategy is BearerAuth, which uses a TokenProvider to set
+  # the Authorization header with a Bearer token.
+  #
+  # Custom strategies can implement alternative auth schemes such as
+  # cookie-based auth, API keys, or mutual TLS.
+  #
+  # To implement a custom strategy, create a class that responds to
+  # #authenticate(headers), where headers is a Hash that you can modify.
+  module AuthStrategy
+    # Apply authentication to the given headers hash.
+    # @param headers [Hash] the request headers to modify
+    def authenticate(headers)
+      raise NotImplementedError, "#{self.class} must implement #authenticate"
+    end
+  end
+
+  # Bearer token authentication strategy (default).
+  # Sets the Authorization header with "Bearer {token}".
+  class BearerAuth
+    include AuthStrategy
+
+    # @param token_provider [TokenProvider] provides access tokens
+    def initialize(token_provider)
+      @token_provider = token_provider
+    end
+
+    # @return [TokenProvider] the underlying token provider
+    attr_reader :token_provider
+
+    def authenticate(headers)
+      headers["Authorization"] = "Bearer #{@token_provider.access_token}"
+    end
+  end
+end

data/lib/basecamp/chain_hooks.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Composes multiple Hooks implementations, calling them in sequence.
+  # Start events are called in order; end events are called in reverse order.
+  class ChainHooks
+    include Hooks
+
+    def initialize(*hooks)
+      @hooks = hooks
+    end
+
+    def on_operation_start(info)
+      @hooks.each { |h| safe_call { h.on_operation_start(info) } }
+    end
+
+    def on_operation_end(info, result)
+      @hooks.reverse_each { |h| safe_call { h.on_operation_end(info, result) } }
+    end
+
+    def on_request_start(info)
+      @hooks.each { |h| safe_call { h.on_request_start(info) } }
+    end
+
+    def on_request_end(info, result)
+      @hooks.reverse_each { |h| safe_call { h.on_request_end(info, result) } }
+    end
+
+    def on_retry(info, attempt, error, delay)
+      @hooks.each { |h| safe_call { h.on_retry(info, attempt, error, delay) } }
+    end
+
+    def on_paginate(url, page)
+      @hooks.each { |h| safe_call { h.on_paginate(url, page) } }
+    end
+
+    private
+
+    def safe_call
+      yield
+    rescue => e
+      warn "Basecamp::ChainHooks: hook raised #{e.class}: #{e.message}"
+    end
+  end
+end