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 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,
)