@esri/arcgis-rest-developer-credentials 1.1.0 → 2.0.0

package/dist/bundled/developer-credentials.esm.js

@@ -1,43 +1,67 @@
 /* @preserve
-* @esri/arcgis-rest-developer-credentials - v1.0.1 - Apache-2.0
+* @esri/arcgis-rest-developer-credentials - v2.0.0 - Apache-2.0
 * Copyright (c) 2017-2025 Esri, Inc.
-* Thu Jan 23 2025 20:05:00 GMT+0000 (Coordinated Universal Time)
+* Thu Feb 20 2025 22:18:42 GMT+0000 (Coordinated Universal Time)
 */
-import { getPortalUrl, createItem, getItem, removeItem } from '@esri/arcgis-rest-portal';
-import { appendCustomParams, request } from '@esri/arcgis-rest-request';
+import { getPortalUrl, createItem, updateItem, getItem } from '@esri/arcgis-rest-portal';
+import { request, appendCustomParams } from '@esri/arcgis-rest-request';
 
+/* Copyright (c) 2023 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
 /**
- * Used to describe privilege list of an app.
+ * Used to retrieve registered app info. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/registered-app-info.htm) for more information.
+ *
+ * ```js
+ * import { getRegisteredAppInfo, IApp } from '@esri/arcgis-rest-developer-credentials';
+ * import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
+ *
+ * const authSession: ArcGISIdentityManager = await ArcGISIdentityManager.signIn({
+ *   username: "xyz_usrName",
+ *   password: "xyz_pw"
+ * });
+ *
+ * getRegisteredAppInfo({
+ *   itemId: "xyz_itemId",
+ *   authentication: authSession
+ * }).then((registeredApp: IApp) => {
+ *   // => {client_id: "xyz_id", client_secret: "xyz_secret", ...}
+ * }).catch(e => {
+ *   // => an exception object
+ * });
+ * ```
+ *
+ * @param requestOptions - Options for {@linkcode getRegisteredAppInfo | getRegisteredAppInfo()}, including an itemId of which app to retrieve and an {@linkcode ArcGISIdentityManager} authentication session.
+ * @returns A Promise that will resolve to an {@linkcode IApp} object representing successfully retrieved app.
  */
-var Privileges;
-(function (Privileges) {
-    Privileges["Basemaps"] = "portal:apikey:basemaps";
-    Privileges["Demographics"] = "premium:user:demographics";
-    Privileges["Elevation"] = "premium:user:elevation";
-    Privileges["FeatureReport"] = "premium:user:featurereport";
-    Privileges["Geocode"] = "premium:user:geocode";
-    Privileges["GeocodeStored"] = "premium:user:geocode:stored";
-    Privileges["GeocodeTemporary"] = "premium:user:geocode:temporary";
-    Privileges["GeoEnrichment"] = "premium:user:geoenrichment";
-    Privileges["NetworkAnalysis"] = "premium:user:networkanalysis";
-    Privileges["NetworkAnalysisRouting"] = "premium:user:networkanalysis:routing";
-    Privileges["NetworkAnalysisOptimizedRouting"] = "premium:user:networkanalysis:optimizedrouting";
-    Privileges["NetworkAnalysisClosestFacility"] = "premium:user:networkanalysis:closestfacility";
-    Privileges["NetworkAnalysisServiceArea"] = "premium:user:networkanalysis:servicearea";
-    Privileges["NetworkAnalysisLocationalLocation"] = "premium:user:networkanalysis:locationallocation";
-    Privileges["NetworkAnalysisVehicleRouting"] = "premium:user:networkanalysis:vehiclerouting";
-    Privileges["NetworkAnalysisOriginDestinationCostMatrix"] = "premium:user:networkanalysis:origindestinationcostmatrix";
-    Privileges["Places"] = "premium:user:places";
-    Privileges["SpatialAnalysis"] = "premium:user:spatialanalysis";
-    Privileges["GeoAnalytics"] = "premium:publisher:geoanalytics";
-    Privileges["RasterAnalysis"] = "premium:publisher:rasteranalysis";
-})(Privileges || (Privileges = {}));
+async function getRegisteredAppInfo(requestOptions) {
+    const userName = await requestOptions.authentication.getUsername();
+    const url = getPortalUrl(requestOptions) +
+        `/content/users/${userName}/items/${requestOptions.itemId}/registeredAppInfo`;
+    requestOptions.httpMethod = "POST";
+    const registeredAppResponse = await request(url, Object.assign(Object.assign({}, requestOptions), { params: { f: "json" } }));
+    return registeredAppResponseToApp(registeredAppResponse);
+}
+
+async function generateApiKeyToken(options) {
+    const portal = getPortalUrl(options);
+    const url = `${portal}/oauth2/token`;
+    const appInfo = await getRegisteredAppInfo({
+        itemId: options.itemId,
+        authentication: options.authentication
+    });
+    const params = {
+        client_id: appInfo.client_id,
+        client_secret: appInfo.client_secret,
+        apiToken: options.apiKey,
+        regenerateApiToken: true,
+        grant_type: "client_credentials"
+    };
+    return request(url, {
+        authentication: options.authentication,
+        params
+    });
+}
 
