/* 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/.
 */

[External="remote_settings"]
typedef extern RemoteSettingsConfig;

namespace suggest {

boolean raw_suggestion_url_matches([ByRef] string raw_url, [ByRef] string url);

};

[Error]
interface SuggestApiError {
    // An operation was interrupted by calling `SuggestStore.interrupt()`
    Interrupted();
    // The server requested a backoff after too many requests
    Backoff(u64 seconds);
    Network(string reason);
    Other(string reason);
};

enum SuggestionProvider {
    "Amp",
    "Pocket",
    "Wikipedia",
    "Amo",
    "Yelp",
    "Mdn",
    "Weather",
    "AmpMobile",
};

[Enum]
interface Suggestion {
    Amp(
        string title,
        string url,
        string raw_url,
        sequence<u8>? icon,
        string full_keyword,
        i64 block_id,
        string advertiser,
        string iab_category,
        string impression_url,
        string click_url,
        string raw_click_url,
        f64 score
    );
    Pocket(
        string title,
        string url,
        f64 score,
        boolean is_top_pick
    );
    Wikipedia(
        string title,
        string url,
        sequence<u8>? icon,
        string full_keyword
    );
    Amo(
        string title,
        string url,
        string icon_url,
        string description,
        string? rating,
        i64 number_of_ratings,
        string guid,
        f64 score
    );
    Yelp(
        string url,
        string title,
        sequence<u8>? icon,
        f64 score,
        boolean has_location_sign,
        boolean subject_exact_match,
        string location_param
    );
    Mdn(
        string title,
        string url,
        string description,
        f64 score
    );
    Weather(
        f64 score
    );
};

dictionary SuggestionQuery {
    string keyword;
    sequence<SuggestionProvider> providers;
    i32? limit = null;
};

dictionary SuggestIngestionConstraints {
    u64? max_suggestions = null;
};

dictionary SuggestGlobalConfig {
    i32 show_less_frequently_cap;
};

[Enum]
interface SuggestProviderConfig {
    Weather(
        i32 min_keyword_length
    );
};

interface SuggestStore {
    [Throws=SuggestApiError]
    constructor([ByRef] string path, optional RemoteSettingsConfig? settings_config = null);

    [Throws=SuggestApiError]
    sequence<Suggestion> query(SuggestionQuery query);

    void interrupt();

    [Throws=SuggestApiError]
    void ingest(SuggestIngestionConstraints constraints);

    [Throws=SuggestApiError]
    void clear();

    [Throws=SuggestApiError]
    SuggestGlobalConfig fetch_global_config();

    [Throws=SuggestApiError]
    SuggestProviderConfig? fetch_provider_config(SuggestionProvider provider);
};

interface SuggestStoreBuilder {
    constructor();

    [Self=ByArc]
    SuggestStoreBuilder data_path(string path);

    [Self=ByArc]
    SuggestStoreBuilder cache_path(string path);

    [Self=ByArc]
    SuggestStoreBuilder remote_settings_config(RemoteSettingsConfig config);

    [Throws=SuggestApiError]
    SuggestStore build();
};