{"id":16700135,"url":"https://github.com/guyzmo/hypertrack_v3","last_synced_at":"2025-04-10T03:51:10.020Z","repository":{"id":137880483,"uuid":"218393272","full_name":"guyzmo/hypertrack_v3","owner":"guyzmo","description":null,"archived":false,"fork":false,"pushed_at":"2019-10-29T22:45:38.000Z","size":7,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T05:05:17.149Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guyzmo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2019-10-29T22:14:11.000Z","updated_at":"2019-11-05T22:07:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"f089d006-d019-496e-91bd-5c908b397263","html_url":"https://github.com/guyzmo/hypertrack_v3","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyzmo%2Fhypertrack_v3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyzmo%2Fhypertrack_v3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyzmo%2Fhypertrack_v3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyzmo%2Fhypertrack_v3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guyzmo","download_url":"https://codeload.github.com/guyzmo/hypertrack_v3/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154999,"owners_count":21056542,"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":[],"created_at":"2024-10-12T18:09:30.154Z","updated_at":"2025-04-10T03:51:10.009Z","avatar_url":"https://github.com/guyzmo.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Gem Version](https://badge.fury.io/rb/hypertrack_v3.svg)](https://badge.fury.io/rb/hypertrack_v3)\n\n# Hypertrack RubyGem\n\nA RubyGem for [Hypertrack](https://www.hypertrack.com/)'s [Backend API Version 3](https://docs.hypertrack.com/#references-apis)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n```ruby\ngem 'hypertrack_v3'\n```\n\nAnd then run `bundle install` on command line.\n\nOr install it yourself as: `gem install hypertrack_v3`\n\n## Initialization\n\n### For the webhooks\n\nThe webhooks are only available if used with rails (it is declared as a rails engine),\nso you should add a `config/initializers/hypertrack_v3.rb` file, such as:\n\n```ruby\nrequire 'hypertrack_v3'\n\nHypertrackV3.error_handler = -\u003e(msg, **args) { Raven.capture_message(msg, **args) }\nHypertrackV3.exception_handler = -\u003e(exc, **args) { Raven.capture_exception(exc, **args) }\n\nclass ::HypertrackV3::Engine::WebhookParser\n  register_hook :location, lambda { |device_id, data, created_at, recorded_at|\n    Rails.logger.debug(\"LocationHook: #{device_id} -\u003e #{data}\")\n  }\n\n  register_hook :device_status, lambda { |device_id, data, created_at, recorded_at|\n    Rails.logger.debug(\"DeviceStatusHook: #{device_id} -\u003e #{data}\")\n  }\n\n  register_hook :battery, lambda { |device_id, data, created_at, recorded_at|\n    Rails.logger.debug(\"BatteryHook: #{device_id} -\u003e #{data}\")\n  }\n\n  register_hook :trip, lambda { |device_id, data, created_at, recorded_at|\n    Rails.logger.debug(\"TripHook: #{device_id} -\u003e #{data}\")\n  }\nend\n```\n\nInstead of just logging when using the hooks, you should do something with them.\n\nThen in your application's `routes.rb`, simply mount the engine:\n\n```ruby\nRails.application.routes.draw do\n  # ...\n  mount HypertrackV3::Engine =\u003e 'webhook/hypertrack'\nend\n```\n\nThere on your hypertrack dashboard, you can declare your webhook as `https://yoursite.tld/webhook/hypertrack`.\nClick on the test webhook button, and you should be all set.\n\n### For the client API\n\nWherever you need to use the HypertrackV3 API client, simply instantiate the client using:\n\n```ruby\nHypertrackV3.new(\n  ENV['HYPERTRACK_ACCOUNT_ID'],\n  ENV['HYPERTRACK_SECRET_KEY']\n)\n```\n\nObviously, it's always better to keep secrets in the environment.\n\n## Usage\n\nThe API client is very simple, and here are the implemented methods:\n\n* [`device_list()`][1]: List all devices\n* [`device_get(id:)`][2]: Gets a device (given a device id)\n* [`device_del(id:)`][3]: Deletes a device (given a device id)\n* [`trip_create(device_id:, destination:, geofences:, metadata:)`][5]: Creates a trip\n  * `device_id` is a device's id (obviously)\n  * `destination` is a GeoJSON formatted location\n  * `geofences` is a list that details the geofences that trigger that trip ([RTFM][5])\n  * `metadata` is a hash containing any string you want to associate to the trip\n* [`trip_list(limit, offset)`][6]: Lists all trips (you can easily paginate using limit and offset)\n* [`trip_get(id:)`][7]: Gets a trip given its id\n* [`trip_set_complete(id:)`][8]: Sets a trip as complete, given its id\n\n\u003e TODO\n\u003e * [`device_update(id:, ...)`][4]: Updates a device (given a device id and ...)\n\n[1]:https://docs.hypertrack.com/#references-apis-devices-get-devices\n[2]:https://docs.hypertrack.com/#references-apis-devices-get-devices-device_id\n[3]:https://docs.hypertrack.com/#references-apis-devices-delete-devices-device_id\n[4]:https://docs.hypertrack.com/#references-apis-devices-patch-devices-device_id\n[5]:https://docs.hypertrack.com/#references-apis-trips-post-trips\n[6]:https://docs.hypertrack.com/#references-apis-trips-get-trips\n[7]:https://docs.hypertrack.com/#references-apis-trips-get-trips-trip_id\n[8]:https://docs.hypertrack.com/#references-apis-trips-post-trips-trip_id-complete\n\nAll data is returned as an OpenStruct hash, so it's easy to use and manipulate.\nFor more information, please refer to [the official documentation](https://docs.hypertrack.com/#references-apis)\n\nThe Webhooks follow the same principles, and the following ones are implemented:\n\n* [`location` hook](https://docs.hypertrack.com/#references-webhooks-location-payload)\n* [`device_status` hook](https://docs.hypertrack.com/#references-webhooks-device-status-payload)\n* [`battery` hook](https://docs.hypertrack.com/#references-webhooks-battery-payload)\n* [`trip` hook](https://docs.hypertrack.com/#references-webhooks-trip-payload)\n\nEach webhook receives a bunch of parameters, and again the data parameter is an OpenStruct hash\nfor easy manipulation. It's blindly implementing the payload format.\n\n## Dependency injection\n\nTo help catch errors nicely, you can inject an error tracking tool using dependency injection,\nthen for every error being returned by the webhooks you'll get a nice trace in your favourite\ntool. For example to implement sentry, you can add to the initializer:\n\n```ruby\nHypertrackV3.error_handler = -\u003e(msg, **args) { Raven.capture_message(msg, **args) }\nHypertrackV3.exception_handler = -\u003e(exc, **args) { Raven.capture_exception(exc, **args) }\n```\n\n## License\n\nLGPL License\n\nCopyright (c) 2019 Bernard Pratz\n\nThis program is free software; you can redistribute it and/or\nmodify it under the terms of the GNU Lesser General Public\nLicense as published by the Free Software Foundation; either\nversion 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\nLesser General Public License for more details.\n\nYou should have received a copy of the GNU Lesser General Public License\nalong with this program; if not, write to the Free Software Foundation,\nInc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguyzmo%2Fhypertrack_v3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguyzmo%2Fhypertrack_v3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguyzmo%2Fhypertrack_v3/lists"}