-/**
- * @internal
- * Used to check privileges validity.
- */
-const arePrivilegesValid = (privileges) => privileges.every((element) => Object.values(Privileges).includes(element));
 /**
  * @internal
  * Encode special params value (e.g. array type...) in advance in order to make {@linkcode encodeParam} works correctly. Usage is case by case.
@@ -59,7 +83,8 @@ function registeredAppResponseToApp(response) {
         "apnsProdCert",
         "apnsSandboxCert",
         "gcmApiKey",
-        "isBeta"
+        "isBeta",
+        "customAppLoginShowTriage"
     ];
     const dateKeys = ["modified", "registered"];
     return Object.keys(response)
@@ -79,13 +104,11 @@ function registeredAppResponseToApp(response) {
  * Used to convert {@linkcode IApp} to {@linkcode IApiKeyInfo} only if `appType` is "apikey".
  */
 function appToApiKeyProperties(response) {
-    if (response.appType !== "apikey" || !("apiKey" in response)) {
-        throw new Error("Item is not an API key.");
-    }
-    delete response.client_id;
     delete response.client_secret;
     delete response.redirect_uris;
     delete response.appType;
+    delete response.customAppLoginShowTriage;
+    delete response.apiKey;
     return response;
 }
 /**
@@ -93,12 +116,14 @@ function appToApiKeyProperties(response) {
  * Used to convert {@linkcode IApp} to {@linkcode IOAuthAppInfo}.
  */
 function appToOAuthAppProperties(response) {
-    if (response.appType === "apikey") {
-        throw new Error("Item is not an OAuth 2.0 app.");
-    }
     delete response.appType;
     delete response.httpReferrers;
     delete response.privileges;
+    delete response.apiKey;
+    delete response.customAppLoginShowTriage;
+    delete response.isPersonalAPIToken;
+    delete response.apiToken1Active;
+    delete response.apiToken2Active;
     return response;
 }
 /**
@@ -131,6 +156,64 @@ function filterKeys(object, includedKeys) {
         return obj;
     }, {});
 }
+/**
+ * Used to determine if a generated key is in slot 1 or slot 2 key.
+ */
+function slotForKey(key) {
+    return parseInt(key.substring(key.length - 10, key.length - 9));
+}
+/**
+ * @internal
+ * Used to generate tokens in slot 1 and/or 2 of an API key.
+ */
+function generateApiKeyTokens(itemId, slots, requestOptions) {
+    return Promise.all(slots.map((slot) => {
+        return generateApiKeyToken(Object.assign({ itemId, apiKey: slot }, requestOptions));
+    })).then((responses) => {
+        return responses
+            .map((responses) => responses.access_token)
+            .reduce((obj, token, index) => {
+            obj[`accessToken${slotForKey(token)}`] = token;
+            return obj;
+        }, {});
+    });
+}
+/**
+ * @internal
+ * Convert boolean flags to an array of slots for {@linkcode generateApiKeyTokens}.
+ */
+function generateOptionsToSlots(generateToken1, generateToken2) {
+    const slots = [];
+    if (generateToken1) {
+        slots.push(1);
+    }
+    if (generateToken2) {
+        slots.push(2);
+    }
+    return slots;
+}
+/**
+ * @internal
+ * Build params for updating expiration dates
+ */
+function buildExpirationDateParams(requestOptions, fillDefaults) {
+    const updateparams = {};
+    if (requestOptions.apiToken1ExpirationDate) {
+        updateparams.apiToken1ExpirationDate =
+            requestOptions.apiToken1ExpirationDate;
+    }
+    if (requestOptions.apiToken2ExpirationDate) {
+        updateparams.apiToken2ExpirationDate =
+            requestOptions.apiToken2ExpirationDate;
+    }
+    if (fillDefaults && !updateparams.apiToken1ExpirationDate) {
+        updateparams.apiToken1ExpirationDate = -1;
+    }
+    if (fillDefaults && !updateparams.apiToken2ExpirationDate) {
+        updateparams.apiToken2ExpirationDate = -1;
+    }
+    return updateparams;
+}
 
 /* Copyright (c) 2023 Environmental Systems Research Institute, Inc.
  * Apache-2.0 */
