Working with Stores

Stores allow users to create multiple file containers, each with separate access rules. Each Context can contain any number of Stores with a unique identifier (storeId) used to distinguish them. Stores do not need to have unique names or assigned public keys.

Permissions

Stores differentiate two types of users: Managers and Regular Users. The table below shows the differences in their permissions:

The values above are the default policy values defined by PrivMX. To read more about Policies and learn how to modify them, go to Policies.

Working with Stores

When working with Stores, you will use storeApi, which provides methods used to manage Stores in given Context.

const storeApi  = await Endpoint.createStoreApi(CONNECTION_ID);

Creating Stores

To create a Store, you need a name and a list of public key - userID pairs. See how to get them in Installation. Due to the fact that each Store is inside a Context, all the public keys have to be registered inside the given Context. You can do it using PrivMX Bridge API.

After creating a Store, all the users with management rights will be able to edit the Store.

The user list in Stores is designed to be flexible, accommodating a wide range of use cases.

const managers = [
    {userId: USER1_ID, pubKey: USER1_PUBLIC_KEY}
];.

const users = [
    {userId: USER1_ID, pubKey: USER1_PUBLIC_KEY},
    {userId: USER2_ID, pubKey: USER2_PUBLIC_KEY}
];

// create a new Store with access for user_1 as manager and user_2 as regular user
// for example, let's put the name of the store as an object in the store's private meta
const storeId = await storeApi.createStore(CONTEXT_ID, users, managers,
    serializeObject("some store's public meta-data"),
    serializeObject("some store's private meta-data")
);

Listing Stores

Your application may include multiple Stores, each associated with different Contexts. You can retrieve a list of all Stores within a given Context. This list will include useful metadata about the Stores, such as the creation date, last file upload date, user list, and information about the last modification. However, to optimize performance, the list will only include the total number of files in each Store, not the full file content.

const defaultListQuery = {skip: 0, limit: 100, sortOrder: "desc"};

const storesList = await storeApi.listStores(
    CONTEXT_ID,
    defaultListQuery
);

// storesList:
{
    readItems: [<storeObject1>, <storeObject2>,..., <storeObjectN>],
    totalAvailable: <number_of_all_stores>
}

A detailed description of the Store object fields can be found in API Reference.

Modifying Stores

Depending on your project's specification, it may be necessary to modify a Store. It could be e.g. changing the name or adding/removing users. Each user with management rights is able to modify Stores, delete them as a whole or only particular files.

To successfully update a Store, you must specify its current version. The version field is mandatory to handle multiple updates on the server and it is incremented by 1 with each update.

Updating a Store means overwriting it with the provided data. The updateStore(...) method needs all the parameters as in the createStore(...) method and a few more. If you want to update one of the parameters - provide it in a new modified form. If, on the other hand, you want to leave the parameter unchanged, provide it as it was before. All current values of the parameters of a given Store can be obtained using getStore(threadId).

Three additional options are available when changing the list of users inside a Store:

• force - applies an update, without checking the current version;
• forceGenerateNewKey - re-encrypts messages in the Store. It's useful when a user is removed and we want to prevent them from accessing the Store.
• policies - allow you to manage access to Stores and files. Read more about Policies.

const store = await storeApi.getStore(storeId);

const newUsers = store.users.map(user => ({
    //Your application must provide a way,
    //to get user's public key from their userId.
    userId: user,
    pubKey: 'USER_PUBLIC_KEY'
    })
);

const newManagers = newUsers.filter(user =>
    store.managers.find(manager => manager == user.userId));

const newPrivateMeta = {
    title: 'New store name'
};

await storeApi.updateStore(
    storeId
    newUsers,
    newManagers,
    store.publicMeta,
    serializeObject(newPrivateMeta)
    store.version,
    false,
    false
);