hcp 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c1c564302b41ae3bae64611780cd75bd3547bb4b85b96e4820a868c913a1769
-  data.tar.gz: 55ea615bb079c1618cf9112d8a44673df5f143058a270453fbe519ae5ed873cb
+  metadata.gz: 2c507e653633d17395829ab18ff34b44313aa37c8e19286aecad3096adae8848
+  data.tar.gz: 3677c714fefd88238ff2ebee783f2d6ba6141bf6a2aa37d994a43b7cd0b292e5
 SHA512:
-  metadata.gz: 2f61c290fa12ea7acaeccc160eeeebc59a9cfb806111ab6b6a8310d8b73b678d232ab5028e86fbb85e0475b4dc0ad34b2c190f8a1845ecfdf323fb7b8dba91f9
-  data.tar.gz: 33a705767166474ecf31a1710d51a837332f554db980fef6e9ce5fad6c30ee54cafecac849a6e4e376323a77f701d9d185ebdb6ba9328bc278dad42a388d1f71
+  metadata.gz: 34f585b624bec1d61839a69a6c2678bad38e8b24bd02605e5fb47aa11fc5fdff5c31cd8e2aab802daa75f943a72cf9c7f39ac97fafa5d15dd52b0efb52ef42d6
+  data.tar.gz: a498b1a75b5f8170837a99661c265800eccaec5d3384c626f5bbbd086373488afbc063172876e04c15abb7c520418aa51e7c6fb3ef2c5ac28d580bcc1795304c

data/CHANGELOG.md

@@ -1,5 +1,7 @@
-## [Unreleased]
+## [1.1.0] - 2026-05-27
 
-## [0.1.0] - 2026-03-24
+- [New] Add Hcp::Event
 
-- Initial release
+## [1.0.0] - 2026-05-15
+
+- Initial release: Lead and Lead::Pipeline classes

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2026 claudiob
+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

data/README.md

@@ -1,39 +1,20 @@
-# Hcp
+# The Housecall Pro API Ruby client
 
-TODO: Delete this and the text below, and describe your gem
+## Available methods
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/hcp`. To experiment with that code, run `bin/console` for an interactive prompt.
+Initialize and create a Lead:
 
-## Installation
+```ruby
+lead = Hcp::Lead.new key:, company_id:
+lead.create name: 'Alice', phone: '8008008000', email: 'alice@example.com',
+  address: { street: '7111 Melrose Ave', city: 'Los Angeles', state: 'CA', zip: '90046' },
+  note: 'Very interested in buying', source: 'The Lead Generator'
+````
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Change the status of a lead in the pipeline:
 
-Install the gem and add to the application's Gemfile by executing:
-
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
-```
-
-If bundler is not being used to manage dependencies, install the gem by executing:
-
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+pipeline = Hcp::Lead::Pipeline.new id:, key:, company_id:
+pipeline.update status_name: 'Won'
 ```
 
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hcp.
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/hcp/error.rb

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

data/lib/hcp/event.rb

@@ -0,0 +1,58 @@
+module Hcp
+  class Event
+    # @see https://docs.housecallpro.com/docs/housecall-public-api/46e9e1be07621-webhooks
+    SIGNATURE_HEADER = 'Api-Signature'
+
+    # @see https://docs.housecallpro.com/docs/housecall-public-api/46e9e1be07621-webhooks
+    TIMESTAMP_HEADER = 'Api-Timestamp'
+
+    # @param params [Hash] the payload for an event webhook.
+    def initialize(params = {})
+      @params = params
+    end
+
+    # @return [Symbol] the type of event, e.g.: :lead_converted, :job_created, :invoice_sent.
+    def type = @params[:event].gsub('.', '_').to_sym
+
+    # @return [String] unique identifier of the lead in a :lead_converted event.
+    def lead_id = @params.dig :lead, :id
+
+    # @return [String] unique identifier of the customer in a :lead_converted or :job_created event.
+    def customer_id = @params.dig resource_type, :customer, :id
+
+    # @return [String] unique identifier of the job in a :job_created/scheduled/completed event.
+    def job_id = @params.dig :job, :id
+
+    # @return [String] unique identifier of the estimate in a :job_created event.
+    def estimate_id = @params.dig :job, :original_estimate_id
+
+    # @return [Symbol] the latest conversion type, can be :estimate or :job.
+    def conversion_type = conversion['type'].downcase.to_sym
+
+    # @return [String] the latest conversion ID, can be an estimate ID or a job ID.
+    def conversion_id = conversion['id']
+
+    # @return [Time] time when the job is scheduled a :job_scheduled event.
+    def scheduled_at = Time.iso8601(@params.dig :job, :schedule, :scheduled_start)
+
+    # @return [Time] time when the job was completed a :job_completed event.
+    def completed_at = Time.iso8601(@params.dig :job, :work_timestamps, :completed_at)
+
+    # @return [String] unique identifier of the invoice in an :invoice_sent event.
+    def invoice_id = @params.dig :invoice, :id
+
+    # @return [String] unique identifier of the job in an :invoice_sent event.
+    def invoice_job_id = @params.dig :invoice, :job_id
+
+    # @return [BigDecimal] dollar amount of the invoice in an :invoice_sent event.
+    def invoice_amount = BigDecimal(@params.dig :invoice, :amount) / 100.0
+
+  private
+
+    # @return [Hash] the latest conversion, applies to 'lead.converted' events.
+    def conversion = @params.dig(:lead, :conversions).last
+
+    # @return [Symbol] the type of resource affected by the event, can be :lead or :job.
+    def resource_type = @params[:event].split('.').first.to_sym
+  end
+end

