versafleet 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2872dea00a6a74e0da415d8aff37a0e9273664d2ceb5769e697879ac7d5f13d3
-  data.tar.gz: 5101033d3ed26baff22805df056213059a2d1639b98608773e732ed885ceea45
+  metadata.gz: 35ddde324fb63af2273c9141dc2e0eb5e7125aac77ff4445c7bafa7d831a42e6
+  data.tar.gz: 102437b0f17c395bc7925a3f0f411a6b2ac8f06241564143e8ed01798be94bf4
 SHA512:
-  metadata.gz: bc310498781806260dac85344782a306a0f4677f38dc686b7b887a02c00f6135c2249cf8aa688730b02870113bba01d4626c5e435f950b4cbc6dbad58ed41fb5
-  data.tar.gz: 3228a237fec17275742a3720cb7c48d61b9c1ac0a0fe478f272aacd88eaa82bd997aa6837a7b81bf4c2ffb126ebbd82b86ca177cf9ffb8ab837b1125a91fcf4c
+  metadata.gz: 3bafe01ca74150bf2f02e8a6eb0f8f87b79aa28d72e63e5d444ecd92427dfc25688d7755ff3ed91a33cf648981af6ddf95fc115a8da41f0865c9529a0f148845
+  data.tar.gz: 5fc7fc2ff39a0bcfb76435d027a1ce5b9b132f8debf45db63798f6f0c6e93c8de452caa36c782dcbdf73bf57115fa358b4a60256f88c45d00423f4c93d0fed97

data/README.md

@@ -19,6 +19,8 @@ gem "versafleet"
 
 To access the API, you'll need to create a `Versafleet::Client` and pass in your API Key and Secret Key. See [How to obtain API keys](https://versafleet.docs.apiary.io/#introduction/to-obtain-api-keys-(please-keep-them-safe!))
 
