@app-connect/core 1.7.37 → 1.7.38

package/connector/registry.js

@@ -1,252 +0,0 @@
-// core/src/connector/registry.js
-const logger = require('../lib/logger');
-class ConnectorRegistry {
-  constructor() {
-      this.connectors = new Map();
-      this.manifests = new Map();
-      this.releaseNotes = {};
-      this.platformInterfaces = new Map(); // Store interface functions per platform
-  }
-
-  setDefaultManifest(manifest) {
-    this.manifests.set('default', manifest);
-  }
-
-  /**
-   * Register an interface function for a specific platform
-   * @param {string} platformName - Platform identifier (e.g., 'pipedrive', 'salesforce')
-   * @param {string} interfaceName - Interface function name (e.g., 'createCallLog', 'findContact')
-   * @param {Function} interfaceFunction - The interface function to register
-   */
-  registerConnectorInterface(platformName, interfaceName, interfaceFunction) {
-    if (typeof interfaceFunction !== 'function') {
-      throw new Error(`Interface function must be a function, got: ${typeof interfaceFunction}`);
-    }
-
-    if (!this.platformInterfaces.has(platformName)) {
-      this.platformInterfaces.set(platformName, new Map());
-    }
-
-    const platformInterfaceMap = this.platformInterfaces.get(platformName);
-    platformInterfaceMap.set(interfaceName, interfaceFunction);
-
-    logger.info(`Registered interface function: ${platformName}.${interfaceName}`);
-  }
-
-  /**
-   * Get registered interface functions for a platform
-   * @param {string} platformName - Platform identifier
-   * @returns {Map} Map of interface functions
-   */
-  getPlatformInterfaces(platformName) {
-    return this.platformInterfaces.get(platformName) || new Map();
-  }
-
-  /**
-   * Check if an interface function is registered for a platform
-   * @param {string} platformName - Platform identifier
-   * @param {string} interfaceName - Interface function name
-   * @returns {boolean} True if interface is registered
-   */
-  hasPlatformInterface(platformName, interfaceName) {
-    const platformInterfaceMap = this.platformInterfaces.get(platformName);
-    return platformInterfaceMap ? platformInterfaceMap.has(interfaceName) : false;
-  }
-
-  /**
-   * Unregister an interface function for a platform
-   * @param {string} platformName - Platform identifier
-   * @param {string} interfaceName - Interface function name
-   */
-  unregisterConnectorInterface(platformName, interfaceName) {
-    const platformInterfaceMap = this.platformInterfaces.get(platformName);
-    if (platformInterfaceMap && platformInterfaceMap.has(interfaceName)) {
-      platformInterfaceMap.delete(interfaceName);
-      logger.info(`Unregistered interface function: ${platformName}.${interfaceName}`);
-    }
-  }
-
-  /**
-   * Register an connector with the core system
-   * @param {string} platform - Platform identifier (e.g., 'pipedrive', 'salesforce')
-   * @param {Object} connector - Connector implementation
-   * @param {Object} manifest - Connector manifest configuration
-   */
-  registerConnector(platform, connector, manifest = null) {
-      // Validate connector interface
-      this.validateConnectorInterface(platform, connector);
-      
-      this.connectors.set(platform, connector);
-      if (manifest) {
-        this.manifests.set(platform, manifest);
-      }
-      
-      logger.info(`Registered connector: ${platform}`);
-  }
-
-  /**
-   * Get connector by platform name with composed interfaces
-   * @param {string} platform - Platform identifier
-   * @returns {Object} Composed connector with interface functions
-   */
-  getConnector(platform) {
-      let connector = this.connectors.get(platform);
-      const platformInterfaceMap = this.platformInterfaces.get(platform);
-
-      if (!connector && (!platformInterfaceMap || platformInterfaceMap.size === 0)) {
-        connector = this.connectors.get('proxy');
-        if (connector) {
-          return connector;
-        }
-        throw new Error(`Connector not found for platform: ${platform}`);
-      }
-
-      // If no connector but interfaces exist, create a composed object with just interfaces
-      if (!connector && platformInterfaceMap && platformInterfaceMap.size > 0) {
-          const composedConnector = {};
-
-          // Add interface functions to the composed connector
-          for (const [interfaceName, interfaceFunction] of platformInterfaceMap) {
-              composedConnector[interfaceName] = interfaceFunction;
-          }
-
-          logger.info(`Returning interface-only connector for platform: ${platform}`);
-          return composedConnector;
-      }
-
-      // If connector exists but no interfaces, return original connector
-      if (connector && (!platformInterfaceMap || platformInterfaceMap.size === 0)) {
-          return connector;
-      }
-
-      // If both connector and interfaces exist, create a composed object
-      const composedConnector = Object.create(connector);
-
-      // Add interface functions to the composed connector
-      for (const [interfaceName, interfaceFunction] of platformInterfaceMap) {
-        // Only add if the interface doesn't already exist in the connector
-        if (!Object.prototype.hasOwnProperty.call(connector, interfaceName)) {
-          composedConnector[interfaceName] = interfaceFunction;
-        }
-      }
-
-      return composedConnector;
-  }
-
-  /**
-   * Get the original connector without composed interfaces
-   * @param {string} platform - Platform identifier
-   * @returns {Object} Original connector implementation
-   */
-  getOriginalConnector(platform) {
-    const connector = this.connectors.get(platform);
-    if (!connector) {
-      throw new Error(`Connector not found for platform: ${platform}`);
-    }
-    return connector;
-  }
-
-  /**
-   * Get manifest for a platform
-   * @param {string} platform - Platform identifier
-   * @returns {Object} Manifest configuration
-   */
-  getManifest(platform, fallbackToDefault = false) {
-      let manifest = this.manifests.get(platform);
-      if (!manifest && fallbackToDefault) {
-        manifest = this.manifests.get('default');
-      }
-      if (!manifest) {
-        throw new Error(`Manifest not found for platform: ${platform}`);
-      }
-      return manifest;
-  }
-
-  /**
-   * Get all registered platforms
-   * @returns {Array<string>} Array of platform names
-   */
-  getRegisteredPlatforms() {
-      return Array.from(this.connectors.keys());
-  }
-
-  /**
-   * Check if platform is registered
-   * @param {string} platform - Platform identifier
-   * @returns {boolean} True if platform is registered
-   */
-  isRegistered(platform) {
-      return this.connectors.has(platform);
-  }
-
-  /**
-   * Validate that connector implements required interface
-   * @param {Object} connector - Connector to validate
-   */
-  validateConnectorInterface(platform, connector) {
-      const requiredMethods = [
-          'createCallLog',
-          'updateCallLog',
-      ];
-
-      for (const method of requiredMethods) {
-          if (typeof connector[method] !== 'function') {
-              throw new Error(`Connector ${platform} missing required method: ${method}`);
-          }
-      }
-  }
-
-  /**
-   * Unregister an connector
-   * @param {string} platform - Platform identifier
-   */
-  unregisterConnector(platform) {
-      this.connectors.delete(platform);
-      this.manifests.delete(platform);
-      this.platformInterfaces.delete(platform);
-      logger.info(`Unregistered connector: ${platform}`);
-  }
-
-  setReleaseNotes(releaseNotes) {
-    this.releaseNotes = releaseNotes;
-  }
-
-  getReleaseNotes() {
-    return this.releaseNotes; 
-  }
-
-  /**
-   * Get connector capabilities summary including composed interfaces
-   * @param {string} platform - Platform identifier
-   * @returns {Object} Connector capabilities
-   */
-  async getConnectorCapabilities(platform) {
-    const originalConnector = this.getOriginalConnector(platform);
-    const composedConnector = this.getConnector(platform);
-    const platformInterfaceMap = this.getPlatformInterfaces(platform);
-    
-    const capabilities = {
-      platform,
-      originalMethods: Object.keys(originalConnector),
-      composedMethods: Object.keys(composedConnector),
-      registeredInterfaces: Array.from(platformInterfaceMap.keys()),
-      authType: null
-    };
-
-    // Get auth type if available
-    if (typeof originalConnector.getAuthType === 'function') {
-      try {
-        capabilities.authType = await originalConnector.getAuthType();
-      } catch (error) {
-        logger.error('Error getting auth type', { stack: error.stack });
-        capabilities.authType = 'unknown';
-      }
-    }
-
-    return capabilities;
-  }
-}
-
-// Export singleton instance
-const connectorRegistry = new ConnectorRegistry();
-module.exports = connectorRegistry;

