places.udl

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

[Custom]
typedef string Url;
[Custom]
typedef i64 PlacesTimestamp;
[Custom]
typedef i32 VisitTransitionSet;
[Custom]
typedef string Guid;

namespace places {
    [Throws=PlacesApiError]
    PlacesApi places_api_new(string db_path);
};

enum ConnectionType {
    "ReadOnly",
    "ReadWrite",
    "Sync", // ideally we wouldn't need to expose this and should guard against it being used (it's internal only)
};

interface SqlInterruptHandle {
     void interrupt();
};

interface PlacesApi {
    [Throws=PlacesApiError]
    PlacesConnection new_connection(ConnectionType conn_type);

    [Self=ByArc]
    void register_with_sync_manager();

    [Throws=PlacesApiError]
    void reset_history();

    [Throws=PlacesApiError]
    string history_sync(string key_id, string access_token, string sync_key, Url tokenserver_url);

    [Throws=PlacesApiError]
    string bookmarks_sync(string key_id, string access_token, string sync_key, Url tokenserver_url);

    [Throws=PlacesApiError]
    void bookmarks_reset();
};

interface PlacesConnection {
    SqlInterruptHandle new_interrupt_handle();

    [Throws=PlacesApiError]
    HistoryMetadata? get_latest_history_metadata_for_url(Url url);

    [Throws=PlacesApiError]
    sequence<HistoryMetadata> get_history_metadata_between(PlacesTimestamp start, PlacesTimestamp end);

    [Throws=PlacesApiError]
    sequence<HistoryMetadata> get_history_metadata_since(PlacesTimestamp since);

    [Throws=PlacesApiError]
    sequence<SearchResult> query_autocomplete(string search, i32 limit);

    /// `url` is a `string` and not a `URL` because `accept_result`
    /// handles malformed urls
    [Throws=PlacesApiError]
    void accept_result(string search_string, string url);

    [Throws=PlacesApiError]
    Url? match_url(string query);

    [Throws=PlacesApiError]
    sequence<HistoryMetadata> query_history_metadata(string query, i32 limit);

    [Throws=PlacesApiError]
    sequence<HistoryHighlight> get_history_highlights(HistoryHighlightWeights weights, i32 limit);

    [Throws=PlacesApiError]
    void note_history_metadata_observation(HistoryMetadataObservation data, NoteHistoryMetadataObservationOptions options);

    [Throws=PlacesApiError]
    void metadata_delete(Url url, Url? referrer_url, string? search_term);

    [Throws=PlacesApiError]
    void metadata_delete_older_than(PlacesTimestamp older_than);

    [Throws=PlacesApiError]
    void apply_observation(VisitObservation visit);

    [Throws=PlacesApiError]
    sequence<Url> get_visited_urls_in_range(PlacesTimestamp start, PlacesTimestamp end, boolean include_remote);

    [Throws=PlacesApiError]
    sequence<HistoryVisitInfo> get_visit_infos(PlacesTimestamp start_date, PlacesTimestamp end_date, VisitTransitionSet exclude_types);

    [Throws=PlacesApiError]
    i64 get_visit_count(VisitTransitionSet exclude_types);

    [Throws=PlacesApiError]
    sequence<HistoryVisitInfo> get_visit_page(i64 offset, i64 count, VisitTransitionSet exclude_types);
    // TODO: bound should be a `PlacesTimestamp`?
    [Throws=PlacesApiError]
    HistoryVisitInfosWithBound get_visit_page_with_bound(i64 bound, i64 offset, i64 count, VisitTransitionSet exclude_types);

    [Throws=PlacesApiError]
    sequence<boolean> get_visited(sequence<string> urls);

    [Throws=PlacesApiError]
    void delete_visits_for(string url);

    [Throws=PlacesApiError]
    void delete_visits_between(PlacesTimestamp start, PlacesTimestamp end);

    [Throws=PlacesApiError]
    void delete_visit(string url, PlacesTimestamp timestamp);

    [Throws=PlacesApiError]
    sequence<TopFrecentSiteInfo> get_top_frecent_site_infos(i32 num_items, FrecencyThresholdOption threshold_option);

    //From a-c: will not remove any history from remote devices, but it will prevent deleted
    // history from returning.
    [Throws=PlacesApiError]
    void delete_everything_history();

    /// Run maintenance on the places DB (prune step)
    ///
    /// The `run_maintenance_*()` functions are intended to be run during idle time and will take steps
    /// to clean up / shrink the database.  They're split up so that we can time each one in the
    /// Kotlin wrapper code (This is needed because we only have access to the Glean API in Kotlin and
    /// it supports a stop-watch style API, not recording specific values).
    ///
    /// db_size_limit is the approximate storage limit in bytes.  If the database is using more space
    /// than this, some older visits will be deleted to free up space.  Pass in a 0 to skip this.
    ///
    /// prune_limit is the maximum number of visits to prune if the database is over db_size_limit
    [Throws=PlacesApiError]
    RunMaintenanceMetrics run_maintenance_prune(u32 db_size_limit, u32 prune_limit);

