active_collab-ruby-sdk 0.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 618cfa962f35bcae3a41e437b9aac7d77ae528f535f452355146ccacdb56885d
+  data.tar.gz: 3f370da2a5aeba7923bdc7cb44531a7c9d5f21eec0ded03bf4312194a0e2c6db
+SHA512:
+  metadata.gz: 47597a3f5889d9abbb95699b3f1dffbe9a231c4eb28112b707af2fe0e9e9a06d56cefa88c1d87d00d52ed5d095fb4bc21694ea7f063996b0279fb7d8ff0dffef
+  data.tar.gz: f23a36519466b76297966bf02f319235113a76d7a3450612f8e4f8c00cd9fd9a40ef41970f4d1198c54cb56b9f109600450e9185a4ca70e1b1c6009db81ddf81

data/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.3.2] - 2026-02-12
+
+### Added
+- `bin/console` script for interactive development sessions.
+
+### Removed
+- `Rakefile` in favor of calling `rspec` directly.
+
+## [0.3.1] - 2026-02-12
+
+### Added
+- `Client#users` convenience method for accessing user endpoints directly.
+- `ostruct` as an explicit runtime dependency for Ruby 4.0 compatibility.
+
+### Changed
+- Cleaned up README code examples.
+
+## [0.3.0] - 2026-02-12
+
+### Added
+- Custom exception hierarchy: `ActiveCollab::Error`, `APIError`, `AuthenticationError`, `NotFoundError`, `RateLimitError`, `ParseError`.
+- HTTP error handling: 4xx/5xx responses now raise descriptive exceptions.
+- JSON parse error handling: invalid response bodies raise `ParseError`.
+- HTTP timeouts (30s open/read) to prevent hanging requests.
+- Comprehensive test coverage for all public methods (63 examples).
+- YARD documentation for all public methods.
+- CHANGELOG, `.rspec`, and `Rakefile`.
+- Gemspec metadata (`homepage_uri`, `source_code_uri`, `changelog_uri`, `rubygems_mfa_required`).
+
+### Changed
+- **Breaking:** `Projects#list` renamed to `Projects#all`.
+- **Breaking:** `Tasks#get` renamed to `Tasks#find`.
+- **Breaking:** `TimeRecords#push` renamed to `TimeRecords#create`.
+- **Breaking:** `Token#header` renamed to `Token#auth_header`.
+- **Breaking:** `Token#raw` removed (use `Token#value` instead).
+- `Response#to_json` renamed to `Response#to_json_string` to avoid shadowing `Object#to_json`. The `format: 'json'` parameter is unchanged.
+- VERSION extracted to dedicated `lib/active_collab/version.rb`.
+- Gemspec no longer loads the entire library at eval time.
+- Development dependencies moved from gemspec to Gemfile.
+- Narrowed ActiveSupport requires to only the extensions actually used.
+- `json` dependency loosened from `~> 2.18` to `~> 2.10`.
+- `activesupport` dependency widened to `>= 7, < 9`.
+- Tasks and TaskLists source files moved from `lib/active_collab/projects/` to `lib/active_collab/` to match their namespace.
+
+### Fixed
+- `Client#initialize` no longer mutates the caller's options hash.
+- `Token#auth_header` now uses correct `AuthApiToken` casing (was `Authapitoken`).
+- Mixed string/symbol key handling in `Tasks#archived` pagination.
+- Added explicit `require 'ostruct'` for Ruby 3.3+ compatibility.
+- `frozen_string_literal: true` added to all source files.
+
+## [0.2.2] - 2025-09-03
+
+### Changed
+- Pinned `activesupport` to `~> 7` minimum.
+
+## [0.2.1] - 2025-06-28
+
+### Fixed
+- Added missing `params` argument to `Projects#list`.
+
+## [0.2.0] - 2025-06-28
+
+### Added
+- Format parameter support (`hash`, `json`, `object`) for all API calls.
+- GET requests now correctly append params as query strings.
+
+## [0.1.0] - 2025-06-15
+
+### Added
+- Initial release with Client, Token, Response, LoginResponse.
+- Projects, Tasks, TaskLists, TimeRecords, and Users resources.
+- Token-based and credential-based authentication.
+
+[0.3.2]: https://github.com/davelens/active_collab-ruby-sdk/compare/0.3.1...0.3.2
+[0.3.1]: https://github.com/davelens/active_collab-ruby-sdk/compare/0.3.0...0.3.1
+[0.3.0]: https://github.com/davelens/active_collab-ruby-sdk/compare/0.2.2...0.3.0
+[0.2.2]: https://github.com/davelens/active_collab-ruby-sdk/compare/0.2.1...0.2.2
+[0.2.1]: https://github.com/davelens/active_collab-ruby-sdk/compare/0.2.0...0.2.1
+[0.2.0]: https://github.com/davelens/active_collab-ruby-sdk/compare/0.1.0...0.2.0
+[0.1.0]: https://github.com/davelens/active_collab-ruby-sdk/releases/tag/0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dave Lens
+
+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,175 @@
+# ActiveCollab Ruby SDK
+
+[![CI](https://github.com/davelens/active_collab-ruby-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/davelens/active_collab-ruby-sdk/actions/workflows/ci.yml?version=1)
+
+A Ruby SDK for the [ActiveCollab](https://activecollab.com/) API. Provides a clean interface for authentication, project management, task tracking, time records, and more.
+
+## Requirements
+- Ruby >= 3.1
+- An ActiveCollab account with API access
+
+## Installation
+Add to your Gemfile:
+```ruby
+gem 'active_collab-ruby-sdk', '~> 0.3'
+```
+
+Or install directly:
+```
+gem install active_collab-ruby-sdk
+```
+
+## Authentication
+The SDK supports two authentication methods.
+
+### Token-based (if you already have a token)
+```ruby
+require 'active_collab'
+
+client = ActiveCollab::Client.new(
+  account_id: '12345',
+  token: 'your-api-token'
+)
+```
+
+### Credential-based (username/password)
+```ruby
+client = ActiveCollab::Client.new(
+  account_id: '12345',
+  username: 'user@example.com',
+  password: 'your-password',
+  client_vendor: 'YourCompany',
+  client_name: 'YourApp'
+)
+
+# Authenticates and stores the token on the client
+client.request_token!
+```
+
+The token is stored on the client instance and sent as the `X-Angie-AuthApiToken` header on all subsequent requests.
+
+## Usage
+### Projects
+```ruby
+# List all projects (returns a Hash by default)
+client.projects.all
+
+# Get projects as a JSON string
+client.projects.all(format: 'json')
+
+# Get projects as an OpenStruct
+client.projects.all(format: 'object')
+```
+
+### Tasks
+```ruby
+tasks = client.projects.tasks(project_id)
+
+# All tasks (active + archived, sorted by created_on desc)
+tasks.all
+
+# Active tasks only
+tasks.active
+
+# Archived tasks (auto-paginates through all pages)
+tasks.archived
+
+# Archived tasks for a specific page (no auto-pagination)
+tasks.archived('page' => 2)
+
+# Find a single task - includes comments!
+tasks.find(task_id)
+
+# Update a task
+tasks.update(task_id, name: 'New name')
+
+# Time records for a specific task
+tasks.time_records(task_id)
+```
+
+### Task Lists
+```ruby
+client.projects.task_lists(project_id).all
+```
+
+### Time Records
+```ruby
+time_records = client.projects.time_records(project_id)
+
+# List all time records for a project
+time_records.all
+
+# Create a new time record
+time_records.create(value: 1.5, user_id: 10, job_type_id: 1)
+```
+
+### Users
+```ruby
+# List all users
+users = client.users.all
+```
+
+### Response Formats
+All resource methods accept a `format` parameter:
+
+| Format     | Return type | Description                  |
+|------------|-------------|------------------------------|
+| `'hash'`   | `Hash`      | Parsed JSON (default)        |
+| `'json'`   | `String`    | Raw JSON response body       |
+| `'object'` | `OpenStruct`| Parsed JSON as OpenStruct    |
+
+```ruby
+client.projects.all(format: 'json')   # => '{"projects": [...]}'
+client.projects.all(format: 'object') # => #<OpenStruct projects=[...]>
+```
+
+### Token Object
+```ruby
+token = client.token
+token.value        # => "your-api-token"
+token.auth_header  # => { "X-Angie-AuthApiToken": "your-api-token" }
+```
+
+### URL Helpers
+```ruby
+# Build an app URL (for linking to the ActiveCollab web UI)
+client.app_url('/projects/3') # => URI("https://next-app.activecollab.com/12345/projects/3")
+```
+
+## Error Handling
+The SDK raises specific exceptions for API errors:
+
+```ruby
+begin
+  client.projects.all
+rescue ActiveCollab::AuthenticationError => e
+  # 401 - invalid or expired token
+  puts e.message # => "API request failed with status 401"
+  puts e.status  # => 401
+  puts e.body    # => raw response body
+rescue ActiveCollab::NotFoundError => e
+  # 404
+rescue ActiveCollab::RateLimitError => e
+  # 429
+rescue ActiveCollab::APIError => e
+  # Any other 4xx/5xx
+rescue ActiveCollab::ParseError => e
+  # Response body was not valid JSON
+  puts e.body # => the raw unparseable body
+end
+```
+
+## Development
+```
+git clone https://github.com/davelens/active_collab-ruby-sdk.git
+cd active_collab-ruby-sdk
+bundle install
+```
+
+Running tests:
+```
+rspec
+```
+
+## License
+[MIT](LICENSE)

data/lib/active_collab/client.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+# HTTP client for the ActiveCollab API.
+#
+# Handles authentication, request construction, and response parsing.
+#
+# @see https://github.com/activecollab/activecollab-feather-sdk/issues/35
+#   Auth flow documentation
+class ActiveCollab::Client
+
+  DEFAULTS = {
+    username: '',
+    password: '',
+    client_vendor: '',
+    client_name: '',
+    account_id: ''
+  }.freeze
+
+  HTTP_METHODS = {
+    'Get'  => Net::HTTP::Get,
+    'Post' => Net::HTTP::Post,
+    'Put'  => Net::HTTP::Put
+  }.freeze
+
+  APP_URL     = 'https://next-app.activecollab.com'
+  API_URL     = 'https://app.activecollab.com'
+  AUTH_URL    = 'https://activecollab.com/api/v1'
+
+  # @param options [Hash] client configuration
+  # @option options [String] :token pre-existing API token
+  # @option options [String] :account_id ActiveCollab account ID
+  # @option options [String] :username email address for authentication
+  # @option options [String] :password password for authentication
+  # @option options [String] :client_vendor vendor name for token issuance
+  # @option options [String] :client_name application name for token issuance
+  def initialize(options = {})
+    @token = options[:token]
+    @options = DEFAULTS.merge(options)
+  end
+
+  # Performs an HTTP request to the given URI.
+  #
+  # @param method [String] HTTP method ('Get', 'Post', or 'Put')
+  # @param uri [URI] the full request URI
+  # @param params [Hash] request parameters
+  # @option params [String] :format response format ('hash', 'json', or 'object')
+  # @return [Hash, String, OpenStruct] parsed response in the requested format
+  # @raise [ActiveCollab::APIError] on 4xx/5xx responses
+  def call(method, uri, params = {})
+    method = HTTP_METHODS.key?(method) ? method : 'Get'
+    data = params.except(:headers, :format)
+    format = if %w[hash json object].include?(params[:format])
+               params[:format]
+             else
+               'hash'
+             end
+
+    if method == 'Get' && data.present?
+      uri.query = [uri.query, data.to_query].compact.join('&')
+      request = Net::HTTP::Get.new(uri)
+    else
+      request = HTTP_METHODS[method].new(uri)
+      request.set_form_data(data) unless method == 'Get'
+    end
+
+    if @token
+      request['X-Angie-AuthApiToken'] = @token
+    end
+
+    response = Net::HTTP.start(
+      request.uri.hostname,
+      request.uri.port,
+      use_ssl: request.uri.scheme == "https",
+      open_timeout: 30,
+      read_timeout: 30
+    ) do |http|
+      http.request(request)
+    end
+
+    handle_response_errors!(response)
+
+    format_method = { 'hash' => :to_hash, 'json' => :to_json_string, 'object' => :to_object }
+    ActiveCollab::Response
+      .new(response.body)
+      .send(format_method[format])
+  end
+
+  # Builds a URL for the ActiveCollab web application UI.
+  #
+  # @param uri [String] path to append (e.g., '/projects/3')
+  # @return [URI] the full app URL
+  def app_url(uri)
+    URI.parse("#{APP_URL}/#{@options[:account_id]}#{uri}")
+  end
+
+  # Builds an API endpoint URL for the given path.
+  #
+  # @param uri [String] API path (e.g., '/projects')
+  # @return [URI] the full API URL
+  def call_url(uri)
+    url = if uri.include?('/external/login')
+            "#{AUTH_URL}#{uri}"
+          else
+            "#{API_URL}/#{@options[:account_id]}/api/v1#{uri}"
+          end
+
+    URI.parse(url)
+  end
+
+  # Performs a GET request.
+  #
+  # @param uri [String] API path
+  # @param params [Hash] query parameters
+  # @return [Hash, String, OpenStruct]
+  def get(uri, params = {})
+    call('Get', call_url(uri), params)
+  end
+
+  # Performs a POST request.
+  #
+  # @param uri [String] API path
+  # @param params [Hash] form data parameters
+  # @return [Hash, String, OpenStruct]
+  def post(uri, params = {})
+    call('Post', call_url(uri), params)
+  end
+
+  # Performs a PUT request.
+  #
+  # @param uri [String] API path
+  # @param params [Hash] form data parameters
+  # @return [Hash, String, OpenStruct]
+  def put(uri, params = {})
+    call('Put', call_url(uri), params)
+  end
+
+  # Authenticates with username/password and stores the resulting token.
+  #
+  # @return [String] the issued API token
+  # @raise [ActiveCollab::AuthenticationError] if credentials are invalid
+  def request_token!
+    login_response = ActiveCollab::LoginResponse.new(
+      login,
+      account_id: @options[:account_id]
+    )
+
+    token = issue_token_intent(
+      client_vendor: @options[:client_vendor],
+      client_name: @options[:client_name],
+      intent: login_response.intent
+    )
+
+    @token = token.value
+    @token
+  end
+
+  # Returns the current token wrapped in a Token object.
+  #
+  # @return [ActiveCollab::Token]
+  def token
+    ActiveCollab::Token.new(@token)
+  end
+
+  # Returns a Projects resource for accessing project endpoints.
+  #
+  # @return [ActiveCollab::Projects]
+  def projects
+    ActiveCollab::Projects.new(self)
+  end
+
+  # Returns a Users resource for accessing user endpoints.
+  #
+  # @return [ActiveCollab::Users]
+  def users
+    ActiveCollab::Users.new(self)
+  end
+
+  private
+
+  def handle_response_errors!(response)
+    status = response.code.to_i
+    return if status < 400
+
+    body = response.body
+    message = "API request failed with status #{status}"
+
+    error_class = case status
+                  when 401 then ActiveCollab::AuthenticationError
+                  when 404 then ActiveCollab::NotFoundError
+                  when 429 then ActiveCollab::RateLimitError
+                  else ActiveCollab::APIError
+                  end
+
+    raise error_class.new(message, status: status, body: body)
+  end
+
+  def issue_token_intent(opts = {})
+    response = post(
+      '/issue-token-intent',
+      client_vendor: opts[:client_vendor],
+      client_name: opts[:client_name],
+      intent: opts[:intent]
+    )
+
+    ActiveCollab::Token.new(response['token'])
+  end
+
+  def login
+    post(
+      '/external/login',
+      username: @options[:username],
+      password: @options[:password]
+    )
+  end
+
+end

data/lib/active_collab/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActiveCollab
+  # Base error class for all ActiveCollab errors.
+  class Error < StandardError; end
+
+  # Raised when the API returns an error HTTP response (4xx/5xx).
+  class APIError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message || "API request failed with status #{status}")
+    end
+  end
+
+  # Raised on 401 Unauthorized responses.
+  class AuthenticationError < APIError; end
+
+  # Raised on 404 Not Found responses.
+  class NotFoundError < APIError; end
+
+  # Raised on 429 Too Many Requests responses.
+  class RateLimitError < APIError; end
+
+  # Raised when a response body cannot be parsed as JSON.
+  class ParseError < Error
+    attr_reader :body
+
+    def initialize(message = nil, body: nil)
+      @body = body
+      super(message || 'Failed to parse response body as JSON')
+    end
+  end
+end

data/lib/active_collab/login_response.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Wraps the response from the ActiveCollab login endpoint.
+#
+# Used internally by {Client#request_token!} to extract the intent
+# token needed for API token issuance.
+class ActiveCollab::LoginResponse
+  # @param values [Hash] parsed login response body
+  # @param account_id [String, nil] the account ID to match
+  def initialize(values, account_id: nil)
+    @values = values
+    @account_id = account_id
+  end
+
+  # Returns the list of accounts from the login response.
+  #
+  # @return [Array<Hash>]
+  def accounts
+    @accounts ||= @values['accounts']
+  end
+
+  # Returns the account matching the configured account ID.
+  #
+  # @return [Hash, nil] the matching account, or nil if not found
+  def account_info
+    return @account unless @account.nil?
+
+    @account = accounts.detect do |account|
+      account['name'].to_s == @account_id.to_s
+    end
+
+    @account
+  end
+
+  # Returns the API URL for the matching account.
+  #
+  # @return [String]
+  def call_url
+    account_info['url']
+  end
+
+  # Returns the user intent token from the login response.
+  #
+  # @return [String, nil]
+  def intent
+    @values.dig('user', 'intent')
+  end
+end

data/lib/active_collab/projects.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Provides access to project-related API endpoints.
+class ActiveCollab::Projects
+  # @param client [ActiveCollab::Client]
+  def initialize(client)
+    @client = client
+  end
+
+  # Lists all projects.
+  #
+  # @param params [Hash] query parameters
+  # @option params [String] :format response format ('hash', 'json', or 'object')
+  # @return [Hash, String, OpenStruct]
+  def all(params = {})
+    @client.get('/projects', params)
+  end
+
+  # Returns a TaskLists resource scoped to the given project.
+  #
+  # @param project_id [Integer, String] the project ID
+  # @return [ActiveCollab::TaskLists]
+  def task_lists(project_id)
+    ActiveCollab::TaskLists.new(@client, project_id)
+  end
+
+  # Returns a Tasks resource scoped to the given project.
+  #
+  # @param project_id [Integer, String] the project ID
+  # @return [ActiveCollab::Tasks]
+  def tasks(project_id)
+    ActiveCollab::Tasks.new(@client, project_id)
+  end
+
+  # Returns a TimeRecords resource scoped to the given project.
+  #
+  # @param project_id [Integer, String] the project ID
+  # @return [ActiveCollab::TimeRecords]
+  def time_records(project_id)
+    ActiveCollab::TimeRecords.new(@client, project_id)
+  end
+end

data/lib/active_collab/response.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+
+# Wraps a raw HTTP response body and provides format conversion.
+class ActiveCollab::Response
+  # @return [String] the raw response body
+  attr_reader :raw_body
+
+  # @param raw_body [String, nil] the raw HTTP response body
+  def initialize(raw_body)
+    @raw_body = raw_body
+    @raw_body = '{}' if raw_body == '' || raw_body.nil?
+  end
+
+  # Returns the raw response body as a JSON string.
+  #
+  # @return [String]
+  def to_json_string
+    @raw_body
+  end
+
+  # Parses the response body as a Ruby Hash.
+  #
+  # @return [Hash]
+  # @raise [ActiveCollab::ParseError] if the body is not valid JSON
+  def to_hash
+    JSON.parse(@raw_body)
+  rescue JSON::ParserError => e
+    raise ActiveCollab::ParseError.new(
+      "Failed to parse response body as JSON: #{e.message}",
+      body: @raw_body
+    )
+  end
+
+  # Parses the response body into an OpenStruct.
+  #
+  # @return [OpenStruct]
+  # @raise [ActiveCollab::ParseError] if the body is not valid JSON
+  def to_object
+    OpenStruct.new(to_hash)
+  end
+end

data/lib/active_collab/task_lists.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Provides access to task list endpoints for a specific project.
+class ActiveCollab::TaskLists
+  # @param client [ActiveCollab::Client]
+  # @param project_id [Integer, String] the project ID
+  def initialize(client, project_id)
+    @client = client
+    @project_id = project_id
+  end
+
+  # Lists all task lists for the project.
+  #
+  # @param params [Hash] query parameters
+  # @return [Hash, String, OpenStruct]
+  def all(params = {})
+    @client
+      .get("/projects/#{@project_id}/task-lists", params)
+  end
+end

data/lib/active_collab/tasks.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Provides access to task-related API endpoints for a specific project.
+class ActiveCollab::Tasks
+  # @param client [ActiveCollab::Client]
+  # @param project_id [Integer, String] the project ID
+  def initialize(client, project_id)
+    @client = client
+    @project_id = project_id
+  end
+
+  # Returns all tasks (active + archived), sorted by created_on descending.
+  #
+  # @param params [Hash] query parameters
+  # @option params [String] 'format' response format ('hash' or 'json')
+  # @return [Hash, String] a hash with a 'tasks' key, or JSON string
+  def all(params = {})
+    temp_params = params.merge('format' => 'hash')
+    all_tasks = [active(temp_params)['tasks'] + archived(temp_params)['tasks']]
+    result = {
+      'tasks' => all_tasks
+        .flatten
+        .sort_by { |t| -t['created_on'] } || []
+    }
+
+    return JSON.generate(result) if params['format'] == 'json'
+    result
+  end
+
+  # Returns active (non-archived) tasks for the project.
+  #
+  # @param params [Hash] query parameters
+  # @return [Hash, String, OpenStruct]
+  def active(params = {})
+    @client
+      .get("/projects/#{@project_id}/tasks", params)
+  end
+
+  # Returns archived tasks for the project.
+  #
+  # Auto-paginates through all pages unless a specific page is requested.
+  #
+  # @param params [Hash] query parameters
+  # @option params [Integer] 'page' specific page to fetch (disables auto-pagination)
+  # @option params [String] 'format' response format ('hash' or 'json')
+  # @return [Hash, String] a hash with a 'tasks' key, or JSON string
+  def archived(params = {})
+    page = params['page'] || 1
+    all_tasks = []
+
+    loop do
+      response = @client
+        .get("/projects/#{@project_id}/tasks/archive", params.merge('page' => page))
+      tasks = response || []
+      all_tasks += tasks
+      break if tasks.empty? || params.key?('page')
+      page += 1
+    end
+
+    result = { 'tasks' => all_tasks.flatten.sort_by { |t| -t['created_on'] } }
+    return JSON.generate(result) if params['format'] == 'json'
+    result
+  end
+
+  # Fetches a single task by ID.
+  #
+  # @param id [Integer, String] the task ID
+  # @param params [Hash] query parameters
+  # @return [Hash, String, OpenStruct]
+  def find(id, params = {})
+    @client
+      .get("/projects/#{@project_id}/tasks/#{id}", params)
+  end
+
+  # Fetches time records for a specific task.
+  #
+  # @param id [Integer, String] the task ID
+  # @param params [Hash] query parameters
+  # @return [Hash, String, OpenStruct]
+  def time_records(id, params = {})
+    @client
+      .get("/projects/#{@project_id}/tasks/#{id}/time-records", params)
+  end
+
+  # Updates a task.
+  #
+  # @param id [Integer, String] the task ID
+  # @param params [Hash] fields to update
+  # @return [Hash, String, OpenStruct]
+  def update(id, params = {})
+    @client
+      .put("/projects/#{@project_id}/tasks/#{id}", params)
+  end
+end

data/lib/active_collab/time_records.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Provides access to time record endpoints for a specific project.
+class ActiveCollab::TimeRecords
+  # @param client [ActiveCollab::Client]
+  # @param project_id [Integer, String] the project ID
+  def initialize(client, project_id)
+    @client = client
+    @project_id = project_id
+  end
+
+  # Lists all time records for the project.
+  #
+  # @param params [Hash] query parameters
+  # @return [Hash, String, OpenStruct]
+  def all(params = {})
+    @client
+      .get("/projects/#{@project_id}/time-records", params)
+  end
+
+  # Creates a new time record for the project.
+  #
+  # @param params [Hash] time record attributes
+  # @return [Hash, String, OpenStruct]
+  def create(params = {})
+    @client
+      .post("/projects/#{@project_id}/time-records", params)
+  end
+end

data/lib/active_collab/token.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Represents an ActiveCollab API authentication token.
+class ActiveCollab::Token
+  # @return [String] the raw token string
+  attr_reader :value
+
+  # @param value [String] the API token
+  def initialize(value)
+    @value = value
+  end
+
+  # Returns the token as an HTTP authentication header hash.
+  #
+  # @return [Hash{Symbol => String}]
+  def auth_header
+    {
+      'X-Angie-AuthApiToken': @value
+    }
+  end
+end

data/lib/active_collab/users.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Provides access to user-related API endpoints.
+class ActiveCollab::Users
+  # @param client [ActiveCollab::Client]
+  def initialize(client)
+    @client = client
+  end
+
+  # Lists all users.
+  #
+  # @return [Hash, String, OpenStruct]
+  def all
+    @client.get('/users')
+  end
+end

data/lib/active_collab/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveCollab
+  VERSION = '0.3.2'
+end

data/lib/active_collab.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/object/to_query'
+
+module ActiveCollab
+  require_relative 'active_collab/version'
+  require_relative 'active_collab/errors'
+  require_relative 'active_collab/client'
+  require_relative 'active_collab/response'
+  require_relative 'active_collab/login_response'
+  require_relative 'active_collab/token'
+  require_relative 'active_collab/projects'
+  require_relative 'active_collab/task_lists'
+  require_relative 'active_collab/tasks'
+  require_relative 'active_collab/time_records'
+  require_relative 'active_collab/users'
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: active_collab-ruby-sdk
+version: !ruby/object:Gem::Version
+  version: 0.3.2
+platform: ruby
+authors:
+- Dave Lens
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: A basic Ruby SDK to interact with the Active Collab API.
+email:
+- github@davelens.be
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/active_collab.rb
+- lib/active_collab/client.rb
+- lib/active_collab/errors.rb
+- lib/active_collab/login_response.rb
+- lib/active_collab/projects.rb
+- lib/active_collab/response.rb
+- lib/active_collab/task_lists.rb
+- lib/active_collab/tasks.rb
+- lib/active_collab/time_records.rb
+- lib/active_collab/token.rb
+- lib/active_collab/users.rb
+- lib/active_collab/version.rb
+homepage: https://github.com/davelens/active_collab-ruby-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/davelens/active_collab-ruby-sdk
+  source_code_uri: https://github.com/davelens/active_collab-ruby-sdk
+  changelog_uri: https://github.com/davelens/active_collab-ruby-sdk/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby SDK for Active Collab API
+test_files: []