connekt-script-writer skill by amplicode

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.

// ✅ CORRECT — pass result via pathParam
val petId by POST("$host/api/pets") {
    contentType("application/json"

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

Script Structure

A .connekt.kts file follows this conventional ordering:

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 — inside the block, this is the OkHttp Response
val result by GET(...) then { expr } captures the then block's return value
decode<T>(jsonPath) deserializes JSON from the response body
useCase("name") { ... } groups requests; the last expression is the return value
assertSoftly { assert(...) } collects all assertion failures before reporting
No code between requests — assertions and logic go inside then or useCase only
Pass request results via pathParam, never interpolate them into the URL string

DSL Reference

HTTP Methods

Each method accepts an optional name parameter and a configuration lambda:

Request Configuration

Headers:

Query parameters:

Path parameters (use {name} placeholders in the URL):

Request options:

Request Bodies

JSON body:

Form data (Content-Type is set automatically):

Multipart:

Byte array:

Authentication

Basic and Bearer:

OAuth2 (authorization code flow):

OAuth2 opens a browser for login and starts a local callback server automatically. The auth object provides accessToken and refreshToken.

Keycloak shorthand:

Response Handling

Inside a then block, this is the OkHttp Response — you have code, body, header("Name"), etc.

Validate and extract:

Typed deserialization with decode<T>():

Raw JSONPath access:

Chaining requests — pass results from one request to the next via pathParam:

Use Cases

Когда использовать useCase

useCase применяется только если сценарий включает несколько запросов с передачей результата между ними (например, создать ресурс, затем проверить его существование).
Один HTTP-запрос (даже с then-блоком) никогда не оборачивается в useCase.
Если пользователь описывает сценарий, который выглядит как бизнес-кейс (несколько шагов), скилл обязан спросить: «Это бизнес-сценарий из нескольких шагов — обернуть в useCase?» — и ждать ответа перед генерацией кода.

Single HTTP request — standalone with then, never wrapped in useCase:

Group multiple related requests with useCase. The last expression is the return value.

Anonymous use cases (no name) work the same way:

Environment Variables

Read from connekt.env.json using property delegation. The property name is the lookup key:

The connekt.env.json file:

Supported types: String, Int, Long, Double, Boolean. Missing keys throw an error.

Assertions

Kotlin assert (with Power Assert diagnostics when --kotlin-power-assert is used):

AssertJ (requires import, deprecated, do not use in new scripts):

Soft assertions — collect all failures before reporting:

Script Imports and Dependencies

Import another script (paths relative to the importing script):

Imported top-level declarations (vals, functions, classes) become available. Transitive imports work.

External Maven dependencies:

SSL/TLS and Client Configuration

Common Patterns

Simple GET with assertions

POST with JSON body and response extraction

CRUD workflow

OAuth2 authenticated requests

File upload (multipart)

Paginated loop

Multi-script reuse with @file:Import

auth_setup.connekt.kts (shared):

api_tests.connekt.kts (imports the above):

Soft assertion response validation

Important Notes

По умолчанию генерируй одиночный запрос — без useCase. useCase оправдан только когда сценарий явно содержит несколько шагов с передачей данных между запросами. Один запрос (с then или без) никогда не оборачивается в useCase. Это правило имеет наивысший приоритет.
The script registers requests — it does not execute them imperatively. No code between requests at the top level. Assertions and logic belong inside then or useCase blocks only.
Never interpolate request results into URLs ("$host/api/pets/$petId") — always use pathParam("petId", petId) with a {petId} placeholder in the URL.
Top-level extension functions on RequestBuilder are fine for reusable request configuration (shared headers, auth, etc.).
Never use deprecated functions: vars, variable<T>(), doRead(), readString(), readInt(), readLong(), readBoolean(). Use decode<T>() for all response extraction.
Cookies are managed automatically in a session jar — no manual cookie handling needed unless you use noCookies().
By default, OkHttp follows 3xx redirects. Use noRedirect() to inspect redirect responses.
insecure() disables all SSL verification — use only for local development.