element-web/packages/module-api/element-web-module-api.api.md

API Report File for "@element-hq/element-web-module-api"

Do not edit this file. It is a report generated by API Extractor.

import { ComponentType } from 'react';
import { IWidget } from 'matrix-widget-api';
import { JSX } from 'react';
import { ReactNode } from 'react';
import { Root } from 'react-dom/client';
import { SVGAttributes } from 'react';

// @public
export interface AccountAuthApiExtension {
    overwriteAccountAuth(accountInfo: AccountAuthInfo): Promise<void>;
}

// @public
export interface AccountAuthInfo {
    accessToken: string;
    deviceId: string;
    homeserverUrl: string;
    refreshToken?: string;
    userId: string;
}

// @public
export interface AccountDataApi {
    delete(eventType: string): Promise<void>;
    get(eventType: string): Watchable<unknown>;
    set(eventType: string, content: unknown): Promise<void>;
}

// @public
export interface Api extends DialogApiExtension, AccountAuthApiExtension, ProfileApiExtension {
    // @alpha
    readonly builtins: BuiltinsApi;
    readonly client: ClientApi;
    // @alpha
    readonly composer: ComposerApi;
    readonly config: ConfigApi;
    createRoot(element: Element): Root;
    // @alpha
    readonly customComponents: CustomComponentsApi;
    // @alpha
    readonly customisations: CustomisationsApi;
    // @alpha
    readonly extras: ExtrasApi;
    readonly i18n: I18nApi;
    readonly navigation: NavigationApi;
    readonly rootNode: HTMLElement;
    // @alpha
    readonly settings: SettingsApi;
    // @alpha
    readonly storageHelper: StorageHelperApi;
    readonly stores: StoresApi;
    // @alpha
    readonly urlPreviews: UrlPreviewApi;
    // @alpha
    readonly widget: WidgetApi;
    // @alpha
    readonly widgetLifecycle: WidgetLifecycleApi;
    // @alpha
    readonly x509?: X509Api;
}

// @alpha
export interface BuiltinsApi {
    renderNotificationDecoration(roomId: string): React.ReactNode;
    renderRoomAvatar(roomId: string, size?: string): React.ReactNode;
    renderRoomView(roomId: string, props?: RoomViewProps): React.ReactNode;
}

// @alpha
export type CapabilitiesApprover = (widget: WidgetDescriptor, requestedCapabilities: Set<string>) => MaybePromise<Set<string> | undefined>;

// @alpha
export interface CertificateInfo {
    // (undocumented)
    issuer: string;
    // (undocumented)
    serialNumber: string;
    // (undocumented)
    subject: string;
    // (undocumented)
    subjectAltName?: string;
    // (undocumented)
    validFrom: Date;
    // (undocumented)
    validTo: Date;
}

// @public
export interface ClientApi {
    accountData: AccountDataApi;
    // @alpha
    readonly creationManagement: ClientCreationManagementApi;
    getRoom: (id: string) => Room | null;
}

// @public
export interface ClientCreationManagementApi {
    // @deprecated
    setUserVerificationCaCertsPem(pem: string | null): void;
    setX509ClientInitOpts(opts: X509ClientInitOpts): void;
}

// @alpha
export interface ComposerApi {
    addFileUploadOption(option: ComposerApiFileUploadOption): void;
    insertPlaintextIntoComposer(plaintext: string, view: ComposerApiTarget): void;
    openFileUploadConfirmation(files: File[], view: ComposerApiTarget): void;
}

// @alpha
export type ComposerApiFileUploadOption = {
    type: string;
    label: string;
    icon?: ComponentType<SVGAttributes<SVGElement>>;
    onSelected: (roomId?: string, view?: ComposerApiTarget, relation?: {
        inReplyToEventId?: string;
        relType?: string;
    }) => Promise<void> | void;
};

// @alpha
export type ComposerApiTarget = {
    view: "room";
} | {
    view: "thread";
};

// Warning: (ae-forgotten-export) The symbol "WebConfigJson" needs to be exported by the entry point index.d.ts
//
// @public
export interface Config extends WebConfigJson {
    // (undocumented)
    brand: string;
}

// @public
export interface ConfigApi {
    // (undocumented)
    get(): Config;
    // (undocumented)
    get<K extends keyof Config>(key: K): Config[K];
    // (undocumented)
    get<K extends keyof Config = never>(key?: K): Config | Config[K];
}

