@crowdin/app-project-module 0.28.0-9 → 0.28.0

package/README.md

@@ -2,7 +2,990 @@
 
 Module that will automatically add all necessary endpoints for Crowdin App.
 
-:bookmark: See the [docs](/docs) for more information.
+It either can extends your [Express](http://expressjs.com/) application or even create it for you.
+
+Module expose two main methods:
+
+- `createApp` to fully create for you Express application
+- `addCrowdinEndpoints` to extend your Express application
+
+In both options you will need to provide Crowdin App configuration file. Please refer to jsdoc for more details.
+
+`addCrowdinEndpoints` will return an object with several methods to help you add your own custom logic [see example](#resources).
+
+- `saveMetadata` to save metadata (may be associated with an organization, project, etc)
+- `getMetadata` to get metadata
+- `deleteMetadata` to delete metadata (usually useful in `onUninstall` hook)
+- `getUserSettings` to get settings that users manage in the integration module
+- `establishCrowdinConnection` method that accept jwt token that you may forward from module UI and it will return back Crowdin client instance and the context.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Sample Project Integration App](#sample-project-integration-app)
+- [Payment](#payment)
+- [Authorization](#authorization)
+  - [Custom login form](#customize-your-app-login-form)
+  - [OAuth2 login](#oauth2-support)
+- [Storage](#storage)
+  - [SQLite](#sqlite)
+  - [PostgreSQL](#postgresql)
+  - [MySQL](#mysql)
+- [Settings window](#settings-window)
+- [Info window](#info-window)
+- [Background tasks](#background-tasks)
+- [Errors handling](#errors-handling)
+  - [Error propagation](#error-propagation)
+  - [Error interceptor](#error-interceptor)
+  - [Debug mode](#debug-mode)
+- [Modules](#modules)
+  - [Custom File Format](#custom-file-format)
+  - [Custom MT](#custom-mt)
+  - [Profile Resources Menu](#profile-resources-menu)
+  - [Other modules](#other-modules)
+- [Other options](#other-options)
+- [Contributing](#contributing)
+- [Seeking Assistance](#seeking-assistance)
+- [License](#license)
+
+## Installation
+
+### npm
+
+  `npm i @crowdin/app-project-module`
+
+### yarn
+
+  `yarn add @crowdin/app-project-module`
+
+## Sample Project Integration App
+
+```javascript
+const crowdinModule = require('@crowdin/app-project-module');
+const crowdinAppFunctions = require('@crowdin/crowdin-apps-functions');
+const axios = require('axios').default;
+
+const configuration = {
+    baseUrl: 'https://123.ngrok.io',
+    clientId: 'clientId',
+    clientSecret: 'clientSecret',
+    scopes: [
+        crowdinModule.Scope.PROJECTS,
+        crowdinModule.Scope.TRANSLATION_MEMORIES
+    ],
+    name: 'Sample App',
+    identifier: 'sample-app',
+    description: 'Sample App description',
+    dbFolder: __dirname,
+    imagePath: __dirname + '/' + 'logo.png',
+    crowdinUrls: { // custom urls to override
+        // apiUrl: 'https://<copy_name>.crowdin.dev/api/v2', // 'https://<org_name>.<copy_name>.crowdin.dev/api/v2' for enterprise
+        // accountUrl: 'https://accounts.<copy_name>.crowdin.dev/oauth/token', // (default https://accounts.crowdin.com/oauth/token)
+        // subscriptionUrl: 'https://<copy_name>.crowdin.dev' // (default https://crowdin.com or https://org.api.crowdin.com)
+    },
+    projectIntegration: {
+        withRootFolder: true,
+        withCronSync: {
+            crowdin: true,
+            integration: true,
+        },
+        webhooks: { //enable webhook
+          crowdinWebhookUrl: '/notify', // override crowdin webhook endpoint
+          integrationWebhookUrl: '/update-entity', // override integration webhook endpoint
+          urlParam: 'information', // override request param name
+          crowdinWebhooks: async (client, projectId, available, appSettings) => { // optional
+            // here you need to create crowdin webhooks if the default doesn't work for you
+            // used with crowdinWebhookInterceptor
+            await client.webhooksApi.addWebhook(projectId, {
+              'Application webhook',
+              url: 'https://123.ngrok.io/notify',
+              events: ['file.translated'],
+              requestType: 'POST',
+            });
+          },
+          crowdinWebhookInterceptor: async (projectId, client, appRootFolder, appSettings, syncSettings) => { // optional
+            // used with crowdinWebhooks
+            return {
+              '101': ['de', 'fr'],
+              '103': ['de'],
+            };
+          }
+          integrationWebhooks: async (credentials, urlParam, available, appSettings, syncSettings) => {
+            // here you need to create webhooks on the integration side
+            // used with integrationWebhookInterceptor or RabbitMQ queue
+            await axios.post('https://site.com/api/webhooks');
+          },
+          integrationWebhookInterceptor: async (projectId, client, rootFolder, appSettings, syncSettings, webhookRequest) => {
+            // used with integrationWebhooks
+            return [
+              {
+                id: '47282999980',
+                name: 'Home page',
+                parentId: '1',
+                type: 'json',
+              },
+              {
+                id: '73291251883',
+                name: 'Intro',
+                parentId: '2',
+                type: 'json',
+              },
+            ];
+          },
+          queueUrl: 'amqp://localhost:5672', // RabbitMQ url to listen to the webhook queue, 
+        },
+        integrationPagination: true, //enable pagination on integration files list
+        integrationOneLevelFetching: true, //turn on request when opening a directory and pass its id
+        integrationSearchListener: true, //turn on search listener and pass search string
+        uploadTranslations: true, //enable the option to download translations from integration. 
+        getIntegrationFiles: async (credentials, appSettings, parentId, search, page) => {
+            //here you need to fetch files/objects from integration
+            const res = [
+                {
+                    id: '12',
+                    name: 'File from integration',
+                    type: 'json',
+                    parentId: '10'
+                },
+                {
+                    id: '14',
+                    name: 'File from integration2',
+                    type: 'xml',
+                    parentId: '11'
+                },
+                {
+                    id: '10',
+                    name: 'Folder from integration'
+                },
+                {
+                    id: '11',
+                    name: 'Folder from integratio2'
+                    customContent: `<div style='color: red;'>Custom Folder name</div>`,
+                    parentId: '1'
+                },
+                {
+                    id: '1',
+                    name: 'Branch from integratio',
+                    nodeType: '2'
+                },
+            ];
+            return {
+                data: res,
+                message: 'Test',
+                stopPagination: true, //send if no next files page
+            };
+        },
+        getFileProgress: async (projectId, client, fileId) => { //Use this function if you require a customized translation progress.
+            return {
+                [fileId]: [
+                    {
+                        languageId: 'uk',
+                        eTag: '49a76a1632973b00175dac942976f7c6',
+                        words: {
+                            total: 180,
+                            translated: 0,
+                            approved: 0
+                        },
+                        phrases: {
+                            total: 6,
+                            translated: 0,
+                            approved: 0
+                        },
+                        translationProgress: 100,
+                        approvalProgress: 0
+                    }
+                ]
+            }
+        },
+        updateCrowdin: async (projectId, client, credentials, request, rootFolder, appSettings, uploadTranslations) => {
+            //here you need to get data from integration and upload it to Crowdin
+            console.log(`Request for updating data in Crowdin ${JSON.stringify(request)}`);
+            const directories = await client.sourceFilesApi
+                .withFetchAll()
+                .listProjectDirectories(projectId);
+            const { folder, files } = await crowdinAppFunctions.getOrCreateFolder({
+                directories: directories.data.map((d) => d.data),
+                client,
+                projectId,
+                directoryName: 'Folder from integration',
+                parentDirectory: rootFolder
+            });
+            const fileContent = {
+                title: 'Hello World',
+            };
+            const fileName = 'integration.json';
+            const fileId = await crowdinAppFunctions.updateOrCreateFile({
+                client,
+                projectId,
+                name: fileName,
+                title: 'Sample file from integration',
+                type: 'json',
+                directoryId: folder.id,
+                data: fileContent,
+                file: files.find((f) => f.name === 'integration.json'),
+            });
+            
+            if (uploadTranslations) {
+              const fileTranslation = {
+                title: 'Hola Mundo',
+              };
+              await crowdinAppFunctions.uploadTranslations(
+                client,
+                projectId,
+                fileId,
+                'es',
+                fileName,
+                fileTranslation,
+              );
+            }
+            
+            return {
+                message: 'Some message',
+            };
+        },
+        updateIntegration: async (projectId, client, credentials, request, rootFolder, appSettings) => {
+            //here should be logic to get translations from Crowdin and upload them to integration
+            console.log(`Request for updating data in Integration ${JSON.stringify(request)}`);
+            const directories = await client.sourceFilesApi
+                .withFetchAll()
+                .listProjectDirectories(projectId);
+            const { files } = await crowdinAppFunctions.getFolder({
+                directories: directories.data.map((d) => d.data),
+                client,
+                projectId,
+                directoryName: 'Folder from integration',
+                parentDirectory: rootFolder
+            });
+            const file = files.find((f) => f.name === 'integration.json');
+            if (file) {
+                const translationsLink =
+                    await client.translationsApi.buildProjectFileTranslation(
+                        projectId,
+                        file.id,
+                        { targetLanguageId: 'uk' },
+                    );
+                if (!translationsLink) {
+                    return;
+                }
+                const response = await axios.get(translationsLink.data.url);
+                console.log(response.data);
+            }
+        },
+        onLogout: async (projectId, client, credentials, appSettings) => {
+            //cleanup logic
+        }
+    }
+};
+
+crowdinModule.createApp(configuration);
+```
+
+## Payment
+
+By default App does not have any subscription and it's free to use. But you can override this.
+
+```javascript
+configuration.pricing = {
+    plantType: 'recurring',
+    trial: 14, //amount of days to use app for free
+    trialCrowdin: 14, //amount of days specifically in crowdin workspace
+    trialEnterprise: 30, //amount of days specifically for enterprise
+    cachingSeconds: 12 * 60 * 60, //time in seconds of how long to cache subscription info
+    infoDisplayDaysThreshold: 14 //number of days threshold to check if subscription info should be displayed (if not defined then info will be always visible)
+};
+```
+
+## Authorization
+
+### Customize your app login form
+
+By default, login page for your app will require only to  enter `apiToken` to communicate with third party service.
+But there is also a possibility to customize it.
+
+```javascript
+configuration.projectIntegration.loginForm = {
+    fields: [
+        {
+            key: 'username',
+            label: 'Username',
+        },
+        {
+            key: 'password',
+            label: 'Password',
+            type: 'password'
+        },
+        {
+            label: 'Api creds',
+        },
+        {
+            helpText: 'Api Key for http requests',
+            key: 'apiKey',
+            label: 'Api Key'
+        },
+        {
+            key: 'server',
+            label: 'Data center',
+            type: 'select',
+            defaultValue: '1',
+            options: [
+                {
+                  value: '1',
+                  label: 'USA'
+                },
+                {
+                  value: '2',
+                  label: 'EU'
+                }
+            ]
+        },
+        {
+            key: 'apiKey',
+            label: 'Api key',
+            type: 'textarea'
+        },      
+        {
+            key: 'fileSecret',
+            label: 'Upload file',
+            type: 'file',
+            accept: '.txt'
+        },
+    ]
+};
+```
+
+### OAuth2 support
+
+In case if third party service uses OAuth2 for authorization use `oauthLogin` field to configure it.  
+`loginForm` **in this case should remain undefined**.
+
+Github example:
+
+```javascript
+configuration.projectIntegration.oauthLogin = {
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    clientId: 'github_app_client_id',
+    clientSecret: 'github_app_client_secret',
+    accessTokenUrl: 'https://github.com/login/oauth/access_token'
+}
+```
+
+Google example:
+
+```javascript
+configuration.projectIntegration.oauthLogin = {
+    scope: 'https%3A//www.googleapis.com/auth/userinfo.email',
+    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    clientId: 'google_web_app_client_id',
+    clientSecret: 'google_web_app_client_secret',
+    accessTokenUrl: 'https://oauth2.googleapis.com/token',
+    extraAutorizationUrlParameters: {
+        response_type: 'code',
+        access_type: 'offline',
+        prompt: 'consent'
+    },
+    extraAccessTokenParameters: {
+        grant_type: 'authorization_code'
+    },
+    extraRefreshTokenParameters: {
+        grant_type: 'refresh_token'
+    },
+    refresh: true
+}
+```
+
+The `oauthLogin` property allows you to customize many different properties, mappings, etc. So that you can integrate with any OAuth2 implementation.  
+Main default values:
+
+- redirect uri prefix will be `/oauth/code`
+- client id field name in url parameters and in request payload will be `client_id`
+- client secret field name in request payload will be `client_secret`
+- access token field name should be `access_token`
+- be default assumption is that token do not have any expiration date, to change this behavior use `refresh` flag so then refresh token and expires in will be taken into consideration
+- access token field name should be `refresh_token`
+- expires in field name should be `expires_in` (value should be in seconds)
+
+This module rely that OAuth2 protocol is implemented by third party service in this way:
+
+- request for access token should be done via POST request to `accessTokenUrl` with JSON body that will contain at least `clientId`, `clientSecret`, `code` and `redirectUri` (also possible to add extra fields via `extraAccessTokenParameters` property)
+- request to refresh token should be done via POST request to `accessTokenUrl` (or `refreshTokenUrl` if defined) with JSON body that will contain at least `clientId`, `clientSecret` and `refreshToken` (also possible to add extra fields via `extraRefreshTokenParameters` property)
+- both requests will return JSON response with body that contains `accessToken` and, if enabled, `refreshToken` (optional) and `expireIn`
+
+To override those requests please use `performGetTokenRequest` and `performRefreshTokenRequest` (e.g. when requests should be done with different HTTP methods or data should be tranfered as query string or form data).
+
+Mailup example:
+
+```javascript
+const clientId = 'client_id';
+const clientSecret = 'client_secret';
+const tokenUrl = 'https://services.mailup.com/Authorization/OAuth/Token';
+
+configuration.projectIntegration.oauthLogin = {
+    authorizationUrl: 'https://services.mailup.com/Authorization/OAuth/LogOn',
+    clientId,
+    clientSecret,
+    extraAutorizationUrlParameters: {
+        response_type: 'code'
+    },
+    refresh: true,
+    performGetTokenRequest: async (code, query, url) => {
+        //query is an object with all query params
+        //url is an url string that OAuth server used to call us back
+        const url = `${tokenUrl}?code=${code}&grant_type=authorization_code`;
+        const headers = {
+            'Authorization': `Bearer ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`
+        };
+        return (await axios.get(url, { headers })).data;
+    },
+    performRefreshTokenRequest: async (credentials) => {
+        const params = {
+            refresh_token: credentials.refreshToken,
+            grant_type: 'refresh_token',
+            client_id: clientId,
+            client_secret: clientSecret
+        };
+        const data = Object.keys(params)
+            .map((key) => `${key}=${encodeURIComponent(params[key])}`)
+            .join('&');
+        const headers = {
+            'Content-Type': 'application/x-www-form-urlencoded'
+        };
+        return (await axios.post(tokenUrl, data, { headers })).data;
+    }
+}
+```
+
+In addition you can specify extra fields on login screen that you can use to dynamically build authorization url.
+
+```javascript
+configuration.projectIntegration.oauthLogin.loginFields = [
+    {
+        key: 'region',
+        label: 'Region',
+        type: 'select',
+        defaultValue: 'NA',
+        options: [
+            {
+                value: 'NA',
+                label: 'North American'
+            },
+            {
+                value: 'EU',
+                label: 'Europe'
+            },
+            {
+                value: 'AZURE_NA',
+                label: 'Azure North American'
+            }
+        ]
+    }
+];
+
+configuration.projectIntegration.oauthLogin.getAuthorizationUrl = (redirectUrl, loginForm) => {
+    const region = loginForm.region;
+    if (region === 'EU') {
+        return `https://eu-region.com?client_id=<client-id>&redirect_uri=${redirectUrl}`;
+    } else {
+        return `https://default-region.com?client_id=<client-id>&redirect_uri=${redirectUrl}`;
+    }
+};
+```
+
+Please refer to jsdoc for more details.
+
+## Storage
+
+Module can be configured to use following storages:
+
+### SQLite
+
+```javascript
+//specify folder where sqlite db file will be located
+configuration.dbFolder = __dirname;
+```
+
+### PostgreSQL
+
+```javascript
+configuration.postgreConfig = {
+    host: 'localhost',
+    user: 'postgres',
+    password: 'password',
+    database: 'test'
+};
+```
+
+### MySQL
+
+```javascript
+configuration.mysqlConfig = {
+    host: 'localhost',
+    user: 'root',
+    password: 'password',
+    database: 'test'
+};
+```
+
+## Settings window
+
+It is also possible to define settings window for your app where users can customize integration flow.
+
+```javascript
+configuration.projectIntegration.getConfiguration = (projectId, crowdinClient, integrationCredentials) => {
+    return [
+        {
+            label: 'GENERAL'
+        },
+        {
+            key: 'flag',
+            label: 'Checkbox',
+            type: 'checkbox'
+        },
+        {
+            key: 'text',
+            label: 'Text input',
+            type: 'text',
+            helpText: 'Help text'
+        },
+        {
+            key: 'option',
+            label: 'Select',
+            type: 'select',
+            defaultValue: '12',
+            isSearchable: true, //allow to search for option(s), default is `false`
+            isMulti: true, //allow to select multiple options, default is `false`
+            options: [
+                {
+                    value: '12',
+                    label: 'Option'
+                }
+            ]
+        }
+    ]
+}
+
+//auto reload on settings updates
+configuration.projectIntegration.reloadOnConfigSave = true;
+```
+
+## Info window
+
+You also can define section with some information notes or help section for your app.
+
+```javascript
+configuration.projectIntegration.infoModal = {
+    title: 'Info',
+    content: `
+        <h1>This is your app help section</h1>
+        </br>
+        <h2>This is just an example</h2>
+    `
+}
+```
+
+## Background tasks
+
+In order to register background tasks that app will invoke periodically invoke you can use `cronJobs` field.
+
+```javascript
+configuration.projectIntegration.cronJobs = [
+    {
+        //every 10 seconds
+        expression: '*/10 * * * * *',
+        task: (projectId, client, apiCredentials, appRootFolder, config) => {
+            console.log(`Running background task for project : ${projectId}`);
+            console.log(`Api credentials : ${JSON.stringify(apiCredentials)}`);
+            console.log(`App config : ${JSON.stringify(config)}`);
+            console.log(appRootFolder ? JSON.stringify(appRootFolder) : 'No root folder');
+        }
+    }
+]
+```
+
+For cron syntax guide please refer to this [documentation](https://github.com/node-cron/node-cron#cron-syntax).
+
+## Errors Handling
+
+### Error propagation
+
+In case if something is wrong with app settings or credentials are invalid you can throw an explanation message that will be then visible on the UI side.  
+e.g. check if entered credentials are valid:
+
+```javascript
+configuration.projectIntegration.checkConnection = (credentials) => {
+    if (!credentials.password  || credentials.password.length < 6) {
+        throw 'Password is too weak';
+    }
+    //or call an service API with those credentials and check if request will be successful
+};
+```
+
+Or if you need to manually control users liveness session you can throw an error with `401` code then your app will automatically do a log out action.  
+e.g. when your service has some specific session duration timeout or extra conditions which are not covered by this framework
+
+```javascript
+configuration.projectIntegration.getIntegrationFiles = async (credentials, appSettings) => {
+    //do a request/custom logic here
+    const sessionStillValid = false;
+    if (!sessionStillValid) {
+        throw {
+             message: 'session expired',
+             code: 401
+        }
+    }
+    //business logic
+}
+```
+
+### Error interceptor
+
+You can also provide interceptor to catch errors and process them (e.g. to log them in the centralized place).
+
+```javascript
+const Sentry = require('@sentry/node');
+
+Sentry.init({
+  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
+  tracesSampleRate: 1.0,
+});
+
+configuration.onError = (error) => {
+    Sentry.captureException(e);
+};
+```
+
+### Debug mode
+
+Also you can turn on the debug mode and application will log everything (useful of debugging).
+
+```javascript
+configuration.logger = {
+    enabled: true
+};
+```
+
+Or even you can pass you own function to log messages (e.g. send them to external monitoring system).
+
+```javascript
+configuration.logger = {
+    enabled: true,
+    log: (message) => {
+        console.log(message);
+    }
+};
+```
+
+## Modules
+
+### Custom File Format
+
+Example of [custom file format module](https://support.crowdin.com/crowdin-apps-modules/#custom-file-format-module).
+
+```javascript
+const crowdinModule = require('@crowdin/app-project-module');
+const convert = require('xml-js');
+
+const configuration = {
+    baseUrl: 'https://123.ngrok.io',
+    clientId: 'clientId',
+    clientSecret: 'clientSecret',
+    name: 'Sample App',
+    identifier: 'sample-app',
+    description: 'Sample App description',
+    dbFolder: __dirname,
+    imagePath: __dirname + '/' + 'logo.png',
+    customFileFormat: {
+        filesFolder: __dirname,
+        type: 'type-xyz',
+        multilingual: false,
+        autoUploadTranslations: true, //useful when single language format
+        signaturePatterns: {
+            fileName: '^.+\.xml$'
+        },
+        customSrxSupported: true,
+        parseFile: async (file, req, client, context, projectId) => {
+            const xml = convert.xml2json(file, { compact: true, spaces: 4 });
+            const fileContent = JSON.parse(xml);
+            //parse logic
+            const strings = [];
+            return { strings, error: 'Some error message' };
+        },
+        buildFile: async (file, req, strings, client, context, projectId) => {
+            const xml = convert.xml2json(file, { compact: true, spaces: 4 });
+            const fileContent = JSON.parse(xml);
+            //build logic
+            const contentFile = convert.json2xml(
+                fileContent,
+                {
+                    compact: true,
+                    ignoreComment: false,
+                    spaces: 4
+                }
+            );
+            return { contentFile }
+        }
+    }
+};
+
+crowdinModule.createApp(configuration);
+```
+
+Also custom file format module can support strings export.
+
+```javascript
+const crowdinModule = require('@crowdin/app-project-module');
+const convert = require('xml-js');
+
+const configuration = {
+    baseUrl: 'https://123.ngrok.io',
+    clientId: 'clientId',
+    clientSecret: 'clientSecret',
+    name: 'Sample App',
+    identifier: 'sample-app',
+    description: 'Sample App description',
+    dbFolder: __dirname,
+    imagePath: __dirname + '/' + 'logo.png',
+    customFileFormat: {
+        filesFolder: __dirname,
+        type: 'type-xyz',
+        stringsExport: true,
+        multilingualExport: true,
+        extensions: [
+            '.resx'
+        ],
+        exportStrings: async (req, strings, client, context, projectId) => {
+            const file = req.file;
+            //export logic
+            return { contentFile: '' }
+        }
+    }
+};
+
+crowdinModule.createApp(configuration);
+```
+
+By default custom file format will use `filesFolder` as a temporary folder to store huge responses. But it can be overridden:
+
+```javascript
+configuration.customFileFormat.storeFile = (content) => {
+    //logic to store file, e.g. put it to AWS S3
+    return '<url-to-download>';
+};
+```
+
+### Custom MT
+
+Example of [custom mt module](https://support.crowdin.com/crowdin-apps-modules/#custom-mt-machine-translation-module).
+
+```javascript
+const crowdinModule = require('@crowdin/app-project-module');
+
+const configuration = {
+    baseUrl: 'https://123.ngrok.io',
+    clientId: 'clientId',
+    clientSecret: 'clientSecret',
+    name: 'Sample App',
+    identifier: 'sample-app',
+    description: 'Sample App description',
+    dbFolder: __dirname,
+    imagePath: __dirname + '/' + 'logo.png',
+    customMT: {
+        translate: async (client, context, projectId, source, target, strings) => {
+            //translate strings
+            const translations = ['hello', 'world'];
+            if (source === 'fr') {
+                throw 'Source language is not supported by the model';
+            }
+            return translations;
+        }
+    }
+};
+
+crowdinModule.createApp(configuration);
+```
+
+### Profile Resources Menu
+
+Example of [resources module](https://support.crowdin.com/crowdin-apps-modules/#resources-module).
+
+```javascript
+const crowdinModule = require('@crowdin/app-project-module');
+
+const configuration = {
+    baseUrl: 'https://123.ngrok.io',
+    clientId: 'clientId',
+    clientSecret: 'clientSecret',
+    name: 'Sample App',
+    identifier: 'sample-app',
+    description: 'Sample App description',
+    dbFolder: __dirname,
+    imagePath: __dirname + '/' + 'logo.png',
+    profileResourcesMenu: {
+      fileName: 'setup.html',
+      uiPath: __dirname + '/' + 'public',
+      environments: 'crowdin-enterprise',
+    },
+};
+
+crowdinModule.createApp(configuration);
+```
+
+The `profileResourcesMenu` module can work as an extension to other modules be something like a configuration UI for them.
+
+```javascript
+const crowdinModule = require('@crowdin/app-project-module');
+const express = require('express');
+
+const app = express();
+
+const configuration = {
+    baseUrl: 'https://123.ngrok.io',
+    clientId: 'clientId',
+    clientSecret: 'clientSecret',
+    name: 'Sample App',
+    identifier: 'sample-app',
+    description: 'Sample App description',
+    dbFolder: __dirname,
+    imagePath: __dirname + '/' + 'logo.png',
+    profileResourcesMenu: {
+      fileName: 'setup.html',
+      uiPath: __dirname + '/' + 'public',
+      environments: 'crowdin',
+    },
+    customMT: {
+        translate,
+    },
+    onUninstall: cleanup
+};
+
+const crowdinApp = crowdinModule.addCrowdinEndpoints(app, configuration);
+
+async function cleanup(organization, allCredentials) {
+    //Cleanup logic
+    await crowdinApp.deleteMetadata(organization);
+}
+
+async function translate(crowdinClient, context, projectId, source, target, strings) {
+    const organization = context.jwtPayload.domain || context.jwtPayload.context.organization_id;
+    const metadata = await crowdinApp.getMetadata(organization);
+    //do translation based on metadata
+    const translations = ['hello', 'world'];
+    return translations;
+}
+
+//extra endpoints for resources UI
+app.post('/metadata', async (req, res) => {
+    const { context } = await crowdinApp.establishCrowdinConnection(req.query.jwt);
+    const organization = context.jwtPayload.domain || context.jwtPayload.context.organization_id;
+    const metadata = await crowdinApp.getMetadata(organization);
+    await crowdinApp.saveMetadata(organization, req.body);
+    res.status(204).end();
+});
+
+app.get('/metadata', async (req, res) => {
+    const { context } = await crowdinApp.establishCrowdinConnection(req.query.jwt);
+    const organization = context.jwtPayload.domain || context.jwtPayload.context.organization_id;
+    const metadata = await crowdinApp.getMetadata(organization) || {};
+    res.status(200).send(metadata);
+});
+
+app.listen(3000, () =>  console.log('Crowdin app started'));
+```
+
+### Other modules
+
+Framework also supports following modules:
+
+- [organization-menu module](https://support.crowdin.com/enterprise/crowdin-apps-modules/#organization-menu-module)
+- [editor-right-panel module](https://support.crowdin.com/crowdin-apps-modules/#editor-panels-module)
+- [project-menu module](https://support.crowdin.com/crowdin-apps-modules/#project-menu-module)
+- [project-menu-crowdsource module](https://developer.crowdin.com/crowdin-apps-module-project-menu-crowdsource/)
+- [project-tools module](https://support.crowdin.com/crowdin-apps-modules/#tools-module)
+- [project-reports module](https://support.crowdin.com/crowdin-apps-modules/#reports-module)
+
+Example of Project Reports Module:
+
+```javascript
+const crowdinModule = require('@crowdin/app-project-module');
+
+const configuration = {
+    baseUrl: 'https://123.ngrok.io',
+    clientId: 'clientId',
+    clientSecret: 'clientSecret',
+    name: 'Sample App',
+    identifier: 'sample-app',
+    description: 'Sample App description',
+    dbFolder: __dirname,
+    imagePath: __dirname + '/' + 'logo.png',
+    projectReports: { //can be editorRightPanel, projectMenu, projectTools, projectMenuCrowdsource
+      imagePath: __dirname + '/' + 'reports.png',
+      fileName: 'reports.html', //optional, only needed if file is not index.html
+      uiPath: __dirname + '/' + 'public', // folder where UI of the module is located (js, html, css files)
+      allowUnauthorized: true //make module publicly available without crowdin context
+    },
+};
+
+crowdinModule.createApp(configuration);
+```
+
+## Other options
+
+### Options for Crowdin JWT token validation
+
+```js
+configuration.jwtValidationOptions = {
+    ignoreExpiration: false, //ignore check if jwt is expired or not
+};
+```
+
+### App authentication type
+
+```js
+configuration.authenticationType = 'authorization_code'; //default is "crowdin_app"
+```
+
+### Disable global error handling
+
+This module will handle all `unhandledRejection` and `uncaughtException` errors, log them and not kill the Node process.  
+Usually this means that code was not properly designed and contains unsafe places. And not always this built in behaviour will be suitable.  
+Therefore you can disable it:
+
+```js
+configuration.disableGlobalErrorHandling = true;
+```
+
+### Use React JSON Schema forms as module front-end
+
+For all modules that have UI (except of `projectIntegration` module) you can use React JSON Schema forms ([docs](/https://github.com/rjsf-team/react-jsonschema-form)) as front-end.
+To achieve this you can specify property `formSchema` in module definition.
+```js
+configuration.projectMenu = {
+  formSchema: {
+    "title": "A registration form",
+    "description": "A simple form example.",
+    "type": "object",
+    "required": [
+      "firstName",
+      "lastName"
+    ],
+    "properties": {
+      "firstName": {
+        "type": "string",
+        "title": "First name",
+        "default": "Chuck"
+      },
+      "lastName": {
+        "type": "string",
+        "title": "Last name"
+      },
+    }
+  }
+};
+```
+By default, form data will be stored in app metadata. To retrieve data you can use this code:
+```js
+crowdinApp.getMetadata(`${organizationId}-${projectId}`);
+```
+To customize this behavior you can provide `formDataUrl` property that will contain URL to custom action in your app. This action should support both GET request for fetching data and POST request to save new data.
 
 ## Contributing