Add support for MSC2871: Notifying the widget of its capabilities

This causes the `ready` event of the `WidgetApi` to change to when the client notifies the widget of its approved capabilities (when the client supports the MSC).

MSC2871: matrix-org/matrix-spec-proposals#2871

Author: turt2live

src/ClientWidgetApi.ts

@@ -25,7 +25,7 @@ import { WidgetApiFromWidgetAction, WidgetApiToWidgetAction } from "./interfaces
 import { IWidgetApiErrorResponseData } from "./interfaces/IWidgetApiErrorResponse";
 import { Capability } from "./interfaces/Capabilities";
 import { ISendEventDetails, WidgetDriver } from "./driver/WidgetDriver";
-import { ICapabilitiesActionResponseData } from "./interfaces/CapabilitiesAction";
+import { ICapabilitiesActionResponseData, INotifyCapabilitiesActionRequestData } from "./interfaces/CapabilitiesAction";
 import {
     ISupportedVersionsActionRequest,
     ISupportedVersionsActionResponseData,
@@ -163,15 +163,23 @@ export class ClientWidgetApi extends EventEmitter {
         // widget has loaded - tell all the listeners that
         this.emit("preparing");
 
+        let requestedCaps: Capability[];
         this.transport.send<IWidgetApiRequestEmptyData, ICapabilitiesActionResponseData>(
             WidgetApiToWidgetAction.Capabilities, {},
         ).then(caps => {
+            requestedCaps = caps.capabilities;
             return this.driver.validateCapabilities(new Set(caps.capabilities));
         }).then(allowedCaps => {
             console.log(`Widget ${this.widget.id} is allowed capabilities:`, Array.from(allowedCaps));
             this.allowedCapabilities = allowedCaps;
             this.allowedEvents = WidgetEventCapability.findEventCapabilities(allowedCaps);
             this.capabilitiesFinished = true;
+            this.transport.send(WidgetApiToWidgetAction.NotifyCapabilities, <INotifyCapabilitiesActionRequestData>{
+                requested: requestedCaps,
+                approved: Array.from(allowedCaps),
+            }).catch(e => {
+                console.warn("non-fatal error notifying widget of approved capabilities:", e);
+            });
             this.emit("ready");
         });
     }

src/WidgetApi.ts

@@ -22,8 +22,12 @@ import {
     ISupportedVersionsActionRequest,
     ISupportedVersionsActionResponseData,
 } from "./interfaces/SupportedVersionsAction";
-import { CurrentApiVersions } from "./interfaces/ApiVersion";
-import { ICapabilitiesActionRequest, ICapabilitiesActionResponseData } from "./interfaces/CapabilitiesAction";
+import { ApiVersion, CurrentApiVersions, UnstableApiVersion } from "./interfaces/ApiVersion";
+import {
+    ICapabilitiesActionRequest,
+    ICapabilitiesActionResponseData,
+    INotifyCapabilitiesActionRequest,
+} from "./interfaces/CapabilitiesAction";
 import { ITransport } from "./transport/ITransport";
 import { PostmessageTransport } from "./transport/PostmessageTransport";
 import { WidgetApiFromWidgetAction, WidgetApiToWidgetAction } from "./interfaces/WidgetApiAction";
@@ -39,11 +43,11 @@ import {
 import { IOpenIDCredentialsActionRequest } from "./interfaces/OpenIDCredentialsAction";
 import { MatrixWidgetType, WidgetType } from "./interfaces/WidgetType";
 import {
+    BuiltInModalButtonID,
     IModalWidgetCreateData,
     IModalWidgetOpenRequestData,
     IModalWidgetOpenRequestDataButton,
     IModalWidgetReturnData,
-    BuiltInModalButtonID,
     ModalButtonID,
 } from "./interfaces/ModalWidgetActions";
 import { ISetModalButtonEnabledActionRequestData } from "./interfaces/SetModalButtonEnabledAction";
@@ -71,6 +75,8 @@ export class WidgetApi extends EventEmitter {
 
     private capabilitiesFinished = false;
     private requestedCapabilities: Capability[] = [];
+    private approvedCapabilities: Capability[];
+    private cachedClientVersions: ApiVersion[];
 
     /**
      * Creates a new API handler for the given widget.
@@ -93,6 +99,20 @@ export class WidgetApi extends EventEmitter {
         this.transport.on("message", this.handleMessage.bind(this));
     }
 
+    /**
+     * Determines if the widget was granted a particular capability. Note that on
+     * clients where the capabilities are not fed back to the widget this function
+     * will rely on requested capabilities instead.
+     * @param {Capability} capability The capability to check for approval of.
+     * @returns {boolean} True if the widget has approval for the given capability.
+     */
+    public hasCapability(capability: Capability): boolean {
+        if (Array.isArray(this.approvedCapabilities)) {
+            return this.approvedCapabilities.includes(capability);
+        }
+        return this.requestedCapabilities.includes(capability);
+    }
+
     /**
      * Request a capability from the client. It is not guaranteed to be allowed,
      * but will be asked for if the negotiation has not already happened.
@@ -277,6 +297,8 @@ export class WidgetApi extends EventEmitter {
                     return this.handleCapabilities(<ICapabilitiesActionRequest>ev.detail);
                 case WidgetApiToWidgetAction.UpdateVisibility:
                     return this.transport.reply(ev.detail, <IWidgetApiRequestEmptyData>{}); // ack to avoid error spam
+                case WidgetApiToWidgetAction.NotifyCapabilities:
+                    return this.transport.reply(ev.detail, <IWidgetApiRequestEmptyData>{}); // ack to avoid error spam
                 default:
                     return this.transport.reply(ev.detail, <IWidgetApiErrorResponseData>{
                         error: {
@@ -293,6 +315,22 @@ export class WidgetApi extends EventEmitter {
         });
     }
 
+    private getClientVersions(): Promise<ApiVersion[]> {
+        if (Array.isArray(this.cachedClientVersions)) {
+            return Promise.resolve(this.cachedClientVersions);
+        }
+
+        return this.transport.send<IWidgetApiRequestEmptyData, ISupportedVersionsActionResponseData>(
+            WidgetApiFromWidgetAction.SupportedApiVersions, {},
+        ).then(r => {
+            this.cachedClientVersions = r.supported_versions;
+            return r.supported_versions;
+        }).catch(e => {
+            console.warn("non-fatal error getting supported client versions: ", e);
+            return [];
+        });
+    }
+
     private handleCapabilities(request: ICapabilitiesActionRequest) {
         if (this.capabilitiesFinished) {
             return this.transport.reply<IWidgetApiErrorResponseData>(request, {
@@ -301,10 +339,27 @@ export class WidgetApi extends EventEmitter {
                 },
             });
         }
-        this.capabilitiesFinished = true;
-        this.emit("ready");
-        return this.transport.reply<ICapabilitiesActionResponseData>(request, {
-            capabilities: this.requestedCapabilities,
+
+        // See if we can expect a capabilities notification or not
+        return this.getClientVersions().then(v => {
+            if (v.includes(UnstableApiVersion.MSC2871)) {
+                this.once(
+                    `action:${WidgetApiToWidgetAction.NotifyCapabilities}`,
+                    (ev: CustomEvent<INotifyCapabilitiesActionRequest>) => {
+                        this.approvedCapabilities = ev.detail.data.approved;
+                        this.emit("ready");
+                    },
+                );
+            } else {
+                // if we can't expect notification, we're as done as we can be
+                this.emit("ready");
+            }
+
+            // in either case, reply to that capabilities request
+            this.capabilitiesFinished = true;
+            return this.transport.reply<ICapabilitiesActionResponseData>(request, {
+                capabilities: this.requestedCapabilities,
+            });
         });
     }
 }

src/interfaces/ApiVersion.ts

@@ -22,6 +22,7 @@ export enum MatrixApiVersion {
 
 export enum UnstableApiVersion {
     MSC2762 = "org.matrix.msc2762",
+    MSC2871 = "org.matrix.msc2871",
 }
 
 export type ApiVersion = MatrixApiVersion | UnstableApiVersion | string;
@@ -31,4 +32,5 @@ export const CurrentApiVersions: ApiVersion[] = [
     MatrixApiVersion.Prerelease2,
     MatrixApiVersion.V010,
     UnstableApiVersion.MSC2762,
+    UnstableApiVersion.MSC2871,
 ];

src/interfaces/CapabilitiesAction.ts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 
-import { IWidgetApiRequest, IWidgetApiRequestEmptyData } from "./IWidgetApiRequest";
+import { IWidgetApiRequest, IWidgetApiRequestData, IWidgetApiRequestEmptyData } from "./IWidgetApiRequest";
 import { WidgetApiToWidgetAction } from "./WidgetApiAction";
 import { Capability } from "./Capabilities";
-import { IWidgetApiResponseData } from "./IWidgetApiResponse";
+import { IWidgetApiAcknowledgeResponseData, IWidgetApiResponseData } from "./IWidgetApiResponse";
 
 export interface ICapabilitiesActionRequest extends IWidgetApiRequest {
     action: WidgetApiToWidgetAction.Capabilities;
@@ -31,3 +31,17 @@ export interface ICapabilitiesActionResponseData extends IWidgetApiResponseData
 export interface ICapabilitiesActionResponse extends ICapabilitiesActionRequest {
     response: ICapabilitiesActionResponseData;
 }
+
+export interface INotifyCapabilitiesActionRequestData extends IWidgetApiRequestData {
+    requested: Capability[];
+    approved: Capability[];
+}
+
+export interface INotifyCapabilitiesActionRequest extends IWidgetApiRequest {
+    action: WidgetApiToWidgetAction.NotifyCapabilities;
+    data: INotifyCapabilitiesActionRequestData;
+}
+
+export interface INotifyCapabilitiesActionResponse extends INotifyCapabilitiesActionRequest {
+    response: IWidgetApiAcknowledgeResponseData;
+}

src/interfaces/WidgetApiAction.ts

@@ -17,6 +17,7 @@
 export enum WidgetApiToWidgetAction {
     SupportedApiVersions = "supported_api_versions",
     Capabilities = "capabilities",
+    NotifyCapabilities = "notify_capabilities",
     TakeScreenshot = "screenshot",
     UpdateVisibility = "visibility",
     OpenIDCredentials = "openid_credentials",