Node API Client Reference


HullClient

HullClient instance constructor - creates new instance to perform API calls, issue traits/track calls and log information

Parameters

  • config [Object][1] configuration object
    • config.id [string][2] Connector ID - required
    • config.secret [string][2] Connector Secret - required
    • config.organization [string][2] Hull organization - required
    • config.requestId [string][2]? additional parameter which will be added to logs context, it can be HTTP request unique id when you init HullClient and you want to group log lines by the request (it can be a job id etc.)
    • config.connectorName [string][2]? additional parameter which will be added to logs context, it's used to track connector name in logs
    • config.firehoseUrl [string][2]? The url track/traits calls should be sent - deprecated option, will be removed in next version
    • config.protocol [string][2] protocol which will be appended to organization url, override for testing only (optional, default https)
    • config.prefix [string][2] prefix of Hull REST API (optional, default /api/v1)

Examples

const HullClient = require("hull-client");
const hullClient = new HullClient({
  id: "HULL_ID",
  secret: "HULL_SECRET",
  organization: "HULL_ORGANIZATION_DOMAIN"
});

configuration

Returns the global configuration object.

Examples

const hullClient = new HullClient({});
hullClient.configuration() == {
  prefix: "/api/v1",
  domain: "hullapp.io",
  protocol: "https",
  id: "58765f7de3aa14001999",
  secret: "12347asc855041674dc961af50fc1",
  organization: "fa4321.hullapp.io",
  version: "0.13.10"
};

Returns [Object][1] current HullClient configuration parameters

as

Parameters

  • userClaim
  • additionalClaims (optional, default {})

Meta

  • deprecated: Use asUser instead

asUser

