@adobe/uix-host-react 0.10.5 → 1.0.1

package/src/components/ExtensibleWrapper/ExtensionManagerProvider.ts

@@ -0,0 +1,324 @@
+/*************************************************************************
+ * ADOBE CONFIDENTIAL
+ * ___________________
+ *
+ * Copyright 2024 Adobe
+ * All Rights Reserved.
+ *
+ * NOTICE: All information contained herein is, and remains
+ * the property of Adobe and its suppliers, if any. The intellectual
+ * and technical concepts contained herein are proprietary to Adobe
+ * and its suppliers and are protected by all applicable intellectual
+ * property laws, including trade secret and copyright laws.
+ * Dissemination of this information or reproduction of this material
+ * is strictly forbidden unless prior written permission is obtained
+ * from Adobe.
+ **************************************************************************/
+
+import {
+  createExtensionRegistryAsObjectsProvider,
+  ExtensionsProvider,
+  InstalledExtensions,
+} from "@adobe/uix-host";
+
+const EXTENSION_MANAGER_URL_PROD = "https://aemx-mngr.adobe.io";
+const EXTENSION_MANAGER_URL_STAGE = "https://aemx-mngr-stage.adobe.io";
+
+const APP_REGISTRY_URL_PROD = "https://appregistry.adobe.io";
+const APP_REGISTRY_URL_STAGE = "https://appregistry-stage.adobe.io";
+
+// Extension Manager stores information about extension points that a particular extension implements
+// in the "extensionPoints" array of objects of the following "ExtensionPoint" type
+// where "extensionPoint" is the name of the extension point, for example, "aem/assets/details/1"
+// "url" is the extension url for the specified extension point
+type ExtensionPoint = {
+  extensionPoint: string;
+  url: string;
+};
+export type ExtensionManagerExtension = {
+  id: string;
+  name: string;
+  title: string;
+  description: string;
+  status: string;
+  supportEmail: string;
+  extId: string;
+  disabled: boolean;
+  extensionPoints: ExtensionPoint[];
+  scope: Record<string, unknown>;
+  configuration?: Record<string, unknown>;
+};
+
+type AuthEMConfig = {
+  schema: "Bearer" | "Basic";
+  imsToken: string;
+};
+export interface ExtensionManagerConfig {
+  apiKey: string;
+  auth: AuthEMConfig;
+  service: string;
+  extensionPoint: string;
+  version: string;
+  imsOrg: string;
+  baseUrl: string;
+  scope?: Record<string, string>;
+}
+
+/** Authentication configuration, including IMS Org ID, access token, and API key */
+export interface AuthConfig {
+  /** IMS Org ID */
+  imsOrg: string;
+  /** Access token for the user */
+  imsToken: string;
+  /** API key */
+  apiKey: string;
+}
+
+/** Discovery configuration, including environment and repo Id */
+export interface DiscoveryConfig {
+  /** Environment level for backend Extension resolution services */
+  experienceShellEnvironment?: "prod" | "stage";
+  scope?: Record<string, string>;
+}
+
+/** Extension point ID */
+export interface ExtensionPointId {
+  /** Service name */
+  service: string;
+  /** Extension point name */
+  name: string;
+  /** Extension point version */
+  version: string;
+}
+
+/**
+ * Sets up new ExtensionsProvider with authentication and discovery information needed to fetch the list of
+ * Extensions from AppRegistry and Extension Manager service, along with the query string portion of URL
+ * to extract the information about development Extensions
+ */
+export interface ExtensionsProviderConfig {
+  /** Discovery configuration */
+  discoveryConfig: DiscoveryConfig;
+  /** Authentication configuration */
+  authConfig: AuthConfig;
+  /** Extension point ID */
+  extensionPointId: ExtensionPointId;
+  providerConfig: ExtensionProviderConfig;
+}
+
+export interface ExtensionProviderConfig {
+  extensionManagerUrl?: string;
+  appRegistryUrl?: string;
+  disableExtensionManager?: boolean;
+}
+export const getExtensionRegistryBaseUrl = (
+  environment: "prod" | "stage" | undefined,
+  registry: string | null
+): string =>
+  environment === "prod"
+    ? APP_REGISTRY_URL_PROD
+    : registry ?? APP_REGISTRY_URL_STAGE;
+
+export const getExtensionManagerBaseUrl = (
+  environment: "prod" | "stage" | undefined,
+  extensionManager: string | null
+): string =>
+  environment === "prod"
+    ? EXTENSION_MANAGER_URL_PROD
+    : extensionManager ?? EXTENSION_MANAGER_URL_STAGE;
+
+/**
+ * Extracts programId and envId from the repo value
+ * @param repo - the repo value
+ * @returns object with programId and envId
+ * @ignore
+ */
+export function extractProgramIdEnvId(repo: string): {
+  programId: string;
+  envId: string;
+} {
+  const regex: RegExp = /p(\d+)-e(\d+)/;
+  const match: RegExpMatchArray | null = regex.exec(repo);
+  if (!match) {
+    throw new Error("Error parsing a repo value");
+  }
+
+  return {
+    programId: match[1],
+    envId: match[2],
+  };
+}
+
+/**
+ * Builds the URL for fetching extensions from the Extension Manager service
+ * @param config - the Extension Manager configuration
+ * @returns the URL for fetching extensions
+ * @ignore
+ */
+export function buildExtensionManagerUrl(
+  config: ExtensionManagerConfig
+): string {
+  const scope = config.scope
+    ? Object.fromEntries(
+        Object.entries(config.scope).map(([k, v]) => [`scope.${k}`, v])
+      )
+    : {};
+  const extensionPoints: string = `${config.service}/${config.extensionPoint}/${config.version}`;
+  const queryParams = new URLSearchParams({
+    ...scope,
+    extensionPoints,
+  });
+
+  return `${config.baseUrl}/v2/extensions?${queryParams.toString()}`;
+}
+
+/**
+ * @ignore
+ */
+export async function fetchExtensionsFromExtensionManager(
+  config: ExtensionManagerConfig
+): Promise<ExtensionManagerExtension[]> {
+  const resp: Response = await fetch(buildExtensionManagerUrl(config), {
+    headers: {
+      Authorization: `Bearer ${config.auth.imsToken}`,
+      "x-api-key": config.apiKey,
+      "x-org-id": config.imsOrg,
+    },
+  });
+
+  if (resp.status !== 200) {
+    throw new Error(
+      `Extension Manager returned non-200 response (${
+        resp.status
+      }): ${await resp.text()}`
+    );
+  }
+
+  return resp.json();
+}
+
+/**
+ * Takes an array of extensions from the App Registry, an array of extensions from the Extension Manager, and
+ * merges them into a list of Extensions. If an extension is disabled in the Extension Manager, it is removed from
+ * the list.
+ * Extension list from the App Registry is used as a base.
+ * @ignore
+ */
+export function mergeExtensions(
+  appRegistryExtensions: InstalledExtensions,
+  extensionManagerExtensions: ExtensionManagerExtension[],
+  extensionPointId: ExtensionPointId
+): InstalledExtensions {
+  const mergedExtensions: InstalledExtensions = Object.assign(
+    appRegistryExtensions,
+    {}
+  );
+  extensionManagerExtensions.forEach((extension: ExtensionManagerExtension) => {
+    if (extension.disabled) {
+      // remove disabled extensions
+      delete mergedExtensions[extension.name];
+    } else {
+      const extPoint: ExtensionPoint | undefined =
+        extension.extensionPoints.find(
+          (_extensionPoint: ExtensionPoint) =>
+            _extensionPoint.extensionPoint ===
+            `${extensionPointId.service}/${extensionPointId.name}/${extensionPointId.version}`
+        );
+      if (extPoint) {
+        // add a new extension record or replace the existing one by an extension record from Extension Manager
+        // extension points are useful for filtering out extensions
+        mergedExtensions[extension.name] = {
+          id: extension.name,
+          url: extPoint.url,
+          configuration: extension.configuration,
+          extensionPoints: extension.extensionPoints.map(
+            (point) => point.extensionPoint
+          ),
+        };
+      } else {
+        //this should never happen because we query Extension Manager service for our specific extension point
+        console.warn(
+          `Extension point ${extensionPointId.service}/${extensionPointId.name}/${extensionPointId.version} not found for extension ${extension.name}`
+        );
+      }
+    }
+  });
+
+  return mergedExtensions;
+}
+
+async function getExtensionManagerExtensions(
+  discoveryConfig: DiscoveryConfig,
+  authConfig: AuthConfig,
+  providerConfig: ExtensionProviderConfig,
+  extensionPointId: ExtensionPointId
+): Promise<InstalledExtensions> {
+  const config = {
+    apiKey: authConfig.apiKey,
+    auth: {
+      schema: "Bearer",
+      imsToken: authConfig.imsToken,
+    },
+    service: extensionPointId.service,
+    extensionPoint: extensionPointId.name,
+    version: extensionPointId.version,
+    imsOrg: authConfig.imsOrg,
+    scope: discoveryConfig.scope,
+  };
+
+  const appRegistryConfig = {
+    ...config,
+    baseUrl: getExtensionRegistryBaseUrl(
+      discoveryConfig.experienceShellEnvironment,
+      providerConfig.appRegistryUrl
+    ),
+  } as ExtensionManagerConfig;
+  const appRegistryExtensionsProvider: ExtensionsProvider =
+    createExtensionRegistryAsObjectsProvider(appRegistryConfig);
+
+  const extensionManagerConfiguration = {
+    ...config,
+    baseUrl: getExtensionManagerBaseUrl(
+      discoveryConfig.experienceShellEnvironment,
+      providerConfig.extensionManagerUrl
+    ),
+  } as ExtensionManagerConfig;
+  const [appRegistryExtensions, extensionManagerExtensions] = await Promise.all(
+    [
+      appRegistryExtensionsProvider(),
+      providerConfig.disableExtensionManager
+        ? []
+        : fetchExtensionsFromExtensionManager(extensionManagerConfiguration),
+    ]
+  );
+
+  if (providerConfig.disableExtensionManager) {
+    return appRegistryExtensions;
+  } else {
+    return mergeExtensions(
+      appRegistryExtensions,
+      extensionManagerExtensions,
+      extensionPointId
+    );
+  }
+}
+
+/**
+ * Creates an extension manager extension provider
+ * @ignore
+ */
+export function createExtensionManagerExtensionsProvider(
+  discoveryConfig: DiscoveryConfig,
+  authConfig: AuthConfig,
+  providerConfig: ExtensionProviderConfig,
+  extensionPointId: ExtensionPointId
+): ExtensionsProvider {
+  return () => {
+    return getExtensionManagerExtensions(
+      discoveryConfig,
+      authConfig,
+      providerConfig,
+      extensionPointId
+    );
+  };
+}

