Aduki API Reference

Aduki is the entry point of the SDK (pro.aduki.sdk.Aduki).

1. Class Signature & Properties

package pro.aduki.sdk

class Aduki internal constructor(
    val apiKey: String = "",
    val token: String = "",
    val options: Options,
    val session: Session = Session(),
    val lifecycle: Lifecycle = Lifecycle(),
    private val httpClient: OkHttpClient? = null,
    manager: Manager? = null,
    worker: Worker? = null,
    mailRepo: MailRepo? = null,
    contactRepo: ContactRepo? = null,
    appointmentRepo: AppointmentRepo? = null,
    mailboxEngine: MailboxEngine? = null,
    contactEngine: ContactEngine? = null,
    scheduleEngine: ScheduleEngine? = null,
    private val scope: CoroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.IO),
    private val dpop: Dpop? = null
)

Public Member Properties

2. Factory & Builder Methods

Aduki.Companion.login

Signs in at Aduki ID for a mail token. See Sign-in.

suspend fun Aduki.Companion.login(
    handle: String,
    password: String,
    code: String? = null,
    endpoint: String = Endpoints.REST,
    identity: String = Endpoints.ID,
    backup: String? = null,
    dpop: Key? = null
): Aduki

• Parameters:
  • handle: Full address, e.g. ada@aduki.me.
  • password: Account password.
  • code / backup: Authenticator code or backup code.
  • dpop: optional device key to bind the session to (DPoP).
  • endpoint: Mail REST base (defaults to https://mail.aduki.pro/v1).
  • identity: Aduki ID base (defaults to https://id.aduki.pro/v1).
• Return Type: Aduki — holding the access token, refresh token and session, with Identity resolved.
• Throws: AdukiException.Unauthorized on a wrong password or second factor; AdukiException.Network otherwise.

Aduki.Companion.builder

Creates a fluent Builder instance for custom client configuration.

fun Aduki.Companion.builder(): Aduki.Builder

Builder Methods

class Builder {
    fun key(key: String): Builder
    fun token(token: String): Builder
    fun endpoint(endpoint: String): Builder
    fun identity(identity: String): Builder
    fun dpop(key: Key): Builder
    fun secure(enabled: Boolean): Builder
    fun pins(vararg pins: Pin): Builder
    fun timeout(seconds: Long): Builder
    fun http(client: OkHttpClient): Builder
    fun manager(manager: Manager): Builder
    fun worker(worker: Worker): Builder
    fun mail(repo: MailRepo): Builder
    fun contacts(repo: ContactRepo): Builder
    fun scheduling(repo: AppointmentRepo, engine: ScheduleEngine? = null): Builder
    fun engines(mailbox: MailboxEngine, contact: ContactEngine): Builder
    fun build(): Aduki
}

• Validation in build(): Enforces that at least one of apiKey or token is non-blank (require(apiKey.isNotBlank() || token.isNotBlank())).

3. Session & Lifecycle Methods

me

Resolves and returns the authenticated user and tenant identity profile.

suspend fun me(): Identity?

• Return Type: Identity? — User ID hex, tenant hex, owner status, scopes, and tier. Returns cached instance from session.identity.value if already resolved; otherwise queries GET /v1/user. Scopes and tier are not part of that response and stay empty.

totp

Deprecated. Second factors are managed in Aduki ID’s Account Center; mail’s /v1/user/totp is going away.

suspend fun totp(code: String): Boolean

• Parameters: code: String — the 6-digit code.
• Return Type: Boolean — true if the server confirms it.

refresh

Renews the access token at Aduki ID (POST /v1/tokens) ahead of time. The SDK also does this by itself on a 401.

suspend fun refresh(): Boolean

• Return Type: Boolean — true if tokens were successfully rotated and updated in session state.

logout

Terminates the session remotely and wipes local credentials.

suspend fun logout(): Boolean

• Return Type: Boolean — true if Aduki ID revoked the session (DELETE /v1/sessions/{hex}); the local session is then cleared. When revocation fails the session is kept with the rotated refresh token so logout() can be retried (or call session.clear()). Also stops watchRights.

rights, watchRights, unwatchRights

Renew the access token on a rights push, or subscribe to the mail event stream that sends them. See Token lifecycle.

suspend fun rights(payload: String): Boolean
fun watchRights(host: String = <REST endpoint without /v1>)
fun unwatchRights()

pause

Notifies the SDK that the host application entered the background (see Lifecycle).

fun pause()

resume

Notifies the SDK that the host application entered the foreground and flushes pending outbox mutations.

fun resume()

4. Complete Sub-Services Index

client.mail (Mail)

• suspend fun send(to: List<String>, subject: String, body: String, mailbox: String = "outbox"): Message
• suspend fun flag(hex: String, flag: Int)
• suspend fun move(hex: String, dest: String)
• suspend fun remove(hex: String)
• fun observe(mailboxHex: String): StateFlow<List<Message>>?
• fun mailboxes(): StateFlow<List<Mailbox>>?
• fun unread(mailboxHex: String): StateFlow<Int>?

client.contacts (Contacts)

• suspend fun sync(tenant: String = ""): Boolean
• fun observe(): StateFlow<List<Contact>>?
• fun search(query: String): StateFlow<List<Contact>>?
• fun get(hex: String): Contact?

client.sync (Sync)

• suspend fun all(mailboxes: List<String> = listOf("inbox")): Boolean
• suspend fun flush(): Int
• fun pending(): Int