// @alpha
export type Container = "top" | "right" | "center";

// @alpha
export interface CustomComponentsApi {
    registerComposerPreview(filterFn: (composerText: string, roomId: string) => boolean, renderer: CustomComposerPreviewRenderFunction): void;
    registerLoginComponent(renderer: CustomLoginRenderFunction): void;
    registerMessageRenderer(eventTypeOrFilter: string | ((mxEvent: MatrixEvent) => boolean), renderer: CustomMessageRenderFunction, hints?: CustomMessageRenderHints): void;
    registerRoomPreviewBar(renderer: CustomRoomPreviewBarRenderFunction): void;
}

// @alpha
export type CustomComposerPreviewComponentProps = {
    text: string;
    roomId: string;
    target?: ComposerApiTarget;
    relation?: {
        inReplyToEventId?: string;
        relType?: string;
    };
};

// @alpha
export type CustomComposerPreviewRenderFunction = ExtendablePropsRenderFunction<CustomComposerPreviewComponentProps>;

// @alpha
export interface CustomisationsApi {
    registerShouldShowComponent(fn: (this: void, component: UIComponent) => boolean | void): void;
}

// @alpha
export type CustomLoginComponentProps = {
    serverConfig: CustomLoginComponentPropsServerConfig;
    fragmentAfterLogin?: string;
    children?: ReactNode;
    onLoggedIn(this: void, data: AccountAuthInfo): void;
    onServerConfigChange(this: void, config: CustomLoginComponentPropsServerConfig): void;
};

// @alpha
export interface CustomLoginComponentPropsServerConfig {
    hsName: string;
    hsUrl: string;
}

// @alpha
export type CustomLoginRenderFunction = ExtendablePropsRenderFunction<CustomLoginComponentProps>;

// @alpha
export type CustomMessageComponentProps = {
    mxEvent: MatrixEvent;
};

// @alpha
export type CustomMessageRenderFunction = (
props: CustomMessageComponentProps,
originalComponent?: (props?: OriginalMessageComponentProps) => React.JSX.Element) => JSX.Element;

// @alpha
export type CustomMessageRenderHints = {
    allowEditingEvent?: boolean;
    allowDownloadingMedia?: (mxEvent: MatrixEvent) => Promise<boolean>;
};

// @alpha
export type CustomRoomPreviewBarComponentProps = {
    roomId?: string;
    roomAlias?: string;
};

// @alpha
export type CustomRoomPreviewBarRenderFunction = (
props: CustomRoomPreviewBarComponentProps,
originalComponent: (props: CustomRoomPreviewBarComponentProps) => JSX.Element) => JSX.Element;

// @public
export interface DialogApiExtension {
    openDialog<M, P extends object>(initialOptions: DialogOptions, dialog: ComponentType<P & DialogProps<M>>, props: P): DialogHandle<M>;
}

// @public
export type DialogHandle<M> = {
    finished: Promise<{
        ok: boolean;
        model: M | null;
    }>;
    close(this: void): void;
};

// @public
export interface DialogOptions {
    ariaLabel?: string;
    title?: string;
}

// @public
export type DialogProps<M> = {
    onSubmit(this: void, model: M): void;
    onCancel(this: void): void;
};

// @alpha
export type ExtendablePropsRenderFunction<BaseProps> = <P extends BaseProps>(
props: P,
originalComponent: (props: P) => JSX.Element) => JSX.Element;

// @alpha
export interface ExtrasApi {
    addRoomHeaderButtonCallback(cb: RoomHeaderButtonsCallback): void;
    getVisibleRoomBySpaceKey(spaceKey: string, cb: () => string[]): void;
    setSpacePanelItem(spaceKey: string, props: SpacePanelItemProps): void;
}

// @alpha
export interface HardwareKey {
    // (undocumented)
    label: string;
    // (undocumented)
    manufacturerID: string;
    // (undocumented)
    maxPinLength: number;
    // (undocumented)
    minPinLength: number;
    // (undocumented)
    model: string;
    // (undocumented)
    serialNumber: string;
}

// @alpha
export type HardwareKeyState = "absent" | "noSigningKey" | "open" | "authenticated";

