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 PrivMX Bridge page.

Helpers

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

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

    /* 
    All the values below like BRIDGE_URL, SOLUTION_ID, CONTEXT_ID 
    should be replaced by the ones corresponding to your Bridge Server 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)
    */

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

To create an app, follow Getting Started instructions.

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.

const connection = await Endpoint.connect(USER1_PRIV, SOLUTION_ID, BRIDGE_URL);

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

const threadApi  = await Endpoint.createThreadApi(connection);

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.

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 messages = await threadApi.listMessages(threadId, defaultListQuery);
console.log("messages", messages);
console.log("messages in human-readable format", 
   messages.readItems.map(x => 
   {
      return {
      publicMeta: deserializedObject(x.publicMeta), 
      privateMeta: deserializedObject(x.privateMeta), 
      data: deserializedObject(x.data)
      }
   }
));

Run your app, simply by opening it in a browser.