+Need more details? See [VersaFleet API Documentation](https://rubydoc.info/gems/versafleet) to see how it works internally.
+
 ```ruby
 client = Versafleet::Client.new(client_id: ENV["CLIENT_ID"], client_secret: ENV["CLIENT_SECRET"])
 ```
@@ -62,7 +64,7 @@ client.tasks.create(task_attributes: {})
 # assign task to driver
 client.tasks.assign(task_id: task_id, task: {driver_id: driver_id, vehicle_id: vehicle_id, remarks: "Notes"})
 # assign multiple tasks to driver
-client.tasks.assign_multiple(task: {ids: [], driver_id: driver_id, vehicle_id: vehicle_id, remarks: "Notes")
+client.tasks.assign_multiple(task: {ids: [], driver_id: driver_id, vehicle_id: vehicle_id, remarks: "Notes"})
 # unassign task
 client.tasks.unassign(task_id: task_id)
 # unassign multiple tasks
@@ -87,9 +89,22 @@ client.tasks.completion_histories(task_id: task_id)
 client.tasks.base_completion_histories(task_id: task_id)
 ```
 
+### Drivers
+
+```ruby
+# list drivers
+client.drivers.list
+# get a driver details
+client.drivers.retrieve(driver_id: driver_id)
+# create driver
+client.drivers.create(driver: {name: "Yolo", dob: "1990-09-09"})
+# update driver
+client.drivers.update(driver_id: driver_id, driver: {name: "Yolo update"})
+```
+
 ## TO DO
 
-- [ ] Add API Documentation
+- [x] Add API Documentation ([#2](https://github.com/maful/versafleet-ruby/pull/2))
 - [ ] Add Docker support
 - [ ] Support to All VersaFleet API endpoints.
 

data/lib/versafleet/client.rb

@@ -1,22 +1,53 @@
 module Versafleet
   class Client
+    # Default API endpoint
     BASE_URL = "https://api.versafleet.co/api"
 
-    attr_reader :client_id, :client_secret
+    # @return [String] Gets the VersaFleet API Key
+    attr_reader :client_id
 
+    # @return [String] Gets the VersaFleet Secret Key
+    attr_reader :client_secret
+
+    # Initialize a new VersaFlet client
+    #
+    # == Example:
+    #
+    #   client = Versafleet::Client.new(client_id: ENV["CLIENT_ID"], client_secret: ENV["CLIENT_SECRET"])
+    #   # use Jobs resource
+    #   client.jobs.list
+    #
+    # @param client_id [String] VersaFleet API Key
+    # @param client_secret [String] VersaFleet Secret Key
     def initialize(client_id:, client_secret:)
       @client_id = client_id
       @client_secret = client_secret
     end
 
+    # Jobs Resource instance
+    #
+    # @return [JobsResource]
     def jobs
       JobsResource.new(self)
     end
 
+    # Tasks Resource instance
+    #
+    # @return [TasksResource]
     def tasks
       TasksResource.new(self)
     end
 
+    # Drivers Resource instance
+    #
+    # @return [DriversResource]
+    def drivers
+      DriversResource.new(self)
+    end
+
+    # Initializes a new Faraday connection
+    #
+    # @return [Faraday::Connection]
     def connection
       @connection ||= Faraday.new(params: default_params) do |conn|
         conn.url_prefix = BASE_URL

data/lib/versafleet/objects/driver.rb

@@ -0,0 +1,4 @@
+module Versafleet
+  class Driver < Object
+  end
+end

data/lib/versafleet/resources/drivers.rb

@@ -0,0 +1,67 @@
+module Versafleet
+  class DriversResource < Resource
+    # List All Drivers
+    #
+    # == Examples:
+    #
+    #   client.drivers.list
+    #   # set per page to 20
+    #   client.drivers.list(per_page: 20)
+    #   # move to page 2
+    #   client.drivers.list(page: 2, per_page: 20)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/drivers-api/list-all-drivers VersaFleet API}
+    #
+    # @param params [Hash] the filter query
+    # @return [Collection]
+    def list(**params)
+      response = get_request("drivers", params: params)
+      Collection.from_response(response, key: "drivers", type: Driver)
+    end
+
+    # Get Driver details
+    #
+    # == Examples:
+    #
+    #   client.drivers.retrieve(driver_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/drivers-api/show-a-driver VersaFleet API}
+    #
+    # @param driver_id [Integer] Driver ID
+    # @return [Driver]
+    def retrieve(driver_id:)
+      Driver.new get_request("drivers/#{driver_id}").body.dig("driver")
+    end
+
+    # Create a Driver
+    #
+    # == Examples:
+    #
+    #   client.drivers.create(driver: {name: "Yolo", dob: "1990-09-09"})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/drivers-api/create-a-driver VersaFleet API}
+    #
+    # @param driver [Hash] Driver request payload
+    # @return [Driver]
+    def create(driver:)
+      payload = {driver: driver}
+      Driver.new post_request("drivers", body: payload).body.dig("driver")
+    end
+
+    # Update Driver
+    #
+    # == Examples:
+    #
+    #   client.drivers.update(driver_id: 123, driver: {name: "John"})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/drivers-api/update-a-driver VersaFleet API}
+    #
+    # @param driver_id [Integer] Driver ID
+    # @param driver [Hash] Driver request payload
+    # @return [Driver]
+    def update(driver_id:, driver:)
+      payload = {driver: driver}
+      Driver.new put_request("drivers/#{driver_id}", body: payload).body.dig("driver")
+    end
+  end
+end

data/lib/versafleet/resources/jobs.rb

@@ -1,26 +1,95 @@
 module Versafleet
   class JobsResource < Resource
+    # List All Jobs
+    #
+    # == Examples:
+    #
+    #   client.jobs.list
+    #   # set per page to 20
+    #   client.jobs.list(per_page: 20)
+    #   # move to page 2
+    #   client.jobs.list(page: 2, per_page: 20)
+    #   # filter by Customer ID
+    #   client.jobs.list(customer_id: 1231)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/list-all-jobs VersaFleet API}
+    #
+    # @param params [Hash] the filter query
+    # @return [Collection]
     def list(**params)
       response = get_request("v2/jobs", params: params)
       Collection.from_response(response, key: "jobs", type: Job)
     end
 
+    # Create a Job
+    #
+    # == Examples:
+    #
+    #   # see the VersaFleet API for the request body reference
+    #   client.jobs.create(job: {})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/create-a-new-job VersaFleet API}
+    #
+    # @param attributes [Hash] Request body
+    # @return [Job]
     def create(**attributes)
       Job.new post_request("v2/jobs", body: attributes).body.dig("job")
     end
 
+    # Update Job
+    #
+    # == Examples:
+    #
+    #   # see the VersaFleet API for the request body reference
+    #   client.jobs.update(job_id: 123, job: {})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/update-job-or-base-task-details VersaFleet API}
+    #
+    # @param job_id [Integer] Job ID
+    # @param attributes [Hash] Request body
+    # @return [Job]
     def update(job_id:, **attributes)
       Job.new put_request("v2/jobs/#{job_id}", body: attributes).body.dig("job")
     end
 
+    # Get Job details
+    #
+    # == Examples:
+    #
+    #   client.jobs.retrieve(job_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/view-details-of-a-job VersaFleet API}
+    #
+    # @param job_id [Integer] Job ID
+    # @return [Job]
     def retrieve(job_id:)
       Job.new get_request("v2/jobs/#{job_id}").body.dig("job")
     end
 
+    # Cancel a Job
+    #
+    # == Examples:
+    #
+    #   client.jobs.cancel(job_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/cancel-a-job VersaFleet API}
+    #
+    # @param job_id [Integer] Job ID
     def cancel(job_id:)
+      # TODO: Remove Job object return
       Job.new put_request("v2/jobs/#{job_id}/cancel", body: {}).body
     end
 
+    # List Tasks of Job
+    #
+    # == Examples:
+    #
+    #   client.jobs.list_tasks(job_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/list-tasks-of-job VersaFleet API}
+    #
+    # @param job_id [Integer] Job ID
+    # @return [Collection]
     def list_tasks(job_id:)
       response = get_request("v2/jobs/#{job_id}/tasks")
       Collection.from_response(response, key: "tasks", type: Task)

data/lib/versafleet/resources/tasks.rb

@@ -1,86 +1,280 @@
 module Versafleet
   class TasksResource < Resource
+    # List All Tasks
+    #
+    # == Examples:
+    #
+    #   client.tasks.list
+    #   # set per page to 20
+    #   client.tasks.list(per_page: 20)
+    #   # set specific date
+    #   client.tasks.list(date: "2021-01-01")
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/list-all-tasks VersaFleet API}
+    #
+    # @param params [Hash] the filter query
+    # @return [Collection]
     def list(**params)
       response = get_request("tasks", params: params)
       Collection.from_response(response, key: "tasks", type: Task)
     end
 
+    # List All Tasks by State
+    #
+    # == Examples:
+    #
+    #   client.tasks.list_by_state
+    #   # tasks by state
+    #   client.tasks.list_by_state(state: "completed")
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/list-all-tasks-by-state VersaFleet API}
+    #
+    # @param params [Hash] the filter query
+    # @return [Collection]
     def list_by_state(**params)
       response = get_request("tasks/by_state", params: params)
       Collection.from_response(response, key: "tasks", type: Task)
     end
 
+    # Get Task details
+    #
+    # == Examples:
+    #
+    #   client.tasks.retrieve(task_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/view-details-of-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
+    # @return [Task]
     def retrieve(task_id:)
       Task.new get_request("tasks/#{task_id}").body.dig("task")
     end
 
+    # Get Task details by Tracking ID
+    #
+    # == Examples:
+    #
+    #   client.tasks.retrieve_by_tracking_id(tracking_id: "1234567891100")
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/view-limited-task-details-from-tracking-id VersaFleet API}
+    #
+    # @param tracking_id [String] Tracking ID
+    # @return [Task]
     def retrieve_by_tracking_id(tracking_id:)
       Task.new post_request("tasks/#{tracking_id}/track", body: {}).body.dig("task")
     end
 
+    # Update Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.update(task_id: 123, task_attributes: {})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/update-a-task-detail VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
+    # @param task_attributes [Hash] Task request payload
+    # @return [Task]
     def update(task_id:, task_attributes:)
       payload = {task_attributes: task_attributes}
       Task.new put_request("tasks/#{task_id}", body: payload).body.dig("task")
     end
 
-    # TODO: Add support for allocate_id
+    # Add Task to Job
+    #
+    # == Examples:
+    #
+    #   client.tasks.create(task_attributes: {})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/add-a-new-task-to-a-job VersaFleet API}
+    #
+    # @param task_attributes [Hash] Task request payload
+    # @return [Task]
     def create(task_attributes:)
+      # TODO: Add support for allocate_id
       payload = {task_attributes: task_attributes}
       Task.new post_request("tasks", body: payload).body.dig("task")
     end
 
+    # Assign a Driver to Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.assign(task_id: 123, task: {driver_id: 12, vehicle_id: 3, remarks: "Notes"})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/assign-a-driver-to-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
+    # @param task [Hash] Driver and Vehicle details
+    # @return [Task]
     def assign(task_id:, task:)
       payload = {task: task}
       Task.new put_request("tasks/#{task_id}/assign", body: payload).body.dig("task")
     end
 
+    # Assign a Driver to Multiple Tasks
+    #
+    # == Examples:
+    #
+    #   client.tasks.assign_multiple(task: {ids: [12,21], driver_id: 11, vehicle_id: 2, remarks: "Notes"})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/assign-a-driver-to-multiple-tasks VersaFleet API}
+    #
+    # @param task [Hash] Task IDs, Driver and Vehicle details
     def assign_multiple(task:)
       payload = {task: task}
       put_request("tasks/assign", body: payload).body
     end
 
+    # Unssign a Driver from Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.unassign(task_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/unassign-a-driver-from-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
+    # @return [Task]
     def unassign(task_id:)
       Task.new put_request("tasks/#{task_id}/unassign", body: {}).body.dig("task")
     end
 
+    # Unsssign a Driver from Multiple Tasks
+    #
+    # == Examples:
+    #
+    #   client.tasks.unassign_multiple(task: {ids: [123,213]})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/unassign-a-driver-from-multiple-tasks VersaFleet API}
+    #
+    # @param task [Hash] Task IDs
     def unassign_multiple(task:)
       payload = {task: task}
       put_request("tasks/unassign", body: payload).body
     end
 
+    # Cancel a Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.cancel(task_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/cancel-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
     def cancel(task_id:)
       put_request("tasks/#{task_id}/cancel", body: {}).body
     end
 
+    # Complete a Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.complete(task_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/complete-/-succeed-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
     def complete(task_id:)
       put_request("tasks/#{task_id}/set_successful", body: {}).body
     end
 
+    # Incomplete a Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.incomplete(task_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/incomplete-/-fail-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
     def incomplete(task_id:)
       put_request("tasks/#{task_id}/set_failed", body: {}).body
     end
 
+    # Set a Task State
+    #
+    # == Examples:
+    #
+    #   client.tasks.set_state(task_id: 123, to_state: "waiting_for_acknowledgement")
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/set-a-task-state VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
+    # @param to_state [String] Task state
     def set_state(task_id:, to_state:)
       payload = {to_state: to_state}
       put_request("tasks/#{task_id}/state", body: payload).body
     end
 
+    # Archive a Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.archive(task_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/archive-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
+    # @return [Task]
     def archive(task_id:)
       Task.new put_request("tasks/#{task_id}/archive", body: {}).body.dig("task")
     end
 
+    # Unarchive a Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.unarchive(task_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/unarchive-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
+    # @return [Task]
     def unarchive(task_id:)
       Task.new put_request("tasks/#{task_id}/unarchive", body: {}).body.dig("task")
     end
 
+    # View Task Completion Histories of a Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.completion_histories(task_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/view-task-completion-histories-of-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
+    # @return [Task]
     def completion_histories(task_id:)
       Task.new get_request("tasks/#{task_id}/task_completion_histories").body
     end
 
+    # View Base Task Completion Histories of a Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.base_completion_histories(task_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/view-base-task-completion-histories-of-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
+    # @return [Task]
     def base_completion_histories(task_id:)
       Task.new get_request("tasks/#{task_id}/base_task_completion_histories").body
     end
 
+    # Allocate a Task
+    #
+    # == Examples:
+    #
+    #   client.tasks.allocate(task_id: 123, sub_account_id: 211)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/tasks-api/allocate-a-task VersaFleet API}
+    #
+    # @param task_id [Integer] Task ID
+    # @param sub_account_id [Integer] Transporter ID
+    # @return [Task]
     def allocate(task_id:, sub_account_id:)
       payload = {task: {allocatee_id: sub_account_id}}
       Task.new put_request("tasks/#{task_id}/allocate", body: payload).body.dig("task")

data/lib/versafleet/version.rb

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

data/lib/versafleet.rb

@@ -12,8 +12,10 @@ module Versafleet
   # Resources (like high level API endpoints)
   autoload :JobsResource, "versafleet/resources/jobs"
   autoload :TasksResource, "versafleet/resources/tasks"
+  autoload :DriversResource, "versafleet/resources/drivers"
 
   # Classes used to return a nicer object wrapping the response data
   autoload :Job, "versafleet/objects/job"
   autoload :Task, "versafleet/objects/task"
+  autoload :Driver, "versafleet/objects/driver"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: versafleet
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Maful Prayoga A
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-13 00:00:00.000000000 Z
+date: 2021-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -38,14 +38,13 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
-description: 
+description:
 email:
 - mafulprayoga@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/release.yml"
 - ".github/workflows/test.yml"
 - ".gitignore"
 - CODE_OF_CONDUCT.md
@@ -60,9 +59,11 @@ files:
 - lib/versafleet/collection.rb
 - lib/versafleet/error.rb
 - lib/versafleet/object.rb
+- lib/versafleet/objects/driver.rb
 - lib/versafleet/objects/job.rb
 - lib/versafleet/objects/task.rb
 - lib/versafleet/resource.rb
+- lib/versafleet/resources/drivers.rb
 - lib/versafleet/resources/jobs.rb
 - lib/versafleet/resources/tasks.rb
 - lib/versafleet/version.rb
@@ -75,7 +76,7 @@ metadata:
   bug_tracker_uri: https://github.com/maful/versafleet-ruby/issues
   source_code_uri: https://github.com/maful/versafleet-ruby
   github_repo: https://github.com/maful/versafleet-ruby
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -91,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.2.22
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Ruby bindings for the VersaFleet API
 test_files: []

data/.github/workflows/release.yml

@@ -1,41 +0,0 @@
-name: Build + Release
-
-on:
-  push:
-    tags:
-      - "v*.*.*"
-
-jobs:
-  build:
-    runs-on: ubuntu-20.04
-
-    strategy:
-      matrix:
-        ruby: ["2.5", "2.6", "2.7", "3.0"]
-
-    steps:
-    - uses: actions/checkout@v2
-
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby }}
-        bundler-cache: true
-
-    - name: StandardRb check
-      run: bundle exec standardrb
-
-    - name: Run tests
-      run: |
-        bundle exec rake test
-
-    - name: Publish to RubyGems
-      run: |
-        mkdir -p $HOME/.gem
-        touch $HOME/.gem/credentials
-        chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem build *.gemspec
-        gem push *.gem
-      env:
-        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"