package/docs/README.md

@@ -1,50 +0,0 @@
-# App Connect Core Docs
-
-This docs set explains the maintained code under `packages/core`, excluding the `mcp/` subsystem.
-
-Use it when you need to change shared backend behavior, trace a request through the framework, or understand which module owns a feature.
-
-## Scope
-
-Included:
-
-- root package entrypoints and route assembly
-- connector infrastructure
-- handlers
-- models, including DynamoDB-backed schemas used outside MCP
-- shared libraries
-- tests that cover the non-MCP package surface
-
-Excluded:
-
-- `mcp/`
-- generated output such as `coverage/`
-- vendored dependencies such as `node_modules/`
-
-## Reading Order
-
-1. [Architecture](architecture.md) for the runtime shape and request flow
-2. [Routes](routes.md) for the HTTP surface in `index.js`
-3. [Handlers](handlers.md) for shared business logic
-4. [Connectors](connectors.md) for registration, proxy behavior, and developer-portal helpers
-5. [Models](models.md) for persistence
-6. [Libraries](libraries.md) for shared helpers and infrastructure code
-7. [Tests](tests.md) for current automated coverage
-
-## File Map
-
-| Area | Files |
-| --- | --- |
-| Package root | `index.js`, `package.json`, `README.md`, `releaseNotes.json`, `jest.config.js` |
-| Connectors | `connector/registry.js`, `connector/developerPortal.js`, `connector/mock.js`, `connector/proxy/index.js`, `connector/proxy/engine.js` |
-| Handlers | `handlers/admin.js`, `handlers/auth.js`, `handlers/calldown.js`, `handlers/contact.js`, `handlers/disposition.js`, `handlers/log.js`, `handlers/plugin.js`, `handlers/managedAuth.js`, `handlers/user.js` |
-| Sequelize models | `models/accountDataModel.js`, `models/adminConfigModel.js`, `models/cacheModel.js`, `models/callDownListModel.js`, `models/callLogModel.js`, `models/llmSessionModel.js`, `models/messageLogModel.js`, `models/sequelize.js`, `models/userModel.js` |
-| DynamoDB models | `models/dynamo/connectorSchema.js`, `models/dynamo/lockSchema.js`, `models/dynamo/noteCacheSchema.js` |
-| Libraries | `lib/analytics.js`, `lib/authSession.js`, `lib/callLogComposer.js`, `lib/constants.js`, `lib/debugTracer.js`, `lib/encode.js`, `lib/errorHandler.js`, `lib/generalErrorMessage.js`, `lib/jwt.js`, `lib/logger.js`, `lib/oauth.js`, `lib/ringcentral.js`, `lib/s3ErrorLogReport.js`, `lib/sharedSMSComposer.js`, `lib/util.js` |
-| Tests | `test/setup.js`, `test/connector/**`, `test/handlers/**`, `test/lib/**`, `test/models/**`, `test/routes/**` excluding `test/mcp/**` |
-
-## Relationship To The Package README
-
-The package [README.md](../README.md) is still the best public-facing quick start.
-
-This docs set is the maintainer-oriented reference for the internals behind that API surface.

