Kotlin SDK

dependencies {
    implementation("ai.vaquill:vaquill-kotlin:0.1.0")
}

./gradlew build
./gradlew publishToMavenLocal    # local check, no signing, no network upload

import ai.vaquill.sdk.VaquillClient
import ai.vaquill.sdk.resources.SearchFilters
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    // apiKey defaults to the VAQUILL_API_KEY environment variable.
    VaquillClient { maxCredits = 25.0 }.use { client ->
        println("balance: ${client.credits.balance()}")

        val hits = client.statutes.search("adverse possession", SearchFilters(state = "tx", limit = 5))
        hits.results?.forEach { println(it.actId) }

        val section = client.statutes.resolve("42 U.S.C. 1983")
        println(section)
    }
}

val client = VaquillClient {
    apiKey = "vq_key_..."                 // default: $VAQUILL_API_KEY
    baseUrl = "https://api.vaquill.ai"    // default: $VAQUILL_BASE_URL, then the production URL
    timeout = Duration.ofSeconds(30)      // per attempt, default 60 s, Duration.ZERO disables it
    maxRetries = 2                        // default 2
    defaultHeader("X-Team", "legal-ops")  // names are matched case-insensitively
    idempotencyKeys = true                // automatic Idempotency-Key on charged calls
    maxCredits = 100.0                    // client-side spend cap
    logger = VaquillLogger.system()       // default; VaquillLogger.NONE silences it
}

val r = client.withResponse { statutes.count(state = "wa") }
println(r.data.count)
println("${r.statusCode} ${r.requestId} consumed=${r.creditsConsumed} replayed=${r.idempotentReplayed}")
println(r.rateLimit.remaining)

VaquillException
  SpendGuardExceededException         client-side maxCredits reached, nothing was sent
  ResponseParseException              a 2xx body was not valid JSON or had the wrong shape
  WebhookVerificationException
    WebhookPayloadException           signature fine, body not an event
  ApiConnectionException              no HTTP response
    ApiTimeoutException
  ApiStatusException (sealed)         status, code, requestId, retryable, retryAfterSeconds, errors, body, headers
    BadRequestException               400
    AuthenticationException           401
    InsufficientCreditsException      402 or code insufficient_credits (never retried)
    PermissionDeniedException         403
    NotFoundException                 404
    ConflictException                 409
      IdempotencyInProgressException         (also IdempotencyConflict)
      IdempotencyReplayUnavailableException  (also IdempotencyConflict)
    UnprocessableEntityException      422, message appends the first errors[] reasons
      IdempotencyKeyReusedException          (also IdempotencyConflict)
    RateLimitException                429
      DailyCapExceededException              code daily_cap_exceeded (never retried)
    InternalServerException           5xx
    UnexpectedStatusException         any other 4xx or 5xx

try {
    client.statutes.getSection("TX-PEN-22.01")
} catch (e: NotFoundException) {
    println("missing (request ${e.requestId})")
} catch (e: RateLimitException) {
    println("retry in ${e.retryAfterSeconds}")
} catch (e: ApiStatusException) {
    println("${e.status} ${e.code}: ${e.message}")
}

client.statutes.search("trespass", options = RequestOptions(idempotencyKey = "order-7731-search-1"))

val p = client.statutes.iterSearch("easement", SearchFilters(state = "ca"), maxPages = 3)
p.items().collect { println(it.actId) }        // every item
p.pages().collect { page -> println(page.size) } // or page by page
println("${p.truncated} ${p.stuck}")

val event = Webhooks.unwrap(
    payload = rawBody,                       // String or ByteArray
    headers = requestHeaders,                // webhook-id, webhook-timestamp, webhook-signature
    secret = System.getenv("VAQUILL_WEBHOOK_SECRET"),
)
println("${event.event} ${event.firedAt} ${event.extra}")