Skip to content

API.md

Latest commit

 

History

History
364 lines (240 loc) · 13.2 KB

API.md

File metadata and controls

364 lines (240 loc) · 13.2 KB

HullClient

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 - required
    • config.secret string Connector Secret - required
    • config.organization string Hull organization - required
    • config.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 logs
    • config.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().logs
    • config.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().firehoseEvents
    • config.firehoseUrl string? The url track/traits calls should be sent, available only for testing purposes
    • config.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 one
    • config.firehoseEvents Array? an optional array to capture all firehose events, you can provide your own array or use captureFirehoseEvents to initiate empty one

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 current HullClient configuration parameters

asUser

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

asAccount

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

EntityScopedHullClient

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" });

token

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 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 token

traits

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 subobjects

Returns Promise

UserScopedHullClient

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" });

account

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 [description] (optional, default Object.freeze({}))

Returns HullClient HullClient scoped to a User and linked to an Account

alias

Issues an alias event on user?

Parameters

Returns Promise

track

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

Parameters

  • event string event name
  • properties 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

AccountScopedHullClient

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" });

Api

Following methods allows to perform api calls against Hull REST API. Their are available on base HullClient and all scoped classes.

api

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 error
    • options.retry Number? controls the time between timeout or 503 error occurence and the next retry being done

get

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

Parameters

  • url 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 error
    • options.retry Number? 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
  • 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 error
    • options.retry Number? 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
  • 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 error
    • options.retry Number? 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
  • 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 error
    • options.retry Number? controls the time between timeout or 503 error occurence and the next retry being done

Utils

The following methods are helper utilities. They are available under utils property

properties.get

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

Returns Promise<Object>

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 settings to update

Returns Promise

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

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 nested object