@app-connect/core 1.7.37 → 1.7.38

package/{handlers → dist/handlers}/managedAuth.js

@@ -1,25 +1,61 @@
-const connectorRegistry = require('../connector/registry');
-const developerPortal = require('../connector/developerPortal');
-const { AccountDataModel } = require('../models/accountDataModel');
+"use strict";
+// @ts-check
+Object.defineProperty(exports, "__esModule", { value: true });
+/** @typedef {import('../types').AppConnectManifest} AppConnectManifest */
+/** @typedef {import('../types').DeveloperPortalManifestProvider} DeveloperPortalManifestProvider */
+/** @typedef {import('../types').ManagedAuthAdminSettingsParams} ManagedAuthAdminSettingsParams */
+/** @typedef {import('../types').ManagedAuthFieldDefinition} ManagedAuthFieldDefinition */
+/** @typedef {import('../types').ManagedAuthFieldDefinitionParams} ManagedAuthFieldDefinitionParams */
+/** @typedef {import('../types').ManagedAuthLoginFailureParams} ManagedAuthLoginFailureParams */
+/** @typedef {import('../types').ManagedAuthRecord} ManagedAuthRecord */
+/** @typedef {import('../types').ManagedAuthState} ManagedAuthState */
+/** @typedef {import('../types').ManagedAuthStateParams} ManagedAuthStateParams */
+/** @typedef {import('../types').ManagedAuthStoredValue} ManagedAuthStoredValue */
+/** @typedef {import('../types').ManagedAuthUserParams} ManagedAuthUserParams */
+/** @typedef {import('../types').ManagedAuthValue} ManagedAuthValue */
+/** @typedef {import('../types').ManagedAuthValues} ManagedAuthValues */
+/** @typedef {import('../types').PersistSubmittedManagedValuesParams} PersistSubmittedManagedValuesParams */
+/** @typedef {import('../types').ResolveApiKeyLoginFieldsParams} ResolveApiKeyLoginFieldsParams */
+/** @typedef {import('../types').ResolveApiKeyLoginFieldsResult} ResolveApiKeyLoginFieldsResult */
+/** @typedef {import('../types').StoredFieldValue} StoredFieldValue */
+/** @typedef {import('../types').UpsertOrgManagedAuthValuesParams} UpsertOrgManagedAuthValuesParams */
+/** @typedef {import('../types').UpsertUserManagedAuthValuesParams} UpsertUserManagedAuthValuesParams */
+const connectorRegistry = /** @type {{ getManifest(platform: string, fallback?: boolean): AppConnectManifest }} */ ( /** @type {unknown} */(require('../connector/registry')));
+const developerPortal = /** @type {DeveloperPortalManifestProvider} */ ( /** @type {unknown} */(require('../connector/developerPortal')));
+const { AccountDataModel: RawAccountDataModel } = require('../models/accountDataModel');
+const AccountDataModel = /** @type {{ findOne(options: Record<string, unknown>): Promise<ManagedAuthRecord | null>, findAll(options: Record<string, unknown>): Promise<ManagedAuthRecord[]>, create(values: Record<string, unknown>): Promise<ManagedAuthRecord>, destroy(options: Record<string, unknown>): Promise<number> }} */ (RawAccountDataModel);
 const { Op } = require('sequelize');
-const { encode, decoded } = require('../lib/encode');
-
+const { encode: rawEncode, decoded: rawDecoded } = require('../lib/encode');
+const encode = /** @type {(value: string) => string} */ (rawEncode);
+const decoded = /** @type {(value: string) => string} */ (rawDecoded);
 const MANAGED_AUTH_ORG_DATA_KEY = 'managed-auth-org';
 const MANAGED_AUTH_USER_DATA_KEY = 'managed-auth-user';
 const MANAGED_AUTH_LOGIN_FAILURE_DATA_KEY = 'managed-auth-login-failure';
-
+/**
+ * @param {{ rcExtensionId: string | number }} params
+ * @returns {string}
+ */
 function getUserManagedAuthDataKey({ rcExtensionId }) {
     return `${MANAGED_AUTH_USER_DATA_KEY}:${rcExtensionId}`;
 }
-
+/**
+ * @param {{ rcExtensionId: string | number }} params
+ * @returns {string}
+ */
 function getManagedAuthLoginFailureDataKey({ rcExtensionId }) {
     return `${MANAGED_AUTH_LOGIN_FAILURE_DATA_KEY}:${rcExtensionId}`;
 }
-
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
 function isFilled(value) {
     return value !== undefined && value !== null && value !== '';
 }
