// Copyright 2021 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module mojom.user_education_internals;

// Generic data about usage of a promo.
struct FeaturePromoDemoPageData {
  // The data being described.
  string name;
  // The value of the data.
  string value;
};

// Common feature block for both tutorials and IPH promos.
struct FeaturePromoDemoPageInfo {
  // The title of the promo, to be presented to the user.
  string display_title;
  // The description of the promo, to be presented to the user.
  string display_description;
  // The actual key used to trigger the promo if it is chosen by the user.
  string internal_name;
  // The type of tutorial or IPH (e.g. "Toast", "Snooze", etc.)
  string type;
  // The milestone at which the tutorial or IPH was added.
  int32 added_milestone;
  // The list of supported platforms as text strings. (This mirrors the use on
  // the flags page.)
  array<string> supported_platforms;
  // The names of other non-IPH features that must be enabled for this promo to
  // display successfully.
  array<string> required_features;
  // A list of human-readable instructions on how to set the browser up so that
  // the tutorial or IPH can be run.
  array<string> instructions;
  // The user education journey that follows this one, if any.
  string followed_by_internal_name;
  // Any additional data about the promo or tutorial.
  array<FeaturePromoDemoPageData> data;
};

// What's New Module data.
struct WhatsNewModuleDemoPageInfo {
  // The name of the module, to be presented to the user.
  string display_title;
  // The actual module name.
  string module_name;
  // Whether the module has an attached browser command.
  bool has_browser_command;
  // Whether the features associated with this module is enabled.
  bool is_feature_enabled;
  // The position of the modules in the enabled-queue.
  int32 queue_position;
};

// What's New Edition data.
struct WhatsNewEditionDemoPageInfo {
  // The name of the edition, to be presented to the user.
  string display_title;
  // The actual edition name.
  string edition_name;
  // Whether the features associated with this edition is enabled.
  bool is_feature_enabled;
  // Whether this edition has been shown to the user.
  bool has_been_used;
  // The major version of chrome this edition was shown.
  int32 version_used;
};

// Provides access to browser-side user education data for
// chrome://user-education-internals
interface UserEducationInternalsPageHandler {
  // Determine if the Feature Engagement backend is initialized. Calling other
  // methods will result in incomplete data/failures if this hasn't returned
  // true.
  IsFeatureEngagementInitialized() => (bool is_initialized);

  // Get the list of all available tutorials. Only needs to be called once
  // since the browser-side list is static and does not change.
  GetTutorials() => (array<FeaturePromoDemoPageInfo> tutorial_infos);

  // Start a tutorial listed in the `GetTutorials` result.
  // Returns an error message if the operation fails; empty string on success.
  StartTutorial(string tutorial_id) => (string error_message);

  // Returns a set of data about the current session state.
  GetSessionData() => (array<FeaturePromoDemoPageData> session_data);

  // Get the list of all available feature promos.
  GetFeaturePromos() => (array<FeaturePromoDemoPageInfo> feature_promos);

  // Start a feature promo from the list of available feature promos using the
  // `feature_name`.
  // Returns an error message if the operation fails; empty string on success.
  ShowFeaturePromo(string feature_name) => (string error_message);

  // Clears the data (snooze, show count, etc.) associated with a promo.
  // Returns an error message if the operation fails; empty string on success.
  ClearFeaturePromoData(string feature_name) => (string error_message);

  // Get the list of all available non-IPH promos.
  GetNonIphPromos() => (array<FeaturePromoDemoPageInfo> non_iph_promos);

  // Clears the feature_engagement data associated with a non-IPH promo.
  // Returns an error message if the operation fails; empty string on success.
  ClearNonIphPromoData(string feature_name) => (string error_message);

  // Clears all session-related User Education data.
  // Returns an error message if the operation fails; empty string on success.
  ClearSessionData() => (string error_message);

  // Starts a new session at the current time.
  // Returns an error message if the operation fails; empty string on success.
  ForceNewSession() => (string error_message);

  // Eliminates all current grace periods, allowing all eligible promos to show.
  // Returns an error message if the operation fails; empty string on success.
  RemoveGracePeriods() => (string error_message);

  // Retrieves "New" Badge data.
  GetNewBadges() => (array<FeaturePromoDemoPageInfo> new_badges);

  // Retrieves What's New module data.
  GetWhatsNewModules() => (array<WhatsNewModuleDemoPageInfo> whats_new_modules);

  // Retrieves What's New edition data.
  GetWhatsNewEditions() =>
    (array<WhatsNewEditionDemoPageInfo> whats_new_editions);

  // Retrieves NTP Promo data.
  GetNtpPromos() => (array<FeaturePromoDemoPageInfo> ntp_promos);

  // Retrieves NTP Promo preferences.
  GetNtpPromoPreferences() =>
    (array<FeaturePromoDemoPageData> ntp_promo_preferences);

  // Clears "New" Badge data associated with a particular feature.
  // Returns an error message if the operation fails; empty string on success.
  ClearNewBadgeData(string feature_name) => (string error_message);

  // Clears What's New data.
  // Returns an error message if the operation fails; empty string on success.
  ClearWhatsNewData() => (string error_message);

  // Clears NTP Promo data for the specified promo ID.
  // Returns an error message if the operation fails; empty string on success.
  ClearNtpPromoData(string id) => (string error_message);

  // Clears all NTP promo preferences.
  ClearNtpPromoPreferences() => (string error_message);

  // Launches What's New page with for the staging environment.
  LaunchWhatsNewStaging();

  // Override the What's New page version used for the current session.
  UpdateWhatsNewVersionOverride(int32 version);
};