README.md

dotnet core HubSpot client

This repository contains a dotnet / dotnet core compatible HubSpot client with support for custom property mapping from your DTOs to HubSpot fields.

Currently working is (almost complete) support for Contact, Company, Deal, LineItem and Owner in the HubSpot API.

If you find something missing or broken, please report an issue or even better fork the repo and submit a PR!

Dotnet targets

Packages for the following dotnet versions are available:

• dotnet 4.6.1
• netstandard 2.0

Which means that you can use the library with fat-framework >= 4.6.1 or netcoreapp >= 2.0

Verified working on Linux, macOS and Windows.

Versioning

We use SemVer 2.0, which means you can depend on HubSpotClient version <major>.*.

This also means that while we are in the 0.* version range, breaking API changes can be made between minor versions - we strive to keep these at a minimum and will be explicitly stated in the release notes.

Nuget Package

You can install the HubSpotClient package from nuget

Using the library

The library has been split into separate clients for each "HubSpot API feature", which means that Contacts, Companies and Deals have separate clients for you to depend on.

Contact

To interact with HubSpot contacts you must use the HubSpotContactClient - it has two constructors, one for quickly getting started (you just provide the api-key) and one with all dependencies as arguments (eager constructor).

It is generally recommended that you use the "eager" constructor as this allows replacing the HTTP client and other dependencies when testing.

However, getting started is as simple as:

using Skarp.HubSpotClient.Contact;
using Xunit;
using Xunit.Abstractions;

public class ContactTest
{
  [Fact]
  public async Task Getting_contacts_work()
  {
    var client = new HubSpotContactClient("my-awesome-api-key-or-pat");
    var contact = await client.GetByEmailAsync<ContactHubSpotEntity>("[email protected]");
    Assert.NotNull(contact); // victory!
  }
}

All client operations takes in a generic type argument T - this is in order to support (de)serialization. The provided ContactHubSpotEntity provides the basic properties one could want on a contact person.

If you require the default props and some additional custom props, simply create your own class instance and inherit from either IHubSpotEntity or the ContactHubSpotEntity:

[DataContract]
public class MyContactEntity : ContactHubSpotEntity
{
  [DataMember(Name="nick-name")] // required so we can serialize to the hubspot property name defined in your account!
  public string NickName {get; set;}
}

All operations (get, create, update) should now include this custom property. If you don't include the DataContract and DataMember attributes your new props will not be serialized and sent to HubSpot!

Company

To consume the HubSpot company api you should use the HubSpotCompanyClient - as with the contacts there is a simple constructor taking in just the apiKey and an eager constructor taking in all dependencies.

Getting started looks something like...

using Skarp.HubSpotClient.Contact;
using Xunit;
using Xunit.Abstractions;

public class CompanyTest
{
  [Fact]
  public async Task Getting_company_works()
  {
    var client = new HubSpotCompanyClient("my-awesome-api-key-or-pat");
    var company = await client.GetByIdAsync<CompanyHubSpotEntity>(42L);
    Assert.NotNull(company); // victory!
  }
}

To create custom DTOs follow the guidelines given for Contacts above.

Deal

TODO

Line Item

To consume the HubSpot line item api you should use the HubSpotLineItemClient - as with the others there is a simple constructor taking in just the apiKey and an eager constructor taking in all dependencies.

Getting started looks something like...

using Skarp.HubSpotClient.LineItem;
using Skarp.HubSpotClient.LineItem.Dto;
using Xunit;
using Xunit.Abstractions;

public class OwnerTest
{
  [Fact]
  public async Task Getting_owner_works()
  {
    var client = new HubSpotLineItemClient("my-awesome-api-key-or-pat");
    var lineItem = await client.GetByIdAsync<LineItemHubSpotEntity>(42L);
    Assert.NotNull(lineItem); // victory!
  }
}

Owner

To consume the HubSpot owner api you should use the HubSpotOwnerClient - as with the others there is a simple constructor taking in just the apiKey and an eager constructor taking in all dependencies.

Getting started looks something like...

using Skarp.HubSpotClient.Owner;
using Skarp.HubSpotClient.Owner.Dto;
using Xunit;
using Xunit.Abstractions;

public class OwnerTest
{
  [Fact]
  public async Task Getting_owner_works()
  {
    var client = new HubSpotOwnerClient("my-awesome-api-key-or-pat");
    var owner = await client.GetByIdAsync<OwnerHubSpotEntity>(42L);
    Assert.NotNull(owner); // victory!
  }
}