HullClient instance constructor - creates new instance to perform API calls, issue traits/track calls and log information
Parameters
config
Object configuration object config.id
string Connector ID - requiredconfig.secret
string Connector Secret - requiredconfig.organization
string Hull organization - requiredconfig.requestId
string? 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? additional parameter which will be added to logs context, it's used to track connector name in logsconfig.captureLogs
boolean? an optional param to enable capturing logs, when enabled logs won't be sent to stdout/stderr and logs
array would be initiated, which you can access via hullClient.configuration().logsconfig.captureFirehoseEvents
boolean? an option param to enable capturing firehose events, when enabled firehose events won't be sent to firehose endpoint and firehoseEvents
array woyld be initiated, which you can access via hullClient.configuration().firehoseEventsconfig.firehoseUrl
string? The url track/traits calls should be sent, available only for testing purposesconfig.protocol
string protocol which will be appended to organization url, override for testing only (optional, default https
)config.prefix
string prefix of Hull REST API, override for testing only (optional, default /api/v1
)config.logs
Array? an optional array to capture all logs entries, you can provide your own array or use captureLogs
to initiate empty oneconfig.firehoseEvents
Array? an optional array to capture all firehose events, you can provide your own array or use captureFirehoseEvents
to initiate empty oneExamples
const HullClient = require("hull-client");
const hullClient = new HullClient({
id: "HULL_ID",
secret: "HULL_SECRET",
organization: "HULL_ORGANIZATION_DOMAIN"
});
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 current HullClient
configuration parameters
Takes User Claims (link to User Identity docs) and returnes HullClient
instance scoped to this User. This makes #traits and #track methods available.
Parameters
userClaim
Object additionalClaims
Object (optional, default {}
)
additionalClaims.create
boolean marks if the user should be lazily created if not found (optional, default true
)additionalClaims.scopes
Array adds scopes claim to the JWT to impersonate a User with admin rights (optional, default []
)additionalClaims.active
string 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 if no valid claims are passed
Returns UserScopedHullClient
Takes Account Claims (link to User Identity docs) and returnes HullClient
instance scoped to this Account. This makes #traits method available.
Parameters
accountClaim
Object additionalClaims
Object (optional, default Object.freeze({})
)
Throws Error If no valid claims are passed
Returns AccountScopedHullClient instance scoped to account claims
Extends HullClient
The following methods are available when HullClient
instance is scoped to an user or an account. How to get scoped client? Use asUser
or asAccount
methods. The EntityScopedHullClient
is never directly returned by the HullClient but is a base class for UserScopedHullClient and AccountScopedHullClient classes.
Examples
const hullClient = new HullClient({ id, secret, organization });
const scopedHullClient = hullClient.asUser({ email: "foo@bar.com "});
scopedHullClient.traits({ new_attribute: "new_value" });
Used for Bring your own users. 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 to authenticate users client-side and cross-domain
Parameters
claims
Object additionalClaimsExamples
hullClient.asUser({ email: "xxx@example.com", external_id: "1234" }).token(optionalClaims);
hullClient.asAccount({ domain: "example.com", external_id: "1234" }).token(optionalClaims);
Returns string token
Saves attributes on the user or account. Only available on User or Account scoped HullClient
instance (see #asuser and #asaccount).
Parameters
traits
Object object with new attributes, it's always flat object, without nested subobjectsReturns Promise
Extends EntityScopedHullClient
The following methods are available when HullClient
instance is scoped to an user only How to get scoped client? Use asUser
method
Examples
const hullClient = new HullClient({ id, secret, organization });
const scopedHullClient = hullClient.asUser({ email: "foo@bar.com "});
scopedHullClient.traits({ new_attribute: "new_value" });
Available only for User scoped HullClient
instance (see #asuser). 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
accountClaim
Object descriptionReturns HullClient HullClient scoped to a User and linked to an Account
Issues an alias
event on user or account
Parameters
body
Object Examples
const hullClient = new HullClient({ id, secret, organization });
const scopedHullClient = hullClient.asUser({ email: "foo@bar.com "});
scopedHullClient.alias({ anonymous_id: "123" });
Returns Promise
Issues an unalias
event on user or account
Parameters
body
Object Examples
const hullClient = new HullClient({ id, secret, organization });
const scopedHullClient = hullClient.asUser({ email: "foo@bar.com "});
scopedHullClient.unalias({ anonymous_id: "123" });
Returns Promise
Stores events on user. Only available on User scoped HullClient
instance (see #asuser).
Parameters
event
string event nameproperties
Object additional information about event, this is a one-level JSON object (optional, default {}
)context
Object The context
object lets you define event meta-data. Everything is optional (optional, default {}
) context.source
string? Defines a namespace, such as zendesk
, mailchimp
, stripe
context.type
string? Define a event type, such as mail
, ticket
, payment
context.created_at
string? Define an event date. defaults to now()
context.event_id
string? 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? Define the Event's IP. Set to null
if you're storing a server call, otherwise, geoIP will locate this event.context.referer
string? Define the Referer. null
for server calls.Returns Promise
Extends EntityScopedHullClient
This is a class returned when we scope client to account. It provides token
and traits
methods.
Examples
const hullClient = new HullClient({ id, secret, organization });
const scopedHullClient = hullClient.asAccount({ domain: "bar.com "});
scopedHullClient.traits({ new_attribute: "new_value" });
Following methods allows to perform api calls against Hull REST API. Their are available on base HullClient
and all scoped classes.
Performs a HTTP request on selected url of Hull REST API (prefixed with prefix
param of the constructor)
Parameters
url
string method
string params
Object? options
Object (optional, default {}
) options.timeout
Number? 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 erroroptions.retry
Number? controls the time between timeout or 503 error occurence and the next retry being donePerforms a GET HTTP request on selected url of Hull REST API (prefixed with prefix
param of the constructor)
Parameters
url
string params
Object (optional, default {}
)options
Object (optional, default {}
) options.timeout
Number? 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 erroroptions.retry
Number? controls the time between timeout or 503 error occurence and the next retry being donePerforms a POST HTTP request on selected url of Hull REST API (prefixed with prefix
param of the constructor
Parameters
url
string params
Object (optional, default {}
)options
Object (optional, default {}
) options.timeout
Number? 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 erroroptions.retry
Number? controls the time between timeout or 503 error occurence and the next retry being donePerforms a DELETE HTTP request on selected url of Hull REST API (prefixed with prefix
param of the constructor)
Parameters
url
string params
Object (optional, default {}
)options
Object (optional, default {}
) options.timeout
Number? 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 erroroptions.retry
Number? controls the time between timeout or 503 error occurence and the next retry being donePerforms a PUT HTTP request on selected url of Hull REST API (prefixed with prefix
param of the constructor)
Parameters
url
string params
Object (optional, default {}
)options
Object (optional, default {}
) options.timeout
Number? 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 erroroptions.retry
Number? controls the time between timeout or 503 error occurence and the next retry being doneThe following methods are helper utilities. They are available under utils
property
Fetches and returns all existing properties in the organization along with their metadata
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 settings to updateReturns Promise
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 flat objectExamples
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 nested object