@app-connect/core 1.7.24 → 1.7.26

package/docs/architecture.md

@@ -1,93 +1,93 @@
-# 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
-- 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 |
+# 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
+- 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,117 +1,116 @@
-# 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()`
-- `getPrivateConnectorList()`
-- `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 `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.
-
+# 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 `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.
+