@app-connect/core 1.7.25 → 1.7.27

package/docs/handlers.md

@@ -1,125 +1,125 @@
-# 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, call-log lookup, and note cache writes | `createCallLog`, `updateCallLog`, `createMessageLog`, `getCallLog`, `saveNoteCache` |
-| `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 setting reads, admin/user setting merge, and updates | `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/plugin.js` | Async plugin task polling and cleanup | `getPluginAsyncTasks` |
-| `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`
-- loads note cache from DynamoDB when `USE_CACHE` and server-side call logging are enabled
-- runs configured plugins before creating or updating logs
-- 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 task state
-- `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 is mainly about merging account-level policy with per-user preferences.
-
-Rules implemented here:
-
-- 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`:
-
-- returns cached async task status
-- deletes terminal task cache records after the client reads them
-
-`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
-
+# 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, call-log lookup, and note cache writes | `createCallLog`, `updateCallLog`, `createMessageLog`, `getCallLog`, `saveNoteCache` |
+| `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 setting reads, admin/user setting merge, and updates | `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/plugin.js` | Async plugin task polling and cleanup | `getPluginAsyncTasks` |
+| `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`
+- loads note cache from DynamoDB when `USE_CACHE` and server-side call logging are enabled
+- runs configured plugins before creating or updating logs
+- 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 task state
+- `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 is mainly about merging account-level policy with per-user preferences.
+
+Rules implemented here:
+
+- 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`:
+
+- returns cached async task status
+- deletes terminal task cache records after the client reads them
+
+`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
+

package/docs/libraries.md