// @public
export interface I18nApi {
    humanizeTime(this: void, timeMillis: number): string;
    get language(): string;
    register(this: void, translations: Partial<Translations>): void;
    translate(this: void, key: keyof Translations, variables?: StringVariables): string;
    translate(this: void, key: keyof Translations, variables: Variables | undefined, tags: Tags): ReactNode;
}

// @alpha
export type IdentityApprover = (widget: WidgetDescriptor) => MaybePromise<boolean | undefined>;

// @alpha
export type LocationRenderFunction = () => JSX.Element;

// @alpha
export interface MatrixEvent {
    content: Record<string, unknown>;
    eventId: string;
    originServerTs: number;
    roomId: string;
    sender: string;
    stateKey?: string;
    type: string;
    unsigned: Record<string, unknown>;
}

// @public
export type MaybePromise<T> = T | PromiseLike<T>;

// @public
export interface Module {
    // (undocumented)
    load(): Promise<void>;
}

// @public
export interface ModuleFactory {
    // (undocumented)
    new (api: Api): Module;
    // (undocumented)
    readonly moduleApiVersion: string;
    // (undocumented)
    readonly prototype: Module;
}

// @public
export class ModuleIncompatibleError extends Error {
    constructor(pluginVersion: string);
}

// @public
export class ModuleLoader {
    constructor(api: Api);
    // Warning: (ae-forgotten-export) The symbol "ModuleExport" needs to be exported by the entry point index.d.ts
    //
    // (undocumented)
    load(moduleExport: ModuleExport): Promise<void>;
    // (undocumented)
    start(): Promise<void>;
}

// @public
export interface NavigationApi {
    openRoom(roomIdOrAlias: string, opts?: OpenRoomOptions): void;
    // @alpha
    registerLocationRenderer(path: string, renderer: LocationRenderFunction): void;
    toMatrixToLink(link: string, join?: boolean): Promise<void>;
}

// @public
export interface OpenRoomOptions {
    autoJoin?: boolean;
    viaServers?: string[];
}

// @alpha
export type OriginalMessageComponentProps = {
    showUrlPreview?: boolean;
};

// @alpha
export type PreloadApprover = (widget: WidgetDescriptor) => MaybePromise<boolean | undefined>;

// @public
export interface Profile {
    displayName?: string;
    isGuest?: boolean;
    userId?: string;
}

// @public
export interface ProfileApiExtension {
    readonly profile: Watchable<Profile>;
}

// @public
export interface RichVariables {
    // (undocumented)
    [key: string]: SubstitutionValue;
    // (undocumented)
    count?: number;
}

// @public
export interface Room {
    getLastActiveTimestamp: () => number;
    id: string;
    name: Watchable<string>;
}

// @alpha
export type RoomHeaderButtonsCallback = (roomId: string) => JSX.Element | undefined;

// @public
export interface RoomListStoreApi {
    getRooms(): Watchable<Room[]>;
    waitForReady(): Promise<void>;
}

// @alpha
export interface RoomViewProps {
    enableReadReceiptsAndMarkersOnActivity?: boolean;
    hideComposer?: boolean;
    hideHeader?: boolean;
    hidePinnedMessageBanner?: boolean;
    hideRightPanel?: boolean;
    hideWidgets?: boolean;
}

// @alpha
export interface SettingsApi {
    getValue<T = any>(settingName: string, roomId?: string | null, excludeDefault?: boolean): T | undefined;
}

// @alpha
export interface SpacePanelItemProps {
    className?: string;
    icon?: JSX.Element;
    label: string;
    onSelected: () => void;
    style?: React.CSSProperties;
    tooltip?: string;
}

// @alpha
export interface StorageHelperApi {
    getPickleKey(userId: string, deviceId: string): Promise<string | null>;
}

// @public
export interface StoresApi {
    roomListStore: RoomListStoreApi;
}

// @public
export interface StringVariables {
    // (undocumented)
    [key: string]: number | string | null | undefined;
    // (undocumented)
    count?: number;
}

// @public
export type SubstitutionValue = number | string | ReactNode | ((sub: string) => ReactNode);

// @public
export type Tags = Record<string, SubstitutionValue>;

// @public
export type Translations = Record<string, {
    [ietfLanguageTag: string]: string;
}>;

