diff --git a/src/WidgetApi.ts b/src/WidgetApi.ts index 649ed29..fbc450f 100644 --- a/src/WidgetApi.ts +++ b/src/WidgetApi.ts @@ -95,6 +95,7 @@ import { IUpdateDelayedEventFromWidgetResponseData, UpdateDelayedEventAction, } from "./interfaces/UpdateDelayedEventAction"; +import { IForwardLogLineFromWidgetRequestData } from "./interfaces/ForwardLogLineAction"; export class WidgetApiResponseError extends Error { static { @@ -834,6 +835,22 @@ export class WidgetApi extends EventEmitter { ); } + /** + * Forward a log line to the parent window. + * Note: This should only be called if the client has indicated they would like logging, + * as per `org.matrix.mscXXXX.log_forwarding` in the URL params. + * + * @param level A string log level. + * @param parts Parts of the log line, may be a string or object based. + * @returns When the line has been acknowledged. + */ + public async forwardLogLine(level: string, ...parts: unknown[]): Promise { + return this.transport.send( + WidgetApiFromWidgetAction.MSCXXXXForwardLogEvent, + { level, parts }, + ); + } + /** * Starts the communication channel. This should be done early to ensure * that messages are not missed. Communication can only be stopped by the client. diff --git a/src/interfaces/ForwardLogLineAction.ts b/src/interfaces/ForwardLogLineAction.ts new file mode 100644 index 0000000..8547d93 --- /dev/null +++ b/src/interfaces/ForwardLogLineAction.ts @@ -0,0 +1,28 @@ +/* + * Copyright 2026 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. + * 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 CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { IWidgetApiRequest, IWidgetApiRequestData } from "./IWidgetApiRequest"; +import { WidgetApiFromWidgetAction } from "./WidgetApiAction"; + +export interface IForwardLogLineFromWidgetRequestData extends IWidgetApiRequestData { + level: string; + parts: unknown[]; +} + +export interface IDownloadFileActionFromWidgetActionRequest extends IWidgetApiRequest { + action: WidgetApiFromWidgetAction.MSCXXXXForwardLogEvent; + data: IForwardLogLineFromWidgetRequestData; +} \ No newline at end of file diff --git a/src/interfaces/WidgetApiAction.ts b/src/interfaces/WidgetApiAction.ts index b6ac75d..8f32b65 100644 --- a/src/interfaces/WidgetApiAction.ts +++ b/src/interfaces/WidgetApiAction.ts @@ -92,6 +92,11 @@ export enum WidgetApiFromWidgetAction { * @experimental It is not recommended to rely on this existing - it can be removed without notice. */ MSC4157UpdateDelayedEvent = "org.matrix.msc4157.update_delayed_event", + + /** + * @experimental It is not recommended to rely on this existing - it can be removed without notice. + */ + MSCXXXXForwardLogEvent = "org.matrix.mscXXXX.forwarded_log_line" } export type WidgetApiAction = WidgetApiToWidgetAction | WidgetApiFromWidgetAction | string; diff --git a/src/templating/url-template.ts b/src/templating/url-template.ts index b700a9b..76c489d 100644 --- a/src/templating/url-template.ts +++ b/src/templating/url-template.ts @@ -26,6 +26,7 @@ export interface ITemplateParams { clientLanguage?: string; deviceId?: string; baseUrl?: string; + logging?: boolean; } export function runTemplate(url: string, widget: IWidget, params: ITemplateParams): string { @@ -47,6 +48,9 @@ export function runTemplate(url: string, widget: IWidget, params: ITemplateParam // TODO: Convert to stable (https://github.com/matrix-org/matrix-spec-proposals/pull/4039) "org.matrix.msc4039.matrix_base_url": params.baseUrl || "", + + // TODO: Convert to stable (https://github.com/matrix-org/matrix-spec-proposals/pull/4039) + "org.matrix.mscXXXX.log_forwarding": params.logging }); let result = url; for (const key of Object.keys(variables)) {