{"id":13817121,"url":"https://github.com/kanet77/togglv8","last_synced_at":"2025-05-15T19:30:59.558Z","repository":{"id":8896033,"uuid":"10617279","full_name":"kanet77/togglv8","owner":"kanet77","description":"Ruby wrapper for Toggl API v8","archived":false,"fork":false,"pushed_at":"2022-01-24T20:08:34.000Z","size":207,"stargazers_count":82,"open_issues_count":12,"forks_count":62,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-21T10:56:03.708Z","etag":null,"topics":["ruby","ruby-wrapper","toggl","toggl-api"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/togglv8","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kanet77.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-06-11T08:15:08.000Z","updated_at":"2025-01-07T08:16:20.000Z","dependencies_parsed_at":"2022-09-03T06:43:12.838Z","dependency_job_id":null,"html_url":"https://github.com/kanet77/togglv8","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanet77%2Ftogglv8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanet77%2Ftogglv8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanet77%2Ftogglv8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanet77%2Ftogglv8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kanet77","download_url":"https://codeload.github.com/kanet77/togglv8/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254407247,"owners_count":22066198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ruby","ruby-wrapper","toggl","toggl-api"],"created_at":"2024-08-04T06:00:34.211Z","updated_at":"2025-05-15T19:30:59.247Z","avatar_url":"https://github.com/kanet77.png","language":"Ruby","funding_links":[],"categories":["API wrapper","Others"],"sub_categories":[],"readme":"\n# Toggl API v8\n\n[![Gem Version](https://badge.fury.io/rb/togglv8.svg)](https://badge.fury.io/rb/togglv8) [![Build Status](https://api.travis-ci.org/kanet77/togglv8.svg \"Build Status\")](https://travis-ci.org/kanet77/togglv8) [![Coverage Status](https://coveralls.io/repos/kanet77/togglv8/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/kanet77/togglv8?branch=master) [![Code Climate](https://codeclimate.com/github/kanet77/togglv8/badges/gpa.svg)](https://codeclimate.com/github/kanet77/togglv8)\n\n[Toggl](http://www.toggl.com) is a time tracking tool.\n\n[togglv8](/) is a Ruby Wrapper for [Toggl API v8](https://github.com/toggl/toggl_api_docs). It is designed to mirror the Toggl API as closely as possible.\n\ntogglv8 supports both [Toggl API](https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md) and [Reports API](https://github.com/toggl/toggl_api_docs/blob/master/reports.md)\n\n## Change Log\n\nSee [CHANGELOG](CHANGELOG.md) for a summary of notable changes in each version.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'togglv8'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install togglv8\n\n## Initialization\n\n### TogglV8::API\n\nTogglV8::API communicates with [Toggl API v8](https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md) and can be initialized in one of three ways.\n\n```ruby\nTogglV8::API.new                      # reads API token from file ~/.toggl\nTogglV8::API.new(api_token)           # explicit API token\nTogglV8::API.new(email, password)     # email \u0026 password\n```\n\n### TogglV8::ReportsV2\n\nTogglV8::ReportsV2 communicates with [Toggl Reports API v2](https://github.com/toggl/toggl_api_docs/blob/master/reports.md) and can be initialized in one of three ways. Toggl.com requires authentication with an API token for Reports API v2.\n\n```ruby\nTogglV8::ReportsV2.new                              # reads API token from file ~/.toggl\nTogglV8::ReportsV2.new(toggl_api_file: toggl_file)  # reads API token from toggl_file\nTogglV8::ReportsV2.new(api_token: api_token)        # explicit API token\n```\n\n**Note:** `workspace_id` must be set in order to generate reports.\n\n```ruby\ntoggl = TogglV8::API.new\nreports = TogglV8::ReportsV2.new\nreports.workspace_id = toggl.workspaces.first['id']\n```\n\n## Usage\n\nThis short example shows one way to create a time entry for the first workspace of the user identified by `\u003cAPI_TOKEN\u003e`. It then generates various reports containing that time entry.\n\n```ruby\nrequire 'togglv8'\nrequire 'json'\n\ntoggl_api    = TogglV8::API.new(\u003cAPI_TOKEN\u003e)\nuser         = toggl_api.me(all=true)\nworkspaces   = toggl_api.my_workspaces(user)\nworkspace_id = workspaces.first['id']\ntime_entry   = toggl_api.create_time_entry({\n  'description' =\u003e \"My awesome workspace time entry\",\n  'wid' =\u003e workspace_id,\n  'duration' =\u003e 1200,\n  'start' =\u003e toggl_api.iso8601((Time.now - 3600).to_datetime),\n  'created_with' =\u003e \"My awesome Ruby application\"\n})\n\nbegin\n  reports               = TogglV8::ReportsV2.new(api_token: \u003cAPI_TOKEN\u003e)\n  begin\n    reports.summary\n  rescue Exception =\u003e e\n    puts e.message      # workspace_id is required\n  end\n  reports.workspace_id  = workspace_id\n  summary               = reports.summary\n  puts \"Generating summary JSON...\"\n  puts JSON.pretty_generate(summary)\n  puts \"Generating summary PDF...\"\n  reports.write_summary('toggl_summary.pdf')\n  puts \"Generating weekly CSV...\"\n  reports.write_weekly('toggl_weekly.csv')\n  puts \"Generating details XLS...\"\n  reports.write_details('toggl_details.xls')\n  # Note: toggl.com does not generate Weekly XLS report (as of 2016-07-24)\nensure\n  toggl_api.delete_time_entry(time_entry['id'])\nend\n```\n\nSee specs for more examples.\n\n**Note:** Requests are rate-limited. The togglv8 gem will handle a 429 response by pausing for 1 second and trying again, for up to 3 attempts. See [Toggl API docs](https://github.com/toggl/toggl_api_docs#the-api-format):\n\n\u003e For rate limiting we have implemented a Leaky bucket. When a limit has been hit the request will get a HTTP 429 response and it's the task of the client to sleep/wait until bucket is empty. Limits will and can change during time, but a safe window will be 1 request per second. Limiting is applied per api token per IP, meaning two users from the same IP will get their rate allocated separately.\n\n## Debugging\n\nThe `TogglV8::API#debug` method determines if debug output is printed to STDOUT. This code snippet demonstrates the debug output.\n\n```ruby\nrequire 'togglv8'\n\ntoggl = TogglV8::API.new\n\ntoggl.debug(true)  # or simply toggl.debug\nuser1 = toggl.me\nputs \"user: #{user1['fullname']}, debug: true\"\n\nputs '-'*80\n\ntoggl.debug(false)\nuser2 = toggl.me\nputs \"user: #{user2['fullname']}, debug: false\"\n```\n\n## Documentation\n\nRun `rdoc` to generate documentation. Open `doc/index.html` in your browser.\n\nAlso available on [DocumentUp](https://documentup.com/kanet77/togglv8)\n\n## Acknowledgements\n\n- Thanks to the following contributors (in alphabetical order):\n    * [archonic](https://github.com/archonic) ([fork](https://github.com/archonic/togglv8))\n    * [ddiatmb](https://github.com/ddiatmb) ([fork](https://github.com/ddiatmb/togglv8))\n    * [itaymendel](https://github.com/itaymendel)\n    * [ppawlikmb](https://github.com/ppawlikmb) ([fork](https://github.com/ppawlikmb/togglv8))\n    * [worldsmithroy](https://github.com/worldsmithroy) ([fork](https://github.com/worldsmithroy/togglv8))\n- Thanks to [Koen Van der Auwera](https://github.com/atog) for the [Ruby Wrapper for Toggl API v6](https://github.com/atog/toggl)\n- Thanks to the Toggl team for exposing the API.\n\n## Contributing\n\n1. Fork it ( https://github.com/kanet77/togglv8/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\nPull Requests that include tests are **much** more likely to be accepted and merged quickly.\n\n## License\n\nCopyright (c) 2013-2016 Tom Kane. Released under the [MIT License](http://opensource.org/licenses/mit-license.php). See [LICENSE.txt](LICENSE.txt) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanet77%2Ftogglv8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkanet77%2Ftogglv8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanet77%2Ftogglv8/lists"}