// @alpha
export const enum UIComponent {
    AddIntegrations = "UIComponent.addIntegrations",
    CreateRooms = "UIComponent.roomCreation",
    CreateSpaces = "UIComponent.spaceCreation",
    ExploreRooms = "UIComponent.exploreRooms",
    FilterContainer = "UIComponent.filterContainer",
    InviteUsers = "UIComponent.sendInvites",
    RoomOptionsMenu = "UIComponent.roomOptionsMenu"
}

// @alpha
export interface UrlPreviewApi {
    registerPreviewHandler(regex: RegExp, handler: UrlPreviewHandler): void;
}

// Warning: (ae-forgotten-export) The symbol "UrlPreview" needs to be exported by the entry point index.d.ts
//
// @alpha
export type UrlPreviewHandler = (url: string, mxEvent?: MatrixEvent) => Promise<UrlPreview | null>;

// @alpha
export interface UserCertificate {
    // (undocumented)
    certificate: CertificateInfo;
    chain: string;
}

// @public
export function useWatchable<T>(watchable: Watchable<T>): T;

// @public
export type Variables = StringVariables | RichVariables;

// @public
export class Watchable<T> {
    constructor(currentValue: T);
    // Warning: (ae-forgotten-export) The symbol "WatchFn" needs to be exported by the entry point index.d.ts
    //
    // (undocumented)
    protected readonly listeners: Set<WatchFn<T>>;
    protected onFirstWatch(): void;
    protected onLastWatch(): void;
    // (undocumented)
    unwatch(listener: (value: T) => void): void;
    get value(): T;
    set value(value: T);
    // (undocumented)
    watch(listener: (value: T) => void): void;
}

// @alpha
export interface WidgetApi {
    getAppAvatarUrl(app: IWidget, width?: number, height?: number, resizeMethod?: string): string | null;
    getWidgetsInRoom(roomId: string): IWidget[];
    isAppInContainer(app: IWidget, container: Container, roomId: string): boolean;
    moveAppToContainer(app: IWidget, container: Container, roomId: string): void;
}

// @alpha
export type WidgetDescriptor = {
    id: string;
    templateUrl: string;
    creatorUserId: string;
    type: string;
    origin: string;
    roomId?: string;
};

// @alpha
export interface WidgetLifecycleApi {
    registerCapabilitiesApprover(approver: CapabilitiesApprover): void;
    registerIdentityApprover(approver: IdentityApprover): void;
    registerPreloadApprover(approver: PreloadApprover): void;
}

// @alpha
export interface X509Api {
    getKeyState(serialNumber: string): Promise<X509Result<HardwareKeyState>>;
    getUserCertificate(): Promise<X509Result<UserCertificate>>;
    listHardwareKeys(): Promise<X509Result<HardwareKey[]>>;
    logIntoKey(serialNumber: string, pin: string): Promise<X509LoginResult>;
    signData(serialNumber: string, data: Uint8Array): Promise<X509Result<Uint8Array>>;
}

// @public
export interface X509ClientInitOpts {
    signer?: (item: Uint8Array) => Promise<{
        signature_bytes: Uint8Array;
        certificate_chain: string;
        signature_scheme: "RsaPssSha512";
    }>;
    userVerificationCaCertsPem?: string;
    validity?: () => number;
}

// @alpha
export interface X509IpcError {
    // (undocumented)
    code: X509IpcErrorCode;
    // (undocumented)
    message?: string;
    pkcs11Code?: number;
}

// @alpha
export type X509IpcErrorCode =
/**
* No PKCS#11 library is configured or it could not be loaded.
*/
| "MODULE_NOT_LOADED"
| "KEY_NOT_FOUND"
| "CERTIFICATE_NOT_FOUND"
| "PRIVATE_KEY_NOT_FOUND"
/**
* `signData` was called before `logIntoKey`, or the session was invalidated since.
*/
| "LOGIN_REQUIRED"
/**
* An upstream error from the PKCS#11 library. Carries a `CKR_*` code.
*/
| "UPSTREAM_PKCS11"
| "UNKNOWN";

// @alpha
export interface X509LoginError extends X509IpcError {
    triesRemaining?: number;
}

// @alpha
export type X509LoginResult = X509Result<void, X509LoginError>;

// @alpha
export type X509Result<T, E extends X509IpcError = X509IpcError> = { ok: true; data: T } | { ok: false; error: E };

// (No @packageDocumentation comment for this package)