(ns crux.api)

  (db
    [node]
    [node ^Date valid-time]
    [node ^Date valid-time ^Date transaction-time]
    "When a valid time is specified then returned db value contains only those
     documents whose valid time is before the specified time.

     When both valid and transaction time are specified returns a db value as of
     the valid time and the latest transaction time indexed at or before the
     specified transaction time.

     If the node hasn't yet indexed a transaction at or past the given
     transaction-time, this throws NodeOutOfSyncException")

  (open-db
    [node]
    [node ^Date valid-time]
    [node ^Date valid-time ^Date transaction-time]
    "When a valid time is specified then returned db value contains only those
     documents whose valid time is before the specified time.

     When both valid and transaction time are specified returns a db value as of
     the valid time and the latest transaction time indexed at or before the
     specified transaction time.

     If the node hasn't yet indexed a transaction at or past the given
     transaction-time, this throws NodeOutOfSyncException

     This DB opens up shared resources to make multiple requests faster - it must
     be `.close`d when you've finished using it (for example, in a `with-open`
     block)")

  (status [node]
    "Returns the status of this node as a map.")

  (submit-tx [node tx-ops]
    "Writes transactions to the log for processing
     tx-ops datalog style transactions.
     Returns a map with details about the submitted transaction,
     including tx-time and tx-id.")

  (tx-committed? [node submitted-tx]
    "Checks if a submitted tx was successfully committed.
     submitted-tx must be a map returned from `submit-tx`.
     Returns true if the submitted transaction was committed,
     false if the transaction was not committed, and throws `NodeOutOfSyncException`
     if the node has not yet indexed the transaction.")

  (await-tx
    [node tx]
    [node tx ^Duration timeout]
    "Blocks until the node has indexed a transaction that is at or past the
  supplied tx. Will throw on timeout. Returns the most recent tx indexed by the
  node.")

  (await-tx-time
    [node ^Date tx-time]
    [node ^Date tx-time ^Duration timeout]
    "Blocks until the node has indexed a transaction that is past the supplied
  txTime. Will throw on timeout. The returned date is the latest index time when
  this node has caught up as of this call.")

 (sync
    [node]
    [node ^Duration timeout]
    "Blocks until the node has caught up indexing to the latest tx available at
  the time this method is called. Will throw an exception on timeout. The
  returned date is the latest transaction time indexed by this node. This can be
  used as the second parameter in (db valid-time, transaction-time) for
  consistent reads.

  timeout – max time to wait, can be nil for the default.
  Returns the latest known transaction time.")

  (listen ^java.lang.AutoCloseable [node event-opts f]
    "Attaches a listener to Crux's event bus.

  `event-opts` should contain `:crux/event-type`, along with any other options the event-type requires.

  We currently only support one public event-type: `:crux/indexed-tx`.
  Supplying `:with-tx-ops? true` will include the transaction's operations in the event passed to `f`.

  `(.close ...)` the return value to detach the listener.

  This is an experimental API, subject to change.")

(open-tx-log ^ICursor [this after-tx-id with-ops?]
  "Reads the transaction log. Optionally includes
  operations, which allow the contents under the :crux.api/tx-ops
  key to be piped into (submit-tx tx-ops) of another
  Crux instance.
  after-tx-id      optional transaction id to start after.
  with-ops?        should the operations with documents be included?
  Returns a cursor over the TxLog.")

  (attribute-stats [node]
    "Returns frequencies of indexed attributes")

  (active-queries [node]
    "Returns a list of currently running queries")

  (recent-queries [node]
    "Returns a list of recently completed/failed queries")

  (slowest-queries [node]
    "Returns a list of slowest completed/failed queries ran on the node")

  (entity [db eid]
    "queries a document map for an entity.
    eid is an object which can be coerced into an entity id.
    returns the entity document map.")

  (entity-tx [db eid]
    "returns the transaction details for an entity. Details
    include tx-id and tx-time.
    eid is an object that can be coerced into an entity id.")

  (q
    [db query]
    "q[uery] a Crux db.

     This function will return a set of result tuples if you do not specify `:order-by`, `:limit` or `:offset`;
     otherwise, it will return a vector of result tuples.)

  (open-q
    [db query]
    "lazily q[uery] a Crux db.
     query param is a datalog query in map, vector or string form.

     This function returns a Cursor of result tuples - once you've consumed
     as much of the sequence as you need to, you'll need to `.close` the sequence.
     A common way to do this is using `with-open`:

     (with-open [res (crux/open-q db '{:find [...]
                                       :where [...]})]
       (doseq [row (iterator-seq res)]
         ...))

     Once the sequence is closed, attempting to iterate it is undefined.
     ")

  (entity-history
    [db eid sort-order]
    [db eid sort-order {:keys [with-docs? with-corrections?]
                        {start-vt :crux.db/valid-time, start-tt :crux.tx/tx-time} :start
                        {end-vt :crux.db/valid-time, end-tt :crux.tx/tx-time} :end}]
    "Eagerly retrieves entity history for the given entity.

    Options:
    * `sort-order`: `#{:asc :desc}`
    * `:with-docs?`: specifies whether to include documents in the entries
    * `:with-corrections?`: specifies whether to include bitemporal corrections in the sequence, sorted first by valid-time, then transaction-time.
    * `:start` (nested map, inclusive, optional): the `:crux.db/valid-time` and `:crux.tx/tx-time` to start at.
    * `:end` (nested map, exclusive, optional): the `:crux.db/valid-time` and `:crux.tx/tx-time` to stop at.

    No matter what `:start` and `:end` parameters you specify, you won't receive
    results later than the valid-time and transact-time of this DB value.

    Each entry in the result contains the following keys:
     * `:crux.db/valid-time`,
     * `:crux.db/tx-time`,
     * `:crux.tx/tx-id`,
     * `:crux.db/content-hash`
     * `:crux.db/doc` (see `with-docs?`).")

  (open-entity-history
    [db eid sort-order]
    [db eid sort-order {:keys [with-docs? with-corrections?]
                        {start-vt :crux.db/valid-time, start-tt :crux.tx/tx-time} :start
                        {end-vt :crux.db/valid-time, end-tt :crux.tx/tx-time} :end}]
    "Lazily retrieves entity history for the given entity.
    Don't forget to close the cursor when you've consumed enough history!
    See `entity-history` for all the options")

  (valid-time [db]
    "returns the valid time of the db.
    If valid time wasn't specified at the moment of the db value retrieval
    then valid time will be time of the latest transaction.")

  (transaction-time [db]
    "returns the time of the latest transaction applied to this db value.
    If a tx time was specified when db value was acquired then returns
    the specified time."))

(defn start-node ^ICruxAPI [options])

(defn new-api-client ^ICruxAPI [url])

(defn new-ingest-client ^ICruxAsyncIngestAPI [options])