Takes User Claims (link to User Identity docs) and returnes HullClient instance scoped to this User. This makes [#traits][3] and [#track][4] methods available.

Parameters

  • userClaim [Object][1]
  • additionalClaims [Object][1] (optional, default {})

    • additionalClaims.create [boolean][5] marks if the user should be lazily created if not found (optional, default true)
    • additionalClaims.scopes [Array][6] adds scopes claim to the JWT to impersonate a User with admin rights (optional, default [])
    • additionalClaims.active [string][2] marks the user as active meaning a reduced latency at the expense of scalability. Don't use for high volume updates (optional, default false)
  • Throws [Error][7] if no valid claims are passed

Returns [HullClient][8]

asAccount

Takes Account Claims (link to User Identity docs) and returnes HullClient instance scoped to this Account. This makes [#traits][3] method available.

Parameters

  • accountClaim [Object][1]
  • additionalClaims [Object][1] (optional, default {})

  • Throws [Error][7] If no valid claims are passed

Returns [HullClient][8] instance scoped to account claims

ScopedHullClient

Following methods are available when HullClient instance is scoped to user or account. How to get scoped client? Use asUser or asAccount methods.

Examples

const hullClient = new HullClient({ id, secret, organization });
const scopedHullClient = hullClient.asUser({ email: "foo@bar.com "});
scopedHullClient.traits({ new_attribute: "new_value" });

token

Used for [Bring your own users][9]. Creates a signed string for the user passed in hash. userHash needs an email field. [You can then pass this client-side to Hull.js][10] to authenticate users client-side and cross-domain

Parameters

  • claims [Object][1] additionalClaims

Examples

hullClient.asUser({ email: "xxx@example.com", external_id: "1234" }).token(optionalClaims);
hullClient.asAccount({ domain: "example.com", external_id: "1234" }).token(optionalClaims);

Returns [string][2] token

traits

Saves attributes on the user or account. Only available on User or Account scoped HullClient instance (see [#asuser][11] and [#asaccount][12]).

Parameters

  • traits [Object][1] object with new attributes, it's always flat object, without nested subobjects
  • context [Object][1] (optional, default {})
    • context.source [string][2]? optional source prefix, if applied all traits will be prefixed with this string (and / character)
    • context.sync [string][2] make the operation synchronous - deprecated option, will be removed in next version (optional, default false)

Returns [Promise][13]

track

Stores events on user. Only available on User scoped HullClient instance (see [#asuser][11]).

Parameters

  • event [string][2] event name
  • properties [Object][1] additional information about event, this is a one-level JSON object (optional, default {})
  • context [Object][1] The context object lets you define event meta-data. Everything is optional (optional, default {})
    • context.source [string][2]? Defines a namespace, such as zendesk, mailchimp, stripe
    • context.type [string][2]? Define a event type, such as mail, ticket, payment
    • context.created_at [string][2]? Define an event date. defaults to now()
    • context.event_id [string][2]? Define a way to de-duplicate events. If you pass events with the same unique event_id, they will overwrite the previous one.
    • context.ip [string][2]? Define the Event's IP. Set to null if you're storing a server call, otherwise, geoIP will locate this event.
    • context.referer [string][2]? Define the Referer. null for server calls.

Returns [Promise][13]

alias

Issues an alias event on user?

Parameters

  • body [Object][1]

Returns [Promise][13]

account

Available only for User scoped HullClient instance (see [#asuser][11]). Returns HullClient instance scoped to both User and Account, but all traits/track call would be performed on the User, who will be also linked to the Account.

Parameters

Returns [HullClient][8] HullClient scoped to a User and linked to an Account

Api

Following methods allows to perform api calls again Hull REST API. Their are available on HullClient and scoped HullClient.

get

Performs a GET HTTP request on selected url of Hull REST API (prefixed with prefix param of the constructor)

Parameters

  • url [string][2]
  • params [Object][1]?
  • options [Object][1] (optional, default {})
    • options.timeout [Number][14]? option controls if the client should retry the request if the client timeout error happens or if there is an error 503 returned serverside - the value of the option is applied for client side error
    • options.retry [Number][14]? controls the time between timeout or 503 error occurence and the next retry being done

post

Performs a POST HTTP request on selected url of Hull REST API (prefixed with prefix param of the constructor)

Parameters

  • url [string][2]
  • params [Object][1]?
  • options [Object][1] (optional, default {})
    • options.timeout [Number][14]? option controls if the client should retry the request if the client timeout error happens or if there is an error 503 returned serverside - the value of the option is applied for client side error
    • options.retry [Number][14]? controls the time between timeout or 503 error occurence and the next retry being done

put

Performs a PUT HTTP request on selected url of Hull REST API (prefixed with prefix param of the constructor)

Parameters

  • url [string][2]
  • params [Object][1]?
  • options [Object][1] (optional, default {})
    • options.timeout [Number][14]? option controls if the client should retry the request if the client timeout error happens or if there is an error 503 returned serverside - the value of the option is applied for client side error
    • options.retry [Number][14]? controls the time between timeout or 503 error occurence and the next retry being done

del

Performs a DELETE HTTP request on selected url of Hull REST API (prefixed with prefix param of the constructor)

Parameters

  • url [string][2]
  • params [Object][1]?
  • options [Object][1] (optional, default {})
    • options.timeout [Number][14]? option controls if the client should retry the request if the client timeout error happens or if there is an error 503 returned serverside - the value of the option is applied for client side error
    • options.retry [Number][14]? controls the time between timeout or 503 error occurence and the next retry being done

Utils

Following methods are helper utilities. They are available under utils property

groupTraits

Meta

  • deprecated: use utils.traits.group instead

properties.get

Gets and returns all existing properties in the organization along with their metadata

Returns [Promise][13]<[Object][1]>

settings.update

Updates private_settings merging them with existing ones before.

Note: this method will trigger hullClient.put and will result in ship:update notify event coming from Hull platform - possible loop condition.

Parameters

  • newSettings [Object][1] settings to update

Returns [Promise][13]

traits.group

The Hull API returns traits in a "flat" format, with '/' delimiters in the key. This method can be used to group those traits into subobjects:

Parameters

  • user [Object][1] flat object

Examples

hullClient.utils.traits.group({
  email: "romain@user",
  name: "name",
  "traits_coconut_name": "coconut",
  "traits_coconut_size": "large",
  "traits_cb/twitter_bio": "parisian",
  "traits_cb/twitter_name": "parisian",
  "traits_group/name": "groupname",
  "traits_zendesk/open_tickets": 18
});

// returns
{
  "email": "romain@user",
  "name": "name",
  "traits": {
    "coconut_name": "coconut",
    "coconut_size": "large"
  },
  "cb": {
    "twitter_bio": "parisian",
    "twitter_name": "parisian"
  },
  "group": {
    "name": "groupname"
  },
  "zendesk": {
    "open_tickets": 18
  }
};

Returns **[Object][1]** nested object

[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[3]: #traits

[4]: #track

[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error

[8]: #hullclient

[9]: http://hull.io/docs/users/byou

[10]: http://www.hull.io/docs/users/byou

[11]: #asuser

[12]: #asaccount

[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise

[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number