@adobe/uix-host 0.6.3

package/dist/port.d.ts

@@ -0,0 +1,173 @@
+import type { Emits, GuestConnection, HostMethodAddress, NamedEvent, RemoteHostApis, GuestApis } from "@adobe/uix-core";
+import { Emitter } from "@adobe/uix-core";
+import { Connection } from "penpal";
+/**
+ * A specifier for methods to be expected on a remote interface.
+ *
+ * @remarks
+ * A CapabilitySpec is a description of an interface, like a very simplified
+ * type definition. It specifies an object structure and the paths in that
+ * structure that must be functions. (It doesn't specify anything about the
+ * signatures or return values of those functions.)
+ *
+ * Use CapabilitySpec objects as queries, or filters, to get a subset of
+ * installed extensions which have registered methods which match the spec.
+ *
+ * @example
+ * As an extensible app developer, you are making an extension point for spell
+ * check. Your code expects extensions to register an API `spellCheck` with
+ * methods called `spellCheck.correct(text)` and `spellCheck.suggest(text)`.
+ *
+ * ```javascript
+ * async function correctText(text) {
+ *   const spellCheckers = host.getLoadedGuests({
+ *     spellCheck: [
+ *       'correct',
+ *       'suggest'
+ *     ]
+ *   });
+ *   let correcting = text;
+ *   for (const checker of spellCheckers) {
+ *     correcting = await checker.apis.spellCheck.correct(correcting);
+ *   }
+ *   return Promise.all(checkers.map(checker =>
+ *     checker.apis.spellCheck.suggest(correcting)
+ *   ));
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type CapabilitySpec<T extends GuestApis> = {
+    [Name in keyof T]: (keyof T[Name])[];
+};
+/** @public */
+declare type PortEvent<GuestApi, Type extends string = string, Detail = Record<string, unknown>> = NamedEvent<Type, Detail & Record<string, unknown> & {
+    guestPort: Port<GuestApi>;
+}>;
+/** @public */
+export declare type PortEvents<GuestApi, HostApi extends Record<string, unknown> = Record<string, unknown>> = PortEvent<GuestApi, "hostprovide"> | PortEvent<GuestApi, "unload"> | PortEvent<GuestApi, "beforecallhostmethod", HostMethodAddress<HostApi>>;
+/** @public */
+export declare type PortOptions = {
+    /**
+     * Time in milliseconds to wait for the guest to connect before throwing.
+     */
+    timeout?: number;
+    /**
+     * Set true to log copiously in the console.
+     */
+    debug?: boolean;
+};
+/**
+ * A Port is the Host-maintained  object representing an extension running as a
+ * guest. It exposes methods registered by the Guest, and can provide Host
+ * methods back to the guest.
+ *
+ * @remarks
+ * When the Host object loads extensions via {@link Host.load}, it creates a
+ * Port object for each extension. When retrieving and filtering extensions
+ * via {@link Host.(getLoadedGuests:2)}, a list of Port objects is returned. From
+ * the point of view of the extensible app using the Host object, extensions
+ * are always Port objects, which expose the methods registered by the
+ * extension at the {@link Port.apis} property.
+ *
+ * @privateRemarks
+ * We've gone through several possible names for this object. GuestProxy,
+ * GuestInterface, GuestConnection, etc. "Port" is not ideal, but it conflicted
+ * the least with other types we defined in early drafts. It's definitely
+ * something we should review.
+ * @public
+ */
+export declare class Port<GuestApi> extends Emitter<PortEvents<GuestApi>> implements GuestConnection {
+    private connection;
+    private debug;
+    private debugLogger?;
+    private frame;
+    private guest;
+    private hostApis;
+    private isLoaded;
+    private runtimeContainer;
+    private sharedContext;
+    private subscriptions;
+    private timeout;
+    /**
+     * Dictionary of namespaced methods that were registered by this guest at the
+     * time of connection, using {@link @adobe/uix-guest#register}.
+     *
+     * @remarks
+     * These methods are proxy methods; you can only pass serializable objects to
+     * them, not class instances, methods or callbacks.
+     * @public
+     */
+    apis: RemoteHostApis;
+    /**
+     * If any errors occurred during the loading of guests, this property will
+     * contain the error that was raised.
+     * @public
+     */
+    error?: Error;
+    private uiConnections;
+    /**
+     * The URL of the guest provided by the extension registry. The Host will
+     * load this URL in the background, in the invisible the bootstrap frame, so
+     * this URL must point to a page that calls {@link @adobe/uix-guest#register}
+     * when it loads.
+     */
+    url: URL;
+    constructor(config: {
+        owner: string;
+        id: string;
+        url: URL;
+        /**
+         * An alternate DOM element to use for invisible iframes. Will create its
+         * own if this option is not populated with a DOM element.
+         */
+        runtimeContainer: HTMLElement;
+        options: PortOptions;
+        debugLogger?: Console;
+        /**
+         * Initial object to populate the shared context with. Once the guest
+         * connects, it will be able to access these properties.
+         */
+        sharedContext: Record<string, unknown>;
+        events: Emits;
+    });
+    /**
+     * Connect an iframe element which is displaying another page in the extension
+     * with the extension's bootstrap frame, so they can share context and events.
+     */
+    attachUI(iframe: HTMLIFrameElement): Connection<RemoteHostApis<GuestApi>>;
+    /**
+     * Returns true if the guest has registered methods matching the provided
+     * capability spec. A capability spec is simply an object whose properties are
+     * declared in an array of keys, description the names of the functions and
+     * methods that the Port will expose.
+     */
+    hasCapabilities(requiredMethods: CapabilitySpec<GuestApis>): boolean;
+    /**
+     * True when al extensions have loaded.
+     */
+    isReady(): boolean;
+    /**
+     * Loads the extension. Returns a promise which resolves when the extension
+     * has loaded. The Host calls this method after retrieving extensions.
+     */
+    load(): Promise<RemoteHostApis<import("@adobe/uix-core").VirtualApi>>;
+    /**
+     * The host-side equivalent of {@link @adobe/uix-guest#register}. Pass a set
+     * of methods down to the guest as proxies.
+     */
+    provide(apis: RemoteHostApis): void;
+    /**
+     * Disconnect from the extension.
+     */
+    unload(): Promise<void>;
+    private assert;
+    private assertReady;
+    private attachFrame;
+    private connect;
+    private getHostMethodCallee;
+    private invokeHostMethod;
+}
+export {};
+//# sourceMappingURL=port.d.ts.map

