{"id":28160778,"url":"https://github.com/leesharma/rescuetime","last_synced_at":"2025-05-15T10:14:59.777Z","repository":{"id":30410442,"uuid":"33963278","full_name":"leesharma/rescuetime","owner":"leesharma","description":"Ruby interface to the RescueTime APIs","archived":false,"fork":false,"pushed_at":"2020-06-13T22:53:47.000Z","size":229,"stargazers_count":18,"open_issues_count":4,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-10T11:47:22.028Z","etag":null,"topics":["api-client","rescuetime","ruby"],"latest_commit_sha":null,"homepage":"","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/leesharma.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-14T23:58:42.000Z","updated_at":"2025-04-29T17:18:12.000Z","dependencies_parsed_at":"2022-09-08T10:40:33.965Z","dependency_job_id":null,"html_url":"https://github.com/leesharma/rescuetime","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/leesharma%2Frescuetime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leesharma%2Frescuetime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leesharma%2Frescuetime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leesharma%2Frescuetime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leesharma","download_url":"https://codeload.github.com/leesharma/rescuetime/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319632,"owners_count":22051077,"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":["api-client","rescuetime","ruby"],"created_at":"2025-05-15T10:14:57.898Z","updated_at":"2025-05-15T10:14:59.766Z","avatar_url":"https://github.com/leesharma.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"rescuetime\n==========\n\n[![Maintainability](https://img.shields.io/codeclimate/maintainability/leesharma/rescuetime.svg?style=flat-square)](https://codeclimate.com/github/leesharma/rescuetime)\n[![Coverage](https://img.shields.io/codeclimate/coverage/leesharma/rescuetime.svg?style=flat-square)](https://codeclimate.com/github/leesharma/rescuetime)\n[![Build](https://img.shields.io/travis/leesharma/rescuetime.svg?style=flat-square)](https://travis-ci.org/leesharma/rescuetime)\n\n[![Downloads](https://img.shields.io/gem/dt/rescuetime.svg?style=flat-square)](https://rubygems.org/gems/rescuetime)\n[![Release](https://img.shields.io/github/release/leesharma/rescuetime.svg?style=flat-square)](https://github.com/leesharma/rescuetime/releases/)\n[![License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](http://opensource.org/licenses/MIT)\n\nA Ruby interface to the RescueTime APIs. Rescuetime provides a simple DSL for interacting\nwith your personal or team RescueTime data. Currently, this gem only supports the Data Analytics API with API key authorization.\n\nFor more information about RescueTime, visit [the RescueTime homepage](https://www.rescuetime.com).\n\n#### README Navigation\n\n* [Installation](#installation)\n* [Usage](#usage)\n   * [Prerequisites](#prerequisites)\n   * [In a Nutshell](#in-a-nutshell) (skip to here if you want to see the syntax)\n   * [Custom Report Formatters](#custom-report-formatters)\n   * [Finding Answers (Documentation)](#finding-answers-documentation)\n   * [Defaults](#defaults)\n   * [Rescuetime Exceptions](#rescuetime-exceptions)\n* [Development](https://github.com/leesharma/rescuetime/wiki/Development) ([section](#development))\n* [Contributing](CONTRIBUTING.md) ([section](#contributing))\n   * [TODO](#todo)\n\n#### Useful Links\n* [RDoc](http://www.rubydoc.info/gems/rescuetime)\n* [Wiki](https://github.com/leesharma/rescuetime/wiki)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'rescuetime'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install rescuetime\n\n## Usage\n\n### Prerequisites\n\nEnsure that you are using a [supported ruby version](https://github.com/leesharma/rescuetime/wiki/Supported-Rubies) for your project.\n\nIn order to use access your RescueTime data, you will need an API key. If you do not already have a key, visit the [API key management page](https://www.rescuetime.com/anapi/manage).\n\n### In a Nutshell\n\n```ruby\nrequire 'rescuetime'\n\n@client = Rescuetime::Client.new(api_key: \u003cYOUR_API_KEY\u003e)\n@client.api_key?            #=\u003e true\n@client.valid_credentials?  #=\u003e true\n\n# Rescuetime uses lazy evaluation, so until you either manipulate the collection\n# or explicitly call for it (with #all), it will remain in the Rescuetime::Collection\n# format.\n@client.overview.class      #=\u003e Rescuetime::Collection\n@client.overview.all.class  #=\u003e Array\n@client.overview.map {...}  #=\u003e Array\n\n@client.overview      # Returns an overview report, defaulting to \"rank\" order\n@client.categories    # Returns a catigorical report, defaulting to \"rank\" order\n@client.activities    # Returns a list of activities, defaulting to \"rank\" order\n@client.productivity  # Returns a productivity report, defaulting to \"rank\" order\n@client.efficiency    # Returns an efficiency report, defaulting to \"time order\"\n\n##\n# Date Range (:date, :frome, :to)\n# -------------------------------\n# Defaults:\n#   If nothing is provided, defaults to current day (since 00:00)\n#   If :from is provided, defaults :to to current day\n#\n# Valid date formats:\n#   - \"YYYY-MM-DD\"    - \"MM-DD-YYYY\"    - \"DD/MM\"\n#   - Object#strftime\n@client.overview                      # Fetches results from today\n@client.overview.date('2014-12-31')   # Fetches results from Dec 31, 2014.\n@client.overview.from('2015-01-01').to('2015-02-01')\n@client.overview.from('2015-04-01')\n\n\n##\n# Report Order (:order_by)\n# ------------------------\n# Defaults:\n#   Efficiency defaults to chronological order; everything else defaults to \"rank\" order\n#\n# You can order_by:\n#   :rank, :time, or :member (note: efficiency can't be sorted by :rank)\n#\n# When ordering by time, default interval is 1 hour.\n# Options include:\n#   :minute (5-minute chunks), :hour, :day, :week, :month\n@client.efficiency    # Defaults to :time\n@client.productivity  # Defaults to :rank\n\n@client.productivity.order_by(:rank)\n@client.productivity.order_by(:time)\n@client.productivity.order_by(:member)\n\n@client.productivity.order_by(:time)  # Defaults to :hour\n@client.productivity.order_by(:time, interval: :minute)\n@client.productivity.order_by(:time, interval: :hour)\n@client.productivity.order_by(:time, interval: :day)\n@client.productivity.order_by(:time, interval: :week)\n@client.productivity.order_by(:time, interval: :month)\n\n##\n# Name Restrictions (:where)\n# --------------------------\n# Fetches results where name is an exact match\n# The following reports can be limited by name:\n#   :activities, :categories, :overview\n#\n# For activities, you can also limit by specific document title\n#   (ex. document 'rails/rails' for activity 'github.com')\n#   Try the query sans document for a list of valid options\n#\n# Names must be exact matches.\n@client.activities.where(name: 'github.com')\n@client.categories.where(name: 'Intelligence')\n@client.overview.where(name: 'Utilities')\n@client.activities.where(name: 'github.com', document: 'vcr/vcr')\n\n##\n# Formatting options (:csv, :array)\n# ---------------------------------\n@client.efficiency                  # Default return type is Array\u003cHash\u003e\n@client.efficiency.format(:cvs)     # Returns a CSV\n@client.efficiency.format(:array)   # Returns Array\u003cHash\u003e\n```\n\n### Custom Report Formatters\n\n*Feature available in v0.4.0 and later*\n\nRescuetime ships with two report formats: CSV and Array. If you would like your\nreport in a different format, don't worry–it's easy to add a custom formatter.\n\nThree things are required to add a custom formatter:\n\n1. [Write a class](#writing-a-formatter) within the module\n   `Rescuetime::Formatters` that inherits from `Rescuetime::Formatters::BaseFormatter`\n   or one of its descendants\n2. Define the class methods `.name` and `.format`\n4. [Register your formatters](#registering-your-formatters) using `Rescuetime.configure`\n\n#### Writing a Formatter\n\nFirst, the formatters themselves. Here is a basic formatter:\n\n```ruby\n# config/formatters/nil_formatter.rb\nmodule Rescuetime::Formatters\n  # Turns a productivity report into nothing useful.\n  class NilFormatter \u003c BaseFormatter\n    # @return [String]  name of this report format\n    def self.name\n      'nil'\n    end\n\n    # @param  [CSV] _report  the raw CSV report from Rescuetime\n    # @return [nil]          the formatted output (in this case, nil)\n    def self.format(_report)\n      nil\n    end\n  end\nend\n```\n\nYou can even inherit from an existing formatter:\n\n```ruby\n# config/formatters/shouty_array_formatter.rb\nmodule Rescuetime::Formatters\n  # Formats a rescuetime report as an array of hashes, except shouting.\n  class ShoutyArrayFormatter \u003c ArrayFormatter\n    # @return [String]  name of this report format\n    def self.name\n      'shouty_array'\n    end\n\n    # @param  [CSV]         report  the raw CSV report from Rescuetime\n    # @return [Array\u003cHash\u003e]         the formatted output (in this case, a shouty\n    #                               array of hashes)\n    def self.format(report)\n      array = super(report)\n      array.map do |hash|\n        terms = hash.map { |key, value| [key.to_s.upcase, value.to_s.upcase] }\n        Hash[terms]\n      end\n    end\n  end\nend\n```\n\n#### Registering your Formatters\n\nBefore setting your report format, add the path to your formatter(s) to the\nRescuetime configuration using the `Rescuetime.configure` method. You will be\nable to set, append to, or manipulate the `formatter_paths` setting.\n\n```ruby\nRescuetime.configure do |config|\n  path = File.expand_path('../my_custom_formatter.rb', __FILE__)\n  config.formatter_paths = [path]\nend\n```\n\nNow Rescuetime will look for the `my_custom_formatter.rb` file. Multiple paths\nmay be added as well.\n\n```ruby\nRescuetime.configure do |config|\n  config.formatter_paths = [\n    'config/formatters/*_formatter.rb',\n    'lib/formatters/**/*_formatter.rb',\n  ]\nend\n```\n\n##### Rails Example\n\nFor example, in a Rails app, you could add the configuration file to `config/initializers`:\n\n```ruby\n# config/initializers/rescuetime.rb\nRescuetime.configure do |config|\n  path = File.expand_path('../../formatters/*_formatter.rb', __FILE__)\n  config.formatter_paths += [path]\nend\n```\n\nRails can now find any formatters ending in `_formatter.rb` in the folder `config/formatters`\n(ex. `config/formatters/xml_formatter.rb`).\n\n### Finding Answers (Documentation)\n\nFor more details, please see [official gem documentation](http://www.rubydoc.info/gems/rescuetime) or [read the wiki](https://github.com/leesharma/rescuetime/wiki).\n\n### Defaults\n\nThe `Rescuetime::Client#activities` action has the following defaults:\n\n```ruby\n\n{ order_by:         'rank'\n  interval:         'hour'\n  date:             \u003cTODAY\u003e }\n\n```\n\n### Rescuetime Exceptions\n\n*Note: In v0.4.0, custom exceptions were moved from the base `Rescuetime`\nnamespace to the `Rescuetime::Errors` namespace. For example, in v0.3.3,\na bad request was represented by `Rescuetime::BadRequest`. In \u003e= v0.4.0,\nit is represented by `Rescuetime::Errors::BadRequest`.*\n\nThere are a number of exceptions that extend from the `Rescuetime::Errors::Error` class:\n\n* **`Rescuetime::Errors::MissingCredentialsError`** is raised when a request is attempted by a client with no credentials. Try setting credentials with `@client.api_key = \u003cYOUR_API_KEY\u003e`.\n* **`Rescuetime::Errors::InvalidCredentialsError`** is raised when a request is attempted by a client with invalid credentials. Double-check your API key and fix your client with `@client.api_key = \u003cVALID_API_KEY\u003e`.\n* **`Rescuetime::Errors::InvalidQueryError`** is raised if you enter an invalid value for any of the RescueTime query methods (or if the server returns a bad query error)\n* **`Rescuetime::Errors::InvalidFormatError`** is raised if you pass a disallowed format to the client\n* HTTP Response Errors:\n    * **4xx =\u003e `Rescuetime::Errors::ClientError`**\n    * 400 =\u003e `Rescuetime::Errors::BadRequest`\n    * 401 =\u003e `Rescuetime::Errors::Unauthorized`\n    * 403 =\u003e `Rescuetime::Errors::Forbidden`\n    * 404 =\u003e `Rescuetime::Errors::NotFound`\n    * 406 =\u003e `Rescuetime::Errors::NotAcceptable`\n    * 422 =\u003e `Rescuetime::Errors::UnprocessableEntity`\n    * 429 =\u003e `Rescuetime::Errors::TooManyRequests`\n    * **5xx =\u003e `Rescuetime::Errors::ServerError`**\n    * 500 =\u003e `Rescuetime::Errors::InternalServerError`\n    * 501 =\u003e `Rescuetime::Errors::NotImplemented`\n    * 502 =\u003e `Rescuetime::Errors::BadGateway`\n    * 503 =\u003e `Rescuetime::Errors::ServiceUnavailable`\n    * 504 =\u003e `Rescuetime::Errors::GatewayTimeout`\n\n## Development\n\nSee the [development page](https://github.com/leesharma/rescuetime/wiki/Development) of the wiki.\n\n## Contributing\n\nSee the [contributing page](CONTRIBUTING.md).\n\n### TODO\n\nThe eventual goal of this gem is full coverage of all Rescuetime APIs.\n\nAssociated issues from our issue tracker are linked when applicable. If you are interested in contributing, please feel free to work on any of these issues! If there is a feature you want that's not on the TODO list, open an issue and we can discuss it.\n\n- [x] Minimum viable functionality (in [v0.1.0])\n- [x] Add support for major query params in Data Analytic API (in [v0.2.0])\n- [x] Lazy query evaluation and method chaining (in [v0.3.0], [v0.3.1], [v0.3.2], [v0.3.3])\n- [x] Add custom report formatters (in [v0.4.0])\n- [ ] Add full coverage of Data Analytics API\n  - [ ] Restrict results by group ([#14])\n  - [ ] Restrict results by person\n- [ ] Add support for \"Daily Summary API\" ([#28])\n- [ ] Add support for \"Alerts Feed API\"\n- [ ] Add support for \"Daily Highlights Feed API\"\n- [ ] Add support for \"Daily Highlights POST API\"\n- [ ] Add OAuth2 support\n\nFor details about completed items, please see [the release page][releases].\n\n[#14]: https://github.com/leesharma/rescuetime/issues/14\n[#28]: https://github.com/leesharma/rescuetime/issues/28\n\n[v0.1.0]:https://github.com/leesharma/rescuetime/releases/tag/v0.1.0\n[v0.2.0]:https://github.com/leesharma/rescuetime/releases/tag/v0.2.0\n[v0.3.0]:https://github.com/leesharma/rescuetime/releases/tag/v0.3.0\n[v0.3.1]:https://github.com/leesharma/rescuetime/releases/tag/v0.3.1\n[v0.3.2]:https://github.com/leesharma/rescuetime/releases/tag/v0.3.2\n[v0.3.3]:https://github.com/leesharma/rescuetime/releases/tag/v0.3.3\n[v0.4.0]:https://github.com/leesharma/rescuetime/releases/tag/v0.4.0\n[releases]:https://github.com/leesharma/rescuetime/releases\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleesharma%2Frescuetime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleesharma%2Frescuetime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleesharma%2Frescuetime/lists"}