package/src/components/ExtensibleWrapper/UrlExtensionProvider.test.ts

@@ -0,0 +1,119 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import {
+  extractExtUrlParams,
+  generateExtensionId,
+  createUrlExtensionsProvider,
+} from "./UrlExtensionProvider";
+import { ExtensionPointId } from "./ExtensionManagerProvider";
+describe("extractExtUrlParams", () => {
+  it("should return an empty object when no query string is provided", () => {
+    expect(extractExtUrlParams(undefined)).toEqual({});
+  });
+
+  it("should return an empty object when the query string does not contain any valid extension params", () => {
+    expect(extractExtUrlParams("foo=bar&baz=qux")).toEqual({});
+  });
+
+  it("should extract valid extension params", () => {
+    const queryString =
+      "ext=foo&ext.service1.name1.version1=http://example.com";
+    const expectedParams = {
+      ext: "foo",
+      "ext.service1.name1.version1": "http://example.com",
+    };
+    expect(extractExtUrlParams(queryString)).toEqual(expectedParams);
+  });
+
+  it('should only include params with the "ext" prefix', () => {
+    const queryString =
+      "ext=foo&other=bar&ext.service1.name1.version1=http://example.com";
+    const expectedParams = {
+      ext: "foo",
+      "ext.service1.name1.version1": "http://example.com",
+    };
+    expect(extractExtUrlParams(queryString)).toEqual(expectedParams);
+  });
+});
+
+describe("generateExtensionId", () => {
+  it("should replace non-word characters with underscores", () => {
+    const url = "http://example.com/some/path";
+    expect(generateExtensionId(url)).toBe("http___example_com_some_path");
+  });
+
+  it("should return the same ID when there are no non-word characters", () => {
+    const url = "extension_1";
+    expect(generateExtensionId(url)).toBe("extension_1");
+  });
+});
+
+describe("createUrlExtensionsProvider", () => {
+  const mockExtensionPointId: ExtensionPointId = {
+    service: "service1",
+    name: "name1",
+    version: "version1",
+  };
+
+  it("should return an ExtensionsProvider that provides installed extensions", async () => {
+    const queryString =
+      "ext=foo&ext.service1/name1/version1=http://example2.com";
+    const provider = createUrlExtensionsProvider(
+      mockExtensionPointId,
+      queryString
+    );
+
+    const extensions = await provider();
+    expect(Object.keys(extensions)).toHaveLength(2);
+    expect(extensions).toHaveProperty("foo");
+    expect(extensions).toHaveProperty("http___example2_com");
+    expect(extensions["http___example2_com"]).toHaveProperty(
+      "url",
+      "http://example2.com"
+    );
+  });
+
+  it("should return an empty object if no valid extensions are found in the query string", async () => {
+    const queryString = "foo=bar&baz=qux";
+    const provider = createUrlExtensionsProvider(
+      mockExtensionPointId,
+      queryString
+    );
+
+    const extensions = await provider();
+    expect(extensions).toEqual({});
+  });
+
+  it("should filter extensions by the correct extension point", async () => {
+    const queryString =
+      "ext.service1/name1/version1=http://example1.com&ext.service2/name2/version2=https://www.test.";
+    const provider = createUrlExtensionsProvider(
+      mockExtensionPointId,
+      queryString
+    );
+
+    const extensions = await provider();
+    expect(extensions).toHaveProperty("http___example1_com");
+  });
+
+  it("should return an empty object when the query string does not match the expected extension point", async () => {
+    const queryString = "ext.service2.name2.version2=http://example1.com";
+    const provider = createUrlExtensionsProvider(
+      mockExtensionPointId,
+      queryString
+    );
+
+    const extensions = await provider();
+    expect(extensions).toEqual({});
+  });
+});

