gohighlevel

# Gemfile
gem "gohighlevel"

require "gohighlevel"

client = HighLevel::Client.new(private_integration_token: "pit-xxxxxxxx")

# Every app is a resource on the client.
contacts = client.contacts.search_contacts_advanced(
  body: { locationId: "loc-123", pageLimit: 20 }
)

tasks = client.contacts.get_all_tasks(contact_id: "contact-456")

# 1. Private Integration Token — simplest, always wins when present.
HighLevel::Client.new(private_integration_token: "pit-xxxx")

# 2. Agency access token.
HighLevel::Client.new(agency_access_token: "agency-xxxx")

# 3. Location access token.
HighLevel::Client.new(location_access_token: "loc-xxxx")

# 4. OAuth app credentials — required for the OAuth flows + 401 refresh.
HighLevel::Client.new(client_id: "xxxx", client_secret: "xxxx")

config = HighLevel::Configuration.new(
  private_integration_token: "pit-xxxx",
  api_version: "2021-07-28",
  session_storage: HighLevel::Storage::Memory.new,
  instrumenter: ActiveSupport::Notifications
)
HighLevel::Client.new(config)

client = HighLevel::Client.new(
  client_id: "xxxx",
  client_secret: "xxxx",
  redirect_uri: "https://your.app/oauth/callback"
)

# 1. Send the user here to authorize.
url = client.oauth.authorization_url(scope: "contacts.readonly contacts.write")

# 2. Exchange the code that comes back on your callback.
tokens = client.oauth.exchange_code(code: params[:code], user_type: "Location")

# 3. Refresh later.
tokens = client.oauth.refresh_token(refresh_token: stored_refresh, user_type: "Location")

# 4. Derive a location token from an agency token.
tokens = client.oauth.get_location_access_token(company_id: "co-1", location_id: "loc-1")

# Redis
store = HighLevel::Storage::Redis.new(url: "redis://localhost:6379/0")
HighLevel::Client.new(client_id: "x", client_secret: "y", session_storage: store)

# ActiveRecord — once, in a migration:
HighLevel::Storage::ActiveRecord::Migration.create_table!(connection)
store = HighLevel::Storage::ActiveRecord.new

# Sinatra
post "/webhooks/highlevel" do
  body = request.body.read
  HighLevel::Webhooks.verify(
    payload: body,
    signature: request.env["HTTP_X_WH_SIGNATURE"],
    public_key: ENV.fetch("HIGHLEVEL_WEBHOOK_PUBLIC_KEY"),
    scheme: :rsa
  )
  # raises HighLevel::Webhooks::InvalidSignatureError if it doesn't verify
  process(JSON.parse(body))
  status 200
rescue HighLevel::Webhooks::InvalidSignatureError
  halt 401
end

# Rails controller
def highlevel
  HighLevel::Webhooks.verify(
    payload: request.raw_post,
    signature: request.headers["X-Wh-Signature"],
    public_key: Rails.application.credentials.highlevel_webhook_public_key
  )
  ProcessWebhookJob.perform_later(request.raw_post)
  head :ok
rescue HighLevel::Webhooks::InvalidSignatureError
  head :unauthorized
end

# A proc that routes pagination params wherever the endpoint wants them.
fetch = ->(**page) do
  client.contacts.search_contacts_advanced(body: { locationId: "loc-1" }.merge(page))
end

# Each page (raw response):
HighLevel::Pagination.each_page(fetch, cursor_field: :skip, items_field: "contacts") do |page|
  puts page["contacts"].size
end

# Each item, flattened across pages:
HighLevel::Pagination.each_item(fetch, cursor_field: :skip, items_field: "contacts") do |contact|
  puts contact["id"]
end

# Without a block, you get an Enumerator:
enum = HighLevel::Pagination.each_item(fetch, cursor_field: :skip, items_field: "contacts")
enum.lazy.select { |c| c["type"] == "lead" }.first(10)

begin
  client.contacts.get_all_tasks(contact_id: "missing")
rescue HighLevel::NotFoundError => e
  e.status        # => 404
  e.response_body # => parsed JSON body
  e.request_id    # => the x-request-id header, if present
end

client = HighLevel::Client.new(
  private_integration_token: "pit-xxxx",
  instrumenter: ActiveSupport::Notifications
)

ActiveSupport::Notifications.subscribe("request.high_level") do |*, payload|
  Rails.logger.info("HighLevel #{payload[:method].upcase} #{payload[:url]} → #{payload[:status]}")
end