jbr 3.13.0 → 5.0.0

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,16 +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 id = @node[:id]
-
-    def quantity = whole @node[:quantity]
-
-    def name = @node[:name]
-
-    def description = @node[:description]
-
-    def amount = @node[:amount]
-  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

data/lib/jbr/request.rb

@@ -1,37 +0,0 @@
-module Jbr
-  # A lead on a Jobber user's board: work someone asked them for.
-  class Request < Resource
-    # The mutation that opens a request against a client and a property.
-    CREATE = <<~GRAPHQL
-      mutation($input: RequestCreateInput!) {
-        requestCreate(input: $input) { request { id property { id } } userErrors { message } }
-      }
-    GRAPHQL
-
-    # @return [String, nil] the client the request was opened against.
-    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 = @oauth.clients.create_with(params).find_or_create_by(phone: params[:phone])
-      @client_id = client.id
-      @property_id = client.property_id
-
-      input = {
-        clientId: @client_id, title: params[:title], propertyId: @property_id,
-        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

@@ -1,26 +0,0 @@
-module Jbr
-  # What every Jobber resource shares: the node Jobber answered with, the credentials it was
-  # read through, and what a list of them was asked and narrowed to.
-  class Resource
-    # @param oauth [OAuth] the credentials to reach Jobber with, where reaching it is needed.
-    # @param node [Hash] the record as Jobber answered it.
-    # @param includes [Hash] what a list was asked to bring back beside its records.
-    # @param filter [Hash] what a list was narrowed to, in the shape Jobber filters by.
-    def initialize(oauth: nil, node: {}, includes: {}, filter: nil)
-      @oauth = oauth
-      @node = node
-      @id = node['id']
-      @includes = includes
-      @filter = filter
-    end
-
-    # @return [String, nil] the Jobber ID, from the node it came in or once one was created.
-    attr_reader :id
-
-  private
-
-    # @return [Time, nil] what Jobber answered under a key, as a time. An empty answer is no
-    #   answer: Time.iso8601 raises on one, where nothing at all it simply has none of.
-    def time(key) = (Time.iso8601 @node[key] if @node[key].present?)
-  end
-end

data/lib/jbr/retriable.rb

@@ -1,20 +0,0 @@
-module Jbr
-  # Jobber refusing a query over what it costs rather than over anything about the query. The
-  # bucket it is priced against refills, so the same question asked later is answered.
-  class Retriable < Error
-    # @param message [String] what Jobber said, with the numbers it said it with.
-    # @param cost [Hash] the `requestedQueryCost` and the `throttleStatus` beside it.
-    def initialize(message, cost = {})
-      super message
-      status = cost['throttleStatus'].to_h
-      @cost = cost['requestedQueryCost']
-      @available = status['currentlyAvailable']
-      @maximum = status['maximumAvailable']
-      @restore_rate = status['restoreRate']
-    end
-
-    # What the query would have cost, the budget it was priced against, and how fast that
-    # budget refills. A cost above the maximum is one no waiting will pay for.
-    attr_reader :cost, :available, :maximum, :restore_rate
-  end
-end

data/lib/jbr/url.rb

@@ -1,16 +0,0 @@
-module Jbr
-  # The page a Jobber user authorizes the app on.
-  class URL
-    # @param params [Hash] the +redirect_uri+ and +state+ to come back with.
-    # @return [String] the URL to send the user to.
-    def self.for(params = {})
-      uri = URI 'https://api.getjobber.com/api/oauth/authorize'
-      uri.query = URI.encode_www_form params.merge(response_type: 'code', client_id: client_id)
-      uri.to_s
-    end
-
-    # @return [String, nil] the client ID of the app being authorized.
-    def self.client_id = ENV['JOBBER_CLIENT_ID']
-    private_class_method :client_id
-  end
-end

data/lib/jbr/visit.rb

@@ -1,24 +0,0 @@
-module Jbr
-  # One stop at a property: when the work on a job is scheduled to happen.
-  class Visit < Resource
-    include Cliental, Named, Properted
-
-    # @return [String, nil] what the visit is called.
-    def title = @node['title']
-
-    # @return [String, nil] the ID of the job the visit belongs to.
-    def job_id = @node.dig 'job', 'id'
-
-    # @return [Boolean, nil] whether the visit takes the whole day rather than an hour of it.
-    def all_day? = @node['allDay']
-
-    # @return [Boolean, nil] whether the client has confirmed the visit.
-    def client_confirmed? = @node['clientConfirmed']
-
-    # @return [Time, nil] the visit start time
-    def starts_at = time 'startAt'
-
-    # @return [Time, nil] the visit end time
-    def ends_at = time 'endAt'
-  end
-end

data/lib/jbr/visits.rb

@@ -1,36 +0,0 @@
-module Jbr
-  # The visits on a Jobber account, oldest first, walked a page at a time.
-  class Visits < Resource
-    include Includable, Listable
-
-    # What a visit answers with, before anything it was asked to bring back with it.
-    FIELDS = 'id title startAt endAt allDay clientConfirmed job { id }'
-
-    # Shadows Enumerable#find on purpose, the way jobs do: a visit is reached by the ID Jobber
-    # files it under, not by asking every visit on the account whether it is the one.
-    # @param id [String] the Jobber ID of the visit.
-    # @return [Visit, nil] nil when Jobber has no visit under that ID.
-    def find(id)
-      node = @oauth.query(one, variables: { id: id })['visit']
-      Visit.new node: node if node
-    end
-
-  private
-
-    def page = paged "#{FIELDS} #{selections}", PAGE
-
-    def one
-      <<~GRAPHQL
-        query($id: EncodedId!) {
-          visit(id: $id) { #{FIELDS} #{selections} }
-        }
-      GRAPHQL
-    end
-
-    def field = 'visits'
-
-    def filtered = 'VisitFilterAttributes'
-
-    def item(node) = Visit.new node: node
-  end
-end