diff --git a/README.md b/README.md index 74a2f7be0..f13deb399 100644 --- a/README.md +++ b/README.md @@ -192,6 +192,10 @@ via an optional `callback` argument. The callback support is now deprecated: new methods do not include a `callback` argument, and in the future it may be removed from existing methods. +## Low level types + +There are some low level TypeScript types exported via the `matrix-js-sdk/lib/types` entrypoint to not bloat the main entrypoint. + ## Examples This section provides some useful code snippets which demonstrate the diff --git a/src/@types/media.ts b/src/@types/media.ts new file mode 100644 index 000000000..20e5ca6c6 --- /dev/null +++ b/src/@types/media.ts @@ -0,0 +1,252 @@ +/* +Copyright 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. +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 { MsgType } from "../@types/event"; + +/** + * Information on encrypted media attachments. + * + * Used within `m.room.message` events that reference files, such as `m.file` and `m.image`. + * + * @see https://spec.matrix.org/v1.9/client-server-api/#extensions-to-mroommessage-msgtypes + */ +export interface EncryptedFile { + /** + * The URL to the file. + */ + url: string; + /** + * A JSON Web Key object. + */ + key: { + alg: string; + key_ops: string[]; // eslint-disable-line camelcase + kty: string; + k: string; + ext: boolean; + }; + /** + * The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64. + */ + iv: string; + /** + * A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. + * Clients should support the SHA-256 hash, which uses the key `sha256`. + */ + hashes: { [alg: string]: string }; + /** + * Version of the encrypted attachment's protocol. Must be `v2`. + */ + v: string; +} + +interface ThumbnailInfo { + /** + * The mimetype of the image, e.g. image/jpeg. + */ + mimetype?: string; + /** + * The intended display width of the image in pixels. + * This may differ from the intrinsic dimensions of the image file. + */ + w?: number; + /** + * The intended display height of the image in pixels. + * This may differ from the intrinsic dimensions of the image file. + */ + h?: number; + /** + * Size of the image in bytes. + */ + size?: number; +} + +interface BaseInfo { + mimetype?: string; + size?: number; +} + +/** + * Information on media attachments of msgtype `m.file` + * + * Used within `m.room.message` events that reference files. + * + * @see https://spec.matrix.org/v1.9/client-server-api/#mfile + */ +export interface FileInfo extends BaseInfo { + /** + * Information on the encrypted thumbnail file, as specified in End-to-end encryption. + * Only present if the thumbnail is encrypted. + * @see https://spec.matrix.org/v1.9/client-server-api/#sending-encrypted-attachments + */ + thumbnail_file?: EncryptedFile; + /** + * Metadata about the image referred to in thumbnail_url. + */ + thumbnail_info?: ThumbnailInfo; + /** + * The URL to the thumbnail of the file. Only present if the thumbnail is unencrypted. + */ + thumbnail_url?: string; +} + +/** + * Information on media attachments of msgtype `m.image` + * + * Used within `m.room.message` events that reference images. + * + * @see https://spec.matrix.org/v1.9/client-server-api/#mimage + */ +export interface ImageInfo extends FileInfo, ThumbnailInfo {} + +/** + * Information on media attachments of msgtype `m.audio` + * + * Used within `m.room.message` events that reference audio files. + * + * @see https://spec.matrix.org/v1.9/client-server-api/#maudio + */ +export interface AudioInfo extends BaseInfo { + /** + * The duration of the audio in milliseconds. + */ + duration?: number; +} + +/** + * Information on media attachments of msgtype `m.video` + * + * Used within `m.room.message` events that reference video files. + * + * @see https://spec.matrix.org/v1.9/client-server-api/#mvideo + */ +export interface VideoInfo extends AudioInfo, ImageInfo { + /** + * The duration of the video in milliseconds. + */ + duration?: number; +} + +/** + * Union type representing the `content.info` field of all specified media events. + */ +export type MediaEventInfo = FileInfo | ImageInfo | AudioInfo | VideoInfo; + +interface BaseContent { + /** + * Required if the file is encrypted. Information on the encrypted file, as specified in End-to-end encryption. + * @see https://spec.matrix.org/v1.9/client-server-api/#sending-encrypted-attachments + */ + file?: EncryptedFile; + /** + * Required if the file is unencrypted. The URL (typically mxc:// URI) to the file. + */ + url?: string; +} + +/** + * Content format of media events with msgtype `m.file` + * + * @see https://spec.matrix.org/v1.9/client-server-api/#mfile + */ +export interface FileContent extends BaseContent { + /** + * A human-readable description of the file. + * This is recommended to be the filename of the original upload. + */ + body: string; + /** + * The original filename of the uploaded file. + */ + filename?: string; + /** + * Information about the file referred to in url. + */ + info?: FileInfo; + /** + * One of: [m.file]. + */ + msgtype: MsgType.File; +} + +/** + * Content format of media events with msgtype `m.image` + * + * @see https://spec.matrix.org/v1.9/client-server-api/#mimage + */ +export interface ImageContent extends BaseContent { + /** + * A textual representation of the image. + * This could be the alt text of the image, the filename of the image, + * or some kind of content description for accessibility e.g. ‘image attachment’. + */ + body: string; + /** + * Metadata about the image referred to in url. + */ + info?: ImageInfo; + /** + * One of: [m.image]. + */ + msgtype: MsgType.Image; +} + +/** + * Content format of media events with msgtype `m.audio` + * + * @see https://spec.matrix.org/v1.9/client-server-api/#maudio + */ +export interface AudioContent extends BaseContent { + /** + * A description of the audio e.g. ‘Bee Gees - Stayin’ Alive’, + * or some kind of content description for accessibility e.g. ‘audio attachment’. + */ + body: string; + /** + * Metadata for the audio clip referred to in url. + */ + info?: AudioInfo; + /** + * One of: [m.audio]. + */ + msgtype: MsgType.Audio; +} + +/** + * Content format of media events with msgtype `m.video` + * + * @see https://spec.matrix.org/v1.9/client-server-api/#mvideo + */ +export interface VideoContent extends BaseContent { + /** + * A description of the video e.g. ‘Gangnam style’, + * or some kind of content description for accessibility e.g. ‘video attachment’. + */ + body: string; + /** + * Metadata about the video clip referred to in url. + */ + info?: VideoInfo; + /** + * One of: [m.video]. + */ + msgtype: MsgType.Video; +} + +/** + * Type representing media event contents for `m.room.message` events listed in the Matrix specification + */ +export type MediaEventContent = FileContent | ImageContent | AudioContent | VideoContent; diff --git a/src/types.ts b/src/types.ts new file mode 100644 index 000000000..dd2d3bef8 --- /dev/null +++ b/src/types.ts @@ -0,0 +1,24 @@ +/* +Copyright 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. +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. +*/ + +/* + * This file is a secondary entrypoint for the js-sdk library, for use by Typescript projects. + * It exposes low-level types and interfaces reflecting structures defined in the Matrix specification. + * + * Remember to only export *public* types from this file. + */ + +export type * from "./@types/media"; diff --git a/typedoc.json b/typedoc.json index 020431cea..017c3a4d6 100644 --- a/typedoc.json +++ b/typedoc.json @@ -2,7 +2,7 @@ "$schema": "https://typedoc.org/schema.json", "plugin": ["typedoc-plugin-mdn-links", "typedoc-plugin-missing-exports", "typedoc-plugin-coverage"], "coverageLabel": "TypeDoc", - "entryPoints": ["src/matrix.ts"], + "entryPoints": ["src/matrix.ts", "src/types.ts"], "excludeExternals": true, "out": "_docs" }