Client Javascript SDK

Overview

Ingrain Client-side SDK is our Javascript client that is meant for client-side usage. The library provides a convenient wrapper for the REST APIs that Ingrain provides.

tip

If you are using React or NextJS, you can use the client for sending events and use our UI Components to simplify the displaying of events.

Installation

npm

npm i @ingrain/ingrain-client-js

yarn

yarn add @ingrain/ingrain-client-js

Usage

The library exports an Ingrain class. To use it:

import { Ingrain } from '@ingrain/ingrain-client-js';

const ingrain = new Ingrain({
  // constructor props
});

By default, the instance gets the user's JWT from local storage using the key ingrain_user_jwt_token. This means that you have to set the JWT in local storage with this key and ensure that the JWT in it is valid for all requests. This behaviour can be overridden by providing a callback method for getUserJwtToken.

Constructor Props

Props	Type	Description
publishableKey	String	Your application's Publishable Key.
getUserJwtToken	GetUserJwtTokenCallback | undefined	A callback function of the signature () => string that will return the user's JWT when called. If undefined, the default behaviour is to get the JWT from local storage using the key ingrain_user_jwt_token. This method will be called before every request is sent.

Methods

Method	Description
setGetUserJwtTokenCallback(getUserJwtToken: GetUserJwtTokenCallback)	Set/change the callback method.
createUserEvent(createUserEventBody: CreateAppUserEvent)	Send an event.
readUserEvents(readQuery: ReadDisplayableAppUserEventsReqQuery)	Read events.

Types

See REST APIs for details of each property or expand the details below.

AppUserEvent details

Properties	Type	Description
actorId	String	ID of the user who performed the action.
actorDisplayName	String	User's name to display in Ingrain's UI components.
actorMetadata	Any | null	Additional metadata for the user. This can be any JSON object. Do not store any sensitive or confidential information here. Fields in this object are also available when defining access control rules.
entityId	String	ID of the entity which the action is performed on.
entityName	String	Unique name of the entity, e.g. "personal-token", "task".
entityDisplayLabel	String	Entity's name to display in Ingrain's UI components, e.g. "Personal Token", "Task".
entityMetadata	Any | null	Additional metadata for the entity. This can be any JSON object. Do not store any sensitive or confidential information here. Fields in this object are also available when defining access control rules.
appUserOrgId	String | null	Use this to store your user's team/org/group ID if your application has such concepts. This is a common use case and hence this field was created as a convenience over storing it in actorMetadata.
entityPropName	String | null	The property of the entity that was changed, e.g. "name", "owner".
action	CREATE | UPDATE | DELETE | VIEW	The action performed.
oldValue	String | null	The old value. Do not store any sensitive or confidential information here. If the updated entity is something confidential, for example an access token, the value should not be sent.
newValue	String | null	The new (updated) value. Do not store any sensitive or confidential information here. If the updated entity is something confidential, for example an access token, the value should not be sent.

CreateAppUserEvent

{
  actorId: string;
  actorDisplayName: string;
  actorMetadata: any;
  entityId: string;
  entityName: string;
  entityDisplayLabel: string;
  entityMetadata: any;
  entityPropName: string | null;
  appUserOrgId: string | null;
  action: Action;
  oldValue: string | null;
  newValue: string | null;
}

ReadDisplayableAppUserEventsReqQuery

{
  page?: number;
  pageSize?: number;
  actorId?: string;
  entityId?: string;
}

Ready-to-use UI Components

The client SDK provides flexibility if you want to build your own UI components to display events. However, if you are using React or NextJS, Ingrain provides UI components out of the box. The components abstract away common functionalities. For more details, proceed to Component References.