@@ -1,101 +1,101 @@
-# Libraries
-
-The `lib/` directory contains cross-cutting helpers used by routes, handlers, and connectors.
-
-## Infrastructure And Security
-
-| File | Responsibility |
-| --- | --- |
-| `lib/jwt.js` | Signs and verifies long-lived JWTs with `APP_SERVER_SECRET_KEY` |
-| `lib/oauth.js` | Builds OAuth clients and refreshes access tokens with lock protection |
-| `lib/authSession.js` | Stores and updates auth-session records used by auth flows |
-| `lib/encode.js` | Small encoding and decoding helpers for encrypted values |
-| `lib/errorHandler.js` | Normalizes API and database errors and exports Express error middleware |
-| `lib/logger.js` | Structured logger plus exported `Logger` class and log-level constants |
-| `lib/debugTracer.js` | Request-scoped trace collector used when debug mode is enabled |
-| `lib/s3ErrorLogReport.js` | S3 bucket setup and presigned upload URL generation for debug reports |
-
-## RingCentral And Analytics Helpers
-
-| File | Responsibility |
-| --- | --- |
-| `lib/ringcentral.js` | RingCentral API wrapper plus token-validity helpers |
-| `lib/analytics.js` | Mixpanel initialization and event tracking |
-| `lib/generalErrorMessage.js` | Shared user-facing warning messages for auth and rate-limit cases |
-
-## Formatting And Utility Helpers
-
-| File | Responsibility |
-| --- | --- |
-| `lib/callLogComposer.js` | Builds plain text, HTML, or Markdown call-log bodies |
-| `lib/sharedSMSComposer.js` | Builds shared-SMS conversation log content |
-| `lib/constants.js` | Defines `LOG_DETAILS_FORMAT_TYPE` values |
-| `lib/util.js` | Hashing, timezone lookup, media-reader links, plugin setting extraction, and date helpers |
-
-## Notes By File
-
-### `lib/analytics.js`
-
-- no-op unless `MIXPANEL_TOKEN` is present
-- attaches package version, app name, connector name, browser, OS, device, and caller metadata to events
-- requires `extensionId` to emit an event
-
-### `lib/jwt.js`
-
-- `generateJwt()` signs with a very long expiration window
-- `decodeJwt()` logs and returns `null` on verification failure instead of throwing
-
-### `lib/errorHandler.js`
-
-Exports:
-
-- `handleApiError()`
-- `handleDatabaseError()`
-- `asyncHandler()`
-- `errorMiddleware()`
-- `getOperationErrorMessage()`
-
-Notable behavior:
-
-- HTTP 429 becomes a rate-limit warning
-- HTTP 4xx up to 409 becomes an authorization-style warning
-- everything else becomes an operation-specific warning response
-
-### `lib/callLogComposer.js`
-
-This module centralizes log-body generation for call logs.
-
-It supports:
-
-- plain text
-- HTML
-- Markdown
-- note insertion
-- session id, subject, duration, result, recording, and timestamp formatting
-- transcript and AI note insertion
-- leg journey formatting
-- ACE transcript, summary, score, bullet summary, and deep link sections
-
-### `lib/sharedSMSComposer.js`
-
-This module formats shared SMS conversations for CRM logging.
-
-It handles:
-
-- message, note, and assignment entities
-- owner and assignee metadata
-- per-format output generation
-- summary counts and formatted timeline entries
-
-### `lib/util.js`
-
-Exports:
-
-- `getTimeZone()`
-- `getHashValue()`
-- `secondsToHoursMinutesSeconds()`
-- `getMostRecentDate()`
-- `getMediaReaderLinkByPlatformMediaLink()`
-- `getPluginsFromUserSettings()`
-
-`getPluginsFromUserSettings()` is especially important because logging handlers use it to discover which plugins should run for call, SMS, or fax workflows.
+# Libraries
+
+The `lib/` directory contains cross-cutting helpers used by routes, handlers, and connectors.
+
+## Infrastructure And Security
+
+| File | Responsibility |
+| --- | --- |
+| `lib/jwt.js` | Signs and verifies long-lived JWTs with `APP_SERVER_SECRET_KEY` |
+| `lib/oauth.js` | Builds OAuth clients and refreshes access tokens with lock protection |
+| `lib/authSession.js` | Stores and updates auth-session records used by auth flows |
+| `lib/encode.js` | Small encoding and decoding helpers for encrypted values |
+| `lib/errorHandler.js` | Normalizes API and database errors and exports Express error middleware |
+| `lib/logger.js` | Structured logger plus exported `Logger` class and log-level constants |
+| `lib/debugTracer.js` | Request-scoped trace collector used when debug mode is enabled |
+| `lib/s3ErrorLogReport.js` | S3 bucket setup and presigned upload URL generation for debug reports |
+
+## RingCentral And Analytics Helpers
+
+| File | Responsibility |
+| --- | --- |
+| `lib/ringcentral.js` | RingCentral API wrapper plus token-validity helpers |
+| `lib/analytics.js` | Mixpanel initialization and event tracking |
+| `lib/generalErrorMessage.js` | Shared user-facing warning messages for auth and rate-limit cases |
+
+## Formatting And Utility Helpers
+
+| File | Responsibility |
+| --- | --- |
+| `lib/callLogComposer.js` | Builds plain text, HTML, or Markdown call-log bodies |
+| `lib/sharedSMSComposer.js` | Builds shared-SMS conversation log content |
+| `lib/constants.js` | Defines `LOG_DETAILS_FORMAT_TYPE` values |
+| `lib/util.js` | Hashing, timezone lookup, media-reader links, plugin setting extraction, and date helpers |
+
+## Notes By File
+
+### `lib/analytics.js`
+
+- no-op unless `MIXPANEL_TOKEN` is present
+- attaches package version, app name, connector name, browser, OS, device, and caller metadata to events
+- requires `extensionId` to emit an event
+
+### `lib/jwt.js`
+
+- `generateJwt()` signs with a very long expiration window
+- `decodeJwt()` logs and returns `null` on verification failure instead of throwing
+
+### `lib/errorHandler.js`
+
+Exports:
+
+- `handleApiError()`
+- `handleDatabaseError()`
+- `asyncHandler()`
+- `errorMiddleware()`
+- `getOperationErrorMessage()`
+
+Notable behavior:
+
+- HTTP 429 becomes a rate-limit warning
+- HTTP 4xx up to 409 becomes an authorization-style warning
+- everything else becomes an operation-specific warning response
+
+### `lib/callLogComposer.js`
+
+This module centralizes log-body generation for call logs.
+
+It supports:
+
+- plain text
+- HTML
+- Markdown
+- note insertion
+- session id, subject, duration, result, recording, and timestamp formatting
+- transcript and AI note insertion
+- leg journey formatting
+- ACE transcript, summary, score, bullet summary, and deep link sections
+
+### `lib/sharedSMSComposer.js`
+
+This module formats shared SMS conversations for CRM logging.
+
+It handles:
+
+- message, note, and assignment entities
+- owner and assignee metadata
+- per-format output generation
+- summary counts and formatted timeline entries
+
+### `lib/util.js`
+
+Exports:
+
+- `getTimeZone()`
+- `getHashValue()`
+- `secondsToHoursMinutesSeconds()`
+- `getMostRecentDate()`
+- `getMediaReaderLinkByPlatformMediaLink()`
+- `getPluginsFromUserSettings()`
+
+`getPluginsFromUserSettings()` is especially important because logging handlers use it to discover which plugins should run for call, SMS, or fax workflows.