@app-connect/core 1.7.21 → 1.7.22

package/docs/models.md

@@ -0,0 +1,144 @@
+# Models
+
+The package uses Sequelize for durable application data and Dynamoose for selected config and cache workflows.
+
+## Sequelize Models
+
+### `models/sequelize.js`
+
+Creates the shared Sequelize instance from `DATABASE_URL`.
+
+### `models/userModel.js`
+
+Stores CRM-authenticated users.
+
+| Field | Notes |
+| --- | --- |
+| `id` | Primary key; effectively `{crmUserId}-{platform}` |
+| `rcAccountId` | RingCentral account id |
+| `hostname` | CRM hostname or tenant host |
+| `timezoneName` | User timezone name when available |
+| `timezoneOffset` | Offset stored as a string |
+| `platform` | Connector platform name |
+| `accessToken` | OAuth access token or API key |
+| `refreshToken` | OAuth refresh token |
+| `tokenExpiry` | Access token expiry |
+| `platformAdditionalInfo` | Connector-specific metadata such as `proxyId` or token URL |
+| `hashedRcExtensionId` | Hashed RingCentral extension id |
+| `userSettings` | Per-user settings JSON |
+
+### `models/callLogModel.js`
+
+Stores the mapping between telephony sessions and CRM call logs.
+
+| Field | Notes |
+| --- | --- |
+| `id` | Telephony call id |
+| `sessionId` | Session id; also part of the composite primary key |
+| `platform` | Connector platform |
+| `thirdPartyLogId` | CRM log id |
+| `userId` | App Connect user id |
+| `contactId` | CRM contact id used for the log |
+
+### `models/messageLogModel.js`
+
+Stores message-log linkage records.
+
+| Field | Notes |
+| --- | --- |
+| `id` | Message id or conversation log id |
+| `platform` | Connector platform |
+| `conversationId` | Conversation identifier |
+| `conversationLogId` | Shared key used to group related message logs |
+| `thirdPartyLogId` | CRM log id |
+| `userId` | App Connect user id |
+
+### `models/adminConfigModel.js`
+
+Stores account-level admin configuration.
+
+| Field | Notes |
+| --- | --- |
+| `id` | Hashed RingCentral account id |
+| `userSettings` | Account-level settings policy |
+| `customAdapter` | Obsolete field kept for compatibility |
+| `adminAccessToken` | RingCentral admin access token |
+| `adminRefreshToken` | RingCentral admin refresh token |
+| `adminTokenExpiry` | Admin token expiry |
+| `userMappings` | JSON mapping between CRM users and RingCentral extensions |
+
+### `models/cacheModel.js`
+
+Stores temporary task state, mainly for async plugin work.
+
+| Field | Notes |
+| --- | --- |
+| `id` | Task id, commonly `{userId}-{uuid}` |
+| `status` | Task status such as `initialized`, `completed`, or `failed` |
+| `userId` | Owning user |
+| `cacheKey` | Logical task family |
+| `data` | Optional task payload |
+| `expiry` | Cleanup cutoff |
+
+### `models/accountDataModel.js`
+
+Stores account-scoped cached data.
+
+Composite primary key:
+
+- `rcAccountId`
+- `platformName`
+- `dataKey`
+
+Main usage in current code:
+
+- cached contact lookups keyed as `contact-${phoneNumber}`
+
+Helper export:
+
+- `getOrRefreshAccountData()` which returns cached data unless `forceRefresh` is set
+
+### `models/callDownListModel.js`
+
+Stores user-owned call-down queue items.
+
+| Field | Notes |
+| --- | --- |
+| `id` | Primary key |
+| `userId` | Owning user |
+| `contactId` | CRM contact id |
+| `contactType` | Contact entity type |
+| `status` | Queue state such as `scheduled` or `called` |
+| `scheduledAt` | Requested follow-up time |
+| `lastCallAt` | Last call timestamp |
+
+This model enables timestamps and indexes on `userId`, `status`, `scheduledAt`, and `userId + status`.
+
+### `models/llmSessionModel.js`
+
+Stores a lightweight mapping from an LLM session id to a JWT token.
+
+## Dynamoose Models
+
+### `models/dynamo/connectorSchema.js`
+
+Stores connector metadata used by proxy integrations.
+
+Important role:
+
+- source of truth for `Connector.getProxyConfig(proxyId)`
+
+This schema is a dependency of auth, contact, log, admin, and proxy connector flows.
+
+### `models/dynamo/lockSchema.js`
+
+Stores distributed lock state used by token refresh and similar coordination logic.
+
+### `models/dynamo/noteCacheSchema.js`
+
+Stores note cache entries keyed by `sessionId`.
+
+Main usage:
+
+- `handlers/log.js` can read cached notes during server-side call logging
+- `saveNoteCache()` writes entries with a TTL