data/lib/hcp/lead/pipeline.rb

@@ -0,0 +1,32 @@
+module Hcp
+  class Lead::Pipeline < Resource
+    def initialize(id: nil, key:, company_id:)
+      @id = id
+      @key = key
+      @company_id = company_id
+    end
+
+    def update(status_name:)
+      status = find_status_by name: status_name
+      raise Error, "Status #{status_name} not found for lead #{@id}" unless status
+
+      payload = { resource_type: 'lead', resource_id: @id, status_id: status['id'] }.to_json
+      Net::HTTP.put uri, payload, headers
+    rescue Errno::ECONNREFUSED => error
+      raise Error, error
+    end
+
+  private
+
+    def find_status_by(name:)
+      body = JSON Net::HTTP.get(uri, headers)
+      body['statuses'].find { |status| status['name'] == name } || unknown_status(name: name)
+    end
+
+    def unknown_status(name:)
+      raise Error, "Status #{name} not found for lead #{@id}"
+    end
+
+    def uri = URI 'https://api.housecallpro.com/pipeline/statuses?resource_type=lead'
+  end
+end

data/lib/hcp/lead.rb

@@ -0,0 +1,35 @@
+module Hcp
+  class Lead < Resource
+    attr_reader :customer_id
+
+    def initialize(id: nil, customer_id: nil, key:, company_id:)
+      @id = id
+      @key = key
+      @company_id = company_id
+      @customer_id = customer_id
+    end
+
+    def create(params = {})
+      body = JSON Net::HTTP.post(uri, lead_for(params).to_json, headers).body
+      @id, @customer_id = body['id'], body.dig('customer', 'id')
+    rescue Errno::ECONNREFUSED => error
+      raise Error, error
+    end
+
+    def lead_for(params = {})
+      {
+        customer: customer_for(params), address: params[:address],
+        lead_source: params[:source], note: params[:note]
+      }.compact_blank
+    end
+
+    def customer_for(params = {})
+      {
+        first_name: params[:name], email: params[:email],
+        mobile_number: params[:phone], lead_source: params[:source],
+      }.compact_blank
+    end
+
+    def uri = URI 'https://api.housecallpro.com/leads'
+  end
+end

data/lib/hcp/resource.rb

@@ -0,0 +1,15 @@
+module Hcp
+  class Resource
+    attr_reader :id
+
+  private
+
+    def headers
+      {
+        'Authorization' => "Token #{@key}",
+        'Content-Type' => 'application/json',
+        'X-Company-Id' => @company_id,
+      }.compact
+    end
+  end
+end

data/lib/hcp/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Ruby client for the Housecall Pro API.
 module Hcp
-  VERSION = "0.1.0"
+  # Current version of the gem.
+  VERSION = '1.1.0'
 end

data/lib/hcp.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "hcp/version"
+require 'json'
+require 'net/http'
 
-module Hcp
-  class Error < StandardError; end
-  # Your code goes here...
-end
+require 'hcp/error'
+require 'hcp/resource'
+require 'hcp/lead'
+require 'hcp/lead/pipeline'
+
+require 'hcp/event'

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: hcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
-- claudiob
+- Claudio Baccigalupo
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Housecall Pro API
 email:
 - claudiob@users.noreply.github.com
@@ -19,17 +33,20 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/hcp.rb
+- lib/hcp/error.rb
+- lib/hcp/event.rb
+- lib/hcp/lead.rb
+- lib/hcp/lead/pipeline.rb
+- lib/hcp/resource.rb
 - lib/hcp/version.rb
-- sig/hcp.rbs
-homepage: https://github.com/HouseAccountEng/hcp
+homepage: https://github.com/claudiob/hcp
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/HouseAccountEng/hcp
-  source_code_uri: https://github.com/HouseAccountEng/hcp
-  changelog_uri: https://github.com/HouseAccountEng/hcp
+  homepage_uri: https://github.com/claudiob/hcp
+  source_code_uri: https://github.com/claudiob/hcp
+  changelog_uri: https://github.com/claudiob/hcp
 rdoc_options: []
 require_paths:
 - lib

data/Rakefile

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec

data/sig/hcp.rbs

@@ -1,4 +0,0 @@
-module Hcp
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end