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

// Use the <code>chrome.feedbackPrivate</code> API to provide Chrome [OS]
// feedback to the Google Feedback servers.
namespace feedbackPrivate {

  dictionary AttachedFile {
    DOMString name;
    [instanceOf=Blob] object? data;
  };

  dictionary LogsMapEntry {
    DOMString key;
    DOMString value;
  };

  // Supported feedback flows.
  enum FeedbackFlow {
    // Flow for regular user. This is the default.
    regular,

    // Flow on the ChromeOS login screen. URL entry, file attaching and landing
    // page is disabled for this flow.
    login,

    // Flow when the feedback is requested from the sad tab ("Aw, Snap!") page
    // when the renderer crashes.
    sadTabCrash,

    // Flow for internal Google users.
    googleInternal,

    // Flow for AI features.
    ai
  };

  dictionary FeedbackInfo {
    // File to attach to the feedback report.
    AttachedFile? attachedFile;

    // An optional tag to label what type this feedback is.
    DOMString? categoryTag;

    // The feedback text describing the user issue.
    DOMString description;

    // The placeholder text that will be shown in the description field when
    // it's empty.
    DOMString? descriptionPlaceholder;

    // The e-mail of the user that initiated this feedback.
    DOMString? email;

    // The URL of the page that this issue was being experienced on.
    DOMString? pageUrl;

    // Optional product ID to override the Chrome [OS] product id that is
    // usually passed to the feedback server.
    long? productId;

    // Screenshot to send with this feedback.
    [instanceOf=Blob] object? screenshot;

    // Optional id for performance trace data that can be included in this
    // report.
    long? traceId;

    // An array of key/value pairs providing system information for this
    // feedback report.
    LogsMapEntry[]? systemInformation;

    // True if we have permission to add histograms to this feedback report.
    boolean? sendHistograms;

    // Optional feedback UI flow. Default is the regular user flow.
    FeedbackFlow? flow;

    // TODO(rkc): Remove these once we have bindings to send blobs to Chrome.
    // Used internally to store the blob uuid after parameter customization.
    DOMString? attachedFileBlobUuid;
    DOMString? screenshotBlobUuid;

    // Whether to use the system-provided window frame or custom frame controls.
    boolean? useSystemWindowFrame;

    // Whether or not to send bluetooth logs with this report.
    boolean? sendBluetoothLogs;

    // Whether or not to send tab titles with this report.
    boolean? sendTabTitles;

    // Whether or not to send Assistant feedback to Assistant server.
    boolean? assistantDebugInfoAllowed;

    // Whether or not triggered from Assistant.
    boolean? fromAssistant;

    // Whether or not to include bluetooth logs.
    boolean? includeBluetoothLogs;

    // Whether to show questionnaire in the report description based on detected
    // domain-related keywords (crbug/1241169).
    boolean? showQuestionnaire;

    // Whether or not triggered for Autofill.
    boolean? fromAutofill;

    // A JSON formatted string containing autofill metadata for this
    // feedback report.
    DOMString? autofillMetadata;

    // Whether or not |autofillMetadata| should be included in the feedback
    // report.
    boolean? sendAutofillMetadata;

    // Whether or not the content is offensive or unsafe.
    boolean? isOffensiveOrUnsafe;

    // A JSON formatted string containing ai metadata.
    DOMString? aiMetadata;
  };

  // Possible statuses that can result from sending feedback.
  enum Status {success, delayed};

  // Landing page types that can be shown after sending feedback.
  enum LandingPageType {normal, techstop, noLandingPage};

  // Result returned from a $(ref:sendFeedback) call.
  dictionary SendFeedbackResult {
    // Status of the sending of a feedback report.
    Status status;

    // The type of landing page shown to the use when the feedback report is
    // successfully sent, if one should be shown.
    LandingPageType landingPageType;
  };

  // Allowed log sources on Chrome OS.
  enum LogSource {
    // Chrome OS system messages.
    messages,

    // Latest Chrome OS UI logs.
    uiLatest,

    // Info about display connectors and connected displays from DRM subsystem.
    drmModetest,

    // USB device list and connectivity graph.
    lsusb,

    // Logs from daemon for Atrus device.
    atrusLog,

    // Network log.
    netLog,

    // Log of system events.
    eventLog,

