@namespace("keybase.1")

protocol home {

  @typedef("string")
  record HomeScreenItemID {}

  enum HomeScreenItemType {
    TODO_1,
    PEOPLE_2,
    ANNOUNCEMENT_3
  }

  variant HomeScreenItemData switch (HomeScreenItemType t) {
    case TODO: HomeScreenTodo;
    case PEOPLE: HomeScreenPeopleNotification;
    case ANNOUNCEMENT: HomeScreenAnnouncement;
    default: void; // Note, if badged, we should urge an upgrade here.
  }
  variant HomeScreenItemDataExt switch (HomeScreenItemType t) {
    case TODO: HomeScreenTodoExt;
    default: void;
  }

  enum AppLinkType {
    NONE_0,
    PEOPLE_1,
    CHAT_2,
    FILES_3,
    WALLET_4,
    GIT_5,
    DEVICES_6,
    SETTINGS_7,
    TEAMS_8
  }

  @typedef("int")
  record HomeScreenAnnouncementID {}

  @typedef("int")
  record HomeScreenAnnouncementVersion {}

  record HomeScreenAnnouncement {
    HomeScreenAnnouncementID id;
    HomeScreenAnnouncementVersion version;
    AppLinkType appLink;
    string confirmLabel;
    boolean dismissable;
    string iconUrl;
    string text;
    string url;
  }

  /* The following are deprecated. */
  /* DEPRECATED_ADD_PHONE_NUMBER_13, */
  /* DEPRECATED_VERIFY_ALL_PHONE_NUMBER_14, */
  /* DEPRECATED_VERIFY_ALL_EMAIL_15, */
  /* DEPRECATED_LEGACY_EMAIL_VISIBILITY_16, */
  /* DEPRECATED_ADD_EMAIL_17, */
  enum HomeScreenTodoType {
    NONE_0,
    BIO_1,
    PROOF_2,
    DEVICE_3,
    FOLLOW_4,
    CHAT_5,
    PAPERKEY_6,
    TEAM_7,
    FOLDER_8,
    GIT_REPO_9,
    TEAM_SHOWCASE_10,
    AVATAR_USER_11,
    AVATAR_TEAM_12,
    ADD_PHONE_NUMBER_18,
    VERIFY_ALL_PHONE_NUMBER_19,
    VERIFY_ALL_EMAIL_20,
    LEGACY_EMAIL_VISIBILITY_21,
    ADD_EMAIL_22,
    ANNONCEMENT_PLACEHOLDER_10000
  }

  /**
    Most of TODO items do not carry additional data, but some do. e.g. TODO
    item to tell user to verify their email address will carry that email
    address.

    All new TODO data bundle types should be records rather than single fields
    to support adding new data to existing TODOs. If a legacy TODO (such as
    VERIFY_ALL_EMAIL) uses a single field, the "TodoExt" field should be used to
    introduce more data to the payload.
  */
  variant HomeScreenTodo switch (HomeScreenTodoType t) {
    case VERIFY_ALL_PHONE_NUMBER: PhoneNumber;
    case VERIFY_ALL_EMAIL: EmailAddress;
    case LEGACY_EMAIL_VISIBILITY: EmailAddress;
    default: void;
  }
  variant HomeScreenTodoExt switch (HomeScreenTodoType t) {
    case VERIFY_ALL_EMAIL: VerifyAllEmailTodoExt;
    default: void;
  }

  record VerifyAllEmailTodoExt {
    UnixTime lastVerifyEmailDate;
  }

  enum HomeScreenPeopleNotificationType {
    FOLLOWED_1,
    FOLLOWED_MULTI_2,
    CONTACT_3,
    CONTACT_MULTI_4
  }

  record HomeScreenPeopleNotificationFollowed {
    Time followTime;
    boolean followedBack;
    UserSummary user;
  }

  record HomeScreenPeopleNotificationFollowedMulti {
    array<HomeScreenPeopleNotificationFollowed> followers;
    int numOthers;
  }

  record HomeScreenPeopleNotificationContact {
    Time resolveTime;
    string username;
    string description;
    string resolvedContactBlob;
  }

  record HomeScreenPeopleNotificationContactMulti {
    array<HomeScreenPeopleNotificationContact> contacts;
    int numOthers;
  }

  variant HomeScreenPeopleNotification switch (HomeScreenPeopleNotificationType t) {
    case FOLLOWED: HomeScreenPeopleNotificationFollowed;
    case FOLLOWED_MULTI: HomeScreenPeopleNotificationFollowedMulti;
    case CONTACT: HomeScreenPeopleNotificationContact;
    case CONTACT_MULTI: HomeScreenPeopleNotificationContactMulti;
  }

  record HomeScreenItem {
    boolean badged;
    HomeScreenItemData data;
    HomeScreenItemDataExt dataExt;
  }

  record Pics {
    @jsonkey("square_40")
    string square40;
    @jsonkey("square_200")
    string square200;
    @jsonkey("square_360")
    string square360;
  }

  record HomeUserSummary {
    UID uid;
    string username;
    string bio;
    @jsonkey("full_name")
    string fullName;
    union { null, Pics } pics;
  }

  record HomeScreen {
    Time lastViewed;
    int version;
    int visits;
    array<HomeScreenItem> items;
    array<HomeUserSummary> followSuggestions;
    int announcementsVersion;
  }

  /**
    HomeGetScreen returns the home screen for the current user.
    If `markViewed` is specified, the server will mark this version of the
    home screen "viewed", potentially updating some badges.
    `numFollowSuggestionsWanted` controls the number of people to return.
    If not specified, it will default to `0`, so no people.  If `-1` is specified,
    the default number will be returned (10).  Otherwise, the caller should
    specify.
   */
  HomeScreen homeGetScreen(boolean markViewed, int numFollowSuggestionsWanted);

  void homeSkipTodoType(HomeScreenTodoType t);
  void homeDismissAnnouncement(HomeScreenAnnouncementID i);
  void homeActionTaken();
  void homeMarkViewed();

}