Merge pull request #1778 from matrix-org/travis/notifications-2

Add minimal types for "notification settings" UI

Author: turt2live

src/@types/PushRules.ts

@@ -0,0 +1,164 @@
+/*
+Copyright 2021 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.
+*/
+
+// allow camelcase as these are things that go onto the wire
+/* eslint-disable camelcase */
+
+export enum PushRuleActionName {
+    DontNotify = "dont_notify",
+    Notify = "notify",
+    Coalesce = "coalesce",
+}
+
+export enum TweakName {
+    Highlight = "highlight",
+    Sound = "sound",
+}
+
+export type Tweak<N extends TweakName, V> = {
+    set_tweak: N;
+    value: V;
+};
+
+export type TweakHighlight = Tweak<TweakName.Highlight, boolean>;
+export type TweakSound = Tweak<TweakName.Sound, string>;
+
+export type Tweaks = TweakHighlight | TweakSound;
+
+export enum ConditionOperator {
+    ExactEquals = "==",
+    LessThan = "<",
+    GreaterThan = ">",
+    GreaterThanOrEqual = ">=",
+    LessThanOrEqual = "<=",
+}
+
+export type PushRuleAction = Tweaks | PushRuleActionName;
+
+export type MemberCountCondition
+    <N extends number, Op extends ConditionOperator = ConditionOperator.ExactEquals>
+    = `${Op}${N}` | (Op extends ConditionOperator.ExactEquals ? `${N}` : never);
+
+export type AnyMemberCountCondition = MemberCountCondition<number, ConditionOperator>;
+
+export const DMMemberCountCondition: MemberCountCondition<2> = "2";
+
+export function isDmMemberCountCondition(condition: AnyMemberCountCondition): boolean {
+    return condition === "==2" || condition === "2";
+}
+
+export enum ConditionKind {
+    EventMatch = "event_match",
+    ContainsDisplayName = "contains_display_name",
+    RoomMemberCount = "room_member_count",
+    SenderNotificationPermission = "sender_notification_permission",
+}
+
+export interface IPushRuleCondition<N extends ConditionKind | string> {
+    [k: string]: any; // for custom conditions, there can be other fields here
+    kind: N;
+}
+
+export interface IEventMatchCondition extends IPushRuleCondition<ConditionKind.EventMatch> {
+    key: string;
+    pattern: string;
+}
+
+export interface IContainsDisplayNameCondition extends IPushRuleCondition<ConditionKind.ContainsDisplayName> {
+    // no additional fields
+}
+
+export interface IRoomMemberCountCondition extends IPushRuleCondition<ConditionKind.RoomMemberCount> {
+    is: AnyMemberCountCondition;
+}
+
+export interface ISenderNotificationPermissionCondition
+    extends IPushRuleCondition<ConditionKind.SenderNotificationPermission> {
+    key: string;
+}
+
+export type PushRuleCondition = IPushRuleCondition<string>
+    | IEventMatchCondition
+    | IContainsDisplayNameCondition
+    | IRoomMemberCountCondition
+    | ISenderNotificationPermissionCondition;
+
+export enum PushRuleKind {
+    Override = "override",
+    ContentSpecific = "content",
+    RoomSpecific = "room",
+    SenderSpecific = "sender",
+    Underride = "underride",
+}
+
+export enum RuleId {
+    Master = ".m.rule.master",
+    ContainsDisplayName = ".m.rule.contains_display_name",
+    ContainsUserName = ".m.rule.contains_user_name",
+    AtRoomNotification = ".m.rule.roomnotif",
+    DM = ".m.rule.room_one_to_one",
+    EncryptedDM = ".m.rule.encrypted_room_one_to_one",
+    Message = ".m.rule.message",
+    EncryptedMessage = ".m.rule.encrypted",
+    InviteToSelf = ".m.rule.invite_for_me",
+    MemberEvent = ".m.rule.member_event",
+    IncomingCall = ".m.rule.call",
+    SuppressNotices = ".m.rule.suppress_notices",
+    Tombstone = ".m.rule.tombstone",
+}
+
+export type PushRuleSet = {
+    [k in PushRuleKind]?: IPushRule[];
+};
+
+export interface IPushRule {
+    actions: PushRuleAction[];
+    conditions?: PushRuleCondition[];
+    default: boolean;
+    enabled: boolean;
+    pattern?: string;
+    rule_id: RuleId | string;
+}
+
+export interface IAnnotatedPushRule extends IPushRule {
+    kind: PushRuleKind;
+}
+
+export interface IPushRules {
+    global: PushRuleSet;
+    device?: PushRuleSet;
+}
+
+export interface IPusher {
+    app_display_name: string;
+    app_id: string;
+    data: {
+        format?: string; // TODO: Types
+        url?: string; // TODO: Required if kind==http
+        brand?: string; // TODO: For email notifications only?
+    };
+    device_display_name: string;
+    kind: string; // TODO: Types
+    lang: string;
+    profile_tag?: string;
+    pushkey: string;
+}
+
+export interface IPusherRequest extends IPusher {
+    append?: boolean;
+}
+
+/* eslint-enable camelcase */