@@ -171,10 +254,6 @@ function filterKeys(object, includedKeys) {
  * @returns A Promise that will resolve to an {@linkcode IApp} object representing the newly registered app.
  */
 async function registerApp(requestOptions) {
-    // privileges validation
-    if (!arePrivilegesValid(requestOptions.privileges)) {
-        throw new Error("The `privileges` option contains invalid privileges.");
-    }
     // build params
     const options = appendCustomParams(requestOptions, [
         "itemId",
@@ -210,7 +289,7 @@ async function registerApp(requestOptions) {
  *   title: "xyz_title",
  *   description: "xyz_desc",
  *   tags: ["xyz_tag1", "xyz_tag2"],
- *   privileges: [Privileges.Geocode, Privileges.FeatureReport],
+ *   privileges: ["premium:user:networkanalysis:routing"],
  *   authentication: authSession
  * }).then((registeredAPIKey: IApiKeyResponse) => {
  *   // => {apiKey: "xyz_key", item: {tags: ["xyz_tag1", "xyz_tag2"], ...}, ...}
@@ -223,9 +302,6 @@ async function registerApp(requestOptions) {
  * @returns A Promise that will resolve to an {@linkcode IApiKeyResponse} object representing the newly registered API key.
  */
 async function createApiKey(requestOptions) {
-    if (!arePrivilegesValid(requestOptions.privileges)) {
-        throw new Error("The `privileges` option contains invalid privileges.");
-    }
     requestOptions.httpMethod = "POST";
     // filter param buckets:
     const baseRequestOptions = extractBaseRequestOptions(requestOptions); // snapshot of basic IRequestOptions before customized params being built into it
@@ -245,52 +321,37 @@ async function createApiKey(requestOptions) {
         "typeKeywords",
         "url"
     ];
-    // step 1: add item
-    const createItemOption = Object.assign(Object.assign({ item: Object.assign(Object.assign({}, filterKeys(requestOptions, itemAddProperties)), { type: "API Key" }) }, baseRequestOptions), { authentication: requestOptions.authentication, params: {
+    /**
+     * step 1: create item
+     */
+    const createItemOption = Object.assign(Object.assign({ item: Object.assign(Object.assign({}, filterKeys(requestOptions, itemAddProperties)), { type: "Application" }) }, baseRequestOptions), { authentication: requestOptions.authentication, params: {
             f: "json"
         } });
     const createItemResponse = await createItem(createItemOption);
-    // step 2: register app
-    const registerAppOption = Object.assign(Object.assign({ itemId: createItemResponse.id, appType: "apikey", redirect_uris: [], httpReferrers: requestOptions.httpReferrers || [], privileges: requestOptions.privileges }, baseRequestOptions), { authentication: requestOptions.authentication });
-    const registeredAppResponse = await registerApp(registerAppOption);
+    /**
+     * getRegisteredAppInfoRoute
+     */
+    const registerAppOptions = Object.assign(Object.assign({ itemId: createItemResponse.id, appType: "multiple", redirect_uris: ["urn:ietf:wg:oauth:2.0:oob"], httpReferrers: requestOptions.httpReferrers || [], privileges: requestOptions.privileges }, baseRequestOptions), { authentication: requestOptions.authentication });
+    const registeredAppResponse = await registerApp(registerAppOptions);
+    /**
+     * step 3: update item with desired expiration dates
+     * you cannot set the expiration date propierties until you
+     * regiester the app so this has to be a seperate step
+     */
+    await updateItem(Object.assign(Object.assign({}, baseRequestOptions), { item: Object.assign({ id: createItemResponse.id }, buildExpirationDateParams(requestOptions, true)), authentication: requestOptions.authentication }));
+    /*
+     * step 4: get item info
+     */
     const itemInfo = await getItem(registeredAppResponse.itemId, Object.assign(Object.assign({}, baseRequestOptions), { authentication: requestOptions.authentication, params: { f: "json" } }));
-    return Object.assign(Object.assign({}, appToApiKeyProperties(registeredAppResponse)), { item: itemInfo });
-}
-
-/* Copyright (c) 2023 Environmental Systems Research Institute, Inc.
- * Apache-2.0 */
-/**
- * Used to retrieve registered app info. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/registered-app-info.htm) for more information.
- *
- * ```js
- * import { getRegisteredAppInfo, IApp } from '@esri/arcgis-rest-developer-credentials';
- * import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
- *
- * const authSession: ArcGISIdentityManager = await ArcGISIdentityManager.signIn({
- *   username: "xyz_usrName",
- *   password: "xyz_pw"
- * });
- *
- * getRegisteredAppInfo({
- *   itemId: "xyz_itemId",
- *   authentication: authSession
- * }).then((registeredApp: IApp) => {
- *   // => {client_id: "xyz_id", client_secret: "xyz_secret", ...}
- * }).catch(e => {
- *   // => an exception object
- * });
- * ```
- *
- * @param requestOptions - Options for {@linkcode getRegisteredAppInfo | getRegisteredAppInfo()}, including an itemId of which app to retrieve and an {@linkcode ArcGISIdentityManager} authentication session.
- * @returns A Promise that will resolve to an {@linkcode IApp} object representing successfully retrieved app.
- */
-async function getRegisteredAppInfo(requestOptions) {
-    const userName = await requestOptions.authentication.getUsername();
-    const url = getPortalUrl(requestOptions) +
-        `/content/users/${userName}/items/${requestOptions.itemId}/registeredAppInfo`;
-    requestOptions.httpMethod = "POST";
-    const registeredAppResponse = await request(url, Object.assign(Object.assign({}, requestOptions), { params: { f: "json" } }));
-    return registeredAppResponseToApp(registeredAppResponse);
+    /**
+     * step 5: generate tokens if requested
+     */
+    const generatedTokens = await generateApiKeyTokens(itemInfo.id, generateOptionsToSlots(requestOptions.generateToken1, requestOptions.generateToken2), Object.assign(Object.assign({}, baseRequestOptions), { authentication: requestOptions.authentication }));
+    /**
+     * step 6: get registered app info to get updated active key status
+     */
+    const updatedRegisteredAppResponse = await getRegisteredAppInfo(Object.assign(Object.assign({}, baseRequestOptions), { itemId: itemInfo.id, authentication: requestOptions.authentication }));
+    return Object.assign(Object.assign(Object.assign({}, generatedTokens), appToApiKeyProperties(updatedRegisteredAppResponse)), { item: itemInfo });
 }
 
 /* Copyright (c) 2023 Environmental Systems Research Institute, Inc.
@@ -327,20 +388,21 @@ async function getRegisteredAppInfo(requestOptions) {
  * @returns A Promise that will resolve to an {@linkcode IApiKeyResponse} object representing updated API key.
  */
 async function updateApiKey(requestOptions) {
-    // privileges validation
-    if (requestOptions.privileges &&
-        !arePrivilegesValid(requestOptions.privileges)) {
-        throw new Error("The `privileges` option contains invalid privileges.");
-    }
     requestOptions.httpMethod = "POST";
-    // get app
     const baseRequestOptions = extractBaseRequestOptions(requestOptions); // get base requestOptions snapshot
+    /**
+     * step 1: update expiration dates if provided. Build the object up to avoid overwriting any existing properties.
+     */
+    if (requestOptions.apiToken1ExpirationDate ||
+        requestOptions.apiToken2ExpirationDate) {
+        const updateParams = buildExpirationDateParams(requestOptions);
+        await updateItem(Object.assign(Object.assign({}, baseRequestOptions), { item: Object.assign({ id: requestOptions.itemId }, updateParams), authentication: requestOptions.authentication }));
+    }
+    /**
+     * step 2: update privileges and httpReferrers if provided. Build the object up to avoid overwriting any existing properties.
+     */
     const getAppOption = Object.assign(Object.assign({}, baseRequestOptions), { authentication: requestOptions.authentication, itemId: requestOptions.itemId });
     const appResponse = await getRegisteredAppInfo(getAppOption);
-    // appType must be APIKey to continue
-    if (appResponse.appType !== "apikey" || !("apiKey" in appResponse)) {
-        throw new Error("Item is not an API key.");
-    }
     const clientId = appResponse.client_id;
     const options = appendCustomParams(Object.assign(Object.assign({}, appResponse), requestOptions), // object with the custom params to look in
     ["privileges", "httpReferrers"] // keys you want copied to the params object
@@ -350,10 +412,20 @@ async function updateApiKey(requestOptions) {
     stringifyArrays(options);
     const url = getPortalUrl(options) + `/oauth2/apps/${clientId}/update`;
     // Raw response from `/oauth2/apps/${clientId}/update`, apiKey not included because key is same.
-    const updateResponse = await request(url, Object.assign(Object.assign({}, options), { authentication: requestOptions.authentication }));
-    const app = registeredAppResponseToApp(Object.assign(Object.assign({}, updateResponse), { apiKey: appResponse.apiKey }));
-    const itemInfo = await getItem(requestOptions.itemId, Object.assign(Object.assign({}, baseRequestOptions), { authentication: requestOptions.authentication, params: { f: "json" } }));
-    return Object.assign(Object.assign({}, appToApiKeyProperties(app)), { item: itemInfo });
+    await request(url, Object.assign(Object.assign({}, options), { authentication: requestOptions.authentication }));
+    /**
+     * step 3: get the updated item info to return to the user.
+     */
+    const updatedItemInfo = await getItem(requestOptions.itemId, Object.assign(Object.assign({}, baseRequestOptions), { authentication: requestOptions.authentication, params: { f: "json" } }));
+    /**
+     * step 4: generate tokens if requested
+     */
+    const generatedTokens = await generateApiKeyTokens(requestOptions.itemId, generateOptionsToSlots(requestOptions.generateToken1, requestOptions.generateToken2), Object.assign(Object.assign({}, baseRequestOptions), { authentication: requestOptions.authentication }));
+    /**
+     * step 5: get updated registered app info
+     */
+    const updatedRegisteredAppResponse = await getRegisteredAppInfo(Object.assign(Object.assign({}, baseRequestOptions), { itemId: requestOptions.itemId, authentication: requestOptions.authentication }));
+    return Object.assign(Object.assign(Object.assign({}, generatedTokens), appToApiKeyProperties(updatedRegisteredAppResponse)), { item: updatedItemInfo });
 }
 
 /* Copyright (c) 2023 Environmental Systems Research Institute, Inc.
@@ -389,42 +461,6 @@ async function getApiKey(requestOptions) {
     return Object.assign(Object.assign({}, appToApiKeyProperties(appResponse)), { item: itemInfo });
 }
 
-/* Copyright (c) 2023 Environmental Systems Research Institute, Inc.
- * Apache-2.0 */
-/**
- * Used to delete the API Key with given `itemId`.
- *
- * ```js
- * import { deleteApiKey, IDeleteApiKeyResponse } from '@esri/arcgis-rest-developer-credentials';
- * import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
- *
- * const authSession: ArcGISIdentityManager = await ArcGISIdentityManager.signIn({
- *   username: "xyz_usrName",
- *   password: "xyz_pw"
- * });
- *
- * deleteApiKey({
- *   itemId: "xyz_itemId",
- *   authentication: authSession
- * }).then((deletedApiKey: IDeleteApiKeyResponse) => {
- *   // => {itemId: "xyz_itemId", success: true}
- * }).catch(e => {
- *   // => an exception object
- * });
- * ```
- *
- * @param requestOptions - Options for {@linkcode deleteApiKey | deleteApiKey()}, including `itemId` of which API key to be deleted and an {@linkcode ArcGISIdentityManager} authentication session.
- * @returns A Promise that will resolve to an {@linkcode IDeleteApiKeyResponse} object representing deletion status.
- */
-async function deleteApiKey(requestOptions) {
-    requestOptions.httpMethod = "POST";
-    const baseRequestOptions = extractBaseRequestOptions(requestOptions);
-    // validate provided itemId associates with API Key
-    await getApiKey(Object.assign(Object.assign({}, baseRequestOptions), { itemId: requestOptions.itemId, authentication: requestOptions.authentication }));
-    const removeItemResponse = await removeItem(Object.assign(Object.assign({}, baseRequestOptions), { id: requestOptions.itemId, authentication: requestOptions.authentication, params: { f: "json" } }));
-    return removeItemResponse;
-}
-
 /* Copyright (c) 2023 Environmental Systems Research Institute, Inc.
  * Apache-2.0 */
 /**
@@ -458,42 +494,6 @@ async function getOAuthApp(requestOptions) {
     return Object.assign(Object.assign({}, appToOAuthAppProperties(appResponse)), { item: itemInfo });
 }
 
-/* Copyright (c) 2023 Environmental Systems Research Institute, Inc.
- * Apache-2.0 */
-/**
- * Used to delete the OAuth2.0 app with given `itemId`.
- *
- * ```js
- * import { deleteOAuthApp, IDeleteOAuthAppResponse } from '@esri/arcgis-rest-developer-credentials';
- * import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
- *
- * const authSession: ArcGISIdentityManager = await ArcGISIdentityManager.signIn({
- *   username: "xyz_usrName",
- *   password: "xyz_pw"
- * });
- *
- * deleteOAuthApp({
- *   itemId: "xyz_itemId",
- *   authentication: authSession
- * }).then((deletedOAuthApp: IDeleteOAuthAppResponse) => {
- *   // => {itemId: "xyz_itemId", success: true}
- * }).catch(e => {
- *   // => an exception object
- * });
- * ```
- *
- * @param requestOptions - Options for {@linkcode deleteOAuthApp | deleteOAuthApp()}, including `itemId` of which OAuth app to be deleted and an {@linkcode ArcGISIdentityManager} authentication session.
- * @returns A Promise that will resolve to an {@linkcode IDeleteOAuthAppResponse} object representing deletion status.
- */
-async function deleteOAuthApp(requestOptions) {
-    requestOptions.httpMethod = "POST";
-    const baseRequestOptions = extractBaseRequestOptions(requestOptions);
-    // validate provided itemId associates with OAuth app
-    await getOAuthApp(Object.assign(Object.assign({}, baseRequestOptions), { itemId: requestOptions.itemId, authentication: requestOptions.authentication }));
-    const removeItemResponse = await removeItem(Object.assign(Object.assign({}, baseRequestOptions), { id: requestOptions.itemId, authentication: requestOptions.authentication, params: { f: "json" } }));
-    return removeItemResponse;
-}
-
 /* Copyright (c) 2023 Environmental Systems Research Institute, Inc.
  * Apache-2.0 */
 /**
@@ -650,5 +650,5 @@ async function unregisterApp(requestOptions) {
     return unregisterAppResponse;
 }
 
-export { Privileges, appToApiKeyProperties, appToOAuthAppProperties, arePrivilegesValid, createApiKey, createOAuthApp, deleteApiKey, deleteOAuthApp, extractBaseRequestOptions, filterKeys, getApiKey, getOAuthApp, getRegisteredAppInfo, registerApp, registeredAppResponseToApp, stringifyArrays, unregisterApp, updateApiKey, updateOAuthApp };
+export { appToApiKeyProperties, appToOAuthAppProperties, buildExpirationDateParams, createApiKey, createOAuthApp, extractBaseRequestOptions, filterKeys, generateApiKeyTokens, generateOptionsToSlots, getApiKey, getOAuthApp, getRegisteredAppInfo, registerApp, registeredAppResponseToApp, slotForKey, stringifyArrays, unregisterApp, updateApiKey, updateOAuthApp };
 //# sourceMappingURL=developer-credentials.esm.js.map