package/src/components/ExtensibleWrapper/UrlExtensionProvider.ts

@@ -0,0 +1,93 @@
+/*************************************************************************
+ * ADOBE CONFIDENTIAL
+ * ___________________
+ *
+ * Copyright 2024 Adobe
+ * All Rights Reserved.
+ *
+ * NOTICE: All information contained herein is, and remains
+ * the property of Adobe and its suppliers, if any. The intellectual
+ * and technical concepts contained herein are proprietary to Adobe
+ * and its suppliers and are protected by all applicable intellectual
+ * property laws, including trade secret and copyright laws.
+ * Dissemination of this information or reproduction of this material
+ * is strictly forbidden unless prior written permission is obtained
+ * from Adobe.
+ **************************************************************************/
+import { ExtensionsProvider, InstalledExtensions } from "@adobe/uix-host";
+import { Extension } from "@adobe/uix-core";
+import { ExtensionPointId } from "./ExtensionManagerProvider";
+
+const EXT_PARAM_PREFIX = "ext";
+
+export interface ExtUrlParams {
+  [key: string]: string;
+}
+
+/**
+ * Extracts extension URLs from the query string
+ * @ignore
+ */
+export function extractExtUrlParams(
+  queryString: string | undefined
+): ExtUrlParams {
+  if (!queryString) {
+    return {};
+  }
+  const params: URLSearchParams = new URLSearchParams(queryString);
+  return Array.from(params.entries()).reduce((extParams, [key, value]) => {
+    if (key === EXT_PARAM_PREFIX || key.startsWith(`${EXT_PARAM_PREFIX}.`)) {
+      extParams[key] = value;
+    }
+    return extParams;
+  }, {} as ExtUrlParams);
+}
+
+/**
+ * Generates an extension ID from the extension URL
+ * @ignore
+ */
+export function generateExtensionId(extensionUrl: string): string {
+  return extensionUrl.replace(/\W/g, "_");
+}
+
+/**
+ * Creates an ExtensionsProvider that provides extensions from the URL
+ * @ignore
+ */
+export function createUrlExtensionsProvider(
+  extensionPointId: ExtensionPointId,
+  queryString: string | undefined
+): ExtensionsProvider {
+  const extUrlParams: ExtUrlParams = extractExtUrlParams(queryString);
+
+  const extensionUrls: string[] = Object.keys(extUrlParams)
+    .filter(
+      (extParam) =>
+        extParam === EXT_PARAM_PREFIX ||
+        extParam ===
+          `${EXT_PARAM_PREFIX}.${extensionPointId.service}/${extensionPointId.name}/${extensionPointId.version}`
+    )
+    .flatMap((extParam) => {
+      const paramValue = extUrlParams[extParam];
+      // If it's a single value, return it in an array. If it's already an array, return it as is.
+      return Array.isArray(paramValue) ? paramValue : [paramValue];
+    });
+
+  const installedExtensions: InstalledExtensions = extensionUrls
+    .map((extensionUrl: string) => {
+      return {
+        id: generateExtensionId(extensionUrl),
+        url: extensionUrl,
+        extensionPoints: [
+          `${extensionPointId.service}/${extensionPointId.name}/${extensionPointId.version}`,
+        ],
+      } as Extension;
+    })
+    .reduce((acc: InstalledExtensions, extension: Extension) => {
+      acc[extension.id] = extension;
+      return acc;
+    }, {} as InstalledExtensions);
+
+  return async () => installedExtensions;
+}

package/src/components/ExtensibleWrapper/index.ts

@@ -0,0 +1,15 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+export * from "./ExtensibleWrapper";
+export * from "./UrlExtensionProvider";
+export * from "./ExtensionManagerProvider";

package/src/components/index.ts

@@ -13,3 +13,4 @@ governing permissions and limitations under the License.
 export * from "./Extensible.js";
 export * from "./GuestUIFrame.js";
 export * from "./ExtensibleComponentBoundary.js";
+export * from "./ExtensibleWrapper/index.js";