toggl_rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a9e314bac612a688395f89e9050e3205e2bbd563074efa11682805f76e02612e
+  data.tar.gz: 18ff60baf2d6e43bce98857d0014cbb3c614dc53ea9868bd627ca602f9ae2e52
+SHA512:
+  metadata.gz: c35729adaf2528f5157936018741056e25eefd9b01db858809eda6e3f2cc2b720115bd5a630328caadd467ec16bebbc3f875a7a0e33ce5ccd11f4b2fdd663ca7
+  data.tar.gz: 40e30a18d467111c32dc544f5cfcf37c2c4cab895c26cc721dd63a7d49803f0ec7b50bae06165b1aead82e686e1cfd8044697886a934f771fb3234a7a90b460e

data/.env_sample

@@ -0,0 +1,5 @@
+export TOGGL_API_TOKEN='API_TOKEN_GOES_HERE'
+export TOGGL_WORKSPACE_ID='8675309'
+export TOGGL_BASIC_AUTH='BASIC AUTH CRED GOES HERE TO FILTER OUT OF VCR CASSETTES' 
+export TOGGL_EMAIL='test@example.net' 
+export TOGGL_ORGANIZATION_ID='9035768' 

data/.rspec

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

data/.ruby-version

@@ -0,0 +1 @@
+3.0.3

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2024 Michael Cordell (https://mikecordell.com)
+
+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,34 @@
+# TogglRb
+
+[![Ruby](https://github.com/mcordell/toggl_rb/actions/workflows/ruby.yml/badge.svg)](https://github.com/mcordell/toggl_rb/actions/workflows/ruby.yml)
+[![Coverage Status](https://coveralls.io/repos/github/mcordell/toggl_rb/badge.svg)](https://coveralls.io/github/mcordell/toggl_rb)
+
+TODO: Delete this and the text below, and describe your gem
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/toggl_rb`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+## Usage
+
+TODO: Write usage instructions here
+
+## 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`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mcordell/toggl_rb.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/toggl_rb/client.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module TogglRb
+  # Config class stores global configuration for the TogglRb gem
+  class Client
+    attr_reader :core_connection, :reports_connection
+
+    URLS = {
+      core: { url: "https://api.track.toggl.com/api/v9" },
+      reports: { url: "https://api.track.toggl.com/reports/api/v3/" }
+    }.freeze
+
+    def initialize
+      @core_connection = Faraday.new(URLS.dig(:core, :url)).tap do |fc|
+        fc.set_basic_auth(config.username, config.password) if config.basic_auth?
+        fc.set_basic_auth(config.api_token, TogglRb::Config::API_TOKEN_PASSWORD) if config.api_token?
+        fc.headers["Content-Type"] = "application/json"
+        fc.headers["Accept"] = "application/json"
+      end
+
+      @reports_connection = Faraday.new(URLS.dig(:reports, :url)).tap do |fc|
+        fc.set_basic_auth(config.username, config.password) if config.basic_auth?
+        fc.set_basic_auth(config.api_token, TogglRb::Config::API_TOKEN_PASSWORD) if config.api_token?
+        fc.headers["Content-Type"] = "application/json"
+        fc.headers["Accept"] = "application/json"
+      end
+    end
+
+    private
+
+    # @return [TogglRb::Config]
+    def config
+      TogglRb.config
+    end
+  end
+end

data/lib/toggl_rb/config.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TogglRb
+  # Config class stores global configuration for the TogglRb gem
+  class Config
+    attr_accessor :username, :password, :api_token
+    attr_writer :debug_logging
+
+    API_TOKEN_PASSWORD = "api_token"
+
+    # Whether username and password are set within this config in order to use basic auth. Basic auth is necessary for
+    # reports API.
+    # @return [Boolean] whether username and password exist
+    def basic_auth?
+      !!(username && password)
+    end
+
+    def api_token?
+      !!api_token
+    end
+
+    # @return [Boolean] whether to log debug messages
+    def debug_logging
+      !!@debug_logging || ENV.fetch("TOGGL_RB_DEBUG_LOG", nil) || false
+    end
+
+    alias debug_logging? debug_logging
+  end
+end

data/lib/toggl_rb/core/groups.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module TogglRb
+  module Core
+    class Groups
+      include EndpointDSL
+
+      request_method :get
+      request_path "organizations/%<organization_id>s/workspaces/%<workspace_id>s/groups"
+      def list(organization_id:, workspace_id:)
+        resource_path = format(request_path, workspace_id: workspace_id, organization_id: organization_id)
+
+        send_request(request_method, resource_path).body_json
+      end
+
+      private
+
+      def send_request(request_method, resource_path, body = nil)
+        if body.nil?
+          TogglRb::Response.new(connection.send(request_method, resource_path))
+        else
+          params = body.to_json unless body.is_a?(String)
+          TogglRb::Response.new(connection.send(request_method, resource_path, params))
+        end
+      end
+
+      def connection
+        TogglRb::Core.connection
+      end
+    end
+  end
+end

data/lib/toggl_rb/core/me.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+module TogglRb
+  module Core
+    class Me
+      include EndpointDSL
+
+      request_method :get
+      request_path "me"
+      def get(with_related_data: false)
+        resource_path = with_related_data ? "#{request_path}?with_related_data=true" : request_path
+        send_request(request_method, resource_path).body_json
+      end
+
+      request_method :get
+      request_path "me/workspaces"
+      query_param :since, Date,
+                  description: "Retrieve workspaces created/modified/deleted since this date using UNIX timestamp, " \
+                               "including the dates a workspace member got added, removed or updated in the workspace."
+      def workspaces(_params = {})
+        # TODO: implement since query_param
+        send_request(request_method, request_path).body_json
+      end
+
+      private
+
+      def send_request(request_method, resource_path, body = nil)
+        rsp = if request_method == :get
+                connection.get(resource_path)
+              else
+                params = body.to_json unless body.is_a?(String)
+                connection.send(request_method, resource_path, params.to_json)
+              end
+        TogglRb::Response.new(rsp)
+      end
+
+      def connection
+        TogglRb::Core.connection
+      end
+    end
+  end
+end

data/lib/toggl_rb/core/projects.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module TogglRb
+  module Core
+    class Projects
+      include TogglRb::EndpointDSL
+
+      request_method :get
+      request_path "workspaces/%<workspace_id>s/projects"
+      query_param :active, "Boolean"
+      query_param :since, "Boolean"
+      query_param :active,	"boolean", description: "active"
+      query_param :since,	Integer,
+                  description: "Retrieve projects created/modified/deleted since this date using UNIX timestamp."
+      query_param :billable,	"boolean", description: "billable"
+      query_param :user_ids,	"array", description: "user_ids"
+      query_param :client_ids,	"array", description: "client_ids"
+      query_param :group_ids,	"array", description: "group_ids"
+      query_param :statuses,	"array", description: "statuses"
+      query_param :name,	String, description: "name"
+      query_param :page,	Integer, description: "page"
+      query_param :sort_field,	String, description: "sort_field"
+      query_param :sort_order,	String, description: "sort_order"
+      query_param :only_templates,	"boolean", description: "only_templates"
+      query_param :per_page,	Integer, description: "Number of items per page, default 151. Cannot exceed 200."
+      def search(workspace_id, query_params = {})
+        params = build_query_params(query_params)
+        resource_path = format(request_path, workspace_id: workspace_id)
+        response = connection.get(resource_path) do |request|
+          request.params = params.request_params
+        end
+        Response.new(response)
+      end
+
+      request_method :post
+      request_path "workspaces/%<workspace_id>s/projects"
+      param :active, "Boolean", description: "Whether the project is active or archived."
+      param :auto_estimates, "Boolean", optional: true, description: "Whether estimates are based on task hours."
+      param :billable, "Boolean", optional: true, description: "Whether the project is billable."
+      param :cid, Integer, description: "Client ID (legacy)."
+      param :client_id, Integer, optional: true, description: "Client ID."
+      param :client_name, String, optional: true, description: "Client name."
+      param :color, String, description: "Project color."
+      param :currency, String, optional: true, description: "Project currency."
+      param :end_date, String, description: "End date of the project timeframe."
+      param :estimated_hours, Integer, optional: true, description: "Estimated hours for the project."
+      param :fixed_fee, "Number", optional: true, description: "Project fixed fee."
+      param :is_private, "Boolean", description: "Whether the project is private."
+      param :name, String, description: "Project name."
+      param :rate, "Number", optional: true, description: "Hourly rate for the project."
+      param :rate_change_mode, String, optional: true,
+                                       description: "Rate change mode (start-today, override-current, override-all)."
+      param :recurring, "Boolean", optional: true, description: "Whether the project is recurring."
+      # nested_param :recurring_parameters do
+      #   param :custom_period, Integer, description: "Custom period for recurring setting."
+      #   param :period, String, description: "Recurring period, e.g., 'monthly'."
+      #   param :project_start_date, String, description: "Start date for the recurring project."
+      # end
+      param :start_date, String, description: "Start date of the project timeframe."
+      param :template, "Boolean", optional: true, description: "Whether the project is a template."
+      param :template_id, "Integer", optional: true, description: "Template ID for the project."
+      def create(workspace_id, project_attributes)
+        resource_path = format(request_path, workspace_id: workspace_id)
+
+        send_request(request_method, resource_path, project_attributes).body_json
+      end
+
+      private
+
+      def send_request(request_method, resource_path, body)
+        params = body.to_json unless body.is_a?(String)
+        TogglRb::Response.new(connection.send(request_method, resource_path, params))
+      end
+
+      def connection
+        TogglRb::Core.connection
+      end
+    end
+  end
+end

data/lib/toggl_rb/core/time_entries.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module TogglRb
+  module Core
+    class TimeEntries
+      include EndpointDSL
+
+      request_method :post
+      request_path "workspaces/%<workspace_id>s/time_entries"
+      param :billable, "Boolean", optional: true, default: false,
+                                  description: "Whether the time entry is marked as billable."
+      param :created_with, String, required: true,
+                                   description: "Identifies the service/application used to create it."
+      param :description, String, optional: true, description: "Time entry description."
+      param :duration, Integer, required: true, description: "Duration in seconds; negative for running entries."
+      param :pid, Integer, optional: true, description: "Project ID (legacy field)."
+      param :project_id, Integer, optional: true, description: "Project ID."
+      param :shared_with_user_ids, "Array<Integer>", optional: true,
+                                                     description: "User IDs to share this time entry with."
+      param :start, Time, required: true, description: "Start time in UTC. Format: 2006-01-02T15:04:05Z."
+      param :start_date, Date, optional: true,
+                               description: "Takes precedence over the date part of 'start'. Format: 2006-11-07."
+      param :stop, Time, optional: true, description: "Stop time in UTC."
+      param :tag_action, String, optional: true, description: "Used when updating; can be 'add' or 'delete'."
+      param :tag_ids, "Array<Integer>", optional: true, description: "Tag IDs to add/remove."
+      param :tags, "Array<String>", optional: true,
+                                    description: "Tag names to add/remove; creates tag if it doesn't exist."
+      param :task_id, Integer, optional: true, description: "Task ID."
+      param :user_id, Integer, optional: true, description: "Time Entry creator ID; uses requester ID if omitted."
+      param :workspace_id, Integer, required: true, description: "Workspace ID."
+      # NOTE: tid is a legacy field for Task ID.
+      # Note: uid is a legacy field for Time Entry creator ID.
+      # NOTE: duronly is deprecated and can be ignored.
+      # NOTE: wid is a legacy param for Workspace ID which will be populated with the passed argument
+      def create(workspace_id, time_entry_attributes)
+        time_entry_attributes[:wid] = workspace_id.to_i
+        resource_path = format(request_path, workspace_id: workspace_id)
+
+        send_request(request_method, resource_path, time_entry_attributes).body_json
+      end
+
+      request_method :patch
+      request_path "workspaces/%<workspace_id>s/time_entries/%<time_entry_ids>s"
+      # @param workspace_id [String|Integer] the workspace ID
+      # @param time_entries [Array<Integer>] the IDs of the task entries to update
+      # @param operation    [TogglRb::JSONPatch] the operation to apply to the time entries
+      def patch(workspace_id, time_entries, operation)
+        resource_path = format(request_path, workspace_id: workspace_id, time_entry_ids: time_entries.join(","))
+
+        send_request(request_method, resource_path, operation).body_json
+      end
+
+      private
+
+      def send_request(request_method, resource_path, body)
+        params = body.to_json unless body.is_a?(String)
+        TogglRb::Response.new(connection.send(request_method, resource_path, params))
+      end
+
+      def connection
+        TogglRb::Core.connection
+      end
+    end
+  end
+end

data/lib/toggl_rb/core/users.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module TogglRb
+  module Core
+    class Users
+      include EndpointDSL
+
+      request_method :get
+      request_path "workspaces/%<workspace_id>s/users"
+      def list(workspace_id)
+        resource_path = format(request_path, workspace_id: workspace_id)
+
+        send_request(request_method, resource_path, nil).body_json
+      end
+
+      private
+
+      def send_request(request_method, resource_path, body)
+        if body.nil?
+          TogglRb::Response.new(connection.send(request_method, resource_path))
+        else
+          params = body.to_json unless body.is_a?(String)
+          TogglRb::Response.new(connection.send(request_method, resource_path, params))
+        end
+      end
+
+      def connection
+        TogglRb::Core.connection
+      end
+    end
+  end
+end

data/lib/toggl_rb/core.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TogglRb
+  module Core
+    require_relative "core/groups"
+    require_relative "core/projects"
+    require_relative "core/time_entries"
+    require_relative "core/users"
+    require_relative "core/me"
+
+    def self.connection
+      TogglRb.client.core_connection
+    end
+  end
+end

data/lib/toggl_rb/endpoint_dsl.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module TogglRb
+  module EndpointDSL
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      ALLOWED_METHOD_TYPES = %i[post get put patch].freeze
+      ALLOWED_PRETTY = ALLOWED_METHOD_TYPES.map { |s| ":#{s}" }.join(", ").freeze
+
+      def method_added(method_name)
+        return if @adding_method || !@current_path
+
+        param_definitions[method_name] = @current_params || {}
+        method_request_paths[method_name] = @current_path
+        method_request_methods[method_name] = @current_method_type
+        method_query_params[method_name] = @current_query_params || {}
+        @current_params = nil # Reset for the next method
+        @current_path = nil
+        @current_method_type = nil
+        super
+      end
+
+      def request_path(path)
+        @current_path = path
+      end
+
+      def request_method(method_type)
+        method_type = method_type.to_sym
+        return @current_method_type = method_type if ALLOWED_METHOD_TYPES.include?(method_type)
+
+        raise ArgumentError, "method type: #{method_type} is not one of #{ALLOWED_PRETTY}"
+      end
+
+      def param_definitions
+        @param_definitions ||= {}
+      end
+
+      def method_query_params
+        @method_query_params ||= {}
+      end
+
+      def method_request_paths
+        @method_request_paths ||= {}
+      end
+
+      def method_request_methods
+        @method_request_methods ||= {}
+      end
+
+      def param(name, type, *other_args)
+        @current_params ||= {}
+        @current_params[name] = { type: type, other_args: other_args }
+      end
+
+      def query_param(name, type, *other_args)
+        @current_query_params ||= {}
+        @current_query_params[name] = { type: type, other_args: other_args }
+      end
+    end
+
+    def params_for_method(method_name)
+      self.class.param_definitions[method_name] || {}
+    end
+
+    def build_params(request_params)
+      caller_info = caller_locations(1, 1).first
+      Params.build(params_for_method(caller_info.label.to_sym), request_params)
+    end
+
+    def build_query_params(request_params)
+      caller_info = caller_locations(1, 1).first
+      QueryParams.build(query_params_for_method(caller_info.label.to_sym), request_params)
+    end
+
+    def request_path
+      caller_info = caller_locations(1, 1).first
+      self.class.method_request_paths.fetch(caller_info.label.to_sym)
+    end
+
+    def request_method
+      caller_info = caller_locations(1, 1).first
+      self.class.method_request_methods.fetch(caller_info.label.to_sym)
+    end
+
+    def query_params_for_method(method_name)
+      self.class.method_query_params[method_name] || {}
+    end
+  end
+end

data/lib/toggl_rb/json_patch.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module TogglRb
+  class JSONPatch
+    # frozen_string_literal: true
+    class Operation
+      attr_accessor(:type, :path, :value)
+
+      def initialize(type, path, value)
+        @type = type
+        @path = path
+        @value = value
+      end
+
+      def to_h
+        { "op" => type, "path" => path, "value" => value }
+      end
+    end
+
+    class Replace < Operation
+      def initialize(path = nil, value = nil)
+        super("replace", path, value)
+      end
+    end
+
+    attr_reader :operations
+
+    def initialize(operations = [])
+      @operations = operations
+    end
+
+    def to_json(*_args)
+      operations.map(&:to_h).to_json
+    end
+
+    def replace(path, value)
+      operations.push(Replace.new(path, value))
+      self
+    end
+  end
+end

data/lib/toggl_rb/param.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TogglRb
+  class Param
+    attr_reader :name, :type, :other_attributes
+
+    def self.build(name, definition)
+      new(
+        name,
+        definition.fetch(:type),
+        definition.fetch(:other_args, [])
+      )
+    end
+
+    def initialize(name, type, other_attributes = [])
+      @name = name
+      @type = type
+      @other_attributes = other_attributes
+    end
+
+    def required?
+      @other_attributes.include?(:required)
+    end
+  end
+end

data/lib/toggl_rb/params.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module TogglRb
+  class Params
+    attr_accessor(:request_params, :first_row_number)
+    attr_reader :definition
+
+    def self.build(params_definition, request_params)
+      new(params_definition).tap { |p| p.request_params = request_params }
+    end
+
+    def initialize(params_definition = {})
+      @definition = params_definition.to_h do |name, definition|
+        p = Param.build(name, definition)
+        [p.name, p]
+      end
+    end
+
+    def validate_required!
+      missing = required_parameters.reject { |p| request_params.key?(p.name) }
+      return if missing.empty?
+
+      missing = missing.count == 1 ? "#{missing.first.name} param" : "#{missing.map(&:name).join(", ")} params"
+
+      raise ArgumentError, "#{missing} must be provided"
+    end
+
+    def to_json(*_args)
+      processed_params.to_json
+    end
+
+    def processed_params
+      return request_params unless @first_row_number
+
+      request_params[:first_row_number] = first_row_number.to_i
+      request_params
+    end
+
+    private
+
+    def required_parameters
+      @definition.values.select(&:required?)
+    end
+  end
+end

data/lib/toggl_rb/query_params.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module TogglRb
+  class QueryParams < Params
+  end
+end

data/lib/toggl_rb/reports/detailed.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+
+module TogglRb
+  module Reports
+    class Detailed
+      include TogglRb::EndpointDSL
+      # @param [String|Integer] workspace_id the toggl workspace id we are searching
+      # @param [Hash] params the options for searching for time entries
+      # @option params [Boolean]        :grouped              Whether time entries should be grouped, optional, default
+      #                                                       false.
+      # @option params [Boolean]        :hide_amounts         Whether amounts should be hidden, optional, default false.
+      # @option params [Integer]        :max_duration_seconds Max duration seconds, optional, filtering attribute.
+      #                                                       Time Audit only, should be greater than MinDurationSeconds.
+      # @option params [Integer]        :min_duration_seconds Min duration seconds, optional, filtering attribute.
+      #                                                       Time Audit only, should be less than MaxDurationSeconds.
+      # @option params [String]         :order_by             Order by field, optional, default "date". Can
+      #                                                       be "date", "user", "duration", "description" or
+      #                                                       "last_update".
+      # @option params [String]         :order_dir            Order direction, optional. Can be ASC or DESC.
+      # @option params [Integer]        :page_size            PageSize defines the number of items per page, optional,
+      #                                                       default 50.
+      # @option params [Array<String>]  :postedFields         -
+      # @option params [Array<Integer>] :project_ids          Project IDs, optional, filtering attribute. To filter
+      #                                                       records with no projects, use [null].
+      # @option params [Integer]        :rounding             Whether time should be rounded, optional, default from
+      #                                                       workspace settings.
+      # @option params [Integer]        :rounding_minutes     Rounding minutes value, optional, default from workspace
+      #                                                       settings. Should be 0, 1, 5, 6, 10, 12, 15, 30, 60 or 240.
+      # @option params [String]         :start_time            -
+      # @option params [Array<Integer>] :tag_ids              Tag IDs, optional, filtering attribute. To filter records
+      #                                                       with no tags, use [null].
+      # @option params [Array<Integer>] :task_ids             Task IDs, optional, filtering attribute. To filter records
+      #                                                       with no tasks, use [null].
+      # @option params [Array<Integer>] :time_entry_ids       TimeEntryIDs filters by time entries. This was added to
+      #                                                       support retro-compatibility with reports v2.
+      # @option params [Array<Integer>] :user_ids             User IDs, optional, filtering attribute.
+      request_path "workspace/%<workspace_id>s/search/time_entries"
+      request_method :post
+      param :start_date, Date, :required, description: "should be less than end_date"
+      param :end_date, Date, description: "should be greater than start_date"
+      param :description, String, description: "filter by description"
+      param :billable, "Boolean", description: "Whether the time entry is set to visible (premium feature)"
+      param :client_ids, "IntegerArray",
+            description: "filter by client ids. Use [nil] to filter records with no clients"
+      param :group_ids, "IntegerArray", description: "filter by group ids"
+      def search_time_entries(workspace_id, params = {})
+        request_options = params.delete(:request_options) || {}
+        params_object = build_params(params)
+        params_object.validate_required!
+        resource_path = format(request_path, workspace_id: workspace_id)
+        response = send_request(request_method, resource_path, params_object)
+        get_all = request_options.fetch(:get_all, false)
+
+        return response.body_json unless get_all
+
+        all_tasks = response.body_json
+
+        while response.more?
+          params_object.first_row_number = response.next_row_number
+          response = send_request(request_method, resource_path, params_object)
+          all_tasks += response.body_json
+        end
+
+        all_tasks
+      end
+
+      private
+
+      def send_request(request_method, resource_path, body)
+        params = body.to_json unless body.is_a?(String)
+        TogglRb::Response.new(connection.send(request_method, resource_path, params))
+      end
+
+      def connection
+        TogglRb::Reports.connection
+      end
+    end
+  end
+end

data/lib/toggl_rb/reports/summary.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module TogglRb
+  module Reports
+    class Summary
+      include TogglRb::EndpointDSL
+
+      request_path "workspace/%<workspace_id>s/summary/time_entries"
+      request_method :post
+      param :billable, "Boolean", optional: true, description: "Whether the time entry is set as billable."
+      param :client_ids, "Array<Integer>", optional: true,
+                                           description: "Client IDs, use [null] to filter records with no clients."
+      param :description, String, optional: true, description: "Description of the filter."
+      param :distinguish_rates, "Boolean", optional: true, default: false,
+                                           description: "Create new subgroups for each rate."
+      param :end_date, String,
+            description: "End date, format example time.DateOnly, must be greater than start date."
+      param :group_ids, "Array<Integer>", optional: true, description: "Group IDs for filtering."
+      param :grouping, String, optional: true, description: "Grouping option."
+      param :include_time_entry_ids, "Boolean", optional: true, default: false,
+                                                description: "Include time entry IDs in results."
+      param :max_duration_seconds, Integer, optional: true, description: "Max duration in seconds."
+      param :min_duration_seconds, Integer, optional: true, description: "Min duration in seconds."
+      param :project_ids, "Array<Integer>", optional: true, description: "Project IDs, use [null] for no projects."
+      param :rounding, Integer, optional: true, description: "Rounding method, default from workspace settings."
+      param :rounding_minutes, Integer, optional: true,
+                                        description: "Rounding minutes, should be specific values."
+      param :start_date, String, required: true,
+                                 description: "Start date, format example time.DateOnly, less than end date."
+      param :sub_grouping, String, optional: true, description: "SubGrouping option."
+      param :tag_ids, "Array<Integer>", optional: true, description: "Tag IDs, use [null] for no tags."
+      param :task_ids, "Array<Integer>", optional: true, description: "Task IDs, use [null] for no tasks."
+      param :time_entry_ids, "Array<Integer>", description: "Filter by time entries, for compatibility."
+      param :user_ids, "Array<Integer>", optional: true, description: "User IDs for filtering."
+      def search_time_entries(workspace_id, params = {})
+        params_object = build_params(params)
+        params_object.validate_required!
+        resource_path = format(request_path, workspace_id: workspace_id)
+        response = send_request(request_method, resource_path, params_object)
+        request_options = params.fetch(:request_options, {})
+        get_all = request_options.fetch(:get_all, false)
+
+        return response.body_json unless get_all
+
+        all_tasks = response.body_json
+
+        while response.more?
+          params_object.first_row_number = response.next_row_number
+          response = send_request(request_method, resource_path, params_object)
+          all_tasks += response.body_json
+        end
+
+        all_tasks
+      end
+
+      private
+
+      def send_request(request_method, resource_path, body)
+        params = body.to_json unless body.is_a?(String)
+        TogglRb::Response.new(connection.send(request_method, resource_path, params))
+      end
+
+      def connection
+        TogglRb::Reports.connection
+      end
+    end
+  end
+end

data/lib/toggl_rb/reports.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module TogglRb
+  # @class Reports provides functionality for leveraging Toggl Data Structure to generate customized reports via the
+  #                reports from the Toggl API.
+  module Reports
+    require_relative "reports/detailed"
+    require_relative "reports/summary"
+
+    def self.connection
+      TogglRb.client.reports_connection
+    end
+  end
+end

data/lib/toggl_rb/response.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module TogglRb
+  class Response
+    extend Forwardable
+    NEXT_ROW_NUMBER_HEADER = "x-next-row-number"
+
+    def initialize(farady_response)
+      @farady_response = farady_response
+    end
+
+    def body_json
+      @body_json ||= JSON.parse(@farady_response.body)
+    end
+
+    def more?
+      !!next_row_number
+    end
+
+    def next_row_number
+      @farady_response.headers[NEXT_ROW_NUMBER_HEADER]
+    end
+
+    def_delegators :@farady_response, :status
+  end
+end

data/lib/toggl_rb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TogglRb
+  VERSION = "0.1.0"
+end

data/lib/toggl_rb.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "toggl_rb/response"
+require_relative "toggl_rb/client"
+require_relative "toggl_rb/config"
+require_relative "toggl_rb/param"
+require_relative "toggl_rb/params"
+require_relative "toggl_rb/query_params"
+require_relative "toggl_rb/endpoint_dsl"
+require_relative "toggl_rb/reports"
+require_relative "toggl_rb/core"
+require_relative "toggl_rb/version"
+require_relative "toggl_rb/json_patch"
+
+module TogglRb
+  class Error < StandardError; end
+
+  def self.debug_logging?
+    config.debug_logging?
+  end
+
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.client
+    @client ||= Client.new
+  end
+
+  def self.operation(operations = [])
+    JSONPatch.new(operations)
+  end
+end

data/sig/toggl_rb.rbs

@@ -0,0 +1,4 @@
+module TogglRb
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: toggl_rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael Cordell
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-04-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+description: A toggl rb API client supporting V9 version of the main API and V3 of
+  the reporting API
+email:
+- mike@mikecordell.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env_sample"
+- ".rspec"
+- ".ruby-version"
+- LICENSE
+- README.md
+- Rakefile
+- lib/toggl_rb.rb
+- lib/toggl_rb/client.rb
+- lib/toggl_rb/config.rb
+- lib/toggl_rb/core.rb
+- lib/toggl_rb/core/groups.rb
+- lib/toggl_rb/core/me.rb
+- lib/toggl_rb/core/projects.rb
+- lib/toggl_rb/core/time_entries.rb
+- lib/toggl_rb/core/users.rb
+- lib/toggl_rb/endpoint_dsl.rb
+- lib/toggl_rb/json_patch.rb
+- lib/toggl_rb/param.rb
+- lib/toggl_rb/params.rb
+- lib/toggl_rb/query_params.rb
+- lib/toggl_rb/reports.rb
+- lib/toggl_rb/reports/detailed.rb
+- lib/toggl_rb/reports/summary.rb
+- lib/toggl_rb/response.rb
+- lib/toggl_rb/version.rb
+- sig/toggl_rb.rbs
+homepage: https://github.com/mcordell/toggl_rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mcordell/toggl_rb
+  source_code_uri: https://github.com/mcordell/toggl_rb
+  changelog_uri: https://github.com/mcordell/toggl_rb/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.17
+signing_key:
+specification_version: 4
+summary: A toggl rb API client supporting V9
+test_files: []