package/docs/architecture.md

@@ -1,94 +0,0 @@
-# Core Architecture
-
-This package is the reusable backend framework behind App Connect server deployments.
-
-Its job is to expose a stable HTTP surface, persist shared state, and delegate CRM-specific work to registered connectors.
-
-## Main Entry Points
-
-`index.js` exports the package assembly surface:
-
-| Export | Purpose |
-| --- | --- |
-| `createCoreApp(options)` | Builds an Express app, installs middleware, and mounts the shared router |
-| `createCoreMiddleware()` | Returns the common JSON, XML, and CORS middleware stack |
-| `createCoreRouter()` | Creates the shared route layer without creating a full app |
-| `initializeCore(options)` | Initializes analytics and database synchronization |
-| `connectorRegistry` | Global registry for manifests, release notes, connectors, and interface composition |
-| `proxyConnector` | Proxy-driven connector implementation used for config-based integrations |
-| `DebugTracer` | Request-level debug tracing helper |
-
-## Runtime Responsibilities
-
-`index.js` owns the framework assembly:
-
-- configures local DynamoDB support when `DYNAMODB_LOCALHOST` is set
-- installs an axios interceptor in local-style environments
-- syncs Sequelize models on startup unless `DISABLE_SYNC_DB_TABLE` or `skipDatabaseInit` disables it
-- adds the `hashedRcExtensionId` column to `users` if an older schema is missing it
-- migrates `callLogs` to include `hashedExtensionId` in the local call-log identity key when an older schema is missing it
-- mounts all shared HTTP routes
-- exposes dev-only mock routes when `IS_PROD === 'false'`
-
-## Request Flow
-
-The non-MCP request path is:
-
-1. Express receives a request through `createCoreApp()` or `createCoreRouter()`.
-2. Core middleware parses JSON or XML and applies CORS defaults.
-3. Route handlers in `index.js` decode JWTs, gather analytics metadata, and call a shared handler.
-4. Handlers load the current user and connector, refresh auth if needed, and call the connector operation.
-5. Models persist linkage data such as user sessions, call log ids, cached account data, and plugin task state.
-6. Libraries compose payloads, normalize errors, emit analytics, and handle logging.
-
-## Connector-Centered Design
-
-The package keeps route shapes and handler logic shared across platforms by pushing CRM-specific behavior behind the connector interface.
-
-Important consequences:
-
-- handlers decide when to load a connector and how to authenticate against it
-- connectors decide how to talk to a CRM
-- proxy connectors make many integrations data-driven instead of code-driven
-- registry-level interface composition lets a platform add methods without mutating the original connector object
-
-## Persistence Layers
-
-There are two storage styles in this package:
-
-- Sequelize models for relational/shared application state
-- Dynamoose models for selected operational state such as proxy connector definitions, distributed locks, and note cache entries
-
-`AccountDataModel` also stores encrypted shared API-key auth values. Shared auth intentionally stays separate from `AdminConfigModel.userMappings`:
-
-- `managed-auth-org` stores account-scoped encrypted auth field values
-- `managed-auth-user` stores per-extension encrypted auth field values
-- server-side logging user mapping continues to live in admin config and is not reused for managed auth
-
-## Cross-Cutting Concerns
-
-Several concerns are applied in multiple modules:
-
-- OAuth refresh via `lib/oauth.js`
-- RingCentral admin and reporting helpers via `lib/ringcentral.js`
-- response-safe error shaping via `lib/errorHandler.js`
-- analytics events via `lib/analytics.js`
-- opt-in debug traces via `lib/debugTracer.js`
-- structured server logging via `lib/logger.js`
-
-## Important Environment Variables
-
-| Variable | Why it matters |
-| --- | --- |
-| `DATABASE_URL` | Sequelize connection string |
-| `DISABLE_SYNC_DB_TABLE` | Skips model sync in `initDB()` |
-| `MIXPANEL_TOKEN` | Enables analytics tracking |
-| `APP_SERVER_SECRET_KEY` | Signs and verifies JWTs and encrypts stored managed auth values |
-| `HASH_KEY` | Hashes RingCentral account and extension identifiers |
-| `DYNAMODB_LOCALHOST` | Points Dynamoose to a local endpoint |
-| `IS_PROD` | Enables local-only logging and mock routes when set to `'false'` |
-| `OVERRIDE_APP_SERVER` | Overrides manifest server URL in `GET /crmManifest` |
-| `OVERRIDE_SERVER_SIDE_LOGGING_SERVER` | Overrides manifest server-side logging URL in `GET /crmManifest` |
-| `RINGCENTRAL_SERVER` | Used by RingCentral OAuth and reporting helpers |
-| `RINGCENTRAL_CLIENT_ID` | Used by RingCentral OAuth and reporting helpers |
-| `RINGCENTRAL_CLIENT_SECRET` | Used by RingCentral OAuth and reporting helpers |