-
+/**
+ * @param {ManagedAuthFieldDefinitionParams} params
+ * @returns {Promise<ManagedAuthFieldDefinition[]>}
+ */
 async function getApiKeyFieldDefinitions({ rcAccountId, platform, connectorId, isPrivate = false }) {
     if (!platform) {
         return [];
@@ -27,23 +63,29 @@ async function getApiKeyFieldDefinitions({ rcAccountId, platform, connectorId, i
     if (connectorId) {
         const manifest = await developerPortal.getConnectorManifest({ rcAccountId, connectorId, isPrivate });
         if (manifest?.platforms?.[platform]?.auth?.apiKey?.page?.content) {
-            return manifest.platforms[platform].auth.apiKey.page.content;
+            return /** @type {ManagedAuthFieldDefinition[]} */ (manifest.platforms[platform].auth.apiKey.page.content);
         }
     }
     try {
         const manifest = connectorRegistry.getManifest(platform, true);
-        return manifest?.platforms?.[platform]?.auth?.apiKey?.page?.content ?? [];
+        return /** @type {ManagedAuthFieldDefinition[]} */ (manifest?.platforms?.[platform]?.auth?.apiKey?.page?.content ?? []);
     }
     catch (error) {
         return [];
     }
 }
-
+/**
+ * @param {ManagedAuthFieldDefinitionParams} params
+ * @returns {Promise<ManagedAuthFieldDefinition[]>}
+ */
 async function getManagedFieldDefinitions({ rcAccountId, platform, connectorId, isPrivate = false }) {
     const fieldDefinitions = await getApiKeyFieldDefinitions({ rcAccountId, platform, connectorId, isPrivate });
     return fieldDefinitions.filter(field => field?.managed);
 }
-
+/**
+ * @param {ManagedAuthValue} value
+ * @returns {ManagedAuthStoredValue}
+ */
 function encryptStoredValue(value) {
     return {
         version: 1,
@@ -51,17 +93,24 @@ function encryptStoredValue(value) {
         value: encode(JSON.stringify(value))
     };
 }
-
+/**
+ * @param {ManagedAuthValue} value
+ * @returns {ManagedAuthValue}
+ */
 function decryptStoredValue(value) {
     if (!value) {
         return undefined;
     }
-    if (value?.encrypted && value?.value) {
-        return JSON.parse(decoded(value.value));
+    const storedValue = /** @type {ManagedAuthStoredValue} */ (value);
+    if (storedValue?.encrypted && storedValue?.value) {
+        return JSON.parse(decoded(storedValue.value));
     }
     return value;
 }
-
+/**
+ * @param {{ rcAccountId?: string | number, platform?: string, dataKey: string }} params
+ * @returns {Promise<ManagedAuthRecord | null>}
+ */
 async function getManagedAuthRecord({ rcAccountId, platform, dataKey }) {
     if (!rcAccountId || !platform) {
         return null;
@@ -74,7 +123,10 @@ async function getManagedAuthRecord({ rcAccountId, platform, dataKey }) {
         }
     });
 }
-
+/**
+ * @param {import('../types').ManagedAuthAccountParams} params
+ * @returns {Promise<ManagedAuthValues>}
+ */
 async function getOrgManagedAuthValues({ rcAccountId, platform }) {
     const record = await getManagedAuthRecord({
         rcAccountId,
@@ -82,13 +134,17 @@ async function getOrgManagedAuthValues({ rcAccountId, platform }) {
         dataKey: MANAGED_AUTH_ORG_DATA_KEY
     });
     const fields = record?.data?.fields ?? {};
+    /** @type {ManagedAuthValues} */
     const decryptedFields = {};
     Object.keys(fields).forEach(key => {
         decryptedFields[key] = decryptStoredValue(fields[key]);
     });
     return decryptedFields;
 }
-
+/**
+ * @param {ManagedAuthUserParams} params
+ * @returns {Promise<ManagedAuthValues>}
+ */
 async function getUserManagedAuthValues({ rcAccountId, platform, rcExtensionId }) {
     if (!rcExtensionId) {
         return {};
@@ -100,13 +156,17 @@ async function getUserManagedAuthValues({ rcAccountId, platform, rcExtensionId }
         dataKey: userDataKey
     });
     const fields = scopedRecord?.data?.fields ?? {};
+    /** @type {ManagedAuthValues} */
     const decryptedFields = {};
     Object.keys(fields).forEach(key => {
         decryptedFields[key] = decryptStoredValue(fields[key]);
     });
     return decryptedFields;
 }
-
+/**
+ * @param {ManagedAuthLoginFailureParams} params
+ * @returns {Promise<boolean>}
+ */
 async function hasManagedAuthLoginFailure({ rcAccountId, platform, rcExtensionId }) {
     if (!rcExtensionId) {
         return false;
@@ -118,7 +178,10 @@ async function hasManagedAuthLoginFailure({ rcAccountId, platform, rcExtensionId
     });
     return !!record;
 }
-
+/**
+ * @param {ManagedAuthLoginFailureParams} params
+ * @returns {Promise<ManagedAuthRecord | undefined>}
+ */
 async function markManagedAuthLoginFailure({ rcAccountId, platform, rcExtensionId }) {
     if (!rcAccountId || !platform || !rcExtensionId) {
         return;
@@ -143,7 +206,10 @@ async function markManagedAuthLoginFailure({ rcAccountId, platform, rcExtensionI
         data
     });
 }
-
+/**
+ * @param {ManagedAuthLoginFailureParams} params
+ * @returns {Promise<number | undefined>}
+ */
 async function clearManagedAuthLoginFailure({ rcAccountId, platform, rcExtensionId }) {
     if (!rcAccountId || !platform || !rcExtensionId) {
         return 0;
@@ -156,17 +222,20 @@ async function clearManagedAuthLoginFailure({ rcAccountId, platform, rcExtension
         }
     });
 }
-
+/**
+ * @param {UpsertOrgManagedAuthValuesParams} params
+ * @returns {Promise<ManagedAuthRecord>}
+ */
 async function upsertOrgManagedAuthValues({ rcAccountId, platform, values = {}, fieldsToRemove = [] }) {
     const existingRecord = await getManagedAuthRecord({
         rcAccountId,
         platform,
         dataKey: MANAGED_AUTH_ORG_DATA_KEY
     });
+    /** @type {Record<string, unknown>} */
     const nextFields = {
         ...(existingRecord?.data?.fields ?? {})
     };
-
     Object.keys(values).forEach(key => {
         if (isFilled(values[key])) {
             nextFields[key] = encryptStoredValue(values[key]);
@@ -175,11 +244,9 @@ async function upsertOrgManagedAuthValues({ rcAccountId, platform, values = {},
     fieldsToRemove.forEach(key => {
         delete nextFields[key];
     });
-
     const nextData = {
         fields: nextFields
     };
-
     if (existingRecord) {
         await existingRecord.update({ data: nextData });
         return existingRecord;
@@ -191,7 +258,10 @@ async function upsertOrgManagedAuthValues({ rcAccountId, platform, values = {},
         data: nextData
     });
 }
-
+/**
+ * @param {UpsertUserManagedAuthValuesParams} params
+ * @returns {Promise<ManagedAuthRecord>}
+ */
 async function upsertUserManagedAuthValues({ rcAccountId, platform, rcExtensionId, rcUserName, values = {}, fieldsToRemove = [] }) {
     if (!rcExtensionId) {
         throw new Error('rcExtensionId is required for user managed auth values');
@@ -202,10 +272,10 @@ async function upsertUserManagedAuthValues({ rcAccountId, platform, rcExtensionI
         platform,
         dataKey: userDataKey
     });
+    /** @type {Record<string, unknown>} */
     const nextFields = {
         ...(existingRecord?.data?.fields ?? {})
     };
-
     Object.keys(values).forEach(key => {
         if (isFilled(values[key])) {
             nextFields[key] = encryptStoredValue(values[key]);
@@ -214,13 +284,11 @@ async function upsertUserManagedAuthValues({ rcAccountId, platform, rcExtensionI
     fieldsToRemove.forEach(key => {
         delete nextFields[key];
     });
-
     const nextData = {
         rcExtensionId,
         rcUserName: rcUserName ?? existingRecord?.data?.rcUserName ?? '',
         fields: nextFields
     };
-
     if (existingRecord) {
         await existingRecord.update({ data: nextData });
         return existingRecord;
@@ -232,7 +300,10 @@ async function upsertUserManagedAuthValues({ rcAccountId, platform, rcExtensionI
         data: nextData
     });
 }
-
+/**
+ * @param {{ value: unknown }} params
+ * @returns {StoredFieldValue}
+ */
 function getStoredFieldValue({ value }) {
     if (!isFilled(value)) {
         return {
@@ -245,7 +316,9 @@ function getStoredFieldValue({ value }) {
         value
     };
 }
-
+/**
+ * @param {ManagedAuthAdminSettingsParams} params
+ */
 async function getManagedAuthAdminSettings({ platform, rcAccountId, connectorId, isPrivate = false }) {
     const fieldDefinitions = await getManagedFieldDefinitions({ rcAccountId, platform, connectorId, isPrivate });
     const orgFieldDefinitions = fieldDefinitions.filter(field => field.managedScope === 'account');
@@ -262,27 +335,27 @@ async function getManagedAuthAdminSettings({ platform, rcAccountId, connectorId,
     });
     const userEntries = userRecords
         .map(record => {
-            const extensionIdFromDataKey = record.dataKey?.split(`${MANAGED_AUTH_USER_DATA_KEY}:`)?.[1];
-            const rcExtensionId = record?.data?.rcExtensionId ?? extensionIdFromDataKey;
-            if (!rcExtensionId) {
-                return null;
-            }
-            return {
-                rcExtensionId,
-                rcUserName: record?.data?.rcUserName ?? '',
-                fields: record?.data?.fields ?? {}
-            };
-        })
+        const extensionIdFromDataKey = record.dataKey?.split(`${MANAGED_AUTH_USER_DATA_KEY}:`)?.[1];
+        const rcExtensionId = record?.data?.rcExtensionId ?? extensionIdFromDataKey;
+        if (!rcExtensionId) {
+            return null;
+        }
+        return {
+            rcExtensionId,
+            rcUserName: record?.data?.rcUserName ?? '',
+            fields: record?.data?.fields ?? {}
+        };
+    })
         .filter(Boolean);
-
+    /** @type {Record<string, StoredFieldValue>} */
     const adminOrgValues = {};
     orgFieldDefinitions.forEach(field => {
         adminOrgValues[field.const] = getStoredFieldValue({
             value: orgValues[field.const]
         });
     });
-
     const adminUserValues = userEntries.map(entry => {
+        /** @type {Record<string, StoredFieldValue>} */
         const fields = {};
         userFieldDefinitions.forEach(field => {
             fields[field.const] = getStoredFieldValue({
@@ -295,7 +368,6 @@ async function getManagedAuthAdminSettings({ platform, rcAccountId, connectorId,
             fields
         };
     });
-
     return {
         hasManagedAuth: fieldDefinitions.length > 0,
         fields: fieldDefinitions,
@@ -305,18 +377,21 @@ async function getManagedAuthAdminSettings({ platform, rcAccountId, connectorId,
         userValues: adminUserValues
     };
 }
-
+/**
+ * @param {ManagedAuthStateParams} params
+ * @returns {Promise<ManagedAuthState>}
+ */
 async function getManagedAuthState({ platform, rcAccountId, rcExtensionId, connectorId, isPrivate = false }) {
     const fieldDefinitions = await getApiKeyFieldDefinitions({ rcAccountId, platform, connectorId, isPrivate });
     const managedFieldDefinitions = fieldDefinitions.filter(field => field?.managed);
     const orgValues = await getOrgManagedAuthValues({ rcAccountId, platform });
     const userValues = await getUserManagedAuthValues({ rcAccountId, platform, rcExtensionId });
     const hasLoginFailureFallback = await hasManagedAuthLoginFailure({ rcAccountId, platform, rcExtensionId });
-
+    /** @type {string[]} */
     const visibleFieldConsts = [];
+    /** @type {string[]} */
     const missingRequiredFieldConsts = [];
     let allRequiredFieldsSatisfied = true;
-
     // Default behavior for connectors without managed auth: render full API key form.
     if (managedFieldDefinitions.length === 0) {
         return {
@@ -327,7 +402,6 @@ async function getManagedAuthState({ platform, rcAccountId, rcExtensionId, conne
             fallbackToManualAuth: false
         };
     }
-
     if (hasLoginFailureFallback) {
         return {
             hasManagedAuth: true,
@@ -337,7 +411,6 @@ async function getManagedAuthState({ platform, rcAccountId, rcExtensionId, conne
             fallbackToManualAuth: true
         };
     }
-
     fieldDefinitions.forEach(field => {
         const storedValue = field.managed
             ? (field.managedScope === 'user' ? userValues[field.const] : orgValues[field.const])
@@ -356,7 +429,6 @@ async function getManagedAuthState({ platform, rcAccountId, rcExtensionId, conne
             allRequiredFieldsSatisfied = false;
         }
     });
-
     return {
         hasManagedAuth: managedFieldDefinitions.length > 0,
         allRequiredFieldsSatisfied,
@@ -365,20 +437,23 @@ async function getManagedAuthState({ platform, rcAccountId, rcExtensionId, conne
         fallbackToManualAuth: false
     };
 }
-
+/**
+ * @param {ResolveApiKeyLoginFieldsParams} params
+ * @returns {Promise<ResolveApiKeyLoginFieldsResult>}
+ */
 async function resolveApiKeyLoginFields({ platform, rcAccountId, rcExtensionId, connectorId, isPrivate = false, apiKey, additionalInfo = {}, preferSubmittedValuesForManagedFields = false }) {
     const fieldDefinitions = await getApiKeyFieldDefinitions({ rcAccountId, platform, connectorId, isPrivate });
+    /** @type {ManagedAuthValues} */
     const resolvedAdditionalInfo = {
         ...(additionalInfo ?? {})
     };
     if (resolvedAdditionalInfo.apiKey === undefined && apiKey !== undefined) {
         resolvedAdditionalInfo.apiKey = apiKey;
     }
-
     const orgValues = await getOrgManagedAuthValues({ rcAccountId, platform });
     const userValues = await getUserManagedAuthValues({ rcAccountId, platform, rcExtensionId });
+    /** @type {string[]} */
     const missingRequiredFieldConsts = [];
-
     fieldDefinitions.forEach(field => {
         if (!field?.managed) {
             if (field.required && !isFilled(resolvedAdditionalInfo[field.const])) {
@@ -386,7 +461,6 @@ async function resolveApiKeyLoginFields({ platform, rcAccountId, rcExtensionId,
             }
             return;
         }
-
         const storedValue = field.managedScope === 'user'
             ? userValues[field.const]
             : orgValues[field.const];
@@ -395,19 +469,20 @@ async function resolveApiKeyLoginFields({ platform, rcAccountId, rcExtensionId,
         if (isFilled(storedValue) && !(preferSubmittedValuesForManagedFields && isFilled(resolvedAdditionalInfo[field.const]))) {
             resolvedAdditionalInfo[field.const] = storedValue;
         }
-
         if (field.required && !isFilled(resolvedAdditionalInfo[field.const])) {
             missingRequiredFieldConsts.push(field.const);
         }
     });
-
     return {
         resolvedAdditionalInfo,
         resolvedApiKey: resolvedAdditionalInfo.apiKey ?? apiKey,
         missingRequiredFieldConsts
     };
 }
-
+/**
+ * @param {PersistSubmittedManagedValuesParams} params
+ * @returns {Promise<void>}
+ */
 async function persistSubmittedManagedValues({ platform, rcAccountId, rcExtensionId, rcUserName, submittedManagedValues = {} }) {
     if (!rcAccountId) {
         return;
@@ -429,7 +504,6 @@ async function persistSubmittedManagedValues({ platform, rcAccountId, rcExtensio
         });
     }
 }
-
 exports.MANAGED_AUTH_ORG_DATA_KEY = MANAGED_AUTH_ORG_DATA_KEY;
 exports.MANAGED_AUTH_USER_DATA_KEY = MANAGED_AUTH_USER_DATA_KEY;
 exports.getApiKeyFieldDefinitions = getApiKeyFieldDefinitions;
@@ -443,4 +517,3 @@ exports.resolveApiKeyLoginFields = resolveApiKeyLoginFields;
 exports.persistSubmittedManagedValues = persistSubmittedManagedValues;
 exports.upsertOrgManagedAuthValues = upsertOrgManagedAuthValues;
 exports.upsertUserManagedAuthValues = upsertUserManagedAuthValues;
-

package/dist/handlers/managedOAuth.d.ts

@@ -0,0 +1,13 @@
+/** @typedef {import('../types').ManagedOAuthAccountParams} ManagedOAuthAccountParams */
+/** @typedef {import('../types').ManagedOAuthPendingParams} ManagedOAuthPendingParams */
+/** @typedef {import('../types').ManagedOAuthRecord} ManagedOAuthRecord */
+/** @typedef {import('../types').ManagedOAuthResolution} ManagedOAuthResolution */
+/** @typedef {import('../types').ManagedOAuthState} ManagedOAuthState */
+/** @typedef {import('../types').ManagedOAuthStateParams} ManagedOAuthStateParams */
+/** @typedef {import('../types').ManagedOAuthStoredData} ManagedOAuthStoredData */
+/** @typedef {import('../types').ManagedOAuthStoredValue} ManagedOAuthStoredValue */
+/** @typedef {import('../types').ManagedOAuthValue} ManagedOAuthValue */
+/** @typedef {import('../types').ManagedOAuthValues} ManagedOAuthValues */
+/** @typedef {import('../types').ResetManagedOAuthResult} ResetManagedOAuthResult */
+/** @typedef {import('../types').UpsertPendingManagedOAuthParams} UpsertPendingManagedOAuthParams */
+export {};