jbr 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e80d8cc7babd6cf1085382e8edb6d1e680afada9eda3cfdf8e3372969a15177d
-  data.tar.gz: dae5536d6035f67546136f12ffe1fc52d602bdffc8dd5eeba120fec2313c4cd7
+  metadata.gz: 9a1fb03ffa4daca5169eaad910f2827a11aee58c2ba49bf8bb7cc783e16cbb5b
+  data.tar.gz: ac95d6fa65c22bd24975c5ba559a1bda62dfd62fdf9f45c9875a60ea1c8e55c8
 SHA512:
-  metadata.gz: f48b5bf3bf903d427172e3e1aedb004887ade4026049275fadfae98e60eff542d548176910a7e221c6c6c9cfd7ced652a7d0eaae6ea28bc57f7f5f1f06f8bc56
-  data.tar.gz: 8cf8d948c812075b068479e25737a0d43999831f2dea87a018d6d62fe8c1049d96bb27076f88173ed91d4bd4ae1939669d768402ee9e8ce8e5c215c14014d909
+  metadata.gz: e3cc394c967fc81fb75ca6abd53e6f2d9f6777b61f44e492a96b44e2e06c091bc4b180b12cd7218578eef76c5368b76d9075830e55dbb9f7e8a793c8fef4a3d6
+  data.tar.gz: 13b17df1cd0f40caafd12d6cfcfc35cff33aa3580fbf12a69b28fdc7c279dda89b3bee03a35a86597dabd4cc27f7a7563c875211c53770684ff2a482c5af0814

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [1.0.2] - 2026-05-22
+
+- [Fix] Ensure .find returns nil if the Jobber resource is not found
+
+## [1.0.0] - 2026-05-15
+
+- Initial release: OAuth, Request, Client, Quote, Job, Invoice, Account classes

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 HouseAccount
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,64 @@
+# Jobber API Ruby client
+
+## Available methods
+
+Initialize the authentication with a code:
+
+```ruby
+oauth = Jbr::OAuth.create code: code, redirect_uri: jobber_callback_url
+```
+
+Access OAuth attributes:
+
+```
+oauth.access_token # => 'eyJhbGciOiJIUzI1NiJ'
+oauth.refresh_token # => 'ea02775958c5fca28d'
+oauth.expires_at # => 2026-05-22 14:32:53
+oauth.account_id # => 'Z2lkOi8vSm9iYmV'
+````
+
+Create a Jobber request, finding or creating a Client with a matching phone number:
+
+```ruby
+request = oauth.requests.create first_name: 'Jane', last_name: 'Doe', phone: '5553335555',
+  email: 'jane@example.com', title: 'New Plumber Lead', instructions: 'Needs new faucet'
+request.id # => 'Z2lkOi8vSm9iYmVyL'
+request.client_id # => 'MwMTU0Mg'
+```
+
+Fetches a quote from Jobber:
+
+```ruby
+quote = oauth.quotes.find 'Z2lkOi8vS'
+quote.id # => 'Z2lkOi8vS'
+quote.request_id # => 'Z2lkOi8vSm9iYmVyL'
+```
+
+Fetches a job from Jobber:
+
+```ruby
+job = oauth.jobs.find 'Njc5MTk5'
+job.id # => 'Z2lkOi8vS'
+job.quote_id # => 'Z2lkOi8vS'
+job.scheduled_at # => 2026-05-14 23:02:52
+job.completed_at # => 2026-05-18 11:36:13
+```
+
+Fetches a non-draft invoice from Jobber:
+
+```ruby
+invoice = oauth.invoices.find 'MjU3ODA0'
+invoice.id # => 'MjU3ODA0'
+invoice.job_id # => 'Z2lkOi8vS'
+invoice.total # => '40.30'
+invoice.issued_date # => 2026-05-22
+invoice.completed_at # => 2026-05-22 14:32:53
+```
+
+
+Revoke authentication:
+
+```ruby
+oauth.delete
+```
+

data/lib/jbr/account.rb

@@ -0,0 +1,11 @@
+module Jbr
+  class Account < Resource
+    FIND = <<~GRAPHQL.freeze
+      { account { id } }
+    GRAPHQL
+
+    def id
+      @id ||= @oauth.query(FIND).dig 'account', 'id'
+    end
+  end
+end

data/lib/jbr/client.rb

@@ -0,0 +1,54 @@
+module Jbr
+  class Client < Resource
+    LOOKUP = <<~GRAPHQL.freeze
+      query($searchTerm: String!) {
+        clientPhones(searchTerm: $searchTerm) { nodes { client { id updatedAt } } }
+      }
+    GRAPHQL
+
+    CREATE = <<~GRAPHQL.freeze
+      mutation($input: ClientCreateInput!) {
+        clientCreate(input: $input) { client { id } userErrors { message } }
+      }
+    GRAPHQL
+
+    # Create a client instance with the provided attributes.
+    # @return [Client] itself
+    # @param params [Hash] the attributes of the client
+    # @option params [String] :first_name the client’s first name
+    # @option params [String] :last_name the client’s last name
+    # @option params [String] :phone the client’s phone number
+    # @option params [<String, nil>] :email the client’s email address
+    def create_with(params = {})
+      self.tap { @create_params = params }
+    end
+
+    def find_or_create_by(phone:)
+      find_by_phone(phone) || create
+      self
+    end
+
+  private
+
+    def find_by_phone(phone)
+      output = @oauth.query LOOKUP, variables: { searchTerm: phone }
+      recent = (output.dig('clientPhones', 'nodes') || []).max_by do |clients|
+        clients.dig('client', 'updatedAt') || ''
+      end
+      @id = recent&.dig 'client', 'id'
+    end
+
+    def create
+      output = @oauth.query CREATE, variables: { input: input }
+      @id = output.dig 'clientCreate', 'client', 'id'
+    end
+
+    def input
+      { firstName: @create_params[:first_name],
+        lastName: @create_params[:last_name],
+        phones: [{ number: @create_params[:phone], primary: true }],
+        emails: ([{ address: @create_params[:email], primary: true }] if @create_params[:email].present?)
+      }.compact
+    end
+  end
+end

data/lib/jbr/error.rb

@@ -0,0 +1,3 @@
+module Jbr
+  Error = Class.new StandardError
+end

data/lib/jbr/invoice.rb

@@ -0,0 +1,38 @@
+module Jbr
+  class Invoice < Resource
+    FIND = <<~GRAPHQL.freeze
+      query($id: EncodedId!) {
+        invoice(id: $id) { id total invoiceStatus issuedDate
+          jobs { nodes { id completedAt } } }
+      }
+    GRAPHQL
+
+    attr_reader :job_id, :total
+
+    def find(id)
+      output = @oauth.query FIND, variables: { id: id  }
+      return unless invoice = output['invoice']
+      return if invoice['invoiceStatus'].eql? 'draft'
+
+      @id = invoice['id']
+      @total = invoice['total']
+      @issued_date = invoice['issuedDate']
+
+      job = invoice.dig('jobs', 'nodes', 0) || {}
+      @job_id = job['id']
+      @completed_at = job['completedAt']
+
+      self
+    end
+
+    # @return [Date] the invoice issued date
+    def issued_date
+      Date.iso8601(@issued_date) if @issued_date
+    end
+
+    # @return [Time] the job completed time
+    def completed_at
+      Time.iso8601(@completed_at) if @completed_at
+    end
+  end
+end

data/lib/jbr/job.rb

@@ -0,0 +1,32 @@
+module Jbr
+  class Job < Resource
+    FIND = <<~GRAPHQL.freeze
+      query($id: EncodedId!) {
+        job(id: $id) { id quote { id } startAt completedAt }
+      }
+    GRAPHQL
+
+    attr_reader :quote_id
+
+    def find(id)
+      output = @oauth.query FIND, variables: { id: id  }
+      return unless job = output['job']
+
+      @id = job['id']
+      @quote_id = job.dig 'quote', 'id'
+      @scheduled_at = job['startAt']
+      @completed_at = job['completedAt']
+      self
+    end
+
+    # @return [Time] the job scheduled time
+    def scheduled_at
+      Time.iso8601(@scheduled_at) if @scheduled_at
+    end
+
+    # @return [Time] the job completed time
+    def completed_at
+      Time.iso8601(@completed_at) if @completed_at
+    end
+  end
+end

data/lib/jbr/oauth.rb

@@ -0,0 +1,84 @@
+module Jbr
+  class OAuth
+    DISCONNECT_MUTATION = <<~GRAPHQL.freeze
+      mutation Disconnect {
+        appDisconnect {
+          app { name author }
+          userErrors { message }
+        }
+      }
+    GRAPHQL
+
+    def initialize(credentials = {})
+      @access_token = credentials[:access_token]
+      @refresh_token = credentials[:refresh_token]
+      @expires_at = credentials[:expires_at]
+      @account_id = credentials[:account_id]
+      @invalid_at = credentials[:invalid_at]
+    end
+
+    attr_reader :access_token, :refresh_token, :expires_at, :invalid_at
+    attr_accessor :account_id
+
+    def account = Account.new oauth: self
+    def clients = Client.new oauth: self
+    def invoices = Invoice.new oauth: self
+    def jobs = Job.new oauth: self
+    def quotes = Quote.new oauth: self
+    def requests = Request.new oauth: self
+
+    def query(statement, variables: {})
+      client.query statement, variables: variables
+    rescue GraphQL::Unauthorized => e
+      refresh ? retry : {}
+    end
+
+    # Delete a token. If the token is invalid, do nothing.
+    def delete
+      client.query DISCONNECT_MUTATION
+    rescue GraphQL::Unauthorized => e
+    end
+
+    def self.create(code:, redirect_uri:)
+      credentials = post code: code, redirect_uri: redirect_uri, grant_type: 'authorization_code'
+      new(credentials).tap { |oauth| oauth.account_id = oauth.account.id }
+    end
+
+  private
+
+    def refresh
+      output = self.class.post refresh_token: @refresh_token, grant_type: 'refresh_token'
+      @access_token = output[:access_token]
+      @refresh_token = output[:refresh_token]
+      @expires_at = output[:expires_at]
+    rescue Error => e
+      @invalid_at = Time.current
+      false
+    end
+
+    def self.post(params = {})
+      uri = URI 'https://api.getjobber.com/api/oauth/token'
+      response = Net::HTTP.post_form uri, params.merge(client_id: client_id, client_secret: client_secret)
+      raise Error, response.body unless response.is_a? Net::HTTPSuccess
+      output = JSON.parse(response.body)
+      { access_token: output['access_token'], refresh_token: output['refresh_token'],
+        expires_at: (Time.current + output.fetch('expires_in', 3600).to_i) }
+    end
+
+    def self.client_id = ENV['JOBBER_CLIENT_ID']
+
+    def self.client_secret = ENV['JOBBER_CLIENT_SECRET']
+
+    def client
+      GraphQL::Client.new endpoint: 'https://api.getjobber.com/api/graphql', token: @access_token, headers: headers
+    end
+
+    def headers = { 'X-JOBBER-GRAPHQL-VERSION' => '2026-04-22' }
+
+    def self.url_for(params = {})
+      uri = URI 'https://api.getjobber.com/api/oauth/authorize'
+      uri.query ||= params.merge(response_type: 'code', client_id: client_id).to_query
+      uri.to_s
+    end
+  end
+end

data/lib/jbr/quote.rb

@@ -0,0 +1,20 @@
+module Jbr
+  class Quote < Resource
+    FIND = <<~GRAPHQL.freeze
+      query($id: EncodedId!) {
+        quote(id: $id) { id request { id } }
+      }
+    GRAPHQL
+
+    attr_reader :request_id
+
+    def find(id)
+      output = @oauth.query FIND, variables: { id: id  }
+      return unless quote = output['quote']
+
+      @id = quote['id']
+      @request_id = quote.dig 'request', 'id'
+      self
+    end
+  end
+end

data/lib/jbr/request.rb

@@ -0,0 +1,28 @@
+module Jbr
+  class Request < Resource
+    CREATE = <<~GRAPHQL.freeze
+      mutation($input: RequestCreateInput!) {
+        requestCreate(input: $input) { request { id } userErrors { message } }
+      }
+    GRAPHQL
+
+    attr_reader :client_id
+
+    # Create a lead in Jobber associated to a new or existing client, matched by phone.
+    # @return [String] the ID of the newly created lead.
+    # @param params [Hash] the attributes of the lead
+    # @option params [String] :first_name the client’s first name
+    # @option params [String] :last_name the client’s last name
+    # @option params [String] :phone the client’s phone number
+    # @option params [<String, nil>] :email the client’s email address
+    # @option params [String] :title the reason why the lead is created
+    # @option params [String] :instructions a comment about the lead
+    def create(params = {})
+      @client_id = @oauth.clients.create_with(params).find_or_create_by(phone: params[:phone]).id
+      input = { clientId: @client_id, title: params[:title], assessment: { instructions: params[:instructions] } }
+      output = @oauth.query CREATE, variables: { input: input }
+      @id = output.dig 'requestCreate', 'request', 'id'
+      self
+    end
+  end
+end

data/lib/jbr/resource.rb

@@ -0,0 +1,9 @@
+module Jbr
+  class Resource
+    def initialize(oauth:)
+      @oauth = oauth
+    end
+
+    attr_reader :id
+  end
+end

data/lib/jbr/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Jbr
+  VERSION = '1.0.2'
+end

data/lib/jbr.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+
+require 'jbr/error'
+require 'jbr/resource'
+require 'jbr/request'
+require 'jbr/oauth'
+
+require 'jbr/account'
+require 'jbr/client'
+require 'jbr/invoice'
+require 'jbr/job'
+require 'jbr/quote'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -15,7 +15,21 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/jbr.rb
+- lib/jbr/account.rb
+- lib/jbr/client.rb
+- lib/jbr/error.rb
+- lib/jbr/invoice.rb
+- lib/jbr/job.rb
+- lib/jbr/oauth.rb
+- lib/jbr/quote.rb
+- lib/jbr/request.rb
+- lib/jbr/resource.rb
+- lib/jbr/version.rb
 homepage: https://github.com/HouseAccountEng/jbr
 licenses:
 - MIT