    /// Run maintenance on the places DB (vacuum step)
    ///
    /// The `run_maintenance_*()` functions are intended to be run during idle time and will take steps
    /// to clean up / shrink the database.  They're split up so that we can time each one in the
    /// Kotlin wrapper code (This is needed because we only have access to the Glean API in Kotlin and
    /// it supports a stop-watch style API, not recording specific values).
    [Throws=PlacesApiError]
    void run_maintenance_vacuum();

    /// Run maintenance on the places DB (optimize step)
    ///
    /// The `run_maintenance_*()` functions are intended to be run during idle time and will take steps
    /// to clean up / shrink the database.  They're split up so that we can time each one in the
    /// Kotlin wrapper code (This is needed because we only have access to the Glean API in Kotlin and
    /// it supports a stop-watch style API, not recording specific values).
    [Throws=PlacesApiError]
    void run_maintenance_optimize();

    /// Run maintenance on the places DB (checkpoint step)
    ///
    /// The `run_maintenance_*()` functions are intended to be run during idle time and will take steps
    /// to clean up / shrink the database.  They're split up so that we can time each one in the
    /// Kotlin wrapper code (This is needed because we only have access to the Glean API in Kotlin and
    /// it supports a stop-watch style API, not recording specific values).
    [Throws=PlacesApiError]
    void run_maintenance_checkpoint();

    [Throws=PlacesApiError]
    BookmarkItem? bookmarks_get_tree([ByRef] Guid item_guid);

    [Throws=PlacesApiError]
    BookmarkItem? bookmarks_get_by_guid([ByRef] Guid guid, boolean get_direct_children);

    // XXX - should return BookmarkData
    [Throws=PlacesApiError]
    sequence<BookmarkItem> bookmarks_get_all_with_url(string url);

    // XXX - should return BookmarkData
    [Throws=PlacesApiError]
    sequence<BookmarkItem> bookmarks_search(string query, i32 limit);

    // XXX - should return BookmarkData
    [Throws=PlacesApiError]
    sequence<BookmarkItem> bookmarks_get_recent(i32 limit);

    [Throws=PlacesApiError]
    boolean bookmarks_delete(Guid id);

    [Throws=PlacesApiError]
    void bookmarks_delete_everything();

    [Throws=PlacesApiError]
    Url? bookmarks_get_url_for_keyword(string keyword);

    [Throws=PlacesApiError]
    void bookmarks_update(BookmarkUpdateInfo data);

    [Throws=PlacesApiError]
    Guid bookmarks_insert(InsertableBookmarkItem bookmark);

    /// Counts the number of bookmarks in the bookmark tree under the specified GUID. Does not count
    /// the passed item, so an empty folder will return zero, as will a non-existing GUID or the
    /// guid of a non-folder item.
    /// Counts only bookmark items - ie, sub-folders and separators are not counted.
    [Throws=PlacesApiError]
    u32 bookmarks_count_bookmarks_in_trees([ByRef] sequence<Guid> folder_guids);

    [Throws=PlacesApiError]
    HistoryMigrationResult places_history_import_from_ios(string db_path, i64 last_sync_timestamp);
};


/// Frecency threshold options for fetching top frecent sites. Requests a page that was visited
/// with a frecency score greater or equal to the value associated with the enums
enum FrecencyThresholdOption {
   /// Returns all visited pages. The frecency score is 0
  "None",
   /// Skip visited pages that were only visited once. The frecency score is 101
  "SkipOneTimePages",
};

dictionary RunMaintenanceMetrics {
    boolean pruned_visits;
    u32 db_size_before;
    u32 db_size_after;
};

dictionary SearchResult {
    Url url;
    string title;
    i64 frecency;
};

// Some kind of namespacing for uniffi would be ideal. Multiple udl/macro defns?
// Everything below is from the crate::storage::history_metadata module...

enum DocumentType {
     /// A page that isn't described by any other more specific types.
    "Regular",
    /// A media page.
    "Media",
};

// Mimics https://searchfox.org/mozilla-central/rev/57f94ca1d57ab745242daafc8926690377579b83/toolkit/components/places/nsINavHistoryService.idl#922
enum VisitType {
    /// This transition type means the user followed a link.
    "Link",
    /// This transition type means that the user typed the page's URL in the
    /// URL bar or selected it from UI (URL bar autocomplete results, etc)
    "Typed",
    "Bookmark",
    "Embed",
    "RedirectPermanent",
    "RedirectTemporary",
    "Download",
    "FramedLink",
    "Reload",
     /// Internal visit type used for meta data updates. Doesn't represent an actual page visit
    "UpdatePlace",
};

