https://github.com/mondaycom/apps-sdk
https://github.com/mondaycom/apps-sdk
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/mondaycom/apps-sdk
- Owner: mondaycom
- License: mit
- Created: 2023-01-17T10:06:50.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-03-16T12:15:40.000Z (2 months ago)
- Last Synced: 2025-03-19T18:07:31.258Z (2 months ago)
- Language: TypeScript
- Size: 575 KB
- Stars: 3
- Watchers: 3
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# apps-sdk
This sdk is used to leverage some of the capabilities exposed via ``:
- [Storage](#storage)
- [Secure storage](#secure-storage)
- [Environment variables manager](#environment-variables-manager)
- [Logger](#logger)
## Storage
* Please note Storage contracts have been updated at version v1.0.0 *
key/value storage for monday-code projects
- This is the way to store customer data for your app
- **_key/value_** based where the **_key_** is a `string` and **_value_** can be `any serializable type` (object, number, string, etc.)
- **_Compartmentalized_** based on **accountId** and **app** for your specific app which means that data stored for one account will not be accessible from the context of another account
- There are two modes for the storage which are based on a passed option `shared`:
- `false` _(default)_ - The stored data will be accessible **only** you "backend" oriented apps (storage will not be shared between integrations and views).
- `true` - The stored data will be accessible from **both** "backend" and "frontend" oriented apps.
### Storage API
There are four methods exposed to manage the storage - `set`, `get`, `search` and `delete`
#### Initialize
- `` - access token of the customer/account the app is working on behalf of
```typescript
import { Storage } from '@mondaycom/apps-sdk';
const storage = new Storage('');
```
#### Set
- `key: string` - key to store the content for
- `value: any` - value to store
- `previousVersion?: string` - the last version of the stored value for a specific key (_OPTIONAL_)
- `shared?: boolean` - whether the stored data will be accessible from both "backend" and "frontend" oriented apps (_OPTIONAL_)
- `version: string` - the new version of the stored value
```typescript
const { version, success, error } = await storage.set(key, value, { previousVersion, shared });
```
#### get
```typescript
const { value, version, success } = await storage.get(key, { shared });
```
#### search
- `key: string` - key aka 'key part' the key must include this string (case insensitive)
- `cursor: string` - current position within the paginated dataset (_OPTIONAL_)
```typescript
const { records, cursor, success } = await storage.search(key, { cursor });
```
#### delete
```typescript
const { success, error } = await storage.delete(key, { shared });
```
## Secure storage
key/value secure storage for monday-code projects
- This is the way to store sensitive customer data (i.e access tokens generated by OAuth for example)
- Has 3 different modes (dependent on where it is used)
- `Secure storage` - when used in a deployed `` project it will automatically utilize the **real** secure storage
- `Local "secure storage"` - a local mock db which will mimic the api exposed by the real secure storage. Will work in this mode when sdk is used locally.
> If there are no permissions to write files on the disk, Local "secure storage" will not be persisted
- **_key/value_** based where the **_key_** is a `string` and **_value_** can be `any type` (object, number, string, etc.)
- **_compartmentalized_** for your **specific app** which means that data stored for one app will not be accessible by other apps
### Secure Storage API
There are three methods exposed to manage the storage - `set`, `get` and `delete`
#### initialize
```typescript
import { SecureStorage } from '@mondaycom/apps-sdk';
const secureStorage = new SecureStorage();
```
#### Set
- `key: string` - key to store the content for
- `value: any` - value to store (must be serializable)
```typescript
await secureStorage.set(key, value);
```
#### get
```typescript
const storedValue = await secureStorage.get(key);
```
#### delete
```typescript
await secureStorage.delete(key);
```
## Environment variables manager
Read environment variables in monday-code projects
- This is the way to **read** environment variables for your app in a project deployed ``.
- Environment variables set via [@mondaycom/apps-cli](https://www.npmjs.com/package/@mondaycom/apps-cli)
```shell
$ mapps code:env -m set -k -v
```
- The environment variables are on the **app** level which means that they are accessible by all the **versions** of the app
### Environment variables manager API
There are two methods exposed to manage the environment variables - `get` and `getKeys`
#### initialize
```typescript
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 });
```
#### get
```typescript
// Get cached environment variable
const cachedValue = envManager.get(key, { invalidate: false });
// Get the latest version of environment variable
const latestValue = envManager.get(key);
```
#### getKeys
```typescript
// Get all cached environment variables keys
const cachedKeys = envManager.getKeys({ invalidate: false });
// Get all environment variables keys
const latestKeys = envManager.getKeys();
```
## Secrets manager
Read secrets in monday-code projects
- This is the way to **read** secrets for your app in a project deployed ``.
- Secrets are set via the Secrets tab in the Dev Center UI in the monday code section
### Secrets manager API
There are two methods exposed to manage the secrets - `get` and `getKeys`
#### initialize
```typescript
import { SecretsManager } from '@mondaycom/apps-sdk';
const secretsManager = new SecretsManager();
```
#### get
```typescript
// Get cached secrets
const cachedValue = secretsManager.get(key, { invalidate: false });
// Get the latest version of a secret
const latestValue = secretsManager.get(key);
```
#### getKeys
```typescript
// Get all cached secrets keys
const cachedKeys = secretsManager.getKeys({ invalidate: false });
// Get all secrets keys
const latestKeys = secretsManager.getKeys();
```
## Logger
Recommended logger for monday-code projects
- This `logger` provides a simple way to log messages for your app in a project deployed ``.
- Logged messages are accessible via via [@mondaycom/apps-cli](https://www.npmjs.com/package/@mondaycom/apps-cli)
```shell
$ mapps code:logs
```
- Logs written **without** this logger may not be accessible via [@mondaycom/apps-cli](https://www.npmjs.com/package/@mondaycom/apps-cli) or not get labeled correctly
### Logger API
There are four methods exposed to manage the environment variables - `info`, `warn`, `error` and `debug`.
#### initialize
```typescript
import { Logger } from '@mondaycom/apps-sdk';
const tag = 'my-app';
// tag will be added to every logged message
const logger = new Logger(tag);
```
#### info
```typescript
logger.info('info message');
```
#### warn
```typescript
logger.warn('warn message');
```
#### debug
```typescript
logger.debug('debug message');
```
#### error
```typescript
// Stack trace will be logged as well if error is provided
logger.error('error message', { error: new Error('error') });
```