Using the SDK

Introduction

ROQ provides an SDK for Node.js applications, simplifying the API's usage but still allowing you to use GraphQL queries and mutations if needed.

Installation and configuration

You can install the SDK using this NPM command:

npm i --save @roq/nodejs

Then you can create an instance of the Platform class and provide the required configuration:

import {Platform} from '@roq/nodejs';
 
const client = new Platform({
    environmentId: 'abc',
    apiKey: 'abc',
    host: 'abc',
});

All the credentials can be retrieved from ROQ Console (opens in a new tab).

User vs SuperAdmin

When you interact with ROQ Platform, you need a user token. A user is usually available on the client side so that you can use its token. But in some cases, there is no user token available. For instance, when you implement logic that is executed as a cron job. For these scenarios, ROQ provides a special user called "super admin". This user has full permissions, so we recommend using it carefully.

The super admin user is always available on ROQ Platform side and isn't shown in ROQ Console. For security reasons it can only be used from the server side of your application.

If you prefer to interact with the current user ID then you can use the asUser function and provide the user's ID. Whenever a user is available, then it should be used.

await client.asUser(userId).sendMail(...)

To interact with ROQ Platform using the super admin user, you can use the asSuperAdmin function:

await client.asSuperAdmin().sendMail(...)

Example: sending mails

The following snipped shows the full example how to send mails using the service account user. Please refer to the Mails API documentation for more details. The credentials are injected via environment variables.

import { Platform } from '@roq/nodejs';
 
const client = new Platform({
  environmentId: env.environmentId,
  apiKey: env.apiKey,
  host: env.host,
});
 
await client.asSuperAdmin().sendMail({
  mail: { 
      key: 'abc123', 
      locale: 'abc123', 
      emails: ['xyz789'], 
      data: [{ key: 'xyz789', value: 'xyz789' }]
  },
});

Example: fetching data

The following snipped fetches 10 users from ROQ Platform and loads their emails into a variable.

const response = await client.asUser(userId).users({ 
    limit: 10, 
    offset: 0, 
    filter: { locale: { equalTo: 'en' } 
    } 
});
const users = response.users.data;
const emails = users.map((user) => user.email);