npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@xapp/stentor-service-gohighlevel

v1.1.2

Published

GoHighLevel (HighLevel / LeadConnector) CRM client: upserts leads as contacts with tags and notes, books appointments and reads calendar availability

Readme

@xapp/stentor-service-gohighlevel

Client for GoHighLevel (HighLevel, also white-labelled as LeadConnector), API v2. It pushes each captured lead into one sub-account (a "location") as a contact, adds tags and a note with the conversation, and books a requested time on a calendar. It also reads calendar availability and lists calendars so Studio can offer them as a dropdown. Implements stentor-models' CrmService.

Usage

import { GoHighLevelService } from "@xapp/stentor-service-gohighlevel";

const ghl = new GoHighLevelService({
    authenticate: () => Promise.resolve("<Private Integration Token or OAuth location token>"),
    locationId: "<sub-account id>",
    calendarId: "<optional calendar id>",
    timezone: "America/Chicago",
    tags: ["xapp ai lead"] // the default; [] adds none
});

await ghl.testConnection();          // throws GoHighLevelError kind "auth" on a bad token
const calendars = await ghl.listCalendars();

const result = await ghl.sendLead(externalLead);
// { contactId, created, noteId?, appointmentId?, partial?, errors? }

Auth is a callback, so the same service works with a Private Integration Token (Settings → Private Integrations in the sub-account) or an OAuth location access token from a Marketplace app. Required scopes: contacts.write, locations.readonly, plus calendars.readonly and calendars/events.write to read availability and book appointments.

Behaviour worth knowing

  • Dedupe is HighLevel's. POST /contacts/upsert matches an existing contact by the sub-account's Allow Duplicate Contact setting (email and/or phone, in its configured priority).
  • Tags are added, never set. Upsert replaces every tag on a matched contact, which would wipe the tags the business's own workflows run on. So the upsert never carries tags; they go through POST /contacts/{id}/tags, which adds. Businesses typically start their follow-up from a Contact Tag workflow trigger on these tags.
  • Booking. When the lead has a DATETIME, a calendarId is configured and the lead is complete, an appointment is created. DATETIME is the business's local wall clock (a trailing Z is ignored) and is sent with the business's UTC offset. HighLevel takes the end time from the calendar's slot length.
  • Incomplete leads follow the partial/abandoned lead standard in packages/services/README.md: skipped without a name plus an email or phone, labelled [Partial …] in the note, and never booked.
  • No retries. Notes and appointments have no idempotency key. If the contact lands but a later step fails, sendLead returns what it created with partial: true, and send still reports Success.
  • Availability comes from GET /calendars/{id}/free-slots, in 30-day requests (HighLevel caps a request at 31 days). A date with no free slot is reported unavailable. With no calendar, or on any error, it fails open (full availability).
  • Errors are GoHighLevelError with kind decided by HTTP status alone: auth (401/403), rate_limit (429), http, network, or config (a tenant-supplied id failed validation and no request was made). The token never appears in a message.
  • Versions. HighLevel requires a Version header per API family: 2021-07-28 for contacts and locations, 2021-04-15 for calendars, as pinned by the published OpenAPI specs.

Functional Test

yarn test:f runs against a live sub-account and is skipped unless GHL_TOKEN and GHL_LOCATION_ID are set (GHL_CALENDAR_ID is optional). It only reads; it never creates a contact, because that would fire the sub-account's own workflows.

Documentation