commonMain.app.bsky.feed.searchPosts.kt Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of bluesky-jvm Show documentation
Bluesky Social API bindings for Kotlin.
The newest version!
@file:Suppress("DEPRECATION")

package app.bsky.feed

import kotlin.Any
import kotlin.Long
import kotlin.Pair
import kotlin.String
import kotlin.Suppress
import kotlinx.collections.immutable.persistentListOf
import kotlinx.collections.immutable.toImmutableList
import kotlinx.serialization.Serializable
import sh.christian.ozone.api.AtIdentifier
import sh.christian.ozone.api.Language
import sh.christian.ozone.api.Uri
import sh.christian.ozone.api.model.ReadOnlyList

/**
 * @param q Search query string; syntax, phrase, boolean, and faceting is unspecified, but Lucene
 * query syntax is recommended.
 * @param sort Specifies the ranking order of results.
 * @param since Filter results for posts after the indicated datetime (inclusive). Expected to use
 * 'sortAt' timestamp, which may not match 'createdAt'. Can be a datetime, or just an ISO date
 * (YYYY-MM-DD).
 * @param until Filter results for posts before the indicated datetime (not inclusive). Expected to
 * use 'sortAt' timestamp, which may not match 'createdAt'. Can be a datetime, or just an ISO date
 * (YYY-MM-DD).
 * @param mentions Filter to posts which mention the given account. Handles are resolved to DID
 * before query-time. Only matches rich-text facet mentions.
 * @param author Filter to posts by the given account. Handles are resolved to DID before
 * query-time.
 * @param lang Filter to posts in the given language. Expected to be based on post language field,
 * though server may override language detection.
 * @param domain Filter to posts with URLs (facet links or embeds) linking to the given domain
 * (hostname). Server may apply hostname normalization.
 * @param url Filter to posts with links (facet links or embeds) pointing to this URL. Server may
 * apply URL normalization or fuzzy matching.
 * @param tag Filter to posts with the given tag (hashtag), based on rich-text facet or tag field.
 * Do not include the hash (#) prefix. Multiple tags can be specified, with 'AND' matching.
 * @param cursor Optional pagination mechanism; may not necessarily allow scrolling through entire
 * result set.
 */
@Serializable
public data class SearchPostsQueryParams(
  /**
   * Search query string; syntax, phrase, boolean, and faceting is unspecified, but Lucene query
   * syntax is recommended.
   */
  public val q: String,
  /**
   * Specifies the ranking order of results.
   */
  public val sort: SearchPostsSort? = SearchPostsSort.Latest,
  /**
   * Filter results for posts after the indicated datetime (inclusive). Expected to use 'sortAt'
   * timestamp, which may not match 'createdAt'. Can be a datetime, or just an ISO date (YYYY-MM-DD).
   */
  public val since: String? = null,
  /**
   * Filter results for posts before the indicated datetime (not inclusive). Expected to use
   * 'sortAt' timestamp, which may not match 'createdAt'. Can be a datetime, or just an ISO date
   * (YYY-MM-DD).
   */
  public val until: String? = null,
  /**
   * Filter to posts which mention the given account. Handles are resolved to DID before query-time.
   * Only matches rich-text facet mentions.
   */
  public val mentions: AtIdentifier? = null,
  /**
   * Filter to posts by the given account. Handles are resolved to DID before query-time.
   */
  public val author: AtIdentifier? = null,
  /**
   * Filter to posts in the given language. Expected to be based on post language field, though
   * server may override language detection.
   */
  public val lang: Language? = null,
  /**
   * Filter to posts with URLs (facet links or embeds) linking to the given domain (hostname).
   * Server may apply hostname normalization.
   */
  public val domain: String? = null,
  /**
   * Filter to posts with links (facet links or embeds) pointing to this URL. Server may apply URL
   * normalization or fuzzy matching.
   */
  public val url: Uri? = null,
  /**
   * Filter to posts with the given tag (hashtag), based on rich-text facet or tag field. Do not
   * include the hash (#) prefix. Multiple tags can be specified, with 'AND' matching.
   */
  public val tag: ReadOnlyList = persistentListOf(),
  public val limit: Long? = 25,
  /**
   * Optional pagination mechanism; may not necessarily allow scrolling through entire result set.
   */
  public val cursor: String? = null,
) {
  init {
    require(tag.count() <= 640) {
      "tag.count() must be <= 640, but was ${tag.count()}"
    }
    require(limit == null || limit >= 1) {
      "limit must be >= 1, but was $limit"
    }
    require(limit == null || limit <= 100) {
      "limit must be <= 100, but was $limit"
    }
  }

  public fun asList(): ReadOnlyList> = buildList {
    add("q" to q)
    add("sort" to sort)
    add("since" to since)
    add("until" to until)
    add("mentions" to mentions)
    add("author" to author)
    add("lang" to lang)
    add("domain" to domain)
    add("url" to url)
    tag.forEach {
      add("tag" to it)
    }
    add("limit" to limit)
    add("cursor" to cursor)
  }.toImmutableList()
}

/**
 * @param hitsTotal Count of search hits. Optional, may be rounded/truncated, and may not be
 * possible to paginate through all hits.
 */
@Serializable
public data class SearchPostsResponse(
  public val cursor: String? = null,
  /**
   * Count of search hits. Optional, may be rounded/truncated, and may not be possible to paginate
   * through all hits.
   */
  public val hitsTotal: Long? = null,
  public val posts: ReadOnlyList,
)