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 🙏

© 2024 – Pkg Stats / Ryan Hefner

@hubspot/api-client

v12.0.1

Published

NodeJS v3 [HubSpot API](https://developers.hubspot.com/docs/api/overview) SDK(Client) files

Downloads

1,537,922

Readme

hubspot-api-nodejs

NodeJS v3 HubSpot API SDK(Client) files

Sample apps

Please, take a look at our Sample apps

Available SDK methods reference

Available SDK methods reference

Installing

npm install @hubspot/api-client

Instantiate client

const hubspot = require('@hubspot/api-client')
const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN })

[!NOTE] Please note that all code examples are written in JavaScript. Some of them won’t work in Typescript without changes.

For ES modules

import { Client } from "@hubspot/api-client";
const hubspotClient = new Client({ accessToken: YOUR_ACCESS_TOKEN });

You'll need to create a private app to get your access token or you can obtain OAuth2 access token.

You can provide developer API key. There is no need to create separate client instances for using endpoints with API key and Developer API key support.

const hubspotClient = new hubspot.Client({ developerApiKey: YOUR_DEVELOPER_API_KEY })
const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN, developerApiKey: YOUR_DEVELOPER_API_KEY })

To change the base path:

const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN, basePath: 'https://some-url' })

To add custom headers to all request:

const hubspotClient = new hubspot.Client({
    accessToken: YOUR_ACCESS_TOKEN,
    defaultHeaders: { 'My-header': 'test-example' },
})

If you're an app developer, you can also instantiate a client and obtain a new accessToken with your app details and a refresh_token:

hubspotClient.oauth.tokensApi
    .create('refresh_token', undefined, undefined, YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REFRESH_TOKEN)
    .then((results) => {
        console.log(results)

        // this assigns the accessToken to the client, so your client is ready
        // to use
        hubspotClient.setAccessToken(results.accessToken)

        return hubspotClient.crm.companies.basicApi.getPage()
    })

Rate limiting

Bottleneck is used for rate limiting. To turn on/off rate limiting use limiterOptions option on Client instance creation. Bottleneck options can be found here. Please note that Apps using OAuth are only subject to a limit of 100 requests every 10 seconds. Limits related to the API Add-on don't apply.

const hubspotClient = new hubspot.Client({
    accessToken: YOUR_ACCESS_TOKEN,
    limiterOptions: DEFAULT_LIMITER_OPTIONS,
})

Default settings for the limiter are:

const DEFAULT_LIMITER_OPTIONS = {
    minTime: 1000 / 9,
    maxConcurrent: 6,
    id: 'hubspot-client-limiter',
}

Search settings for the limiter are:

const SEARCH_LIMITER_OPTIONS = {
    minTime: 550,
    maxConcurrent: 3,
    id: 'search-hubspot-client-limiter',
}

Retry mechanism

It's possible to turn on retry for failed requests with statuses 429 or 5xx. To turn on/off configurable retries use numberOfApiCallRetries option on Client instance creation. numberOfApiCallRetries can be set to a number from 0 - 6. If numberOfApiCallRetries is set to a number greater than 0 it means that if any API Call receives ISE5xx this call will be retried after a delay 200 * retryNumber ms and if 429 (Rate limit is exceeded) is returned for "TEN_SECONDLY_ROLLING" the call will be retried after a delay 10 sec. Number of retries will not exceed numberOfApiCallRetries value.

const hubspotClient = new hubspot.Client({
    accessToken: YOUR_ACCESS_TOKEN,
    numberOfApiCallRetries: 3,
})

Usage

All methods return a promise. The success includes the serialized to JSON body and response objects. Use the API method via:

hubspotClient.crm.contacts.basicApi
    .getPage(limit, after, properties, propertiesWithHistory, associations, archived)
    .then((results) => {
        console.log(results)
    })
    .catch((err) => {
        console.error(err)
    })

{EXAMPLE} Create Contact, Company and associate created objects

const contactObj = {
    properties: {
        firstname: yourValue,
        lastname: yourValue,
    },
}
const companyObj = {
    properties: {
        domain: yourValue,
        name: yourValue,
    },
}

const createContactResponse = await hubspotClient.crm.contacts.basicApi.create(contactObj)
const createCompanyResponse = await hubspotClient.crm.companies.basicApi.create(companyObj)
await hubspotClient.crm.associations.v4.basicApi.create(
    'companies',
    createCompanyResponse.id,
    'contacts',
    createContactResponse.id,
    [
        {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": AssociationTypes.companyToContact
              // AssociationTypes contains the most popular HubSpot defined association types
        }
    ]
)

{EXAMPLE} Get associated Companies by Contact

const companies = await hubspotClient.crm.associations.v4.basicApi.getPage(
    'contact',
    hubspotContactId,
    'company',
    after,
    pageSize,
  );

{EXAMPLE} Update multiple objects in batch mode

const dealObj = {
    id: yourId,
    properties: {
        amount: yourValue,
    },
}

const dealObj2 = {
    id: yourId,
    properties: {
        amount: yourValue,
    },
}

await hubspotClient.crm.deals.batchApi.update({ inputs: [dealObj, dealObj2] })

{EXAMPLE} Import Contacts

const fs = require('fs')

const fileName = 'test.csv'

const file = {
    data: fs.createReadStream(fileName),
    name: fileName,
};