package/docs/connectors.md

@@ -1,116 +0,0 @@
-# Connectors
-
-Connectors are the extension seam that lets the shared framework support multiple CRMs.
-
-## Registry
-
-`connector/registry.js` exports a singleton `ConnectorRegistry`.
-
-### Responsibilities
-
-- register connector implementations by platform name
-- store manifests by platform
-- store release notes
-- register extra interface methods per platform
-- compose registered interfaces onto a connector at read time
-- fall back to the `proxy` connector when a platform-specific connector is missing
-
-### Important behavior
-
-| Method | Notes |
-| --- | --- |
-| `registerConnector()` | Validates that the connector implements `createCallLog` and `updateCallLog` |
-| `getConnector()` | Returns the original connector, an interface-only connector, a composed connector, or the proxy connector fallback |
-| `registerConnectorInterface()` | Adds methods without mutating the original connector object |
-| `getManifest(platform, fallbackToDefault)` | Throws if no manifest exists |
-| `getConnectorCapabilities()` | Summarizes original methods, composed methods, registered interfaces, and auth type |
-
-## Proxy Connector
-
-The proxy connector makes integrations configurable through stored connector metadata instead of custom connector code.
-
-### Files
-
-| File | Role |
-| --- | --- |
-| `connector/proxy/index.js` | User-facing connector implementation for auth, contacts, call logs, message logs, dispositions, and logout |
-| `connector/proxy/engine.js` | Low-level request templating, auth header creation, and response mapping |
-
-### What `proxy/index.js` does
-
-- loads proxy config from `models/dynamo/connectorSchema.js`
-- resolves auth type from config, defaulting to `apiKey`
-- builds `getOauthInfo()` for OAuth-style proxy integrations
-- performs `getUserInfo()`, `findContact()`, `createContact()`, `findContactWithName()`, `createCallLog()`, `getCallLog()`, `updateCallLog()`, `createMessageLog()`, `updateMessageLog()`, `upsertCallDisposition()`, and `getUserList()`
-- clears stored tokens in `unAuthorize()`
-- exposes connector-specific log format through `meta.logFormat`
-
-### What `proxy/engine.js` does
-
-- resolves dot-path expressions with `getByPath()`
-- renders template strings like `{{ user.accessToken }}`
-- recursively renders query params, headers, and bodies
-- composes auth headers from operation-specific or global auth config
-- performs axios requests from the rendered config
-- maps contact and call-log responses into App Connect's shared shape
-
-## Developer Portal Helpers
-
-`connector/developerPortal.js` wraps public API calls to the App Connect Developer Portal.
-
-Exports:
-
-- `getPublicConnectorList()`
-- `getConnectorManifest()`
-
-These functions are small fetch helpers and return `null` on failure after logging.
-
-## Mock Connector Helpers
-
-`connector/mock.js` is not a full connector implementation. It is a development helper used by the dev-only mock routes.
-
-Exports:
-
-- `createUser()`
-- `deleteUser()`
-- `getCallLog()`
-- `createCallLog()`
-- `cleanUpMockLogs()`
-
-## Connector Contract In Practice
-
-The shared framework expects these methods most often:
-
-- `getAuthType()`
-- `getOauthInfo()` or `getBasicAuth()`
-- `getUserInfo()`
-- `authValidation()`
-- `createCallLog()`
-- `updateCallLog()`
-- `getCallLog()`
-- `createMessageLog()`
-- `updateMessageLog()`
-- `findContact()`
-- `createContact()`
-- `findContactWithName()`
-- `unAuthorize()`
-- optional methods such as `refreshUserInfo()`, `getUserList()`, `getLicenseStatus()`, `upsertCallDisposition()`, `getServerLoggingSettings()`, `updateServerLoggingSettings()`, and `onUpdateUserSettings()`
-
-## API-Key Managed Auth Fields
-
-`apiKey` connector manifests can now annotate auth fields in `platform.auth.apiKey.page.content[]` with:
-
-- `managed?: boolean`
-- `managedScope?: 'account' | 'user'`
-- `hidden?: boolean`
-
-Behavior:
-
-- `managed: true` marks a field as eligible for admin-managed storage and server-side auto-fill
-- `managedScope: 'account'` stores one encrypted value per RingCentral account
-- `managedScope: 'user'` stores encrypted values per RingCentral extension inside that account
-- `hidden: true` hides input field from users
-- stored managed auth values are encrypted at rest by default
-
-This does not change the connector runtime contract. `handlers/auth.onApiKeyLogin()` still resolves the manifest-driven auth payload and passes the final field map through `additionalInfo` into connector `getUserInfo()`. Existing connectors like Redtail that already read extra API-key fields from `additionalInfo` remain compatible.
-