package/docs/routes.md

@@ -0,0 +1,115 @@
+# Core Routes
+
+This page documents the non-MCP HTTP routes defined in `index.js`.
+
+## Route Design Notes
+
+- Most routes accept a `jwtToken` query parameter and resolve the current user from it.
+- Many routes emit analytics using request headers such as `rc-extension-id`, `rc-account-id`, `user-agent`, `developer-author-name`, and `eventAddedVia`.
+- When the request header `is-debug` is set to `'true'`, route handlers can return `DebugTracer` output wrappers.
+- Several routes are marked obsolete in code but still present for compatibility.
+
+## System And Metadata Routes
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/releaseNotes` | Merges package release notes with connector release notes |
+| `GET` | `/crmManifest` | Returns a platform manifest, with optional server URL overrides |
+| `GET` | `/isAlive` | Simple health check returning `OK` |
+| `GET` | `/implementedInterfaces` | Reports which connector methods exist for a platform |
+| `GET` | `/serverVersionInfo` | Returns manifest version data; marked obsolete in code |
+| `GET` | `/.well-known/openai-apps-challenge` | Returns the ChatGPT verification code |
+| `GET` | `/.well-known/oauth-protected-resource` | OAuth protected-resource metadata |
+| `GET` | `/.well-known/oauth-authorization-server` | OAuth authorization-server metadata |
+| `GET` | `/oauth/authorize_shim` | Rebuilds OAuth params and redirects to RingCentral |
+| `POST` | `/oauth/register` | Returns RingCentral client credentials for the shim flow |
+
+## Authentication Routes
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/licenseStatus` | Checks connector-specific license status for the current user |
+| `GET` | `/authValidation` | Verifies the current CRM auth session |
+| `GET` | `/hostname` | Returns host-related info used during auth flows |
+| `GET` | `/oauth-callback` | Completes connector OAuth and persists the user |
+| `POST` | `/apiKeyLogin` | Handles API-key based login flows |
+| `GET` | `/apiKeyManagedAuthState` | Returns required-field readiness for shared API-key auth |
+| `POST` | `/unAuthorize` | Logs the user out of the CRM |
+| `GET` | `/userInfoHash` | Returns a hash derived from user information |
+| `GET` | `/ringcentral/oauth/callback` | Completes the admin RingCentral OAuth callback |
+
+## Admin Routes
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/admin/settings` | Validates RingCentral admin role and saves admin settings |
+| `GET` | `/admin/settings` | Returns admin settings for the current account |
+| `POST` | `/admin/userMapping` | Builds a mapping between CRM users and RingCentral extensions |
+| `POST` | `/admin/reinitializeUserMapping` | Rebuilds user mappings from scratch |
+| `GET` | `/admin/serverLoggingSettings` | Loads connector-specific server logging settings |
+| `POST` | `/admin/serverLoggingSettings` | Updates connector-specific server logging settings |
+| `GET` | `/admin/managedAuth` | Returns admin-facing managed-auth field definitions and masked stored values |
+| `POST` | `/admin/managedAuth` | Upserts org-level or extension-level managed auth values |
+| `GET` | `/ringcentral/admin/report` | Returns aggregated RingCentral call activity metrics |
+| `GET` | `/ringcentral/admin/userReport` | Returns per-extension call and SMS metrics |
+
+## User Settings Routes
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/user/preloadSettings` | Loads settings used to bootstrap client-side configuration |
+| `GET` | `/user/settings` | Returns merged user and admin settings |
+| `POST` | `/user/settings` | Updates per-user settings, with connector hooks when present |
+
+## Contact Routes
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/contact` | Finds contacts by phone number |
+| `POST` | `/contact` | Creates a new contact |
+| `GET` | `/custom/contact/search` | Finds contacts by name |
+
+## Logging And Disposition Routes
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/callLog/cacheNote` | Stores a temporary note for server-side call logging |
+| `GET` | `/callLog` | Looks up existing call logs by session id |
+| `POST` | `/callLog` | Creates a CRM call log and stores the local linkage record |
+| `PATCH` | `/callLog` | Updates an existing CRM call log |
+| `PUT` | `/callDisposition` | Upserts call disposition data through the connector |
+| `POST` | `/messageLog` | Creates or updates CRM logs for SMS, fax, and shared SMS |
+
+## Call-Down Routes
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/calldown` | Schedules a call-down item |
+| `GET` | `/calldown` | Lists the current user's call-down items |
+| `DELETE` | `/calldown/:id` | Removes a call-down item |
+| `PATCH` | `/calldown/:id` | Updates or marks a call-down item |
+
+## Plugin And Debug Routes
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/debug/report/url` | Returns a presigned URL for error log upload |
+| `POST` | `/pluginAsyncTask` | Returns async plugin task status and cleans up finished task cache entries |
+
+## Development-Only Mock Routes
+
+These routes are only mounted when `IS_PROD === 'false'`.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/registerMockUser` | Creates a mock user |
+| `DELETE` | `/deleteMockUser` | Removes a mock user |
+| `GET` | `/mockCallLog` | Reads mock call logs |
+| `POST` | `/mockCallLog` | Creates a mock call log |
+| `DELETE` | `/mockCallLog` | Clears mock call logs |
+
+## Operational Notes
+
+- `createCoreRouter()` currently contains a large amount of orchestration logic in addition to route registration.
+- Most route handlers duplicate a common pattern: decode JWT, load user, resolve connector, refresh auth, call handler, then track analytics.
+- If route count continues growing, this file is a strong candidate for modular route extraction by feature area.

package/docs/tests.md

@@ -0,0 +1,73 @@
+# Tests
+
+This page maps the non-MCP test suite under `packages/core/test`.
+
+## Test Setup
+
+| File | Purpose |
+| --- | --- |
+| `test/setup.js` | Shared test bootstrapping for Jest |
+| `jest.config.js` | Package-local Jest configuration |
+
+## Connector Tests
+
+| File | Coverage |
+| --- | --- |
+| `test/connector/registry.test.js` | Registry behavior, connector registration, and interface composition |
+| `test/connector/proxy/engine.test.js` | Proxy request rendering, auth header building, and response mapping |
+| `test/connector/proxy/index.test.js` | Proxy connector behavior across connector operations |
+| `test/connector/proxy/sample.json` | Sample proxy config fixture used by tests |
+
+## Handler Tests
+
+| File | Coverage |
+| --- | --- |
+| `test/handlers/admin.test.js` | Admin settings and reporting behavior |
+| `test/handlers/auth.test.js` | OAuth, API-key login, and auth validation behavior |
+| `test/handlers/contact.test.js` | Contact lookup and creation flows |
+| `test/handlers/log.test.js` | Call-log and message-log workflows |
+| `test/handlers/plugin.test.js` | Async plugin task polling and cleanup |
+| `test/handlers/managedAuth.test.js` | Shared-auth field loading, encryption, masking, and login-time field resolution |
+
+## Route Tests
+
+| File | Coverage |
+| --- | --- |
+| `test/routes/managedAuthRoutes.test.js` | Shared-auth API route behavior and validation paths |
+
+## Library Tests
+
+| File | Coverage |
+| --- | --- |
+| `test/lib/callLogComposer.test.js` | Call-log formatting |
+| `test/lib/debugTracer.test.js` | Debug trace capture and serialization |
+| `test/lib/jwt.test.js` | JWT sign and verify helpers |
+| `test/lib/logger.test.js` | Logger behavior |
+| `test/lib/oauth.test.js` | OAuth client and token-refresh behavior |
+| `test/lib/ringcentral.test.js` | RingCentral API wrapper helpers |
+| `test/lib/sharedSMSComposer.test.js` | Shared-SMS formatting |
+| `test/lib/util.test.js` | Hashing, formatting, and utility helpers |
+
+## Model Tests
+
+| File | Coverage |
+| --- | --- |
+| `test/models/models.test.js` | General Sequelize model behavior |
+| `test/models/accountDataModel.test.js` | Account-data cache behavior |
+| `test/models/dynamo/connectorSchema.test.js` | Dynamo-backed connector schema behavior |
+
+## Coverage Gaps To Be Aware Of
+
+The current non-MCP test suite does not appear to have direct dedicated files for:
+
+- `handlers/calldown.js`
+- `handlers/disposition.js`
+- `lib/authSession.js`
+- `lib/encode.js`
+- `lib/errorHandler.js`
+- `lib/generalErrorMessage.js`
+- `lib/s3ErrorLogReport.js`
+- `models/callDownListModel.js`
+- `models/llmSessionModel.js`
+- `models/dynamo/lockSchema.js`
+- `models/dynamo/noteCacheSchema.js`

package/handlers/admin.js

@@ -8,10 +8,29 @@ const logger = require('../lib/logger');
 const { handleDatabaseError } = require('../lib/errorHandler');
 
 const CALL_AGGREGATION_GROUPS = ["Company", "CompanyNumbers", "Users", "Queues", "IVRs", "IVAs", "SharedLines", "UserGroups", "Sites", "Departments"]
+const RC_EXTENSION_ENDPOINT = 'https://platform.ringcentral.com/restapi/v1.0/account/~/extension/~';
+
+async function validateRcUserToken({ rcAccessToken }) {
+    if (!rcAccessToken) {
+        throw new Error('rcAccessToken is required');
+    }
+    const rcExtensionResponse = await axios.get(
+        RC_EXTENSION_ENDPOINT,
+        {
+            headers: {
+                Authorization: `Bearer ${rcAccessToken}`,
+            },
+        });
+    const extensionData = rcExtensionResponse.data ?? {};
+    return {
+        rcAccountId: extensionData?.account?.id?.toString() ?? '',
+        rcExtensionId: extensionData?.id?.toString() ?? ''
+    };
+}
 
 async function validateAdminRole({ rcAccessToken }) {
     const rcExtensionResponse = await axios.get(
-        'https://platform.ringcentral.com/restapi/v1.0/account/~/extension/~',
+        RC_EXTENSION_ENDPOINT,
         {
             headers: {
                 Authorization: `Bearer ${rcAccessToken}`,
@@ -489,6 +508,7 @@ async function reinitializeUserMapping({ user, hashedRcAccountId, rcExtensionLis
 }
 
 exports.validateAdminRole = validateAdminRole;
+exports.validateRcUserToken = validateRcUserToken;
 exports.upsertAdminSettings = upsertAdminSettings;
 exports.getAdminSettings = getAdminSettings;
 exports.updateAdminRcTokens = updateAdminRcTokens;
@@ -497,4 +517,4 @@ exports.updateServerLoggingSettings = updateServerLoggingSettings;
 exports.getAdminReport = getAdminReport;
 exports.getUserReport = getUserReport;
 exports.getUserMapping = getUserMapping;
-exports.reinitializeUserMapping = reinitializeUserMapping;
+exports.reinitializeUserMapping = reinitializeUserMapping;

package/handlers/auth.js

@@ -6,6 +6,7 @@ const { RingCentral } = require('../lib/ringcentral');
 const adminCore = require('./admin');
 const { Connector } = require('../models/dynamo/connectorSchema');
 const { handleDatabaseError } = require('../lib/errorHandler');
+const managedAuthCore = require('./managedAuth');
 
 async function onOAuthCallback({ platform, hostname, tokenUrl, query, hashedRcExtensionId, isFromMCP = false }) {
     const callbackUri = query.callbackUri;
@@ -77,11 +78,50 @@ async function onOAuthCallback({ platform, hostname, tokenUrl, query, hashedRcEx
     }
 }
 
-async function onApiKeyLogin({ platform, hostname, apiKey, proxyId, rcAccountId, hashedRcExtensionId, additionalInfo }) {
+async function onApiKeyLogin({ platform, hostname, apiKey, proxyId, rcAccountId, rcExtensionId, connectorId, isPrivate, hashedRcExtensionId, additionalInfo }) {
     const platformModule = connectorRegistry.getConnector(platform);
-    const basicAuth = platformModule.getBasicAuth({ apiKey });
-    const { successful, platformUserInfo, returnMessage } = await platformModule.getUserInfo({ authHeader: `Basic ${basicAuth}`, hostname, platform, additionalInfo, apiKey, proxyId });
+    let resolvedAdditionalInfo = additionalInfo;
+    let resolvedApiKey = apiKey;
+    if (rcAccountId && rcExtensionId) {
+        const managedFieldDefinitions = await managedAuthCore.getManagedFieldDefinitions({ platform, connectorId, isPrivate });
+        const shouldFallbackToManualAuth = managedFieldDefinitions.length > 0
+            && await managedAuthCore.hasManagedAuthLoginFailure({ rcAccountId, platform, rcExtensionId });
+        const managedAuthResult = await managedAuthCore.resolveApiKeyLoginFields({
+            platform,
+            rcAccountId,
+            rcExtensionId,
+            connectorId,
+            isPrivate,
+            apiKey,
+            additionalInfo,
+            preferSubmittedValuesForManagedFields: shouldFallbackToManualAuth
+        });
+        resolvedAdditionalInfo = managedAuthResult.resolvedAdditionalInfo;
+        resolvedApiKey = managedAuthResult.resolvedApiKey;
+        const missingRequiredFieldConsts = managedAuthResult.missingRequiredFieldConsts;
+        if (missingRequiredFieldConsts.length > 0) {
+            return {
+                userInfo: null,
+                returnMessage: {
+                    messageType: 'warning',
+                    message: 'Missing required authentication fields.',
+                    ttl: 3000,
+                    missingRequiredFieldConsts
+                }
+            };
+        }
+    }
+    const basicAuth = platformModule.getBasicAuth({ apiKey: resolvedApiKey });
+    const { successful, platformUserInfo, returnMessage } = await platformModule.getUserInfo({
+        authHeader: `Basic ${basicAuth}`,
+        hostname,
+        platform,
+        additionalInfo: resolvedAdditionalInfo,
+        apiKey: resolvedApiKey,
+        proxyId
+    });
     if (successful) {
+        await managedAuthCore.clearManagedAuthLoginFailure({ rcAccountId, platform, rcExtensionId });
         let userInfo = null;
         try {
             userInfo = await saveUserInfo({
@@ -91,7 +131,7 @@ async function onApiKeyLogin({ platform, hostname, apiKey, proxyId, rcAccountId,
                 proxyId,
                 hashedRcExtensionId,
                 rcAccountId,
-                accessToken: platformUserInfo.overridingApiKey ?? apiKey
+                accessToken: platformUserInfo.overridingApiKey ?? resolvedApiKey
             });
         }
         catch (error) {
@@ -105,11 +145,12 @@ async function onApiKeyLogin({ platform, hostname, apiKey, proxyId, rcAccountId,
             returnMessage
         };
     }
-    else {
-        return {
-            userInfo: null,
-            returnMessage
-        }
+    if (managedFieldDefinitions.length > 0) {
+        await managedAuthCore.markManagedAuthLoginFailure({ rcAccountId, platform, rcExtensionId });
+    }
+    return {
+        userInfo: null,
+        returnMessage
     }
 }
 
@@ -244,4 +285,4 @@ exports.onOAuthCallback = onOAuthCallback;
 exports.onApiKeyLogin = onApiKeyLogin;
 exports.authValidation = authValidation;
 exports.getLicenseStatus = getLicenseStatus;
-exports.onRingcentralOAuthCallback = onRingcentralOAuthCallback;
+exports.onRingcentralOAuthCallback = onRingcentralOAuthCallback;

package/handlers/log.js

@@ -405,11 +405,11 @@ async function updateCallLog({ jwtToken, platform, userId, incomingData, hashedA
                 let pluginDataResponse = null;
                 switch (pluginSetting.value.access) {
                     case 'public':
-                        pluginDataResponse = await axios.get(`${process.env.DEV_PORTAL_URL}/public-api/connectors/${pluginId}/manifest?type=plugin`);
+                        pluginDataResponse = await axios.get(`https://appconnect.labs.ringcentral.com/public-api/connectors/${pluginId}/manifest?type=plugin`);
                         break;
                     case 'private':
                     case 'shared':