package/dist/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../src/port.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@adobe/uix-host",
+  "version": "0.6.3",
+  "description": "Tools for embedding UIX Extensions into Adobe apps",
+  "author": "Adobe, Inc,",
+  "type": "module",
+  "module": "dist/esm/index.js",
+  "main": "dist/index.js",
+  "exports": {
+    "import": "./dist/esm/index.js",
+    "require": "./dist/index.js"
+  },
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "watch": "tsup --watch --silent"
+  },
+  "browserslist": [
+    "> 0.2%, last 2 versions, not dead"
+  ],
+  "bugs": "https://git.corp.adobe.com/dx-devex-acceleration/uix-sdk/issues",
+  "dependencies": {
+    "@adobe/uix-core": "^0.6.3",
+    "penpal": "~6.2.2"
+  },
+  "files": [
+    "README.md",
+    "dist",
+    "src",
+    "tsconfig.json"
+  ],
+  "homepage": "https://git.corp.adobe.com/dx-devex-acceleration/uix-sdk",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://git.corp.adobe.com/dx-devex-acceleration/uix-sdk.git"
+  },
+  "sideEffects": false
+}

package/src/debug-host.ts

@@ -0,0 +1,79 @@
+/*
+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.
+*/
+
+/* eslint-disable @typescript-eslint/restrict-template-expressions */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/**
+ * Adapter to attach console logging listeners to a Host running in an app
+ * @hidden
+ */
+import {
+  debugEmitter,
+  EmitterDebugLogger,
+  Emits,
+  GuestConnection,
+} from "@adobe/uix-core";
+import type { PortEvents } from "./port.js";
+import type { HostEventLoadAllGuests, HostEvents } from "./host.js";
+
+type GenericPortEvents = PortEvents<Record<string, unknown>>;
+
+type Portlike = GuestConnection & Emits<GenericPortEvents>;
+
+export function debugHost(host: Emits<HostEvents>): EmitterDebugLogger {
+  const hostLogger = debugEmitter(host, {
+    theme: "blue medium",
+    type: "Host",
+  });
+  hostLogger
+    .listen("guestbeforeload", (log, event) => {
+      const { detail } = event;
+      const guest = detail.guest as Portlike;
+      log.info(event, `Guest ID ${guest.id}`);
+      const portLogger = debugEmitter(guest, {
+        theme: "green medium",
+        type: "Port",
+        id: `${host.id} ➔ ${guest.id}`,
+      });
+      portLogger
+        .listen("hostprovide", (log, event) => {
+          log.info("received APIs", event.detail.apis);
+        })
+        .listen("beforecallhostmethod", (log, event) => {
+          log.info(event.detail);
+        })
+        .listen("unload", (log, event) => {
+          log.info(event.detail);
+          log.detach();
+        });
+    })
+    .listen("guestload", (log, e) => {
+      log.info(e.detail.guest.id, e.detail.guest);
+    })
+    .listen("error", (log, e) => {
+      log.error(`Error: ${e.detail.error.message}`, e);
+    })
+    .listen(
+      "loadallguests",
+      (log, { detail: { failed, loaded, host } }: HostEventLoadAllGuests) => {
+        if (failed.length > 0) {
+          log.error("%d guests failed to load!", failed.length);
+        }
+        log.info("%d guests loaded", loaded.length, host);
+      }
+    )
+    .listen("unload", (log) => {
+      log.info("Unloaded guest and container.");
+      log.detach();
+    });
+  return hostLogger;
+}

