Web / React SDK

The Vascular JavaScript SDK (@vascular-io/vascular-js) is the client for React and React Native web applications. It must connect through Envoy, not directly to Vascular Inbox port 3000.

Repository: github.com/vascular-io/vascular-js

Prerequisites

• Vascular Inbox deployed and reachable from Envoy
• Envoy configured on port 8081
• API key, app key, and user ID — see Authentication

Installation

npm install @vascular-io/vascular-js

import Vascular, { Language } from '@vascular-io/vascular-js';

Initialize

Create a Vascular client with your API key, app key, user ID, endpoint (Envoy URL), and optional languages:

const vascular = new Vascular({
  apiKey: 'API_KEY',
  appKey: 'APP_KEY',
  userId: 'USER_ID',
  endpoint: 'https://api.your-domain.com',
  languages: [Language.ENUK],
});

If languages is not provided, the SDK defaults to Language.ENUK.

Usage

All network operations are asynchronous and should be awaited.

Create user

Creates a user. If userId is not provided, the SDK uses the user ID passed to the constructor.

const createdUser = await vascular.createUser();
const createdOtherUser = await vascular.createUser(otherUserId);

Returns:

{
  userId: string,
  inboxId: string,
  metadata: string,
}

Get user

Fetches a user. If userId is not provided, the SDK uses the user ID passed to the constructor.

const user = await vascular.getUser();
const otherUser = await vascular.getUser(otherUserId);

Returns:

{
  uuid: string,
  createdAt: string,
  metadata: string,
}

Inbox

Fetches the first inbox page.

const messages = await vascular.inbox();

Returns an array of inbox messages.

Next inbox page

Fetches the next inbox page using the pagination state from the previous inbox() or inboxNext() call.

const messages = await vascular.inboxNext();

Get message by ID

const message = await vascular.getMessageById('MESSAGE_ID');

Read messages

Marks the given message IDs as read.

const status = await vascular.readMessages(['message-id-1', 'message-id-2']);

Open messages

Marks the given message IDs as opened.

const status = await vascular.openMessages(['message-id-1', 'message-id-2']);

Delete message

const status = await vascular.deleteMessage('MESSAGE_ID');

Add tags

Adds tags to the current user.

const status = await vascular.addTags(['music', 'sport']);

Delete tags

Deletes matching tags from the current user. Tags that do not exist are ignored.

const status = await vascular.deleteTags(['music', 'sport']);

When no matching tags exist, the SDK returns 'Nothing to be deleted'.

List tags

const tags = await vascular.tags();

Returns:

[
  {
    uuid: string,
    name: string,
    createdAt: string,
  }
]

Multiple languages

When you initialize the SDK with multiple languages, each inbox message can contain message data keyed by language name.

const vascular = new Vascular({
  apiKey: 'API_KEY',
  appKey: 'APP_KEY',
  userId: 'USER_ID',
  endpoint: 'https://api.your-domain.com',
  languages: [Language.ENUS, Language.NB],
});

const messages = await vascular.inbox();
const message = messages[0];

const englishMessage = message.messageData.enUs;
const norwegianMessage = message.messageData.nb;

Data structures

Inbox message

{
  uuid: string,
  status: Status,
  provider: Provider,
  created_at: Timestamp,
  expdate: Timestamp,
  type: Type,
  messageData: {
    enUs?: MessageData,
    enUk?: MessageData,
    nb?: MessageData,
  },
}

Message data

{
  title: string,
  body: string,
  media: {
    thumbnail: string,
    image: string,
  },
  actions: [{ name: string, value: string }],
  subTitle: string,
}

Enums

Language

Value	Message data key
Language.ENUS	enUs
Language.ENUK	enUk
Language.NB	nb

Provider

api · sfmc · dashboard

Status

delivered · opened · read · deleted · admin_deleted

Type

info · campaign · payment · notification

Related

• Authentication
• Envoy proxy for web SDKs
• Client SDKs overview