// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//
// Sync protocol datatype extension for history entries.

// If you change or add any fields in this file, update proto_visitors.h and
// potentially proto_enum_conversions.{h, cc}.

syntax = "proto2";

option go_package = "./sync_pb";

option java_multiple_files = true;
option java_package = "org.chromium.components.sync.protocol";

option optimize_for = LITE_RUNTIME;

package sync_pb;

import "sync_enums.proto";

// A history sync entity - this roughly represents one navigation, including its
// full redirect chain (but not referrals). Fields correspond to similarly named
// fields in history::VisitRow and history::URLRow.
message HistorySpecifics {
  // Timestamp, also called "global ID" in some places (e.g. in delete
  // directives). This uniquely identifies the entity.
  optional int64 visit_time_windows_epoch_micros = 1;

  // Cache GUID of the client that produced this entity, aka the "originator".
  optional string originator_cache_guid = 2;

  message RedirectEntry {
    // ID of the visit on the originator client, unique within that client.
    optional int64 originator_visit_id = 1;
    // URL that was visited.
    optional string url = 2;
    // Title of the page corresponding to this URL.
    optional string title = 3;
    // True if the URL should NOT be used for auto-complete.
    optional bool hidden = 4;
    // The redirect type (if any).
    optional SyncEnums.PageTransitionRedirectType redirect_type = 5;
  }
  // The redirect chain. The first entry is the URL the user originally
  // navigated to; the last one is where they ended up. If there were no
  // redirects, this has only one entry.
  repeated RedirectEntry redirect_entries = 3;

  // Whether the redirect chain in this entity is the continuation of a prior
  // chain, and whether a continuation of this chain exists, in other entities.
  // These are effectively the inverse of the CHAIN_START/CHAIN_END page
  // transition qualifiers in Chrome. They are typically both false, since the
  // whole chain is included in `redirect_entries`, but in some cases (notably,
  // client redirects) a redirect chain may be split up across multiple
  // entities.
  optional bool redirect_chain_start_incomplete = 19;
  optional bool redirect_chain_end_incomplete = 20;

  // If this is set to true, then the redirect chain was too long and some
  // entries were trimmed from the middle, so `redirect_entries` only
  // corresponds to some of the first plus some of the last entries of the
  // actual redirect chain.
  optional bool redirect_chain_middle_trimmed = 21;

  message PageTransition {
    // The core transition type.
    optional SyncEnums.PageTransition core_transition = 1 [default = LINK];
    // Qualifiers:
    // A supervised user tried to access this URL but was blocked.
    optional bool blocked = 2;
    // User used the Forward or Back button to navigate among browsing history.
    optional bool forward_back = 3;
    // User used the address bar to trigger this navigation.
    optional bool from_address_bar = 4;
    // User is navigating to the home page.
    optional bool home_page = 5;
  }
  // The PageTransition for the navigation.
  optional PageTransition page_transition = 4;

  // The ID of the visit, on the originator client, that was a referrer for
  // this one, or 0 if no referrer exists.
  optional int64 originator_referring_visit_id = 5;
  // The ID of the visit, on the originator client, that opened this one, or 0
  // if no opener exists.
  optional int64 originator_opener_visit_id = 6;
  // The ID of the cluster that this visit belongs to on the originator client,
  // or 0 if the originator client does not support setting this field or the
  // visit does not belong to any cluster.
  optional int64 originator_cluster_id = 22;

  // The duration of the visit, in microseconds. Zero if the visit hasn't been
  // finished (or the duration wasn't updated for some other reason).
  optional int64 visit_duration_micros = 7;

  // The kind of browser where this visit happened.
  optional SyncEnums.BrowserType browser_type = 8;

  // The SessionID of the window and tab where the visit happened. Can be used
  // to link together possibly-related visits.
  // Note: These are only unique per-client, so always use together with
  // `originator_cache_guid`.
  optional int32 window_id = 9;
  optional int32 tab_id = 10;

  // The ID for the task associated with this navigation, which is globally
  // unique with high probability.
  optional int64 task_id = 11;
  // The IDs of ancestor tasks. These can be used to construct a tree of related
  // visits.
  optional int64 root_task_id = 12;
  optional int64 parent_task_id = 13;

  // The HTTP response code of the navigation.
  optional int32 http_response_code = 14;

  // The language of the content on the page, as an ISO 639 language code
  // (usually two letters). May be "und" if the language couldn't be determined.
  optional string page_language = 15;

  // Whether a password field was found on the page.
  optional SyncEnums.PasswordState password_state = 16;

  // URL of the favicon for this page.
  optional string favicon_url = 17;

  // The URL of the referrer (indicated by `originator_referring_visit_id`), if
  // any.
  optional string referrer_url = 18;

  // Visit has an image derived from public version of the page. This can be
  // used to provide more visual experience.
  optional bool has_url_keyed_image = 23;

  message Category {
    // ID of the category, this typically is an MID.
    optional string id = 1;
    // Weight of the category, this is an integer value informing the confidence
    // of a visit belonging to this category.
    optional int32 weight = 2;
  }

  // Categories tagged for the visit.
  repeated Category categories = 24;

  // Related search URLs for a Google SRP visit, to provide next steps to user.
  repeated string related_searches = 25;

  // ID of the app (non-BrApp) this entity was generated for, if any. Only
  // visits originating from Android devices may have this set.
  optional string app_id = 26;
}