src/@types/requests.ts

@@ -19,7 +19,7 @@ import { Preset, Visibility } from "./partials";
 import { SearchKey } from "./search";
 import { IRoomEventFilter } from "../filter";
 
-// allow camelcase as these are things go onto the wire
+// allow camelcase as these are things that go onto the wire
 /* eslint-disable camelcase */
 
 export interface IJoinRoomOpts {

src/@types/threepids.ts

@@ -0,0 +1,28 @@
+/*
+Copyright 2021 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.
+*/
+
+export enum ThreepidMedium {
+    Email = "email",
+    Phone = "msisdn",
+}
+
+// TODO: Are these types universal, or specific to just /account/3pid?
+export interface IThreepid {
+    medium: ThreepidMedium;
+    address: string;
+    validated_at: number; // eslint-disable-line camelcase
+    added_at: number; // eslint-disable-line camelcase
+}

src/client.ts

@@ -144,6 +144,8 @@ import {
 } from "./@types/search";
 import { ISynapseAdminDeactivateResponse, ISynapseAdminWhoisResponse } from "./@types/synapse";
 import { ISpaceSummaryEvent, ISpaceSummaryRoom } from "./@types/spaces";
+import { IPusher, IPusherRequest, IPushRules, PushRuleAction, PushRuleKind, RuleId } from "./@types/PushRules";
+import { IThreepid } from "./@types/threepids";
 
 export type Store = IStore;
 export type SessionStore = WebStorageSessionStore;
@@ -595,35 +597,13 @@ interface IUserDirectoryResponse {
     limited: boolean;
 }
 
-interface IThreepid {
-    medium: "email" | "msisdn";
-    address: string;
-    validated_at: number;
-    added_at: number;
-}
-
 interface IMyDevice {
     device_id: string;
     display_name?: string;
     last_seen_ip?: string;
     last_seen_ts?: number;
 }
 
-interface IPusher {
-    pushkey: string;
-    kind: string;
-    app_id: string;
-    app_display_name: string;
-    device_display_name: string;
-    profile_tag?: string;
-    lang: string;
-    data: {
-        url?: string;
-        format?: string;
-        brand?: string; // undocumented
-    };
-}
-
 interface IDownloadKeyResult {
     failures: { [serverName: string]: object };
     device_keys: {
@@ -3883,7 +3863,7 @@ export class MatrixClient extends EventEmitter {
      * @return {Promise} Resolves: to an empty object
      * @return {module:http-api.MatrixError} Rejects: with an error response.
      */
-    public async sendReadReceipt(event: MatrixEvent, opts: { hidden?: boolean }, callback?: Callback): Promise<{}> {
+    public async sendReadReceipt(event: MatrixEvent, opts?: { hidden?: boolean }, callback?: Callback): Promise<{}> {
         if (typeof (opts) === 'function') {
             callback = opts as any as Callback; // legacy
             opts = {};
@@ -5220,20 +5200,20 @@ export class MatrixClient extends EventEmitter {
         if (!mute) {
             // Remove the rule only if it is a muting rule
             if (hasDontNotifyRule) {
-                deferred = this.deletePushRule(scope, "room", roomPushRule.rule_id);
+                deferred = this.deletePushRule(scope, PushRuleKind.RoomSpecific, roomPushRule.rule_id);
             }
         } else {
             if (!roomPushRule) {
-                deferred = this.addPushRule(scope, "room", roomId, {
+                deferred = this.addPushRule(scope, PushRuleKind.RoomSpecific, roomId, {
                     actions: ["dont_notify"],
                 });
             } else if (!hasDontNotifyRule) {
                 // Remove the existing one before setting the mute push rule
                 // This is a workaround to SYN-590 (Push rule update fails)
                 deferred = utils.defer();
-                this.deletePushRule(scope, "room", roomPushRule.rule_id)
+                this.deletePushRule(scope, PushRuleKind.RoomSpecific, roomPushRule.rule_id)
                     .then(() => {
-                        this.addPushRule(scope, "room", roomId, {
+                        this.addPushRule(scope, PushRuleKind.RoomSpecific, roomId, {
                             actions: ["dont_notify"],
                         }).then(() => {
                             deferred.resolve();
@@ -6974,7 +6954,7 @@ export class MatrixClient extends EventEmitter {
 
     /**
      * @param {module:client.callback} callback Optional.
-     * @return {Promise} Resolves: TODO
+     * @return {Promise} Resolves to a list of the user's threepids.
      * @return {module:http-api.MatrixError} Rejects: with an error response.
      */
     public getThreePids(callback?: Callback): Promise<{ threepids: IThreepid[] }> {
@@ -7205,22 +7185,23 @@ export class MatrixClient extends EventEmitter {
     /**
      * Adds a new pusher or updates an existing pusher
      *
-     * @param {Object} pusher Object representing a pusher
+     * @param {IPusherRequest} pusher Object representing a pusher
      * @param {module:client.callback} callback Optional.
      * @return {Promise} Resolves: Empty json object on success
      * @return {module:http-api.MatrixError} Rejects: with an error response.
      */
-    public setPusher(pusher: IPusher, callback?: Callback): Promise<{}> {
+    public setPusher(pusher: IPusherRequest, callback?: Callback): Promise<{}> {
         const path = "/pushers/set";
         return this.http.authedRequest(callback, "POST", path, null, pusher);
     }
 
     /**
+     * Get the push rules for the account from the server.
      * @param {module:client.callback} callback Optional.
-     * @return {Promise} Resolves: TODO
+     * @return {Promise} Resolves to the push rules.
      * @return {module:http-api.MatrixError} Rejects: with an error response.
      */
-    public getPushRules(callback?: Callback): Promise<any> { // TODO: Types
+    public getPushRules(callback?: Callback): Promise<IPushRules> {
         return this.http.authedRequest(callback, "GET", "/pushrules/").then(rules => {
             return PushProcessor.rewriteDefaultRules(rules);
         });
@@ -7235,7 +7216,13 @@ export class MatrixClient extends EventEmitter {
      * @return {Promise} Resolves: an empty object {}
      * @return {module:http-api.MatrixError} Rejects: with an error response.
      */
-    public addPushRule(scope: string, kind: string, ruleId: string, body: any, callback?: Callback): Promise<{}> {
+    public addPushRule(
+        scope: string,
+        kind: PushRuleKind,
+        ruleId: Exclude<string, RuleId>,
+        body: any,
+        callback?: Callback,
+    ): Promise<any> { // TODO: Types
         // NB. Scope not uri encoded because devices need the '/'
         const path = utils.encodeUri("/pushrules/" + scope + "/$kind/$ruleId", {
             $kind: kind,
@@ -7252,7 +7239,12 @@ export class MatrixClient extends EventEmitter {
      * @return {Promise} Resolves: an empty object {}
      * @return {module:http-api.MatrixError} Rejects: with an error response.
      */
-    public deletePushRule(scope: string, kind: string, ruleId: string, callback?: Callback): Promise<{}> {
+    public deletePushRule(
+        scope: string,
+        kind: PushRuleKind,
+        ruleId: Exclude<string, RuleId>,
+        callback?: Callback,
+    ): Promise<any> { // TODO: Types
         // NB. Scope not uri encoded because devices need the '/'
         const path = utils.encodeUri("/pushrules/" + scope + "/$kind/$ruleId", {
             $kind: kind,
@@ -7273,8 +7265,8 @@ export class MatrixClient extends EventEmitter {
      */
     public setPushRuleEnabled(
         scope: string,
-        kind: string,
-        ruleId: string,
+        kind: PushRuleKind,
+        ruleId: RuleId | string,
         enabled: boolean,
         callback?: Callback,
     ): Promise<{}> {
@@ -7299,9 +7291,9 @@ export class MatrixClient extends EventEmitter {
      */
     public setPushRuleActions(
         scope: string,
-        kind: string,
-        ruleId: string,
-        actions: string[],
+        kind: PushRuleKind,
+        ruleId: RuleId | string,
+        actions: PushRuleAction[],
         callback?: Callback,
     ): Promise<{}> {
         const path = utils.encodeUri("/pushrules/" + scope + "/$kind/$ruleId/actions", {