{"id":19724174,"url":"https://github.com/fastruby/harvesting","last_synced_at":"2025-05-07T13:01:40.078Z","repository":{"id":41896168,"uuid":"131765310","full_name":"fastruby/harvesting","owner":"fastruby","description":"Ruby wrapper for the Harvest API v2 ","archived":false,"fork":false,"pushed_at":"2024-05-23T17:59:35.000Z","size":342,"stargazers_count":28,"open_issues_count":7,"forks_count":30,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-02T14:11:04.883Z","etag":null,"topics":["api","api-wrapper","gem","harvest","harvest-api","ruby","rubygems"],"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/fastruby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-01T21:31:29.000Z","updated_at":"2024-02-08T06:57:50.000Z","dependencies_parsed_at":"2024-11-11T23:28:14.155Z","dependency_job_id":"585ca6ef-a03e-4c76-83e5-0cd95e20cf7e","html_url":"https://github.com/fastruby/harvesting","commit_stats":{"total_commits":162,"total_committers":25,"mean_commits":6.48,"dds":0.6049382716049383,"last_synced_commit":"ca45207c0096b2ac64a1435ca2727042f84fe318"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastruby%2Fharvesting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastruby%2Fharvesting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastruby%2Fharvesting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastruby%2Fharvesting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastruby","download_url":"https://codeload.github.com/fastruby/harvesting/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252883219,"owners_count":21819157,"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","api-wrapper","gem","harvest","harvest-api","ruby","rubygems"],"created_at":"2024-11-11T23:24:46.418Z","updated_at":"2025-05-07T13:01:40.044Z","avatar_url":"https://github.com/fastruby.png","language":"Ruby","readme":"# Harvesting\n\n[![Build Status](https://travis-ci.org/fastruby/harvesting.svg?branch=main)](https://travis-ci.org/fastruby/harvesting)\n[![Code Climate](https://codeclimate.com/github/fastruby/harvesting/badges/gpa.svg)](https://codeclimate.com/github/fastruby/harvesting)\n[![codecov](https://codecov.io/gh/fastruby/harvesting/branch/main/graph/badge.svg)](https://codecov.io/gh/fastruby/harvesting)\n\nA Ruby gem to interact with the Harvest API v2.0 and forward.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'harvesting'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install harvesting\n\n## Documentation\n\nThe API is documented [here](https://www.rubydoc.info/gems/harvesting)\n\n## Usage\n\nIn order to start using this gem you will need your personal token and an\naccount id:\n\n### Identity\n\nYou can find these details over here: https://id.getharvest.com/developers\n\nIf you don't specify values for `access_token` or `account_id`, it will default\nto these environment variables:\n\n* `ENV['HARVEST_ACCESS_TOKEN']`\n* `ENV['HARVEST_ACCOUNT_ID']`\n\nThat means that you could build a client like this:\n\n```ruby\n# $ export HARVEST_ACCESS_TOKEN=abc\n# $ export HARVEST_ACCOUNT_ID=12345678\nclient = Harvesting::Client.new\nclient.me\n# =\u003e #\u003cHarvesting::Models::User:0x007ff8830658f0 @attributes={\"id\"=\u003e2108614, \"first_name\"=\u003e\"Ernesto\", \"last_name\"=\u003e\"Tagwerker\", ... \u003e\n```\n\nIf you don't specify a valid combination of token and account id, your code will\nraise this error:\n\n```ruby\nclient = Harvesting::Client.new(access_token: \"foo\", account_id: \"bar\")\nclient.me\n# Harvesting::AuthenticationError: {\"error\":\"invalid_token\",\"error_description\":\"The access token provided is expired, revoked, malformed or invalid for other reasons.\"}\n```\n\nIf your personal token and account id are valid, you should see something like\nthis:\n\n```ruby\nclient = Harvesting::Client.new(access_token: \"\u003cyour token here\u003e\", account_id: \"\u003cyour account id here\u003e\")\nuser = client.me\n# =\u003e #\u003cHarvesting::Models::User:0x007ff8830658f0 @attributes={\"id\"=\u003e2108614, \"first_name\"=\u003e\"Ernesto\", \"last_name\"=\u003e\"Tagwerker\", ... \u003e\n\nuser.id\n# =\u003e 2108614\n```\n\n### Clients\n\n```ruby\nclient.clients\n# =\u003e #\u003cHarvesting::Models::Clients:0x007ff718d65fd0\u003e\n\nclient = client.clients.first\n# =\u003e #\u003cHarvesting::Models::Client:0x007ff718cf5fc8 @attributes={\"id\"=\u003e6760580, \"name\"=\u003e\"Toto\",\n# ... \u003e\n```\n\n### Time Entries\n\n```ruby\ntime_entries = client.time_entries\n# =\u003e #\u003cHarvesting::Models::TimeEntries:0x007ff71913e3a0 @attributes={\"per_page\"=\u003e100, \"total_pages\"=\u003e1, \"total_entries\"=\u003e14, \"next_page\"=\u003enil, \"previous_page\"=\u003enil, \"page\"=\u003e1, \"links\"=\u003e{\"first\"=\u003e\"https://api.harvestapp.com/v2/time_entries?limit=1\u0026page=1\u0026per_page=100\", \"next\"=\u003enil, \"previous\"=\u003enil, \"last\"=\u003e\"https://api.harvestapp.com/v2/time_entries?limit=1\u0026page=1\u0026per_page=100\"}}, ... \u003e\n\nentry = time_entries.first\n# =\u003e #\u003cHarvesting::Models::TimeEntry:0x007ff71913dfe0 @attributes={\"id\"=\u003e792860513, \"spent_date\"=\u003e\"2018-05-14\", \"hours\"=\u003e1.0, \"notes\"=\u003e\"hacked the things\", \"is_locked\"=\u003efalse, \"locked_reason\"=\u003enil, \"is_closed\"=\u003efalse, \"is_billed\"=\u003efalse, \"timer_started_at\"=\u003enil, \"started_time\"=\u003enil, \"ended_time\"=\u003enil, \"is_running\"=\u003efalse, \"billable\"=\u003etrue, \"budgeted\"=\u003efalse, \"billable_rate\"=\u003enil, \"cost_rate ... \u003e\n```\n\n### Tasks\n\n```ruby\ntasks = client.tasks\n# =\u003e #\u003cHarvesting::Models::Tasks:0x007ff718897990 @attributes={\"per_page\"=\u003e100, \"total_pages\"=\u003e1, \"total_entries\"=\u003e6, \"next_page\"=\u003enil, \"previous_page\"=\u003enil, \"page\"=\u003e1, \"links\"=\u003e{\"first\"=\u003e\"https://api.harvestapp.com/v2/tasks?page=1\u0026per_page=100\", \"next\"=\u003enil, ... \u003e\n```\n\n### Projects\n\n```ruby\nprojects = client.projects\n# =\u003e #\u003cHarvesting::Models::Projects:0x007ff718e1c8e8 @attributes={\"per_page\"=\u003e100, \"total_pages\"=\u003e1, \"total_entries\"=\u003e1, \"next_page\"=\u003enil, \"previous_page\"=\u003enil, \"page\"=\u003e1, \"links\"=\u003e{\"first\"=\u003e\"https://api.harvestapp.com/v2/projects?page=1\u0026per_page=100\", ... \u003e\n\nproject = projects.first\n# =\u003e #\u003cHarvesting::Models::Project:0x007ff718e1c618 @attributes={\"id\"=\u003e17367712, \"name\"=\u003e\"Foo\", \"code\"=\u003e\"\", \"is_active\"=\u003etrue, \"is_billable\"=\u003etrue, \"is_fixed_fee\"=\u003efalse, \"bill_by\"=\u003e\"none\", \"budget\"=\u003enil, \"budget_by\"=\u003e\"none\", \"budget_is_monthly\"=\u003efalse, \"notify_when_over_budget\"=\u003efalse, \"over_budget_notification_percentage\"=\u003e80.0, \"show_budget_to_all\"=\u003efalse, \"created_at\"=\u003e\"2018-05-13T03:30:06Z\", ... \u003e\n```\n\n### Invoices\n```ruby\ninvoices = client.invoices\n# =\u003e #\u003cHarvesting::Models::Invoices:0x00007fc8905671f0 @models={}, @attributes={\"per_page\"=\u003e100, \"total_pages\"=\u003e1, \"total_entries\"=\u003e3, \"next_page\"=\u003enil, \"previous_page\"=\u003enil, \"page\"=\u003e1, \"links\"=\u003e{\"first\"=\u003e\"https://api.harvestapp.com/v2/invoices?page=1\u0026per_page=100\", ... \u003e\n\ninvoice = invoices.first\n# =\u003e #\u003cHarvesting::Models::Invoice:0x00007f8c37eb6d18 @models={}, @attributes={\"id\"=\u003e23831208, \"client_key\"=\u003e\"73688e97a43ed497ace45939eb76db6b18427b80\", \"number\"=\u003e\"3\", \"purchase_order\"=\u003e\"\", \"amount\"=\u003e750.0, \"due_amount\"=\u003e750.0, \"tax\"=\u003enil, \"tax_amount\"=\u003e0.0, \"tax2\"=\u003enil, \"tax2_amount\"=\u003e0.0, \"discount\"=\u003enil, \"discount_amount\"=\u003e0.0, \"subject\"=\u003e\"\", \"notes\"=\u003e\"\", \"state\"=\u003e\"draft\", \"period_start\"=\u003enil, ... \u003e\n```\n\nAn invoice can have many line items:\n```ruby\nline_items = invoice.line_items\n# =\u003e [#\u003cHarvesting::Models::LineItem:0x00007f92617ce8e0 @models={}, @attributes={\"id\"=\u003e109677268, \"kind\"=\u003e\"Service\", \"description\"=\u003e\"\", \"quantity\"=\u003e3.0, \"unit_price\"=\u003e250.0, \"amount\"=\u003e750.0, \"taxed\"=\u003efalse, \"taxed2\"=\u003efalse, \"project\"=\u003e{\"id\"=\u003e24566828, \"name\"=\u003e\"Harvest Billing Automation\", \"code\"=\u003e\"\"}}, ... \u003e]\n```\n\nYou can filter invoices by various attributes. E.g. `client.invoices(state: \"draft\")` only returns invoices in a draft state.\n\n### Nested Attributes\n\nThe Harvest v2 API embeds some data in JSON objects. You can access nested attributes quite naturally.\nFor example, to access the user id for a time entry instance, `entry`, use:\n\n```ruby\nentry.user.id\n```\n\nOr to access the name of the client on a project instance, `project`:\n```ruby\nproject.client.name\n```\n\n## Tips\n\n### Deleting All Items\n\nWhen you need to delete all items, care needs to be taken, because the API uses pagination. The following code will only delete data from _every other_ page.\n\n```ruby\n# WARNING - only deletes every other page\nclient.time_entries.each do |time_entry|\n  time_entry.delete\nend\n```\n\nWhile iterating over items from the first page, all of those items will be deleted. This will result in moving items from the second page onto the first page. If there are only two pages, then the second page will be empty. If there are more than two pages, then the second page will now contain items which would have previously appeared on the third page. Deleting those items will move the items from the fourth page on to the third page, and so on.\n\nInstead you need to make sure you get access to all of the time entry objects before you try to delete any of them. The easiest way to do this is to convert the `Enumerable` instance into an `Array`, by calling `#to_a`, before you iterate over it.\n\n```ruby\n# GOOD - This should do what you want\nclient.time_entries.to_a.each do |time_entry|\n  time_entry.delete\nend\n```\n\n## Roadmap\n\nThere are many things to be developed for this gem. For now they are tracked here: [TODO.md](https://github.com/fastruby/harvesting/blob/main/TODO.md)\n\n## Releases\n\nYou can find more info [here](RELEASE_NOTES.md)\n\n## Development\n\nAfter 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.\n\n    ./bin/setup\n    rake\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\n### Using Docker\n\nThis setup allows you to create a completely isolated development environment for working on this gem. The version of ruby used for development and the gems that it depends on will remain inside the container.\n\nAfter checking out the repo, run `docker-compose build` to create the `gem` container. Running `docker-compose run gem bash` will get you a bash session inside the container. From there, you can follow the instructions in the \"Without Docker\" section above.\n\n### Running Tests\n\nThe tests in this project use the [VCR gem](https://github.com/vcr/vcr) to record and playback all interactions with the Harvest API. This allows you to run the test suite without having an account at Harvest for testing.\n\nIf you add a test that requires making an additional API call, then you'll need to make adjustments to the `.env` file to provide account details that are required by the test suite.\n\n*WARNING*: The test suite is destructive. It deletes all entities from the account before it runs. _DO NOT_ run it against a Harvest account which contains information that you need to preserve. Instead, create a Harvest account for testing.\n\nIf you need to refresh the VCR cassettes, the easiest way is to delete all of the files located under [`fixtures/vcr_cassettes`](fixtures/vcr_cassettes). The next time the test suite is run, VCR will make actual calls against the Harvest API and record the responses into updated cassette files.\n\nEffort has been taken to ensure that private information is excluded from the recorded cassettes. To adjust this further, add additional `filter_sensitive_data` calls to [`spec/spec_helper.rb`](spec/spec_helper.rb).\n\n### Models\n\nThe models in this project reflect the Harvest v2 API endpoints:\n\n * client\n * contact\n * task\n * task_assignment\n * project\n * user\n * time_entry\n\nThere are also models for the Harvest v2 API collection endpoints:\n\n * clients\n * contacts\n * tasks\n * task_assignments\n * projects\n * users\n * time_entries\n\nThese collection models handle the Harvest v2 API pagination automatically, making it easy to enumerate through all the instances of each type.\n\nThe models try to reduce code duplication through base class helper functions to automatically define accessors for the attributes included in each type returned by the Harvest v2 API.\nThe `Harvesting::Base::attributed` method will define accessors for each simple attribute included in an array passed as an argument. Data is returned from these accessors as strings.\n\nSome data is returned from Harvest as nested JSON (e.g. time_entry.project.name). A base class helper to expose this using the available models\nis also present. The `Harvesting::Base::modeled` method will define accessors for each object attribute included in options. Both the name of the attribute and the model to use in accessing that data is supplied.\nData is returned from these accessors as model objects.\n\nNOTE: Nesting model objects requires that the nested model types be defined before the nesting model type. E.g. if `project` contains a nested `client`, then `client` must be defined *before* `project` in the `harvesting.rb` include list.\n\n## Releases\n\nTo 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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\nWe follow semantic versioning for version numbers: [https://semver.org](https://semver.org)\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at [https://github.com/fastruby/harvesting](https://github.com/fastruby/harvesting). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\nWhen Submitting a Pull Request:\n\n* If your PR closes any open GitHub issues, please include `Closes #XXXX` in your comment\n\n* Please include a summary of the change and which issue is fixed or which feature is introduced.\n\n* If changes to the behavior are made, clearly describe what changes.\n\n* If changes to the UI are made, please include screenshots of the before and after.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Harvesting project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/fastruby/harvesting/blob/main/CODE_OF_CONDUCT.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastruby%2Fharvesting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastruby%2Fharvesting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastruby%2Fharvesting/lists"}