jbr 3.12.0 → 4.0.0

data/lib/jbr/client.rb

@@ -1,98 +0,0 @@
-module Jbr
-  # A person a Jobber user works for, and the property the work happens at.
-  class Client < Resource
-    # The query that finds a client by phone, with the properties already on file.
-    LOOKUP = <<~GRAPHQL
-      query($searchTerm: String!) {
-        clientPhones(first: 1, searchTerm: $searchTerm) { nodes {
-          client { id updatedAt clientProperties { nodes { id address { #{Property::SELECTION} } }} }
-        } }
-      }
-    GRAPHQL
-
-    # The mutation that opens a client, with a first property when an address is given.
-    CREATE = <<~GRAPHQL
-      mutation($input: ClientCreateInput!) {
-        clientCreate(input: $input) {
-          client { id clientProperties(first: 1) { nodes { id } } }
-          userErrors { message }
-        }
-      }
-    GRAPHQL
-
-    # @return [String, nil] the property the work happens at.
-    attr_reader :property_id
-
-    # @return [String, nil] what the client is called.
-    def first_name = @node['firstName']
-
-    def last_name = @node['lastName']
-
-    # @return [String, nil] the business the client is, where the client is a business.
-    def company_name = @node['companyName']
-
-    # Jobber files nobody without one name or the other, so there is always one to call them.
-    # @return [String, nil] the person's first name, or the business's name. Never empty.
-    def name = first_name.presence || company_name.presence
-
-    # @return [String, nil] the address to write to.
-    def email = @node['email']
-
-    # The number to reach them on, without its country code.
-    # @return [String, nil] ten digits, or nil where Jobber holds none we can dial.
-    def phone = Phone.from(@node['phones'])
-
-    # 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
-
-    # Reach the client behind a phone number, opening one if Jobber has none.
-    # @param phone [String] the number to match on.
-    # @return [Client] itself.
-    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
-      return unless recent
-
-      @id = recent.dig 'client', 'id'
-      @property_id = Property.new(oauth: @oauth).find_or_create_for client_id: @id,
-        address: @create_params[:address],
-        existing: recent.dig('client', 'clientProperties', 'nodes') || []
-      true
-    end
-
-    def create
-      output = @oauth.query CREATE, variables: { input: input }
-      @id = output.dig 'clientCreate', 'client', 'id'
-
-      properties = output.dig('clientCreate', 'client', 'clientProperties', 'nodes') || []
-      @property_id = (properties.first || {})['id']
-    end
-
-    def input
-      address, email = @create_params[:address], @create_params[:email]
-      { firstName: @create_params[:first_name],
-        lastName: @create_params[:last_name],
-        properties: ([ { address: Property.address_from(address) } ] if address.present?),
-        phones: [ { number: @create_params[:phone], primary: true } ],
-        emails: ([ { address: email, primary: true } ] if email.present?),
-      }.compact
-    end
-  end
-end

data/lib/jbr/cliental.rb

@@ -1,14 +0,0 @@
-module Jbr
-  # Extends a record that names the client the work is for: a visit, a job, a property,
-  # anything Jobber files under somebody.
-  module Cliental
-    # What Jobber calls each field of that client.
-    FIELDS = %w[id firstName lastName companyName email]
-
-    # What to ask for wherever a record names its client.
-    SELECTION = "client { #{FIELDS.join ' '} #{Phone::SELECTION} }"
-
-    # @return [Client] who the work is for.
-    def client = Client.new node: @node.fetch('client', {})
-  end
-end

data/lib/jbr/invoice.rb

@@ -1,43 +0,0 @@
-module Jbr
-  # A bill a Jobber user issued for finished work.
-  class Invoice < Resource
-    # The query that reads one invoice, its total, its date and the job it bills.
-    FIND = <<~GRAPHQL
-      query($id: EncodedId!) {
-        invoice(id: $id) { id total invoiceStatus issuedDate
-          jobs { nodes { id completedAt } } }
-      }
-    GRAPHQL
-
-    # @return [String, nil] the ID of the job billed, and the amount as Jobber writes it.
-    attr_reader :job_id, :total
-
-    # @param id [String] the Jobber ID of the invoice.
-    # @return [Invoice, nil] itself, or nil when the invoice is missing or still a draft.
-    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_at = invoice['issuedDate']
-
-      job = invoice.dig('jobs', 'nodes', 0) || {}
-      @job_id = job['id']
-      @completed_at = job['completedAt']
-
-      self
-    end
-
-    # @return [Date] the invoice issued time
-    def issued_at
-      Time.iso8601(@issued_at) if @issued_at
-    end
-
-    # @return [Time] the job completed time
-    def completed_at
-      Time.iso8601(@completed_at) if @completed_at
-    end
-  end
-end

data/lib/jbr/itemized.rb

@@ -1,9 +0,0 @@
-module Jbr
-  # Extends a record Jobber itemizes: a job, whose lines say what the work actually was
-  # where the title only says what somebody called it.
-  module Itemized
-    # @return [Array<LineItem>] the lines the record is made of, empty where the query never
-    #   asked for them — a page costs what it carries, so nothing nested arrives unasked.
-    def line_items = LineItem.from @node.dig('lineItems', 'nodes')
-  end
-end

data/lib/jbr/job.rb

@@ -1,40 +0,0 @@
-module Jbr
-  # Work a Jobber user accepted and scheduled.
-  class Job < Resource
-    include Cliental, Itemized, Named, Properted
-
-    # @return [String, nil] what the job is called, where whoever opened it named it.
-    def title = @node['title']
-
-    # @return [String, nil] what the work is, in the words whoever opened the job wrote.
-    def instructions = @node['instructions']
-
-    # What the job's lines add up to, each as how many of what: `3 Faucet install and 2 Valve
-    # change` — `to_sentence` reading each line's own string form. The lines say what the work
-    # was where a title only says what it was called, so this reads better than one, and falls
-    # back to {#name} where the job has no lines or the query never asked for them.
-    # @return [String] the lines as a sentence, or the title, or the ID. Never nil, never empty.
-    def summary = line_items.to_sentence.presence || name
-
-    # @return [String, nil] where Jobber files the job in its own workflow.
-    def status = @node['jobStatus']
-
-    # @return [String, nil] the ID of the quote the job was won with.
-    def quote_id = @node.dig 'quote', 'id'
-
-    # @return [Float, nil] what the job comes to.
-    def total = @node['total']
-
-    # @return [Float, nil] what the quote the job was won with came to.
-    def quote_total = @node.dig 'quote', 'amounts', 'total'
-
-    # @return [Time, nil] the job opening time
-    def created_at = time 'createdAt'
-
-    # @return [Time, nil] the job scheduled time
-    def scheduled_at = time 'startAt'
-
-    # @return [Time, nil] the job completed time
-    def completed_at = time 'completedAt'
-  end
-end

data/lib/jbr/line_item.rb

@@ -1,36 +0,0 @@
-module Jbr
-  # One line of the work a job is made of: how many of a thing, and what it is called.
-  class LineItem < Resource
-    # What Jobber calls each field of a line.
-    FIELDS = %w[quantity name]
-
-    # The most lines to read off one record. Bounded because Jobber prices a connection by the
-    # page it is asked for and prices an unbounded one at its own maximum, so the lines of a
-    # page of jobs were charged for as though every job had the largest job's worth of them.
-    PAGE = 20
-
-    # What to ask for wherever a record lists the lines it is made of.
-    SELECTION = "lineItems(first: #{PAGE}) { nodes { #{FIELDS.join ' '} } }"
-
-    # @param nodes [Array<Hash>, nil] the lines as Jobber answered them, if it answered any.
-    # @return [Array<LineItem>] one per line, in the order Jobber holds them.
-    def self.from(nodes) = nodes.to_a.map { |node| new node: node }
-
-    # @return [Integer, Float, nil] how many of it the job is for.
-    def quantity = whole @node['quantity']
-
-    # @return [String, nil] what the line is called.
-    def name = @node['name']
-
-    # @return [String] how many of what: `3 Bathroom Faucet Installation`, and the name alone
-    #   where Jobber holds no quantity for the line.
-    def to_s = [ quantity, name ].compact.join ' '
-
-  private
-
-    # Jobber answers every quantity as a Float, and a whole one reads as an Integer:
-    # `3 Faucets` rather than `3.0 Faucets`. A fraction keeps its point — `3.5 Faucets` —
-    # since rounding it would lie about what was billed.
-    def whole(number) = number && ((number % 1).zero? ? number.to_i : number)
-  end
-end

data/lib/jbr/mock/client.rb

@@ -1,17 +0,0 @@
-module Jbr
-  # A client that reads from {Jbr.mock} instead of Jobber.
-  class Mock::Client < Client
-    # @return [Object, nil] the values the app asked for.
-    def id = @node[:id]
-
-    def first_name = @node[:first_name]
-
-    def last_name = @node[:last_name]
-
-    def company_name = @node[:company_name]
-
-    def email = @node[:email]
-
-    def phone = @node[:phone]
-  end
-end

data/lib/jbr/mock/job.rb

@@ -1,31 +0,0 @@
-module Jbr
-  # A job that reads from {Jbr.mock} instead of Jobber.
-  class Mock::Job < Job
-    # @return [Object, nil] the values the app asked for.
-    def id = @node[:id]
-
-    def title = @node[:title]
-
-    def instructions = @node[:instructions]
-
-    def status = @node[:status]
-
-    def quote_id = @node[:quote_id]
-
-    def total = @node[:total]
-
-    def quote_total = @node[:quote_total]
-
-    def created_at = @node[:created_at]
-
-    def client = Mock::Client.new(node: @node.fetch(:client, {}))
-
-    def property = Mock::Property.new(node: @node.fetch(:property, {}))
-
-    def line_items = Mock::LineItem.from(@node.fetch(:line_items, []))
-
-    def scheduled_at = @node[:scheduled_at]
-
-    def completed_at = @node[:completed_at]
-  end
-end

data/lib/jbr/mock/line_item.rb

@@ -1,10 +0,0 @@
-module Jbr
-  # A line of a job that reads from {Jbr.mock} instead of Jobber.
-  class Mock::LineItem < LineItem
-    # @return [Object, nil] the values the app asked for. The quantity is still read whole,
-    #   so an app that mocks `3.0` of a thing sees the `3` a page would show.
-    def quantity = whole @node[:quantity]
-
-    def name = @node[:name]
-  end
-end

data/lib/jbr/mock/oauth.rb

@@ -1,22 +0,0 @@
-module Jbr
-  # Credentials that answer from {Jbr.mock} instead of Jobber.
-  class Mock::OAuth < OAuth
-    # The mocked resources these credentials read and write.
-    def invoices = Mock::Invoice.new(oauth: self)
-    def jobs = Mock::Jobs.new(oauth: self)
-    def quotes = Mock::Quote.new(oauth: self)
-    def requests = Mock::Request.new(oauth: self)
-    def account = Mock::Account.new oauth: self
-    def visits = Mock::Visits.new(oauth: self)
-
-    # Revoking a mocked token asks nobody.
-    def delete; end
-
-    # @return [Hash] canned credentials, unless the app asked for a refusal.
-    def self.post(_)
-      raise Error, Jbr.mock.oauth_error if Jbr.mock.oauth_error
-
-      { access_token: 'mock-token', refresh_token: 'mock-token', expires_at: (Time.now + 3600) }
-    end
-  end
-end

data/lib/jbr/mock/property.rb

@@ -1,19 +0,0 @@
-module Jbr
-  # A property that reads from {Jbr.mock} instead of Jobber.
-  class Mock::Property < Property
-    # @return [Object, nil] the values the app asked for.
-    def id = @node[:id]
-
-    def street = @node[:street]
-
-    def city = @node[:city]
-
-    def zip = @node[:zip]
-
-    def latitude = @node[:latitude]
-
-    def longitude = @node[:longitude]
-
-    def client = Mock::Client.new(node: @node.fetch(:client, {}))
-  end
-end

data/lib/jbr/mock/request.rb

@@ -1,12 +0,0 @@
-module Jbr
-  # A request that records what {Jbr.mock} was told to answer.
-  class Mock::Request < Request
-    # @return [Mock::Request] itself, carrying the mocked IDs.
-    def create(_)
-      @id = Jbr.mock.request[:id]
-      @client_id = Jbr.mock.request[:client_id]
-
-      self
-    end
-  end
-end

data/lib/jbr/mock/url.rb

@@ -1,9 +0,0 @@
-module Jbr
-  # The authorize URL an app under test asked for.
-  class Mock::URL < URL
-    # @return [String] whatever {Jbr.mock} was told to answer.
-    def self.for(_)
-      Jbr.mock.oauth_url
-    end
-  end
-end

data/lib/jbr/mocking.rb

@@ -1,30 +0,0 @@
-module Jbr
-  # The switch an app under test throws to answer Jobber without a network. Touching
-  # {#mock} once turns every entry point below over to its Mock counterpart.
-  module Mocking
-    # @return [Mock] the answers this process gives, created on first use.
-    def mock
-      @mock ||= Jbr::Mock.new
-    end
-
-    # @param params [Hash] the +code+ and +redirect_uri+ to exchange.
-    # @return [OAuth] credentials for the account that authorized the app.
-    def create_oauth(params = {})
-      (@mock ? Mock::OAuth : OAuth).create(**params)
-    end
-
-    # @param params [Hash] the +redirect_uri+ and +state+ to come back with.
-    # @return [String] the URL a Jobber user authorizes the app on.
-    def oauth_url_for(params = {})
-      (@mock ? Mock::URL : URL).for(**params)
-    end
-
-    # @param params [Hash] credentials already on file.
-    # @return [OAuth] those credentials, ready to read and write with.
-    def oauth_for(params = {})
-      (@mock ? Mock::OAuth : OAuth).new(params)
-    end
-  end
-
-  extend Mocking
-end

data/lib/jbr/named.rb

@@ -1,9 +0,0 @@
-module Jbr
-  # Extends a record Jobber lets go untitled: a visit, a job, anything somebody may have
-  # opened without ever typing a name for it.
-  module Named
-    # Untitled happens often enough, and something has to stand in for it on a list.
-    # @return [String] the title, or the ID Jobber files the record under. Never empty.
-    def name = title.presence || id
-  end
-end

data/lib/jbr/oauth.rb

@@ -1,94 +0,0 @@
-module Jbr
-  # Credentials for one Jobber account, and the gateway to all they read or write.
-  class OAuth
-    include Refreshing
-
-    # The mutation that revokes the app on the account.
-    DISCONNECT_MUTATION = <<~GRAPHQL
-      mutation Disconnect {
-        appDisconnect {
-          app { name author }
-          userErrors { message }
-        }
-      }
-    GRAPHQL
-
-    # @param credentials [Hash] the tokens, their expiry, the account, when it went bad, and
-    #   the `store:` these are kept in, where processes share them. See {Refreshing}.
-    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]
-      @store = credentials[:store]
-    end
-
-    # The credentials as Jobber last gave them, plus the moment a refusal to refresh landed.
-    attr_reader :access_token, :refresh_token, :expires_at, :invalid_at
-    # @return [String, nil] the account these credentials reach.
-    attr_accessor :account_id
-
-    # The resources these credentials read and write.
-    def account = Account.new oauth: self
-    def clients = Client.new oauth: self
-    def invoices = Invoice.new oauth: self
-    def jobs = Jobs.new oauth: self
-    def quotes = Quote.new oauth: self
-    def requests = Request.new oauth: self
-    def visits = Visits.new oauth: self
-
-    # Run a statement, refreshing a stale token. Nothing here ever sleeps: where Jobber holds
-    # the app to a limit it says so, and a caller asking from a background job has a queue that
-    # will bring the whole job back later — which is worth more than a worker asleep holding a
-    # transaction open.
-    # @return [Hash] the data Jobber answered, or empty when the credentials are dead.
-    def query(statement, variables: {})
-      client.query statement, variables: variables
-    rescue GraphQL::Unauthorized
-      refresh ? retry : {}
-    rescue GraphQL::Throttled => error
-      raise Retriable.new(error.message, error.cost)
-    rescue GraphQL::Error => error
-      # The transport's own class never leaves the gem: a caller told to rescue `Jbr::Error`
-      # was not catching a throttle, a 500 or an unreadable answer, and had its own job blow
-      # up instead of hearing that Jobber would not answer.
-      raise Error, error.message
-    end
-
-    # Delete a token. If the token is invalid, do nothing.
-    def delete
-      client.query DISCONNECT_MUTATION
-    rescue GraphQL::Unauthorized => e
-    end
-
-    # Exchange an authorization code for credentials, then learn their account.
-    # @param code [String] the code Jobber sent to the redirect URI.
-    # @param redirect_uri [String] the URI the code came back to.
-    # @return [OAuth] the new credentials.
-    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
-
-    # @return [String, nil] The client ID to interact with the API.
-    def self.client_id = ENV['JOBBER_CLIENT_ID']
-
-    # @return [String, nil] The client secret to interact with the API.
-    def self.client_secret = ENV['JOBBER_CLIENT_SECRET']
-
-    # Exchange a code or a refresh token for credentials.
-    def self.post(params = {})
-      Token.post params.merge(client_id: client_id, client_secret: client_secret)
-    end
-
-  private
-
-    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' }
-  end
-end

data/lib/jbr/properted.rb

@@ -1,17 +0,0 @@
-module Jbr
-  # Extends a record that stands at a property: a visit, a job, anything Jobber files
-  # somewhere.
-  module Properted
-    # What to ask for where a record names the place the work happens at.
-    # @param client [Boolean] whether the place's own client comes back with it, which spares
-    #   a second query for somebody Jobber already knows the place belongs to.
-    def self.selection(client: false)
-      [ 'property { id address {', Property::SELECTION, '}',
-        (Cliental::SELECTION if client), '}',
-      ].compact.join ' '
-    end
-
-    # @return [Property] where the work happens, and who Jobber holds the place for.
-    def property = Property.new node: @node.fetch('property', {})
-  end
-end

data/lib/jbr/property.rb

@@ -1,93 +0,0 @@
-module Jbr
-  # Where the work happens: one address on a client's file.
-  class Property < Resource
-    include Cliental
-
-    # The mutation that adds a property to a client already on file.
-    CREATE = <<~GRAPHQL
-      mutation propertyCreateMutation($clientId: EncodedId!, $input: PropertyCreateInput!) {
-        propertyCreate(clientId: $clientId, input: $input) {
-          properties { id }
-          userErrors { message }
-        }
-      }
-    GRAPHQL
-
-    # What Jobber calls each address field, against what a caller passes.
-    FIELDS = { street1: :street, city: :city, province: :state, postalCode: :zip }
-
-    # The two Jobber tucks inside the address and a property carries beside the street.
-    COORDINATES = %i[latitude longitude]
-
-    # The address as Jobber answers it, asked for wherever a property is read.
-    SELECTION = "#{FIELDS.keys.join ' '} coordinates { #{COORDINATES.join ' '} }"
-
-    # Where the place is, in the fields a caller passes to open one.
-    # @return [Hash] any of :street, :city, :state, :zip, :latitude and :longitude.
-    def address = Property.fields_from @node['address']
-
-    # @return [String, nil] the street the work happens on.
-    def street = address[:street]
-
-    # @return [String, nil] the town the work happens in.
-    def city = address[:city]
-
-    # @return [String, nil] the postal code the work happens in.
-    def zip = address[:zip]
-
-    # @return [Float, nil] how far north the work happens.
-    def latitude = address[:latitude]
-
-    # @return [Float, nil] how far east the work happens.
-    def longitude = address[:longitude]
-
-    # The fields a match is made on. City and state are written but never matched:
-    # Jobber holds whatever was typed, so "NC" and "North Carolina" -- or "Winston Salem"
-    # and "Winston-Salem" -- would read as two homes. The ZIP already places the home.
-    MATCHED = %i[street1 postalCode]
-
-    # The address as Jobber takes it, from the fields a caller passes.
-    # @param fields [Hash] any of :street, :city, :state and :zip.
-    # @return [Hash] the address, without the fields the caller left out.
-    def self.address_from(fields = {})
-      FIELDS.to_h { |jobber, ours| [ jobber, fields[ours] ] }.compact_blank
-    end
-
-    # The fields a caller reads, from the address as Jobber holds it.
-    # @param address [Hash, nil] the address Jobber answered, if it answered one.
-    # @return [Hash] any of :street, :city, :state, :zip, :latitude and :longitude,
-    #   without the ones Jobber left out.
-    def self.fields_from(address)
-      address ||= {}
-      coordinates = address['coordinates'] || {}
-      FIELDS.to_h { |jobber, ours| [ ours, address[jobber.to_s] ] }.
-        merge(COORDINATES.to_h { |ours| [ ours, coordinates[ours.to_s] ] }).compact_blank
-    end
-
-    # Reach the property at an address, adding one when none of the client's matches.
-    # @param client_id [String] the client the property belongs to.
-    # @param address [Hash] the fields the work happens at.
-    # @param existing [Array<Hash>] the properties already on the client's file.
-    # @return [String, nil] the property ID.
-    def find_or_create_for(client_id:, address:, existing: [])
-      wanted = self.class.address_from address
-      match = existing.find { |property| same_address? wanted, property['address'] }
-      return match['id'] if match
-
-      output = @oauth.query CREATE, variables: {
-        clientId: client_id, input: { properties: [ { address: wanted } ] },
-      }
-      (output&.dig('propertyCreate', 'properties')&.first || {})['id']
-    end
-
-  private
-
-    # Field by field, because Jobber answers every field it was asked for, nil included,
-    # while a caller's address carries only what they had -- an absent field and a nil
-    # one are the same address. All of {MATCHED} has to agree: a home with no street
-    # parsed must not match the one house on the client's file that does have one.
-    def same_address?(wanted, address)
-      MATCHED.all? { |field| wanted[field] == (address || {})[field.to_s] }
-    end
-  end
-end

data/lib/jbr/quote.rb

@@ -1,25 +0,0 @@
-module Jbr
-  # A price a Jobber user sent to their client.
-  class Quote < Resource
-    # The query that reads one quote and the request it came from.
-    FIND = <<~GRAPHQL
-      query($id: EncodedId!) {
-        quote(id: $id) { id request { id } }
-      }
-    GRAPHQL
-
-    # @return [String, nil] the ID of the request the quote answers.
-    attr_reader :request_id
-
-    # @param id [String] the Jobber ID of the quote.
-    # @return [Quote, nil] itself, or nil when Jobber has no such quote.
-    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