Connekt Script Writer

# Connekt Script Writer

Connekt is an HTTP client driven by Kotlin scripts. Scripts use the `.connekt.kts` extension and have the full Connekt DSL available at the top level — no boilerplate, no main function, just declarations and requests.

When generating scripts, always read from `connekt.env.json` for base URLs and secrets using `val x: String by env` rather than hardcoding values. Save scripts with the `.connekt.kts` extension.

## Execution Model

**A script only registers requests — the runner decides which request to execute.** The script is NOT run top-to-bottom like a regular program. This means:

- **No imperative code between requests.** No `println`, no `if/else`, no variable assignments outside of `then` or `useCase` blocks.
- **Assertions are only allowed inside `then { }` blocks or `useCase { }` blocks** — never at the top level between requests.
- **Never interpolate results from other requests directly into a URL.** Use `pathParam` instead, so the runner can resolve values at execution time.
- **Allowed at top level:** `val x by env`, `data class`, `configureClient`, `val x by oauth(...)`, extension functions (e.g. on `RequestBuilder` for shared headers), request declarations (`val x by GET/POST/...`), and `useCase` blocks.

```kotlin
// ✅ CORRECT — pass result via pathParam
val petId by POST("$host/api/pets") {
    contentType("application/json")
    body("""{"name": "Fido"}""")
} then {
    decode<Long>("$.id")
}

GET("$host/api/pets/{petId}") {
    pathParam("petId", petId)
} then {
    assert(code == 200)
}

// ❌ WRONG — never interpolate request results in URL
GET("$host/api/pets/$petId") then {
    assert(code == 200)
}
```

**Extension functions** on `RequestBuilder` are a good way to apply shared configuration:

```kotlin
fun RequestBuilder.withApiKey() {
    header("X-Api-Key", apiKey)
    header("X-Request-Id", java.util.UUID.randomUUID().toString())
}

GET("$host/api/pets") {
    withApiKey()
}
```

## Script Structure

A `.connekt.kts` file follows this conventional ordering:

```kotlin
// 1. File-level annotations (imports, dependencies)
@file:Import("shared_auth.connekt.kts")
@file:DependsOn("com.example:my-lib:1.0")

// 2. Third-party imports (if needed)
import org.assertj.core.api.Assertions.assertThat

// 3. Environment variables from connekt.env.json
val host: String by env
val apiKey: String by env

// 4. Data classes for typed deserialization
data class Pet(val id: Long, val name: String, val status: String)

// 5. Global client configuration
configureClient {
    insecure()  // for local dev only
}

// 6. OAuth setup (if needed)
val auth by oauth(
    authorizeEndpoint = "...",
    clientId = "...",
    clientSecret = "...",
    scope = "openid",
    tokenEndpoint = "...",
    redirectUri = "http://localhost:8080/callback"
)

// 7. HTTP requests
val pets by GET("$host/api/pets") then {
    decode<List<Pet>>("$.content")
}

// 8. Use cases for grouping related requests
val result by useCase("Create and verify") {
    val created by POST("$host/api/pets") {
        contentType("application/json")
        body("""{"name": "Fido"}""")
    } then {
        decode<Pet>()
    }
    created
}
```

Key conventions:
- `val x by env` reads from `connekt.env.json` — the property name is the lookup key
- `val response by GET(...)` delegates execution and binds the result
- `then { ... }` chains response handling