package/docs/handlers.md

@@ -1,128 +0,0 @@
-# Handlers
-
-Handlers contain the shared business workflows behind the route layer.
-
-## Handler Overview
-
-| File | Responsibility | Main exports |
-| --- | --- | --- |
-| `handlers/auth.js` | Connector login, OAuth callback handling, user persistence, and auth validation | `onOAuthCallback`, `onApiKeyLogin`, `authValidation`, `getLicenseStatus`, `onRingcentralOAuthCallback` |
-| `handlers/contact.js` | Contact search, creation, and account-data caching | `findContact`, `createContact`, `findContactWithName` |
-| `handlers/log.js` | Call logging, message logging, plugin execution, async plugin callbacks, call-log lookup, and note cache writes | `createCallLog`, `updateCallLog`, `createMessageLog`, `getCallLog`, `saveNoteCache`, `handleAsyncPluginCallback` |
-| `handlers/admin.js` | Admin settings, RingCentral reporting, server logging settings, and user mapping | `validateAdminRole`, `upsertAdminSettings`, `getAdminSettings`, `updateAdminRcTokens`, `getServerLoggingSettings`, `updateServerLoggingSettings`, `getAdminReport`, `getUserReport`, `getUserMapping`, `reinitializeUserMapping` |
-| `handlers/user.js` | User info refresh, user setting reads, admin/user setting merge, and updates | `refreshUserInfo`, `getUserSettingsByAdmin`, `getUserSettings`, `updateUserSettings` |
-| `handlers/disposition.js` | Call-disposition writes against an existing log | `upsertCallDisposition` |
-| `handlers/calldown.js` | User-owned call-down scheduling | `schedule`, `list`, `remove`, `markCalled`, `update` |
-| `handlers/managedAuth.js` | Shared API-key auth field discovery, secure storage, and login-time field resolution | `getManagedAuthAdminSettings`, `getManagedAuthState`, `resolveApiKeyLoginFields`, `upsertOrgManagedAuthValues`, `upsertUserManagedAuthValues` |
-
-## Common Execution Pattern
-
-Most connector-backed handlers follow the same sequence:
-
-1. Load the current `UserModel` row.
-2. Derive `proxyId` and optional proxy configuration from `platformAdditionalInfo`.
-3. Resolve the connector from `connectorRegistry`.
-4. Ask the connector for its auth type.
-5. Refresh OAuth tokens through `lib/oauth.js` or build API-key auth.
-6. Call the connector method with normalized inputs.
-7. Return a shared `successful` plus `returnMessage` shape.
-
-## `auth.js`
-
-Key behavior:
-
-- `onOAuthCallback()` completes the external OAuth code exchange, calls `getUserInfo()`, and persists the user through `saveUserInfo()`.
-- `onApiKeyLogin()` uses connector-provided basic-auth construction and the same user persistence path.
-- `onApiKeyLogin()` resolves shared API-key fields from `handlers/managedAuth.js`, ignores end-user overrides for shared fields, and returns `missingRequiredFieldConsts` when required fields are missing.
-- `saveUserInfo()` updates or creates `UserModel`, preserving existing `platformAdditionalInfo` keys and adding `proxyId`.
-- `authValidation()` refreshes OAuth tokens when needed, then delegates session validation to the connector.
-- `getLicenseStatus()` is connector-defined and only wrapped here.
-- `onRingcentralOAuthCallback()` stores admin RingCentral tokens in `AdminConfigModel`.
-
-## `contact.js`
-
-Key behavior:
-
-- `findContact()` checks `AccountDataModel` cache first using `contact-${phoneNumber}` as the data key.
-- Found contacts are cached per `rcAccountId` and `platformName`.
-- Cache refresh can be forced with `isForceRefreshAccountData`.
-- Missing or expired users return warning-style response objects rather than throwing.
-- `findContactWithName()` mirrors the phone lookup path without the account-data cache.
-
-Known caveat called out in code:
-
-- account-data contact caching assumes one RingCentral account does not need separate caches for multiple CRM platforms at the same time
-
-## `log.js`
-
-This is the heaviest handler in the package.
-
-Key responsibilities:
-
-- prevents duplicate call-log creation by checking `CallLogModel` on `sessionId` plus extension identity (`hashedExtensionId` first, with legacy `extensionNumber` fallback)
-- loads note cache from DynamoDB when `USE_CACHE` and server-side call logging are enabled
-- runs configured synchronous plugins before creating or updating logs
-- dispatches configured asynchronous call plugins after call-log create or update succeeds
-- handles async plugin callbacks by appending Agent notes on success or marking task cache as failed on failure
-- composes log body content with `composeCallLog()` or `composeSharedSMSLog()`
-- stores local mappings between telephony ids and CRM log ids
-- handles normal SMS, fax, group SMS, and shared SMS cases
-- enriches tracking metadata for analytics callers
-
-Important persistence behavior:
-
-- `CallLogModel` stores the App Connect to CRM mapping for call logs
-- `MessageLogModel` stores the App Connect to CRM mapping for message logs
-- `CacheModel` stores async plugin callback tasks with a one-week expiry; successful callbacks delete the task and failed callbacks keep the task with status `failed`
-- `NoteCache` stores temporary notes keyed by session id
-
-## `admin.js`
-
-Key responsibilities:
-
-- validates RingCentral admin role from the current extension token
-- validates arbitrary RingCentral user tokens with `validateRcUserToken()`
-- stores and reads account-level admin configuration
-- stores admin OAuth tokens used for RingCentral reporting
-- fetches call aggregation and user activity metrics from RingCentral
-- delegates server-side logging settings to connector-specific methods when available
-- builds CRM user to RingCentral extension mappings through `getUserList()`
-
-## `user.js`
-
-This module handles user-owned workflows that do not belong to login, contact, or logging handlers.
-
-Rules implemented here:
-
-- `refreshUserInfo()` loads the current user, refreshes OAuth credentials when needed or builds API-key auth, then delegates to the connector's `refreshUserInfo({ user, authHeader, proxyConfig })`
-- if no admin settings exist, return user settings directly
-- admin settings can override or hide user settings
-- plugin settings merge at both the plugin level and nested config-field level
-- connectors can intercept setting updates with `onUpdateUserSettings()`
-
-## Smaller Handler Modules
-
-`disposition.js`:
-
-- requires an existing local call-log mapping before writing disposition data
-
-`calldown.js`:
-
-- decodes the JWT directly
-- keeps operations scoped to the authenticated user
-- supports schedule, list, remove, mark-as-called, and partial update flows
-
-`plugin.js`:
-
-- registers and unregisters account-level plugins
-- validates plugin registration against RingCentral account identity
-- reads plugin license status through the installed plugin profile
-
-`managedAuth.js`:
-
-- reads API-key field definitions from either the developer portal manifest or the connector registry manifest
-- isolates managed field definitions with `managed: true` and `managedScope` (`account` or `user`)
-- encrypts managed auth values before writing to `AccountDataModel`
-- provides admin views with stored values using `{ hasValue, value }` while keeping database values encrypted at rest
-- resolves login fields by merging stored managed values and non-managed end-user inputs
-