Pass HTTP status code & errcode from CS-API errors

.eslintrc.js

@@ -31,6 +31,9 @@ module.exports = {
         "files": ["src/**/*.ts", "test/**/*.ts"],
         "extends": ["matrix-org/ts"],
         "rules": {
+            // TypeScript has its own version of this
+            "babel/no-invalid-this": "off",
+
             "quotes": "off",
         },
     }],

src/ClientWidgetApi.ts

@@ -330,15 +330,13 @@
             });
         }
 
-        const onErr = (e: any) => {
+        const onErr = (e: unknown) => {
             console.error("[ClientWidgetApi] Failed to handle navigation: ", e);
-            return this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: {message: "Error handling navigation"},
-            });
+            this.handleDriverError(e, request, "Error handling navigation");
         };
 
         try {
-            this.driver.navigate(request.data.uri.toString()).catch(e => onErr(e)).then(() => {
+            this.driver.navigate(request.data.uri.toString()).catch((e: unknown) => onErr(e)).then(() => {
                 return this.transport.reply<IWidgetApiAcknowledgeResponseData>(request, {});
             });
         } catch (e) {
@@ -437,7 +435,7 @@
         if (request.data.room_ids) {
             askRoomIds = request.data.room_ids as string[];
             if (!Array.isArray(askRoomIds)) {
                 askRoomIds = [askRoomIds as any as string];
             }
             for (const roomId of askRoomIds) {
                 if (!this.canUseRoomTimeline(roomId)) {
@@ -554,11 +552,9 @@
                     delay_id: sentEvent.delayId,
                 }),
             });
-        }).catch(e => {
+        }).catch((e: unknown) => {
             console.error("error sending event: ", e);
-            return this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: {message: "Error sending event"},
-            });
+            this.handleDriverError(e, request, "Error sending event");
         });
     }
 
@@ -581,11 +577,9 @@
             case UpdateDelayedEventAction.Send:
                 this.driver.updateDelayedEvent(request.data.delay_id, request.data.action).then(() => {
                     return this.transport.reply<IWidgetApiAcknowledgeResponseData>(request, {});
-                }).catch(e => {
+                }).catch((e: unknown) => {
                     console.error("error updating delayed event: ", e);
-                    return this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                        error: {message: "Error updating delayed event"},
-                    });
+                    this.handleDriverError(e, request, "Error updating delayed event");
                 });
                 break;
             default:
@@ -618,9 +612,7 @@
                 await this.transport.reply<ISendToDeviceFromWidgetResponseData>(request, {});
             } catch (e) {
                 console.error("error sending to-device event", e);
-                await this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                    error: {message: "Error sending event"},
-                });
+                this.handleDriverError(e, request, "Error sending event");
             }
         }
     }
@@ -735,9 +727,7 @@
             );
         } catch (e) {
             console.error("error getting the relations", e);
-            await this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: { message: "Unexpected error while reading relations" },
-            });
+            this.handleDriverError(e, request, "Unexpected error while reading relations");
         }
     }
 
@@ -778,9 +768,7 @@
             );
         } catch (e) {
             console.error("error searching in the user directory", e);
-            await this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: { message: "Unexpected error while searching in the user directory" },
-            });
+            this.handleDriverError(e, request, "Unexpected error while searching in the user directory");
         }
     }
 
@@ -800,9 +788,7 @@
             );
         } catch (e) {
             console.error("error while getting the media configuration", e);
-            await this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: { message: "Unexpected error while getting the media configuration" },
-            });
+            this.handleDriverError(e, request, "Unexpected error while getting the media configuration");
         }
     }
 
@@ -822,9 +808,7 @@
             );
         } catch (e) {
             console.error("error while uploading a file", e);
-            await this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: { message: "Unexpected error while uploading a file" },
-            });
+            this.handleDriverError(e, request, "Unexpected error while uploading a file");
         }
     }
 