package/src/extensions-provider/composition.ts

@@ -0,0 +1,30 @@
+/*
+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 { InstalledExtensions, ExtensionsProvider } from "../host.js";
+
+/**
+ * Combine multiple {@link @adobe/uix-host#ExtensionsProvider} callbacks into a
+ * single callback, which aggregates and dedupes all extensions from all
+ * providers into one namespaced object.
+ * @public
+ */
+export function combineExtensionsFromProviders(
+  ...providers: Array<ExtensionsProvider>
+): ExtensionsProvider {
+  return () =>
+    Promise.all(providers.map((ep: ExtensionsProvider) => ep())).then(
+      (extensionsBatches: Array<InstalledExtensions>) => {
+        return Object.assign({}, ...extensionsBatches);
+      }
+    );
+}

package/src/extensions-provider/extension-registry.ts

@@ -0,0 +1,152 @@
+/*
+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 { InstalledExtensions, ExtensionsProvider } from "../host.js";
+
+interface ExtensionDefinition {
+  name: string;
+  title: string;
+  description: string;
+  icon: string;
+  publisher: string;
+  endpoints: Record<string, EndpointDefinition>;
+  xrInfo: ExtensionInfo;
+  status: string;
+}
+
+type EndpointDefinition = Record<string, Array<OperationDefinition>>;
+
+interface ExtensionInfo {
+  supportEmail: string;
+  appId: string;
+}
+
+interface OperationDefinition {
+  href: string;
+  metadata: OperationMetadata;
+}
+
+interface OperationMetadata {
+  services: Array<object>;
+  profile: OperationProfile;
+}
+
+interface OperationProfile {
+  client_id: string;
+  scope: string;
+}
+
+/** @public */
+export interface ExtensionRegistryEndpointRegistration {
+  service: string;
+  extensionPoint: string;
+  version: string;
+}
+
+/** @public */
+export interface ExtensionRegistryExtensionRegistration
+  extends ExtensionRegistryEndpointRegistration {
+  imsOrg: string;
+}
+
+/** @public */
+export interface ExtensionRegistryConnection {
+  baseUrl?: string;
+  apiKey: string;
+  auth: {
+    schema: "Basic" | "Bearer";
+    imsToken: string;
+  };
+}
+
+/** @public */
+export interface ExtensionRegistryConfig
+  extends ExtensionRegistryExtensionRegistration,
+    ExtensionRegistryConnection {}
+
+function buildEndpointPath(
+  config: ExtensionRegistryEndpointRegistration
+): string {
+  return `${config.service}/${config.extensionPoint}/${config.version}`;
+}
+
+function ensureProtocolSpecified(url: string) {
+  if (url.startsWith("https://")) {
+    return url;
+  }
+  if (url.startsWith("http://")) {
+    return url;
+  }
+  return `https://${url}`;
+}
+
+async function fetchExtensionsFromRegistry(
+  config: ExtensionRegistryConfig
+): Promise<Array<ExtensionDefinition>> {
+  const resp = await fetch(
+    `${ensureProtocolSpecified(
+      config.baseUrl || "appregistry.adobe.io"
+    )}/myxchng/v1/org/${encodeURIComponent(
+      config.imsOrg
+    )}/xtn/${buildEndpointPath(config)}?auth=true`,
+    {
+      headers: {
+        Accept: "application/json",
+        Authorization: `${config.auth.schema} ${config.auth.imsToken}`, // todo: check if auth schema needed (initial implementation was without it)
+        "X-Api-Key": config.apiKey,
+      },
+    }
+  );
+
+  if (resp.status != 200) {
+    throw new Error(
+      `extension registry returned non-200 response (${
+        resp.status
+      }): ${await resp.text()}`
+    );
+  }
+
+  return await resp.json();
+}
+
+function extensionRegistryExtensionsProvider(
+  config: ExtensionRegistryConfig
+): Promise<InstalledExtensions> {
+  const erEndpoint = buildEndpointPath(config);
+  return fetchExtensionsFromRegistry(config).then((out) =>
+    out.reduce((a, e: ExtensionDefinition) => {
+      if (e.status !== "PUBLISHED") {
+        return a;
+      }
+
+      return {
+        ...a,
+        // todo: make safer way to extract href
+        [e.name]: e.endpoints[erEndpoint].view[0].href,
+      };
+    }, {})
+  );
+
+  return Promise.resolve({});
+}
+
+/**
+ * Create a callback that fetches extensions from the registry.
+ * @public
+ */
+export function createExtensionRegistryProvider(
+  config: ExtensionRegistryConfig
+): ExtensionsProvider {
+  return function () {
+    return extensionRegistryExtensionsProvider(config);
+  };
+}

package/src/extensions-provider/index.ts

@@ -0,0 +1,14 @@
+/*
+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 "./extension-registry.js";
+export * from "./composition.js";