[Custom]
typedef string TabsGuid;

// a local timestamp, a custom type to avoid using the int directly.
[Custom]
typedef i64 Timestamp;

// exported via proc-macros
typedef dictionary ClientRemoteTabs;
typedef dictionary RemoteTabRecord;
typedef dictionary LocalTabsInfo;

namespace tabs {

};

[Error]
interface TabsApiError {
    SyncError(string reason);
    SqlError(string reason);
    UnexpectedTabsError(string reason);
};


interface TabsStore {
    constructor(string path);

    void close_connection();

    sequence<ClientRemoteTabs> get_all();

    /// An API for clients which know nothing about windows or tab groups.
    void set_local_tabs(sequence<RemoteTabRecord> remote_tabs);

    /// More context-aware API for setting information about a tab like window and groups.
    void set_local_tabs_info(LocalTabsInfo info);

    [Self=ByArc]
    RemoteCommandStore new_remote_command_store();

    [Self=ByArc]
    void register_with_sync_manager();

    [Self=ByArc]
    TabsBridgedEngine bridged_engine();

};

/// A command which should be sent to a remote device.
[Enum]
interface RemoteCommand {
    CloseTab(string url);
    // CloseInactive(); ??
};

interface RemoteCommandStore {
    /// Add a new command, after which it will be pending. Returns false if the command is already active.
    [Throws=TabsApiError]
    boolean add_remote_command([ByRef] string device_id, [ByRef] RemoteCommand command);

    /// Add a new command with an explicit timestamp. Primarily used by tests.
    [Throws=TabsApiError]
    boolean add_remote_command_at([ByRef] string device_id, [ByRef] RemoteCommand command, Timestamp when);

    /// Removes the remote command. Typically used to implement "undo" but may also be used by the queue
    /// processor when it gives up trying to send a command.
    [Throws=TabsApiError]
    boolean remove_remote_command([ByRef] string device_id, [ByRef] RemoteCommand command);

    /// Return all unsent commands. This is for the code sending the commands, result is sorted by time_requested.
    [Throws=TabsApiError]
    sequence<PendingCommand> get_unsent_commands();

    /// Flag a command as sent.
    [Throws=TabsApiError]
    boolean set_pending_command_sent([ByRef]PendingCommand command);
};

/// Represents a "pending" command.
dictionary PendingCommand {
    string device_id;
    RemoteCommand command;
    Timestamp time_requested;
    Timestamp? time_sent;
};

/// Note the canonical docs for this are in https://searchfox.org/mozilla-central/source/services/interfaces/mozIBridgedSyncEngine.idl
/// It's only actually used in desktop, but it's fine to expose this everywhere.
/// NOTE: all timestamps here are milliseconds.
interface TabsBridgedEngine {
    // readonly attribute long storageVersion;
    // readonly attribute boolean allowSkippedRecord;

    // XXX - better logging story than this?
    // attribute mozIServicesLogSink logger;

    [Throws=TabsApiError]
    i64 last_sync();

    [Throws=TabsApiError]
    void set_last_sync(i64 last_sync);

    [Throws=TabsApiError]
    string? sync_id();

    [Throws=TabsApiError]
    string reset_sync_id();

    [Throws=TabsApiError]
    string ensure_current_sync_id([ByRef]string new_sync_id);

    [Throws=TabsApiError]
    void prepare_for_sync([ByRef]string client_data);

    [Throws=TabsApiError]
    void sync_started();

    [Throws=TabsApiError]
    void store_incoming(sequence<string> incoming_envelopes_as_json);

    [Throws=TabsApiError]
    sequence<string> apply();

    [Throws=TabsApiError]
    void set_uploaded(i64 new_timestamp, sequence<TabsGuid> uploaded_ids);

    [Throws=TabsApiError]
    void sync_finished();

    [Throws=TabsApiError]
    void reset();

    [Throws=TabsApiError]
    void wipe();
};