@@ -844,12 +828,20 @@
             );
         } catch (e) {
             console.error("error while downloading a file", e);
-            this.transport.reply<IWidgetApiErrorResponseData>(request, {
-                error: { message: "Unexpected error while downloading a file" },
-            });
+            this.handleDriverError(e, request, "Unexpected error while downloading a file");
         }
     }
 
+    private handleDriverError(e: unknown, request: IWidgetApiRequest, message: string) {
+        const data = this.driver.processError(e);
+        this.transport.reply<IWidgetApiErrorResponseData>(request, {
+            error: {
+                message,
+                ...data,
+            },
+        });
+    }
+
     private handleMessage(ev: CustomEvent<IWidgetApiRequest>) {
         if (this.isStopped) return;
         const actionEv = new CustomEvent(`action:${ev.detail.action}`, {

src/WidgetApi.ts

@@ -33,7 +33,7 @@ import {
 import { ITransport } from "./transport/ITransport";
 import { PostmessageTransport } from "./transport/PostmessageTransport";
 import { WidgetApiFromWidgetAction, WidgetApiToWidgetAction } from "./interfaces/WidgetApiAction";
-import { IWidgetApiErrorResponseData } from "./interfaces/IWidgetApiErrorResponse";
+import { IWidgetApiErrorResponseData, IWidgetApiErrorResponseDataDetails } from "./interfaces/IWidgetApiErrorResponse";
 import { IStickerActionRequestData } from "./interfaces/StickerAction";
 import { IStickyActionRequestData, IStickyActionResponseData } from "./interfaces/StickyAction";
 import {
@@ -95,6 +95,19 @@ import {
     UpdateDelayedEventAction,
 } from "./interfaces/UpdateDelayedEventAction";
 
+export class WidgetApiResponseError extends Error {
+    static {
+        this.prototype.name = this.name;
+    }
+
+    public constructor(
+        message: string,
+        public readonly data: IWidgetApiErrorResponseDataDetails,
+    ) {
+        super(message);
+    }
+}
+
 /**
  * API handler for widgets. This raises events for each action
  * received as `action:${action}` (eg: "action:screenshot").

src/driver/WidgetDriver.ts

@@ -22,6 +22,7 @@ import {
     IRoomEvent,
     IRoomAccountData,
     ITurnServer,
+    IWidgetApiErrorResponseDataDetails,
     UpdateDelayedEventAction,
 } from "..";
 
@@ -358,4 +359,14 @@ export abstract class WidgetDriver {
     ): Promise<{ file: XMLHttpRequestBodyInit }> {
         throw new Error("Download file is not implemented");
     }
+
+    /**
+     * Expresses an error thrown by this driver in a format compatible with the Widget API.
+     * @param error The error to handle.
+     * @returns The error expressed as a {@link IWidgetApiErrorResponseDataDetails},
+     * or undefined if it cannot be expressed as one.
+     */
+    public processError(error: unknown): IWidgetApiErrorResponseDataDetails | undefined {
+        return undefined;
+    }
 }

src/interfaces/IWidgetApiErrorResponse.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 The Matrix.org Foundation C.I.C.
+ * Copyright 2020 - 2024 The Matrix.org Foundation C.I.C.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,20 +16,42 @@
 
 import { IWidgetApiResponse, IWidgetApiResponseData } from "./IWidgetApiResponse";
 
+/**
+ * The format of errors returned by Matrix API requests
+ * made by a WidgetDriver.
+ */
+export interface IMatrixApiError {
+    /** The HTTP status code of the associated request. */
+    http_status: number;  // eslint-disable-line camelcase
+    /** Any HTTP response headers that are relevant to the error. */
+    http_headers: {[name: string]: string};  // eslint-disable-line camelcase
+    /** The URL of the failed request. */
+    url: string;
+    /** @see {@link https://spec.matrix.org/latest/client-server-api/#standard-error-response} */
+    response: {
+        errcode: string;
+        error: string;
+    } & IWidgetApiResponseData; // extensible
+}
+
+export interface IWidgetApiErrorResponseDataDetails {
+    /** Set if the error came from a Matrix API request made by a widget driver */
+    matrix_api_error?: IMatrixApiError;  // eslint-disable-line camelcase
+}
+
 export interface IWidgetApiErrorResponseData extends IWidgetApiResponseData {
     error: {
+        /** A user-friendly string describing the error */
         message: string;
-    };
+    } & IWidgetApiErrorResponseDataDetails;
 }
 
 export interface IWidgetApiErrorResponse extends IWidgetApiResponse {
     response: IWidgetApiErrorResponseData;
 }
 
-export function isErrorResponse(responseData: IWidgetApiResponseData): boolean {
-    if ("error" in responseData) {
-        const err = <IWidgetApiErrorResponseData>responseData;
-        return !!err.error.message;
-    }
-    return false;
+export function isErrorResponse(responseData: IWidgetApiResponseData): responseData is IWidgetApiErrorResponseData {
+    const error = responseData.error;
+    return typeof error === "object" && error !== null &&
+        "message" in error && typeof error.message === "string";
 }

src/transport/ITransport.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 The Matrix.org Foundation C.I.C.
+ * Copyright 2020 - 2024 The Matrix.org Foundation C.I.C.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -71,11 +71,12 @@ export interface ITransport extends EventEmitter {
 
     /**
      * Sends a request to the remote end.
-     * @param {WidgetApiAction} action The action to send.
-     * @param {IWidgetApiRequestData} data The request data.
-     * @returns {Promise<IWidgetApiResponseData>} A promise which resolves
-     * to the remote end's response, or throws with an Error if the request
-     * failed.
+     * @param action The action to send.
+     * @param data The request data.
+     * @returns A promise which resolves to the remote end's response.
+     * @throws {Error} if the request failed with a generic error.
+     * @throws {WidgetApiResponseError} if the request failed with error details
+     * that can be communicated to the Widget API.
      */
     send<T extends IWidgetApiRequestData, R extends IWidgetApiResponseData = IWidgetApiAcknowledgeResponseData>(
         action: WidgetApiAction,
@@ -88,9 +89,10 @@ export interface ITransport extends EventEmitter {
      * data.
      * @param {WidgetApiAction} action The action to send.
      * @param {IWidgetApiRequestData} data The request data.
-     * @returns {Promise<IWidgetApiResponseData>} A promise which resolves
-     * to the remote end's response, or throws with an Error if the request
-     * failed.
+     * @returns {Promise<IWidgetApiResponseData>} A promise which resolves to the remote end's response
+     * @throws {Error} if the request failed with a generic error.
+     * @throws {WidgetApiResponseError} if the request failed with error details
+     * that can be communicated to the Widget API.
      */
     sendComplete<T extends IWidgetApiRequestData, R extends IWidgetApiResponse>(action: WidgetApiAction, data: T)
         : Promise<R>;

src/transport/PostmessageTransport.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 The Matrix.org Foundation C.I.C.
+ * Copyright 2020 - 2024 The Matrix.org Foundation C.I.C.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,11 +19,11 @@ import { ITransport } from "./ITransport";
 import {
     invertedDirection,
     isErrorResponse,
-    IWidgetApiErrorResponseData,
     IWidgetApiRequest,
     IWidgetApiRequestData,
     IWidgetApiResponse,
     IWidgetApiResponseData,
+    WidgetApiResponseError,
     WidgetApiAction,
     WidgetApiDirection,
     WidgetApiToWidgetAction,
@@ -194,8 +194,8 @@ export class PostmessageTransport extends EventEmitter implements ITransport {
         if (!req) return; // response to an unknown request
 
         if (isErrorResponse(response.response)) {
-            const err = <IWidgetApiErrorResponseData>response.response;
-            req.reject(new Error(err.error.message));
+            const {message, ...data} = response.response.error;
+            req.reject(new WidgetApiResponseError(message, data));
         } else {
             req.resolve(response);
         }