/// This is used as an "input" to the api.
dictionary HistoryMetadataObservation {
    string url;
    string? referrer_url = null;
    string? search_term = null;
    i32? view_time = null;
    DocumentType? document_type = null;
    string? title = null;
};

/// The action to take when recording a history metadata observation for
/// a page that doesn't have an entry in the history database.
enum HistoryMetadataPageMissingBehavior {
    /// Insert an entry for the page into the history database.
    "InsertPage",

    /// Ignore and discard the observation. This is the default behavior.
    "IgnoreObservation",
};

/// Options for recording history metadata observations.
dictionary NoteHistoryMetadataObservationOptions {
    HistoryMetadataPageMissingBehavior if_page_missing = "IgnoreObservation";
};

/// This is what is returned.
dictionary HistoryMetadata {
    string url;
    string? title;
    string? preview_image_url;
    i64 created_at;
    i64 updated_at;
    i32 total_view_time;
    string? search_term;
    DocumentType document_type;
    string? referrer_url;
};

dictionary HistoryHighlightWeights {
    double view_time;
    double frequency;
};

dictionary HistoryHighlight {
    double score;
    i32 place_id;
    string url;
    string? title;
    string? preview_image_url;
};

dictionary HistoryVisitInfo {
    Url url;
    string? title;
    PlacesTimestamp timestamp;
    VisitType visit_type;
    boolean is_hidden;
    Url? preview_image_url;
    boolean is_remote;
};

dictionary HistoryVisitInfosWithBound {
    sequence<HistoryVisitInfo> infos;
    i64 bound;
    i64 offset;
};

/// Encapsulates either information about a visit to a page, or meta information about the page,
/// or both. Use [VisitType.UPDATE_PLACE] to differentiate an update from a visit.
dictionary VisitObservation {
    Url url;
    string? title = null;
    VisitType? visit_type;
    boolean? is_error = null;
    boolean? is_redirect_source = null;
    boolean? is_permanent_redirect_source = null;
    PlacesTimestamp? at = null;
    Url? referrer = null;
    boolean? is_remote = null;
    Url? preview_image_url = null;
};

/// Exists just to convince uniffi to generate `liftSequence*` helpers!
dictionary Dummy {
    sequence<HistoryMetadata>? md;
};

dictionary TopFrecentSiteInfo {
    Url url;
    string? title;
};

dictionary HistoryMigrationResult {
    u32 num_total;
    u32 num_succeeded;
    u32 num_failed;
    u64 total_duration;
};


[Error]
interface PlacesApiError {
    UnexpectedPlacesException(string reason);
    UrlParseFailed(string reason);
    PlacesConnectionBusy(string reason);
    OperationInterrupted(string reason);
    UnknownBookmarkItem(string reason);
    InvalidBookmarkOperation(string reason);
};

dictionary BookmarkData {
    Guid guid;
    Guid parent_guid;
    u32 position;
    PlacesTimestamp date_added;
    PlacesTimestamp last_modified;
    Url url;
    string? title;
};

dictionary BookmarkSeparator {
    Guid guid;
    PlacesTimestamp date_added;
    PlacesTimestamp last_modified;
    Guid parent_guid;
    u32 position;
};

dictionary BookmarkFolder {
    Guid guid;
    PlacesTimestamp date_added;
    PlacesTimestamp last_modified;
    Guid? parent_guid;
    u32 position;
    string? title;
    sequence<Guid>? child_guids;
    sequence<BookmarkItem>? child_nodes;
};

[Enum]
interface BookmarkItem {
    Bookmark(BookmarkData b);
    Separator(BookmarkSeparator s);
    Folder(BookmarkFolder f);
};

dictionary BookmarkUpdateInfo {
    Guid guid;
    string? title;
    string? url;
    Guid? parent_guid;
    u32? position;
};

// Structs for inserting new bookmark items.

/// Where the item should be placed.
[Enum]
interface BookmarkPosition {
    Specific(u32 pos);
    Append();
};

dictionary InsertableBookmark {
    Guid? guid = null;
    Guid parent_guid;
    BookmarkPosition position;
    PlacesTimestamp? date_added = null;
    PlacesTimestamp? last_modified = null;
    Url url;
    string? title = null;
};

dictionary InsertableBookmarkSeparator {
    Guid? guid = null;
    Guid parent_guid;
    BookmarkPosition position;
    PlacesTimestamp? date_added = null;
    PlacesTimestamp? last_modified = null;
};

dictionary InsertableBookmarkFolder {
    Guid? guid = null;
    Guid parent_guid;
    BookmarkPosition position;
    PlacesTimestamp? date_added = null;
    PlacesTimestamp? last_modified = null;
    string? title = null;
    sequence<InsertableBookmarkItem> children;
};

[Enum]
interface InsertableBookmarkItem {
    Bookmark(InsertableBookmark b);
    Folder(InsertableBookmarkFolder f);
    Separator(InsertableBookmarkSeparator s);
};