JavaScript SDK for monday code
The monday code JavaScript SDK gives developers useful tools to build and host secure apps using monday code that seamlessly integrate with the monday.com platform. It currently contains six methods:
This document will walk through each available method, its parameters, and relevant code samples. You can also access the SDK here.
Install the SDK
You can install the monday code Javascript SDK using npm install
:
npm i @mondaycom/apps-sdk
Storage
The storage
method stores your app's customer data. The data is stored securely and logically segregated, meaning it is stored in smaller categories on the same device to easily grant or block access. It is segregated according to the accountId
and app
, so data stored by one account is inaccessible by other accounts to provide an additional layer of security.
The following limits apply to the storage
methods:
- Key length limit: 256
- Storage limit per key: 6MB
Parameters
Parameter | Type | Description | Required |
---|---|---|---|
key | String | The key to store content for. | Yes |
value | Any serializable object | The value to store. | Yes |
shared | Boolean | False if stored data is not shared between integrations and views. It is only accessible from backend-oriented apps. This is the default.True if stored data is accessible from both frontend and backend-oriented apps. | No |
Initialize
Parameter | Description |
---|---|
ACCESS_TOKEN | The access token of the customer/account the app works for. |
import { Storage } from '@mondaycom/apps-sdk';
const storage = new Storage('<ACCESS_TOKEN>');
Methods
We expose three methods to manage the storage: set
, get
, and delete
.
set
set
The storage.set
method stores value
under key
in the database.
Parameter | Type | Description | Required |
---|---|---|---|
key | String | The key to store content for. | Yes |
value | Any | The value to store. | Yes |
previousVersion | String | The last version of the stored value for a specific key. | No |
shared | Boolean | False if stored data is not shared between integrations and views. It is only accessible from backend-oriented apps. This is the default.True if stored data is accessible from both frontend and backend-oriented apps. | No |
version | String | The new version of the stored value. | Yes |
const { version } = await storage.set(key, value, { previousVersion, shared });
get
get
The storage.get
method returns a stored value from the database under key
.
const storedValue = await storage.get(key, { shared });
delete
delete
The storage.delete
method deletes a stored value under key
from the database.
await storage.delete(key, { shared });
Secure storage
The secureStorage
method stores sensitive customer data for monday-code projects. The data is stored securely and logically segregated, meaning it is stored in smaller categories on the same device to easily grant or block access. It is segregated for your specific app, so data stored by one app is inaccessible by other apps to provide an additional layer of security.
This method will automatically utilize the real secure storage if your monday-code project is deployed. If you use the SDK locally, it will utilize the local secure storage, or a local mock database that mimics the API exposed by the real secure storage. The local secure storage will not be retained if you don't have permissions to write files on the disk.
The following limits apply to the secureStorage
methods:
- Key length limit: 256
- Storage limit per key: 6MB
Parameters
Parameter | Type | Description | Required |
---|---|---|---|
key | String | The key to store content for. | Yes |
value | Any | The serializable value to store. | Yes |
Initialize
import { SecureStorage } from '@mondaycom/apps-sdk';
const secureStorage = new SecureStorage();
Methods
We expose three methods to manage secure storage: set
, get
, and delete
.
set
set
The secureStorage.set
method stores value
under key
in the database.
Parameter | Type | Description | Required |
---|---|---|---|
key | String | The key to store content for. | Yes |
value | Any | The serializable value to store. If the value is not an object, it will be wrapped in an object with a key value . | Yes |
await secureStorage.set(key, value);
get
get
The secureStorage.get
method returns a stored value from the database under key
.
const storedValue = await secureStorage.get(key);
delete
delete
The secureStorage.delete
method deletes a stored value under key
from the database.
await secureStorage.delete(key);
Environment variables manager
The EnvironmentVariablesManager
method enables you to read your app's environment variables in a deployed monday-code project. If you need to set the variables, you can use the CLI.
The variables are on an app level, so you can access them with all app versions.
If you are using the node.js SDK, we encourage you to utilize the environment variables manager to load variables without redeploying your server. If you are using other languages, you need to redeploy the service so new variables will take effect.
Initialize
import { EnvironmentVariablesManager } from '@mondaycom/apps-sdk';
// Initialize the environment variables manager without injecting env into `process.env`
let envManager = new EnvironmentVariablesManager();
// Initialize the environment variables manager and inject env into `process.env`
envManager = new EnvironmentVariablesManager({ updateProcessEnv: true });
Methods
We expose two methods to manage the environment variables: get
and getKeys
.
get
get
The envManager.get
method retrieves environment variables.
// Get cached environment variable
const cachedValue = envManager.get(key, { invalidate: false });
// Get the latest version of environment variable
const latestValue = envManager.get(key);
getKeys
getKeys
The envManager.getKeys
method retrieves environment variables keys.
// Get all cached environment variables keys
const cachedKeys = envManager.getKeys({ invalidate: false });
// Get all environment variables keys
const latestKeys = envManager.getKeys();
Secrets manager
The SecretsManager
method enables you to read secrets for your app in a deployed monday-code project. You can set secrets in the monday code section of the Developer Center UI.
Initialize
import { SecretsManager } from '@mondaycom/apps-sdk';
const secretsManager = new SecretsManager();
Methods
We expose two methods to manage secrets: get
and getKeys
.
get
get
The get
method retrieves secrets.
// Get cached secrets
const cachedValue = secretsManager.get(key, { invalidate: false });
// Get the latest version of a secret
const latestValue = secretsManager.get(key);
getKeys
getKeys
The getKeys
method retrieves secrets keys.
// Get all cached secrets keys
const cachedKeys = secretsManager.getKeys({ invalidate: false });
// Get all secrets keys
const latestKeys = secretsManager.getKeys();
Logger
The logger
is a simple way to log your app's messages in a monday-code project. You can access the logged messages via the CLI. Logs written without the logger
are not accessible using the CLI and may not get labeled correctly.
Initialize
import { Logger } from '@mondaycom/apps-sdk';
const tag = 'my-app';
// tag will be added to every logged message
const logger = new Logger(tag);
Methods
We expose four methods to manage environment variables: info
, warn
, error
, and debug
.
info
info
The logger.info
method logs an info message.
logger.info('info message');
warn
warn
The logger.warn
method logs a warning message.
logger.warn('warn message');
debug
debug
The logger.debug
method logs a debug message.
logger.debug('debug message');
error
error
The logger.error
method logs an error message.
// Stack trace will be logged as well if error is provided
logger.error('error message', { error: new Error('error') });
Queue
We support a queue built on a simple publish-subscribe (i.e., pub/sub) model. Please note that each minor and major app version has its own queue.
Initialize
import { Queue } from "@mondaycom/apps-sdk";
const queue = new Queue();
Methods
We expose two methods to manage the queue: publishMessage
and validateMessageSecret
.
publishMessage
publishMessage
The publishMessage
method publishes a message to the queue. It takes the message
parameter as a string.
After publishing, messages are sent as POST requests to a specific app endpoint: /mndy-queue
.
const messageContent = JSON.stringify({ content: "This is a message" })
const messageId = await queue.publishMessage(messageContent)
validateMessageSecret
validateMessageSecret
Each message contains a random secret
string in the query params of the request that can be used to authenticate the request. The validateMessageSecret
method confirms whether or not a message is valid and that the request to the /mndy-queue
endpoint was triggered by monday code.
Please note that each minor and major app version has its own secret for the message.
const queryParams = req.query;
if (!queue.validateMessageSecret(queryParams.secret)) {
logger.info("Queue message received is not valid, since secret does not match. This message could come from an attacker.");
throw new Error('not allowed');
}
Receiving a message
All messages will be sent to your app as HTTP POST requests at the /mndy-queue
endpoint.
app.post(
"/mndy-queue",
async (req, res) => {
try {
const { body, query } = req;
readQueueMessage({ body, query });
return res.status(200).send({}); // return 200 to ACK the queue message
} catch (err) {
logger.error(err.error);
return res.status(500).send({ message: "internal server error" });
}
}
);
Responding to a message
When you receive a message, you should respond to the request with a success status (HTTP 200) within 10 minutes. If you don't respond in that time, or if you return an error, we will attempt to resend the queue item 9 more times. The message will disappear after the tenth and final attempt.
Updated about 2 months ago