-                        pluginDataResponse = await axios.get(`${process.env.DEV_PORTAL_URL}/public-api/connectors/${pluginId}/manifest?access=internal&type=connector&accountId=${user.rcAccountId}`);
+                        pluginDataResponse = await axios.get(`https://appconnect.labs.ringcentral.com/public-api/connectors/${pluginId}/manifest?access=internal&type=connector&accountId=${user.rcAccountId}`);
                         break;
                     default:
                         throw new Error('Invalid plugin access');
@@ -643,11 +643,11 @@ async function createMessageLog({ platform, userId, incomingData }) {
             let pluginDataResponse = null;
             switch (pluginSetting.value.access) {
                 case 'public':
-                    pluginDataResponse = await axios.get(`${process.env.DEV_PORTAL_URL}/public-api/connectors/${pluginId}/manifest?type=plugin`);
+                    pluginDataResponse = await axios.get(`https://appconnect.labs.ringcentral.com/public-api/connectors/${pluginId}/manifest?type=plugin`);
                     break;
                 case 'private':
                 case 'shared':
-                    pluginDataResponse = await axios.get(`${process.env.DEV_PORTAL_URL}/public-api/connectors/${pluginId}/manifest?access=internal&type=connector&accountId=${user.rcAccountId}`);
+                    pluginDataResponse = await axios.get(`https://appconnect.labs.ringcentral.com/public-api/connectors/${pluginId}/manifest?access=internal&type=connector&accountId=${user.rcAccountId}`);
                     break;
                 default:
                     throw new Error('Invalid plugin access');