const importRequest = {
    name: 'import(' + fileName + ')',
    files: [
        {
            fileName: fileName,
            fileImportPage: {
                hasHeader: true,
                columnMappings: [
                    {
                        columnName: 'First Name',
                        propertyName: 'firstname',
                        columnObjectType: 'CONTACT',
                    },
                    {
                        columnName: 'Email',
                        propertyName: 'email',
                        columnObjectType: 'CONTACT',
                    },
                ],
            },
        },
    ],
}

const response = await  hubspotClient.crm.imports.coreApi.create(file, JSON.stringify(importRequest));

console.log(response)

{EXAMPLE} Search Contacts

Only 3 FilterGroups with max 3 Filters are supported.

Despite sorts is an array, however, currently, only one sort parameter is supported.

In JS sorts it's possible to set as:

  1. < propertyName > - returned results will be sorted by provided property name in 'ASCENDING' order. e.g: `'hs_object_id'``
  2. < direction > - returned results will be sorted by provided property name and sort direction. e.g: { propertyName: 'hs_object_id', direction: 'ASCENDING' } or { propertyName: 'hs_object_id', direction: 'DESCENDING' }

In TS sorts it's possible to set as:

  1. < propertyName > - returned results will be sorted by provided property name in 'ASCENDING' order. e.g: ['hs_object_id']
  2. < direction > - use ["-createdate"] to sort in desc and sorts: ["createdate"] in asc order.

after for initial search should be set as 0

Example for JS:

const publicObjectSearchRequest = {
    filterGroups: [
    {
        filters: [
        {
            propertyName: 'createdate',
            operator: 'GTE',
            value: `${Date.now() - 30 * 60000}`
        }
        ]
    }
    ],
    sorts: [{ propertyName: 'createdate', direction: 'DESCENDING' }],
    properties: ['createdate', 'firstname', 'lastname'],
    limit: 100,
    after: 0,
}

const response = await hubspotClient.crm.contacts.searchApi.doSearch(publicObjectSearchRequest)

console.log(response)

Example for TS:

const objectSearchRequest: PublicObjectSearchRequest = {
    filterGroups: [
        {
            filters: [
                {
                propertyName: "createdate",
                operator: "GTE",
                value: "1615709177000",
                },
            ],
        },
    ],
    sorts: ["-createdate"],
    properties: ["email", "createdate"],
    limit: 100,
    after: '0',
};

const response = await hubspotClient.crm.contacts.searchApi.doSearch(objectSearchRequest);

console.log(response)

Get all

getAll method is available for all major objects (Companies, Contacts, Deals, LineItems, Products, Quotes & Tickets) and works like

const allContacts = await hubspotClient.crm.contacts.getAll()

[!NOTE] Please note that pagination is used under the hood to get all results.

Upload a file (via the SDK)

const response = await hubspotClient.files.filesApi.upload(
    {
        data: fs.createReadStream('./photo.jpg'),
        name: 'photo.jpg'
    },
    undefined,
    '/folder',
    'photo.jpg',
    undefined,
    JSON.stringify({
        access: 'PRIVATE',
        overwrite: false,
        duplicateValidationStrategy: 'NONE',
        duplicateValidationScope: 'ENTIRE_PORTAL',
    })
)

console.log(response)

OAuth

Obtain your authorization url

const clientId = 'your_client_id'
const redirectUri = 'take_me_to_the_ballpark'
const scope = 'some scopes'
const uri = hubspotClient.oauth.getAuthorizationUrl(clientId, redirectUri, scope)

Obtain an access token from an authorization_code

return hubspotClient.oauth.tokensApi.create(
        'authorization_code',
        code, // the code you received from the oauth flow
        YOUR_REDIRECT_URI,
        YOUR_CLIENT_ID,
        YOUR_CLIENT_SECRET,
    ).then(...)

CMS

Get audit logs

const response = await hubspotClient.cms.auditLogs.auditLogsApi.getPage()

Not wrapped endpoint(s)

It is possible to access the hubspot request method directly, it could be handy if client doesn't have implementation for some endpoint yet. Exposed request method benefits by having all configured client params.

hubspotClient.apiRequest({
    method: 'PUT',
    path: '/some/api/not/wrapped/yet',
    body: { key: 'value' },
})

Get contacts

const response = await hubspotClient.apiRequest({
    path: '/crm/v3/objects/contacts',
})
const json = await response.json()
console.log(json)

Upload a file

const formData = new FormData();
const options = {
// some options
};
formData.append("folderPath", '/');
formData.append("options", JSON.stringify(options));
formData.append("file", fs.createReadStream('file path'));

const response = await hubspotClient.apiRequest({
    method: 'POST',
    path: '/filemanager/api/v3/files/upload',
    body: formData,
    defaultJson: false
});

console.log(response);

Reserved words

The SDK has reserved words(e.g. from, in). Full list of reserved words. When you face with a reserved word you have to add _ before the word(e.g. _from, _in).

const BatchInputPublicAssociation = {
    inputs: [
        {
            _from: {
                id : 'contactID'
            },
            to: {
                id: 'companyID'
            },
            type: 'contact_to_company'
        }
    ]
};

const response = await hubspotClient.crm.associations.batchApi.create(
    'contacts',
    'companies',
    BatchInputPublicAssociation
);

Typescript

You may use this library in your Typescript project via:

import * as hubspot from '@hubspot/api-client'
const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN , developerApiKey: YOUR_DEVELOPER_API_KEY })

License

Apache 2.0

Contributing

Install project dependencies with

npm install

You can run the tests by executing:

npm run test

You can check the TypeScript code by running:

npm run lint

If there is a linting error based on formatting, you can run the command below to auto-correct the formatting:

npm run prettier:write