First app

A step-by-step tutorial that will guide you through creating your first app using JavaScript WebEndpoint with PrivMX Bridge.

PrivMX Bridge

To proceed with this tutorial, you should already have your Bridge Server up and running. If not, you can find step-by-step instructions on quick start page.

Most of the Endpoint's methods (for example creating or updating containers like Threads, Stores, etc.) require some data to be passed as a buffer. In JavaScript that buffer is represented as Uint8Array.

A common way to serialize JS objects is to serialize them to a JSON string using JSON.stringify. Next, in order to encode strings you can use TextEncoder. Because it's so common, in our examples we will use helper functions to do these conversions underneath.

function strToUInt8(text) {
   return (new TextEncoder()).encode(text);
}
 
function uInt8ToStr(arr) {
   return (new TextDecoder()).decode(arr);
}
 
function deserializeObject(binary){
   return JSON.parse(uInt8ToStr(binary));
}
 
function serializeObject(object) {
   return strToUInt8(JSON.stringify(object));
}

Initial Assumptions

All the values below like BRIDGE_URL, SOLUTION_ID, CONTEXT_ID should be replaced by the ones corresponding to your PrivMX Bridge instance.

The private keys here are for demonstration purposes only. Normally, they should be kept separately by each user and stored in a safe place, or generated from a password (see the derivePrivateKey() method in the Crypto API)

The initial assumptions for all the code examples below are as follows:

const BRIDGE_URL = "http://localhost:9111";
const SOLUTION_ID = "YOUR_SOLUTION_ID";
const CONTEXT_ID = "YOUR_CONTEXT_ID";
 
const USER1_ID = "user_1";
const USER1_PUBLIC_KEY = "PUBLIC_KEY_1";
const USER1_PRIV = "PRIVATE_KEY_1";
 
const USER2_ID = "user_2";
const USER2_PUBLIC_KEY = "PUBLIC_KEY_2";
 
const USER3_ID = "user_3";
const USER3_PUBLIC_KEY = "PUBLIC_KEY_3";
 
// Initialize Endpoint and its Wasm assets
await Endpoint.setup("/public");

Basic Serialization Example - JSON

const dataObject = {
    content: 'MESSAGE_CONTENT',
    type: 'text'
};
 
const binaryData = serializeObject(dataObject); // returns data encoded to Uint8Array
const deserializedObject = deserializeObject(binaryData); // returns JavaScript object

Create Client App

First, you have to connect to your Bridge instance using Endpoint.connect method. It requires the API keys generated while initializing your local instance earlier.

import {Endpoint} from "@simplito/privmx-webendpoint"
 
const connection = await Endpoint.connect(USER1_PRIV, SOLUTION_ID, BRIDGE_URL);
const threadApi  = await Endpoint.createThreadApi(connection);

When connected, you have access to all SDK methods. This example shows how to create a Thread, send, and download a message.

To create a Thread inside the Context, use proper methods. Note that you have to pass user ID - public key pair to make a list of users and managers.

//using constants from initial assumptions
const exampleUser = {
     userId: USER1_ID,
     pubKey: USER1_PUBLIC_KEY,
};
 
const newThreadId = await threadApi.createThread(
   CONTEXT_ID, 
   [exampleUser], // list of users who will have access to the created Thread
   [exampleUser], // list of managers of that Thread
   strToUInt8("some public meta-data"),
   strToUInt8("some private meta-data, such as thread name")
);

With the Thread created, you can now send the first message.

await threadApi.sendMessage(
   threadId, 
   strToUInt8("some public meta-data"), 
   strToUInt8("some private meta-data"), 
   strToUInt8("some message content")
);

To get a list of messages inside a Thread, use listMessages method. Because data inside messages is in Uint8Array you have to deserialize it to human-readable string. Endpoint takes care of encrypting your data before sending it to PrivMX Bridge.

const defaultListQuery = {skip: 0, limit: 100, sortOrder: "desc"};
const messagesList = await threadApi.listMessages(threadId, defaultListQuery);
const decodedMessages = messages.readItems.map(x => {
    return {
        publicMeta: deserializedObject(x.publicMeta),
        privateMeta: deserializedObject(x.privateMeta),
        data: deserializedObject(x.data)
    }
})
 
console.log("messages", messages);
console.log("messages in human-readable format", decodedMessages)

Next Steps

With everything ready to go, now it's time to start using all the capabilities of Endpoint and Bridge.

Learn how to use:

Threads - for exchanging encrypted messages;
Stores - for saving and sharing encrypted files;
Inboxes - for one way communication with external users.

PrivMX Bridge

Helpers

Initial Assumptions

Basic Serialization Example - JSON

Create Client App

Next Steps

On this page