Expose crypto-api as its own typedoc module (#4439)

Currently the crypto-api hierarchy is exposed only as a `Crypto` namespace
under the "matrix" entrypoint in the documentation.

This isn't really right: it's meant to be a separate entrypoint (in the same
way as `types`, `testing` and `utils` are). This PR fixes that problem.

Author: richvdh

src/crypto-api/index.ts

@@ -25,6 +25,15 @@ import { BackupTrustInfo, KeyBackupCheck, KeyBackupInfo } from "./keybackup.ts";
 import { ISignatures } from "../@types/signed.ts";
 import { MatrixEvent } from "../models/event.ts";
 
+/**
+ * `matrix-js-sdk/lib/crypto-api`: End-to-end encryption support.
+ *
+ * The most important type is {@link CryptoApi}, an instance of which can be retrieved via
+ * {@link MatrixClient.getCrypto}.
+ *
+ * @packageDocumentation
+ */
+
 /**
  * Public interface to the cryptography parts of the js-sdk
  *
@@ -181,7 +190,7 @@ export interface CryptoApi {
     /**
      * Return whether we trust other user's signatures of their devices.
      *
-     * @see {@link Crypto.CryptoApi#setTrustCrossSignedDevices}
+     * @see {@link CryptoApi.setTrustCrossSignedDevices}
      *
      * @returns `true` if we trust cross-signed devices, otherwise `false`.
      */
@@ -228,7 +237,7 @@ export interface CryptoApi {
      *
      * @throws an error if the device is unknown, or has not published any encryption keys.
      *
-     * @remarks Fires {@link CryptoEvent#DeviceVerificationChanged}
+     * @remarks Fires {@link matrix.CryptoEvent.DeviceVerificationChanged}
      */
     setDeviceVerified(userId: string, deviceId: string, verified?: boolean): Promise<void>;
 
@@ -259,7 +268,7 @@ export interface CryptoApi {
      *
      * @returns True if cross-signing is ready to be used on this device
      *
-     * @throws May throw {@link ClientStoppedError} if the `MatrixClient` is stopped before or during the call.
+     * @throws May throw {@link matrix.ClientStoppedError} if the `MatrixClient` is stopped before or during the call.
      */
     isCrossSigningReady(): Promise<boolean>;
 
@@ -327,7 +336,7 @@ export interface CryptoApi {
      * @returns The current status of cross-signing keys: whether we have public and private keys cached locally, and
      * whether the private keys are in secret storage.
      *
-     * @throws May throw {@link ClientStoppedError} if the `MatrixClient` is stopped before or during the call.
+     * @throws May throw {@link matrix.ClientStoppedError} if the `MatrixClient` is stopped before or during the call.
      */
     getCrossSigningStatus(): Promise<CrossSigningStatus>;
 
@@ -407,8 +416,8 @@ export interface CryptoApi {
      *
      * If an all-devices verification is already in flight, returns it. Otherwise, initiates a new one.
      *
-     * To control the methods offered, set {@link ICreateClientOpts.verificationMethods} when creating the
-     * MatrixClient.
+     * To control the methods offered, set {@link matrix.ICreateClientOpts.verificationMethods} when creating the
+     * `MatrixClient`.
      *
      * @returns a VerificationRequest when the request has been sent to the other party.
      */
@@ -422,8 +431,8 @@ export interface CryptoApi {
      *
      * If a verification for this user/device is already in flight, returns it. Otherwise, initiates a new one.
      *
-     * To control the methods offered, set {@link ICreateClientOpts.verificationMethods} when creating the
-     * MatrixClient.
+     * To control the methods offered, set {@link  matrix.ICreateClientOpts.verificationMethods} when creating the
+     * `MatrixClient`.
      *
      * @param userId - ID of the owner of the device to verify
      * @param deviceId - ID of the device to verify
@@ -480,7 +489,7 @@ export interface CryptoApi {
     /**
      * Determine if a key backup can be trusted.
      *
-     * @param info - key backup info dict from {@link MatrixClient#getKeyBackupVersion}.
+     * @param info - key backup info dict from {@link matrix.MatrixClient.getKeyBackupVersion}.
      */
     isKeyBackupTrusted(info: KeyBackupInfo): Promise<BackupTrustInfo>;
 
@@ -500,7 +509,7 @@ export interface CryptoApi {
      *
      * If there are existing backups they will be replaced.
      *
-     * The decryption key will be saved in Secret Storage (the {@link SecretStorageCallbacks.getSecretStorageKey} Crypto
+     * The decryption key will be saved in Secret Storage (the {@link matrix.SecretStorage.SecretStorageCallbacks.getSecretStorageKey} Crypto
      * callback will be called)
      * and the backup engine will be started.
      */
@@ -841,9 +850,9 @@ export class DeviceVerificationStatus {
      * Check if we should consider this device "verified".
      *
      * A device is "verified" if either:
-     *  * it has been manually marked as such via {@link MatrixClient#setDeviceVerified}.
+     *  * it has been manually marked as such via {@link matrix.MatrixClient.setDeviceVerified}.
      *  * it has been cross-signed with a verified signing key, **and** the client has been configured to trust
-     *    cross-signed devices via {@link Crypto.CryptoApi#setTrustCrossSignedDevices}.
+     *    cross-signed devices via {@link CryptoApi.setTrustCrossSignedDevices}.
      *
      * @returns true if this device is verified via any means.
      */

src/crypto-api/keybackup.ts

@@ -35,7 +35,7 @@ export interface Aes256AuthData {
  * Information about a server-side key backup.
  *
  * Returned by [`GET /_matrix/client/v3/room_keys/version`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3room_keysversion)
- * and hence {@link MatrixClient#getKeyBackupVersion}.
+ * and hence {@link matrix.MatrixClient.getKeyBackupVersion}.
  */
 export interface KeyBackupInfo {
     algorithm: string;
@@ -63,7 +63,7 @@ export interface BackupTrustInfo {
 }
 
 /**
- * The result of {@link Crypto.CryptoApi.checkKeyBackupAndEnable}.
+ * The result of {@link CryptoApi.checkKeyBackupAndEnable}.
  */
 export interface KeyBackupCheck {
     backupInfo: KeyBackupInfo;

src/crypto-api/verification.ts

@@ -119,7 +119,7 @@ export interface VerificationRequest
      *
      * If a verifier has already been created for this request, returns that verifier.
      *
-     * This does *not* send the `m.key.verification.start` event - to do so, call {@link Crypto.Verifier#verify} on the
+     * This does *not* send the `m.key.verification.start` event - to do so, call {@link Verifier.verify} on the
      * returned verifier.
      *
      * If no previous events have been sent, pass in `targetDevice` to set who to direct this request to.
@@ -281,7 +281,7 @@ export interface Verifier extends TypedEventEmitter<VerifierEvent, VerifierEvent
      * Cancel a verification.
      *
      * We will send an `m.key.verification.cancel` if the verification is still in flight. The verification promise
-     * will reject, and a {@link Crypto.VerifierEvent#Cancel} will be emitted.
+     * will reject, and a {@link crypto-api.VerifierEvent.Cancel | VerifierEvent.Cancel} will be emitted.
      *
      * @param e - the reason for the cancellation.
      */

src/matrix.ts

@@ -108,12 +108,7 @@ export type { ISSOFlow as SSOFlow, LoginFlow } from "./@types/auth.ts";
 export type { IHierarchyRelation as HierarchyRelation, IHierarchyRoom as HierarchyRoom } from "./@types/spaces.ts";
 export { LocationAssetType } from "./@types/location.ts";
 
-/**
- * Types supporting cryptography.
- *
- * The most important is {@link Crypto.CryptoApi}, an instance of which can be retrieved via
- * {@link MatrixClient.getCrypto}.
- */
+/** @deprecated Backwards-compatibility re-export. Import from `crypto-api` directly. */
 export * as Crypto from "./crypto-api/index.ts";
 
 let cryptoStoreFactory = (): CryptoStore => new MemoryCryptoStore();

src/models/typed-event-emitter.ts

@@ -65,7 +65,7 @@ export class TypedEventEmitter<
     SuperclassArguments extends ListenerMap<any> = Arguments,
 > extends EventEmitter {
     /**
-     * Alias for {@link TypedEventEmitter#on}.
+     * Alias for {@link on}.
      */
     public addListener<T extends Events | EventEmitterEvents>(
         event: T,
@@ -124,7 +124,7 @@ export class TypedEventEmitter<
     }
 
     /**
-     * Alias for {@link TypedEventEmitter#removeListener}
+     * Alias for {@link removeListener}
      */
     public off<T extends Events | EventEmitterEvents>(event: T, listener: Listener<Events, Arguments, T>): this {
         return super.off(event, listener);
@@ -139,7 +139,7 @@ export class TypedEventEmitter<
      * being added, and called, multiple times.
      *
      * By default, event listeners are invoked in the order they are added. The
-     * {@link TypedEventEmitter#prependListener} method can be used as an alternative to add the
+     * {@link prependListener} method can be used as an alternative to add the
      * event listener to the beginning of the listeners array.
      *
      * @param event - The name of the event.
@@ -158,7 +158,7 @@ export class TypedEventEmitter<
      * Returns a reference to the `EventEmitter`, so that calls can be chained.
      *
      * By default, event listeners are invoked in the order they are added.
-     * The {@link TypedEventEmitter#prependOnceListener} method can be used as an alternative to add the
+     * The {@link prependOnceListener} method can be used as an alternative to add the
      * event listener to the beginning of the listeners array.
      *
      * @param event - The name of the event.

src/secret-storage.ts

@@ -164,7 +164,7 @@ export interface SecretStorageCallbacks {
      * Descriptions of the secret storage keys are also stored in server-side storage, per the
      * [matrix specification](https://spec.matrix.org/v1.6/client-server-api/#key-storage), so
      * before a key can be used in this way, it must have been stored on the server. This is
-     * done via {@link SecretStorage.ServerSideSecretStorage#addKey}.
+     * done via {@link ServerSideSecretStorage#addKey}.
      *
      * Obviously the keys themselves are not stored server-side, so the js-sdk calls this callback
      * in order to retrieve a secret storage key from the application.

src/store/indexeddb.ts

@@ -24,7 +24,7 @@ import { logger } from "../logger.ts";
 import { ISavedSync } from "./index.ts";
 import { IIndexedDBBackend } from "./indexeddb-backend.ts";
 import { ISyncResponse } from "../sync-accumulator.ts";
-import { TypedEventEmitter } from "../models/typed-event-emitter.ts";
+import { EventEmitterEvents, TypedEventEmitter } from "../models/typed-event-emitter.ts";
 import { IStateEventWithRoomId } from "../@types/search.ts";
 import { IndexedToDeviceBatch, ToDeviceBatchWithTxnId } from "../models/ToDeviceMessage.ts";
 import { IStoredClientOpts } from "../client.ts";
@@ -118,7 +118,10 @@ export class IndexedDBStore extends MemoryStore {
         }
     }
 
-    public on = this.emitter.on.bind(this.emitter);
+    /** Re-exports `TypedEventEmitter.on` */
+    public on(event: EventEmitterEvents | "degraded" | "closed", handler: (...args: any[]) => void): void {
+        this.emitter.on(event, handler);
+    }
 
     /**
      * @returns Resolved when loaded from indexed db.

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", "src/types.ts", "src/testing.ts", "src/utils/*.ts"],
+    "entryPoints": ["src/matrix.ts", "src/crypto-api", "src/types.ts", "src/testing.ts", "src/utils/*.ts"],
     "excludeExternals": true,
     "out": "_docs"
 }