gerbeur/shared/notification.ts

/**
 * Notifications tell a user when someone follows them or their playlists,
 * upvotes, comments, likes or mentions them, or posts where they follow. This
 * module types the ones `api/services/notification-service.ts` makes, and the
 * data each kind carries. The client's `/notifications` page lists them and
 * turns each into a sentence and a link.
 *
 * @module
 */

/**
 * Says which of the `…Data` interfaces a notification's `data` is. Each value
 * has one `notify…` trigger in `notification-service.ts`.
 */
export type NotificationType =
  | "playlist_followed"
  | "user_followed"
  | "user_dump_posted"
  | "playlist_dump_added"
  | "dump_upvoted"
  | "user_mentioned"
  | "dump_commented"
  | "comment_liked";

/**
 * Where a notification's dump is now, for its link (`dumpPath`). The server
 * joins it each time it sends the notification, so a renamed dump or poster
 * still links right; it is absent once the dump is deleted.
 */
export interface DumpRef {
  dumpSlug?: string;
  dumpOwnerUsername?: string;
}

/** Where a notification's playlist is now, joined as {@link DumpRef} is. */
export interface PlaylistRef {
  playlistSlug?: string;
  playlistOwnerUsername?: string;
}

/**
 * Carried by a `playlist_followed` notification, sent to a playlist's owner.
 */
export interface PlaylistFollowedData extends PlaylistRef {
  followerId: string;
  followerUsername: string;
  playlistId: string;
  playlistTitle: string;
}

/** Carried by a `user_followed` notification, sent to the user followed. */
export interface UserFollowedData {
  followerId: string;
  followerUsername: string;
}

/**
 * Carried by a `user_dump_posted` notification, sent to the followers of a
 * user who posted a public dump.
 */
export interface UserDumpPostedData extends DumpRef {
  dumperId: string;
  dumperUsername: string;
  dumpId: string;
  dumpTitle: string;
}

/**
 * Carried by a `playlist_dump_added` notification, sent to the followers of a
 * public playlist when a public dump is added to it.
 */
export interface PlaylistDumpAddedData extends DumpRef, PlaylistRef {
  dumpId: string;
  dumpTitle: string;
  playlistId: string;
  playlistTitle: string;
}

/** Carried by a `dump_upvoted` notification, sent to the dump's poster. */
export interface DumpUpvotedData extends DumpRef {
  voterId: string;
  voterUsername: string;
  dumpId: string;
  dumpTitle: string;
}

/**
 * Carried by a `user_mentioned` notification, sent to a user @mentioned in a
 * comment, a dump, a playlist's description or a chat message, or to every
 * user by a chat message's `@everyone`. Its
 * {@link DumpRef} is the dump's, or the comment's dump's; its
 * {@link PlaylistRef} the playlist's.
 */
export interface UserMentionedData extends DumpRef, PlaylistRef {
  mentionerId: string;
  mentionerUsername: string;
  contextType: "comment" | "dump" | "playlist" | "chat";
  /** The id of the comment, dump, playlist or chat message. */
  contextId: string;
  /**
   * The title of the dump or playlist, or of the dump a comment is under;
   * empty for the chat.
   */
  contextTitle: string;
  /**
   * Set only for a comment. It names the dump the comment is under, which the
   * notification's link opens.
   */
  dumpId?: string;
  /**
   * Set when the user was reached by `@everyone` rather than by name. A
   * message naming them as well notifies them once, by name.
   */
  everyone?: true;
}

/** Carried by a `dump_commented` notification, sent to the dump's poster. */
export interface DumpCommentedData extends DumpRef {
  commenterId: string;
  commenterUsername: string;
  commentId: string;
  dumpId: string;
  dumpTitle: string;
}

/** Carried by a `comment_liked` notification, sent to the comment's author. */
export interface CommentLikedData extends DumpRef {
  likerId: string;
  likerUsername: string;
  commentId: string;
  dumpId: string;
  dumpTitle: string;
}

/**
 * Stored when the notification is made, so a title changed later still shows
 * the old one. The `…Username` fields and the refs are joined when it is sent,
 * so they follow a rename. The notification's `type` says which member it is.
 */
export type NotificationData =
  | PlaylistFollowedData
  | UserFollowedData
  | UserDumpPostedData
  | PlaylistDumpAddedData
  | DumpUpvotedData
  | UserMentionedData
  | DumpCommentedData
  | CommentLikedData;

/**
 * Pushed to its user's sockets in a `notification_created` message when it is
 * made, and returned by `GET /api/me/notifications`.
 */
export interface Notification {
  id: string;
  userId: string;
  type: NotificationType;
  data: NotificationData;
  read: boolean;
  createdAt: Date;
}