runtime/io.github.kikin81.atproto.runtime

Package-level declarations

Core runtime primitives: value classes, AtField, open-union base types, XrpcClient, auth provider interface, pagination Flow builders, and record encode/decode helpers. Everything here is hand-written — this is the stable, non-generated surface the SDK builds on.

Types

AtField

sealed interface AtField<out T>

Three-state optional field for AT Protocol mutation payloads.

AtFieldSerializer

class AtFieldSerializer<T : Any>(inner: KSerializer<T>) : KSerializer<AtField<T>>

AtIdentifier

@JvmInline

@Serializable

value class AtIdentifier(val raw: String)

A Did or a Handle. Format: at-identifier.

AtUri

@JvmInline

@Serializable

value class AtUri(val raw: String)

An AT Protocol URI (e.g. at://did:plc:abc/app.bsky.feed.post/tid). Format: at-uri.

AtUriParts

data class AtUriParts(val repo: AtIdentifier, val collection: Nsid?, val rkey: RecordKey?, val fragment: String?)

The structural decomposition of an AtUri into its constituent parts.

AuthProvider

interface AuthProvider

Supplies authentication headers for XRPC requests. Attached at client construction or per-call via XrpcClient.query / XrpcClient.procedure overrides.

BearerTokenAuth

class BearerTokenAuth(token: String) : AuthProvider

Fixed bearer token. Suitable for app-password sessions or service tokens.

Blob

@Serializable

data class Blob(val ref: CidLink, val mimeType: String, val size: Long, val type: String = "blob")

A reference to an uploaded blob as embedded in a record body.

Cid

@JvmInline

@Serializable

value class Cid(val raw: String)

A content identifier (IPLD CID). Format: cid.

CidLink

@Serializable

data class CidLink(val link: String)

A CID link as encoded by the AT Protocol data model.

Datetime

@JvmInline

@Serializable

value class Datetime(val raw: String)

An RFC3339 datetime with required timezone. Format: datetime.

Did

@JvmInline

@Serializable

value class Did(val raw: String)

A decentralized identifier (e.g. did:plc:abc123). Format: did.

Handle

@JvmInline

@Serializable

value class Handle(val raw: String)

A user-facing handle (e.g. alice.bsky.social). Format: handle.

Language

@JvmInline

@Serializable

value class Language(val raw: String)

A BCP-47 language tag. Format: language.

NoAuth

object NoAuth : AuthProvider

No authentication — requests are sent without auth headers.

NoXrpcParams

@Serializable

data object NoXrpcParams

Sentinel "no query-string parameters" value for XRPC calls that take no URL parameters (e.g. procedures with a JSON input body and nothing else, or queries with no filters). Emitted by the generator's service classes wherever a params argument is required by the XrpcClient API but the underlying lexicon def declares no parameters.

Nsid

@JvmInline

@Serializable

value class Nsid(val raw: String)

A namespaced identifier (e.g. app.bsky.feed.post). Format: nsid.

OpenUnionMember

interface OpenUnionMember

Marker interface implemented by every member of a generated sealed-interface union. Gives the runtime a common upper bound to target and lets consumers write helpers generic over any union-typed value.

OpenUnionSerializer

abstract class OpenUnionSerializer<T : OpenUnionMember>(baseClass: KClass<T>) : KSerializer<T>

Base serializer for generator-emitted open unions.

RecordKey

@JvmInline

@Serializable

value class RecordKey(val raw: String)

A record key component of an AT URI. Format: record-key.

Tid

@JvmInline

@Serializable

value class Tid(val raw: String)

A timestamp identifier used as a record key. Format: tid.

UnknownMemberSerializer

abstract class UnknownMemberSerializer<T : UnknownOpenUnionMember>(serialName: String) : KSerializer<T>

Base serializer for a generator-emitted Unknown variant.

UnknownOpenUnionMember

interface UnknownOpenUnionMember : OpenUnionMember

Sub-interface implemented by the generator-emitted Unknown variant of each sealed union. Carries the original $type string and the full raw JSON object so that re-serialization is lossless.

Uri

@JvmInline

@Serializable

value class Uri(val raw: String)

A generic URI. Format: uri.

XrpcClient

class XrpcClient(baseUrl: String, val httpClient: HttpClient, val json: Json = DefaultJson, val authProvider: AuthProvider = NoAuth)

Ktor-backed XRPC client. Wraps a caller-supplied HttpClient so consumers control the engine, timeouts, retries, and logging. Generated XRPC bindings call query for GET /xrpc/<nsid> and procedure for POST /xrpc/<nsid>.

XrpcError

open class XrpcError(val errorName: String, val errorMessage: String?, val status: Int) : RuntimeException

Base type for all errors surfaced by XrpcClient. Generated XRPC bindings extend this with typed subclasses for each declared error name; unknown error names fall through to Unknown.

XrpcErrorMapper

fun interface XrpcErrorMapper

Maps a decoded {error, message} body onto a typed XrpcError. Generated per-endpoint code supplies a mapper that pattern-matches on name; any unmapped name SHOULD be returned as XrpcError.Unknown.

Properties

DefaultXrpcErrorMapper

val DefaultXrpcErrorMapper: XrpcErrorMapper

Default mapper that always returns XrpcError.Unknown.

DOLLAR_TYPE

const val DOLLAR_TYPE: String

The $type key used throughout AT Protocol JSON payloads.

UnitResponseSerializer

val UnitResponseSerializer: KSerializer<Unit>

Stable KSerializer reference for procedures and queries whose output.schema is absent. The generator's service classes use this as the responseSerializer argument when a method's return type is Unit so callers don't have to construct one themselves.

Functions

decodeRecord

inline fun <T> JsonObject.decodeRecord(json: Json = recordDecoderJson): T

fun <T> JsonObject.decodeRecord(serializer: KSerializer<T>, json: Json = recordDecoderJson): T

encodeRecord

inline fun <T> encodeRecord(record: T, type: String, json: Json = recordEncoderJson): JsonObject

fun <T> encodeRecord(serializer: KSerializer<T>, record: T, type: String, json: Json = recordEncoderJson): JsonObject

normalizeDollarType

fun normalizeDollarType(type: String): String

Normalize a $type discriminator value for equality matching.

paginate

fun <R, T> paginate(fetch: suspend (cursor: String?) -> R, getCursor: (R) -> String?, getItems: (R) -> List<T>): Flow<T>

paginatePages

fun <R, T> paginatePages(fetch: suspend (cursor: String?) -> R, getCursor: (R) -> String?, getItems: (R) -> List<T>): Flow<List<T>>

parse

fun AtUri.parse(): AtUriParts

Parses this AtUri into its AtUriParts.

parseOrNull

fun AtUri.parseOrNull(): AtUriParts?

Like parse, but returns null instead of throwing on structural failure.

present

inline fun <T : Any> present(value: T): AtField.Defined<T>

Wraps value as AtField.Defined. Reads like natural English at call sites:

presentOrNull

inline fun <T : Any> presentOrNull(value: T?): AtField<T>

Converts a nullable value into an AtField: non-null → AtField.Defined, null → AtField.Null (an explicit clear, not "leave unchanged").

toInstant

fun Datetime.toInstant(): Instant

Parse this AT Protocol Datetime as a kotlinx.datetime.Instant.

toInstantOrNull

fun Datetime.toInstantOrNull(): Instant?

Parse this AT Protocol Datetime as a kotlinx.datetime.Instant, returning null on malformed input instead of throwing.