    // Update engine log.
    updateEngineLog,

    // Log of the current power manager session.
    powerdLatest,

    // Log of the previous power manager session.
    powerdPrevious,

    // Info about system PCI buses devices.
    lspci,

    // Info about system network interface.
    ifconfig,

    // Info about system uptime.
    uptime
  };

  // Source of the feedback.
  enum FeedbackSource {quickoffice};

  // Input parameters for a readLogSource() call.
  dictionary ReadLogSourceParams {
    // The log source from which to read.
    LogSource source;

    // For file-based log sources, read from source without closing the file
    // handle. The next time $(ref:readLogSource) is called, the file read will
    // continue where it left off. $(ref:readLogSource) can be called with
    // <code>incremental=true</code> repeatedly. To subsequently close the file
    // handle, pass in <code>incremental=false</code>.
    boolean incremental;

    // To read from an existing file handle, set this to a valid
    // <code>readerId</code> value that was returned from a previous
    // $(ref:readLogSource) call. The reader must previously have been created
    // for the same value of <code>source</code>. If no <code>readerId</code> is
    // provided, $(ref:readLogSource) will attempt to open a new log source
    // reader handle.
    long? readerId;
  };

  // Result returned from a $(ref:readLogSource) call.
  dictionary ReadLogSourceResult {
    // The ID of the log source reader that was created to read from the log
    // source. If the reader was destroyed at the end of a read by passing in
    // <code>incremental=false</code>, this is always set to 0. If the call was
    // to use an existing reader with an existing ID, this will be set to the
    // same <code>readerId</code> that was passed into $(ref:readLogSource).
    long readerId;

    // Each DOMString in this array represents one line of logging that was
    // fetched from the log source.
    DOMString[] logLines;
  };

  callback GetUserEmailCallback = void(DOMString email);
  callback GetSystemInformationCallback =
      void(LogsMapEntry[] systemInformation);
  callback SendFeedbackCallback = void(SendFeedbackResult result);
  callback ReadLogSourceCallback = void (ReadLogSourceResult result);

  interface Functions {
    // Returns the email of the currently active or logged in user.
    static void getUserEmail(GetUserEmailCallback callback);

    // Returns the system information dictionary.
    static void getSystemInformation(GetSystemInformationCallback callback);

    // Opens the feedback report window.
    static void openFeedback(FeedbackSource source);

    // Sends a feedback report.
    // |loadSystemInfo|: Optional flag when present and is true, the backend
    // should load system information before sending the report. This is added
    // to reduce user's wait time when sending reports because loading system
    // information is slow.
    // |formOpenTime|: The epoch time when the feedback form was opened. This is
    // used for metrics.
    static void sendFeedback(
        FeedbackInfo feedback,
        optional boolean loadSystemInfo,
        optional double formOpenTime,
        SendFeedbackCallback callback);

    // Reads from a log source indicated by <code>source</code>.
    // <p>If <code>incremental</code> is false:
    // <ul>
    //   <li>Returns the entire contents of the log file.</li>
    //   <li>Returns <code>readerId</code> value of 0 to callback.</li>
    // </ul>
    // If <code>incremental</code> is true, and no <code>readerId</code> is
    // provided:
    // <ul>
    //   <li>Returns the entire contents of the log file.</li>
    //   <li>Starts tracking the file read handle, which is returned as a
    //       nonzero <code>readerId</code> value in the callback.
    //       </li>
    //   <li>If can't create a new file handle, returns <code>readerId</code>
    //       value of 0 in the callback.
    //       </li>
    // </ul>
    // If <code>incremental</code> is true, and a valid non-zero
    // <code>readerId</code> is provided:
    // <ul>
    //   <li>Returns new lines written to the file since the last time this
    //       function was called for the same file and <code>readerId</code>.
    //       </li>
    //   <li>Returns the same <code>readerId</code> value to the callback.</li>
    // </ul>
    static void readLogSource(
        ReadLogSourceParams params,
        ReadLogSourceCallback callback);

  };

  interface Events {
    // Fired when the a user requests the launch of the feedback UI. We're
    // using an event for this versus using the override API since we want
    // to be invoked, but not showing a UI, so the feedback extension can
    // take a screenshot of the user's desktop.
    static void onFeedbackRequested(FeedbackInfo feedback);
  };
};