ORM Query Check API

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="YOUR_TOKEN"

# api METHOD PATH [JSON_BODY] [extra curl args...]
# Prints the envelope: {"data": ...} on 2xx, {"error": {"code", "message", "details"}} otherwise.
api() {
  local method="$1" path="$2" body="${3-}"
  shift 2
  [ $# -gt 0 ] && shift
  if [ -n "$body" ]; then
    curl -sS -X "$method" "$BASE$path" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary "$body" "$@"
  else
    curl -sS -X "$method" "$BASE$path" \
      -H "Authorization: Bearer $TOKEN" "$@"
  fi
}

import json
import requests

BASE = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN"


class ApiError(Exception):
    def __init__(self, status, code, message, details):
        super().__init__(f"{status} {code}: {message}")
        self.status, self.code, self.details = status, code, details


def call(method, path, body=None, headers=None, auth=True):
    """Send body as JSON; return the envelope's "data", raise ApiError on non-2xx."""
    h = {"Content-Type": "application/json"}
    if auth and TOKEN:
        h["Authorization"] = "Bearer " + TOKEN
    h.update(headers or {})
    r = requests.request(method, BASE + path, headers=h,
                         data=None if body is None else json.dumps(body), timeout=300)
    try:
        env = r.json()
    except ValueError:
        env = {}
    if not r.ok:
        err = env.get("error") or {}
        raise ApiError(r.status_code, err.get("code"), err.get("message") or r.reason, err.get("details"))
    return env.get("data")

// Node 20+ (run as an ES module, e.g. api.mjs) or a browser console.
const BASE = "https://api.skillsafe.ai/v1/app-api";
const TOKEN = "YOUR_TOKEN";
let token = TOKEN;

async function call(method, path, body, extraHeaders = {}, auth = true) {
  const headers = { "Content-Type": "application/json", ...extraHeaders };
  if (auth && token) headers["Authorization"] = "Bearer " + token;
  const res = await fetch(BASE + path, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const env = await res.json().catch(() => ({}));
  if (!res.ok) {
    const err = new Error((env.error && env.error.message) || res.statusText);
    err.status = res.status;
    err.code = env.error && env.error.code;
    err.details = env.error && env.error.details;
    throw err;
  }
  return env.data;
}

// main.go - the imports cover every step on this page; steps 2-4 go in main,
// steps 5 and 6 add package-level functions.
package main

import (
	"bufio"
	"bytes"
	"crypto/sha256"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"strings"
	"time"
)

const base = "https://api.skillsafe.ai/v1/app-api"

var token = os.Getenv("SKILLSAFE_TOKEN") // or "YOUR_TOKEN"

var client = &http.Client{Timeout: 5 * time.Minute}

type APIError struct {
	Status  int             `json:"-"`
	Code    string          `json:"code"`
	Message string          `json:"message"`
	Details json.RawMessage `json:"details"`
}

func (e *APIError) Error() string { return fmt.Sprintf("%d %s: %s", e.Status, e.Code, e.Message) }

// call sends body as JSON and decodes the envelope's "data" into out.
func call(method, path string, body any, headers map[string]string, out any) error {
	var rdr io.Reader
	if body != nil {
		b, err := json.Marshal(body)
		if err != nil {
			return err
		}
		rdr = bytes.NewReader(b)
	}
	req, err := http.NewRequest(method, base+path, rdr)
	if err != nil {
		return err
	}
	req.Header.Set("Content-Type", "application/json")
	if token != "" {
		req.Header.Set("Authorization", "Bearer "+token)
	}
	for k, v := range headers {
		req.Header.Set(k, v)
	}
	resp, err := client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	var env struct {
		Data  json.RawMessage `json:"data"`
		Error *APIError       `json:"error"`
	}
	_ = json.NewDecoder(resp.Body).Decode(&env)
	if resp.StatusCode < 200 || resp.StatusCode > 299 {
		e := env.Error
		if e == nil {
			e = &APIError{Message: resp.Status}
		}
		e.Status = resp.StatusCode
		return e
	}
	if out != nil && len(env.Data) > 0 {
		return json.Unmarshal(env.Data, out)
	}
	return nil
}

func main() {
	// steps 2-4 go here
}

// Api.java - Java 17+, java.net.http plus Jackson (com.fasterxml.jackson.core:jackson-databind).
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Duration;
import java.util.HexFormat;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.stream.Collectors;
import java.util.stream.Stream;

public class Api {
    static final String BASE = "https://api.skillsafe.ai/v1/app-api";
    static String token = "YOUR_TOKEN";
    static final ObjectMapper JSON = new ObjectMapper();
    static final HttpClient HTTP = HttpClient.newHttpClient();

    static class ApiException extends RuntimeException {
        final int status;
        final String code;
        final JsonNode details;

        ApiException(int status, String code, String message, JsonNode details) {
            super(status + " " + code + ": " + message);
            this.status = status;
            this.code = code;
            this.details = details;
        }
    }

    static HttpRequest.Builder request(String method, String path, Object body, Map<String, String> headers) throws Exception {
        HttpRequest.BodyPublisher pub = body == null
            ? HttpRequest.BodyPublishers.noBody()
            : HttpRequest.BodyPublishers.ofString(JSON.writeValueAsString(body));
        HttpRequest.Builder b = HttpRequest.newBuilder(URI.create(BASE + path))
            .timeout(Duration.ofMinutes(5))
            .header("Content-Type", "application/json")
            .method(method, pub);
        if (token != null && !token.isEmpty()) b.header("Authorization", "Bearer " + token);
        if (headers != null) headers.forEach(b::header);
        return b;
    }

    static ApiException apiError(int status, JsonNode env) {
        JsonNode err = env == null ? JSON.createObjectNode() : env.path("error");
        return new ApiException(status, err.path("code").asText(null),
            err.path("message").asText("HTTP " + status), err.get("details"));
    }

    /** Send body as JSON; return the envelope's "data", throw ApiException on non-2xx. */
    static JsonNode call(String method, String path, Object body, Map<String, String> headers) throws Exception {
        HttpResponse<String> res = HTTP.send(request(method, path, body, headers).build(),
            HttpResponse.BodyHandlers.ofString());
        JsonNode env;
        try { env = JSON.readTree(res.body()); } catch (Exception e) { env = null; }
        if (res.statusCode() < 200 || res.statusCode() > 299) throw apiError(res.statusCode(), env);
        return env == null ? JSON.missingNode() : env.path("data");
    }

    public static void main(String[] args) throws Exception {
        // the statements of steps 2-6 go here; steps 5 and 6 also add static methods to this class
    }
}

require "json"
require "net/http"
require "uri"

BASE = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN"
$token = TOKEN

class ApiError < StandardError
  attr_reader :status, :code, :details

  def initialize(status, code, message, details)
    super("#{status} #{code}: #{message}")
    @status, @code, @details = status, code, details
  end
end

def build_request(method, path, body = nil, headers = {}, auth = true)
  uri = URI(BASE + path)
  req = Net::HTTP.const_get(method.capitalize).new(uri)
  req["Content-Type"] = "application/json"
  req["Authorization"] = "Bearer #{$token}" if auth && !$token.to_s.empty?
  headers.each { |k, v| req[k] = v }
  req.body = JSON.generate(body) unless body.nil?
  [uri, req]
end

# Send body as JSON; return the envelope's "data", raise ApiError on non-2xx.
def call(method, path, body = nil, headers = {}, auth = true)
  uri, req = build_request(method, path, body, headers, auth)
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 300) { |h| h.request(req) }
  env = (JSON.parse(res.body.to_s) rescue {})
  unless res.is_a?(Net::HTTPSuccess)
    err = env["error"] || {}
    raise ApiError.new(res.code.to_i, err["code"], err["message"] || res.message, err["details"])
  end
  env["data"]
end

<?php
// PHP 8.1+ with the curl extension.
const BASE = "https://api.skillsafe.ai/v1/app-api";
$token = "YOUR_TOKEN";

class ApiError extends Exception {
    public function __construct(public int $status, public ?string $errCode, string $message, public mixed $details) {
        parent::__construct("$status $errCode: $message");
    }
}

function apiError(int $status, array $env): ApiError {
    $e = $env["error"] ?? [];
    return new ApiError($status, $e["code"] ?? null, $e["message"] ?? "HTTP $status", $e["details"] ?? null);
}

/** Send $body as JSON; return the envelope's "data", throw ApiError on non-2xx. */
function call(string $method, string $path, mixed $body = null, array $headers = [], bool $auth = true): mixed {
    global $token;
    $h = ["Content-Type: application/json"];
    if ($auth && $token !== "") $h[] = "Authorization: Bearer $token";
    foreach ($headers as $k => $v) $h[] = "$k: $v";
    $ch = curl_init(BASE . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => $h,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 300,
    ]);
    if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_UNESCAPED_SLASHES));
    $raw = curl_exec($ch);
    if ($raw === false) throw new RuntimeException(curl_error($ch));
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $env = json_decode($raw, true) ?: [];
    if ($status < 200 || $status > 299) throw apiError($status, $env);
    return $env["data"] ?? null;
}

// Program.cs - .NET 8, top-level statements. Steps 2-6 continue below the helper;
// keep the ApiException class at the very end of the file.
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;

const string Base = "https://api.skillsafe.ai/v1/app-api";
var token = "YOUR_TOKEN";
var http = new HttpClient { Timeout = TimeSpan.FromMinutes(5) };

HttpRequestMessage Build(HttpMethod method, string path, JsonNode? body,
    Dictionary<string, string>? headers = null, bool auth = true)
{
    var req = new HttpRequestMessage(method, Base + path);
    if (auth && token != "") req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
    if (headers != null) foreach (var (k, v) in headers) req.Headers.TryAddWithoutValidation(k, v);
    if (body != null) req.Content = new StringContent(body.ToJsonString(), Encoding.UTF8, "application/json");
    return req;
}

ApiException ApiErr(int status, JsonNode? env, string? reason) =>
    new(status, env?["error"]?["code"]?.GetValue<string>(),
        env?["error"]?["message"]?.GetValue<string>() ?? reason ?? "", env?["error"]?["details"]);

// Send body as JSON; return the envelope's "data", throw ApiException on non-2xx.
async Task<JsonNode?> Call(HttpMethod method, string path, JsonNode? body = null,
    Dictionary<string, string>? headers = null, bool auth = true)
{
    using var res = await http.SendAsync(Build(method, path, body, headers, auth));
    var text = await res.Content.ReadAsStringAsync();
    JsonNode? env = null;
    try { env = JsonNode.Parse(text); } catch (JsonException) { }
    if (!res.IsSuccessStatusCode) throw ApiErr((int)res.StatusCode, env, res.ReasonPhrase);
    return env?["data"];
}

// ... steps 2-6 go here ...

class ApiException(int status, string? code, string message, JsonNode? details)
    : Exception($"{status} {code}: {message}")
{
    public int Status => status;
    public string? Code => code;
    public JsonNode? Details => details;
}

# A guest token: no Authorization header, body {"slug": "orm-query-check"}.
GUEST=$(curl -sS -X POST "$BASE/guest" \
  -H "Content-Type: application/json" \
  --data-binary '{"slug":"orm-query-check"}')
echo "$GUEST" | jq '.data.guest_id'
TOKEN=$(echo "$GUEST" | jq -r '.data.token')

# Metered runs (task "write" and "review") need a personal, signed-in token instead:
# copy it from https://orm-query-check.skillsafe.ai/tokens.html
# TOKEN="YOUR_TOKEN"

# A guest token: no Authorization header, body {"slug": "orm-query-check"}.
guest = call("POST", "/guest", {"slug": "orm-query-check"}, auth=False)
print("guest_id:", guest["guest_id"])
TOKEN = guest["token"]

# Metered runs (task "write" and "review") need a personal, signed-in token instead:
# copy it from https://orm-query-check.skillsafe.ai/tokens.html
# TOKEN = "YOUR_TOKEN"

// A guest token: no Authorization header, body {"slug": "orm-query-check"}.
const guest = await call("POST", "/guest", { slug: "orm-query-check" }, {}, false);
console.log("guest_id:", guest.guest_id);
token = guest.token;

// Metered runs (task "write" and "review") need a personal, signed-in token instead:
// copy it from https://orm-query-check.skillsafe.ai/tokens.html
// token = TOKEN;

// A guest token: no Authorization header, body {"slug": "orm-query-check"}.
var guest struct {
	Token   string `json:"token"`
	GuestID string `json:"guest_id"`
}
personal := token
token = "" // call() sends no Authorization header while token is empty
if err := call("POST", "/guest", map[string]string{"slug": "orm-query-check"}, nil, &guest); err != nil {
	panic(err)
}
fmt.Println("guest_id:", guest.GuestID)
token = guest.Token

// Metered runs (task "write" and "review") need a personal, signed-in token instead:
// copy it from https://orm-query-check.skillsafe.ai/tokens.html into SKILLSAFE_TOKEN.
if personal != "" {
	token = personal
}

// A guest token: no Authorization header, body {"slug": "orm-query-check"}.
String personal = token;
token = null; // request() sends no Authorization header while token is null
JsonNode guest = call("POST", "/guest", Map.of("slug", "orm-query-check"), null);
System.out.println("guest_id: " + guest.path("guest_id").asText());
token = guest.path("token").asText();

// Metered runs (task "write" and "review") need a personal, signed-in token instead:
// copy it from https://orm-query-check.skillsafe.ai/tokens.html
// token = personal;

# A guest token: no Authorization header, body {"slug": "orm-query-check"}.
guest = call("POST", "/guest", { slug: "orm-query-check" }, {}, false)
puts "guest_id: #{guest["guest_id"]}"
$token = guest["token"]

# Metered runs (task "write" and "review") need a personal, signed-in token instead:
# copy it from https://orm-query-check.skillsafe.ai/tokens.html
# $token = TOKEN

// A guest token: no Authorization header, body {"slug": "orm-query-check"}.
$guest = call("POST", "/guest", ["slug" => "orm-query-check"], [], false);
echo "guest_id: {$guest["guest_id"]}\n";
$token = $guest["token"];

// Metered runs (task "write" and "review") need a personal, signed-in token instead:
// copy it from https://orm-query-check.skillsafe.ai/tokens.html
// $token = "YOUR_TOKEN";

// A guest token: no Authorization header, body {"slug": "orm-query-check"}.
var guest = (await Call(HttpMethod.Post, "/guest",
    new JsonObject { ["slug"] = "orm-query-check" }, auth: false))!;
Console.WriteLine($"guest_id: {guest["guest_id"]}");
token = guest["token"]!.GetValue<string>();

// Metered runs (task "write" and "review") need a personal, signed-in token instead:
// copy it from https://orm-query-check.skillsafe.ai/tokens.html
// token = "YOUR_TOKEN";

api GET /me | jq '.data'
# {"subject_type": "...", "subject_id": "...", "credits": 12345, ...}

me = call("GET", "/me")
print(me["subject_type"], me["subject_id"], "credits:", me.get("credits"))

const me = await call("GET", "/me");
console.log(me.subject_type, me.subject_id, "credits:", me.credits);

var me map[string]any
if err := call("GET", "/me", nil, nil, &me); err != nil {
	panic(err)
}
fmt.Println(me["subject_type"], me["subject_id"], "credits:", me["credits"])

JsonNode me = call("GET", "/me", null, null);
System.out.println(me.path("subject_type").asText() + " " + me.path("subject_id").asText()
    + " credits: " + me.path("credits"));

me = call("GET", "/me")
puts "#{me["subject_type"]} #{me["subject_id"]} credits: #{me["credits"]}"

$me = call("GET", "/me");
echo "{$me["subject_type"]} {$me["subject_id"]} credits: " . ($me["credits"] ?? "?") . "\n";

var me = (await Call(HttpMethod.Get, "/me"))!;
Console.WriteLine($"{me["subject_type"]} {me["subject_id"]} credits: {me["credits"]}");

cat > schema.prisma <<'PRISMA'
generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id          Int       @id @default(autoincrement())
  title       String
  published   Boolean   @default(false)
  publishedAt DateTime?
  author      User      @relation(fields: [authorId], references: [id])
  authorId    Int
}
PRISMA

# facts is sent as a STRING holding JSON; the page builds it with kit.js facts().
cat > facts.json <<'JSON'
{
  "provider": "postgresql",
  "generator": "prisma-client",
  "client_api": "prisma-orm-7 (prisma-client generator)",
  "capabilities": {"provider": "postgresql", "mode_insensitive": true, "and_return": true, "skip_duplicates": true, "json_filters": "array path like ['a','b']", "scalar_lists": true, "is_set": false},
  "models": [
    {"model": "User", "accessor": "user", "fields": ["id:Int", "email:String", "name:String?", "posts:Post[](relation, list)"], "unique": ["id", "email"]},
    {"model": "Post", "accessor": "post", "fields": ["id:Int", "title:String", "published:Boolean", "publishedAt:DateTime?", "author:User(relation)", "authorId:Int"], "unique": ["id"]}
  ],
  "enums": {},
  "schema_problems": []
}
JSON

INPUT=$(jq -n \
  --rawfile schema schema.prisma \
  --arg facts "$(jq -c . facts.json)" \
  --arg request "Published posts whose title contains a search term, ignoring case, newest first by publish date, 20 per page, with the author's name." \
  '{task: "write", schema: $schema, request: $request, facts: $facts}')

api POST /estimate "$INPUT" | jq '.data'
# hold_credits = the reservation, not the price; min_credits = the balance floor

SCHEMA = """generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id          Int       @id @default(autoincrement())
  title       String
  published   Boolean   @default(false)
  publishedAt DateTime?
  author      User      @relation(fields: [authorId], references: [id])
  authorId    Int
}
"""

# facts is sent as a STRING holding JSON; the page builds it with kit.js facts().
FACTS = """{
  "provider": "postgresql",
  "generator": "prisma-client",
  "client_api": "prisma-orm-7 (prisma-client generator)",
  "capabilities": {"provider": "postgresql", "mode_insensitive": true, "and_return": true, "skip_duplicates": true, "json_filters": "array path like ['a','b']", "scalar_lists": true, "is_set": false},
  "models": [
    {"model": "User", "accessor": "user", "fields": ["id:Int", "email:String", "name:String?", "posts:Post[](relation, list)"], "unique": ["id", "email"]},
    {"model": "Post", "accessor": "post", "fields": ["id:Int", "title:String", "published:Boolean", "publishedAt:DateTime?", "author:User(relation)", "authorId:Int"], "unique": ["id"]}
  ],
  "enums": {},
  "schema_problems": []
}"""

write_input = {
    "task": "write",
    "schema": SCHEMA,
    "request": "Published posts whose title contains a search term, ignoring case, newest first by publish date, 20 per page, with the author's name.",
    "facts": FACTS,
}

est = call("POST", "/estimate", write_input)  # the body IS the input object
print("hold_credits:", est.get("hold_credits"), "min_credits:", est.get("min_credits"))

const SCHEMA = `generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id          Int       @id @default(autoincrement())
  title       String
  published   Boolean   @default(false)
  publishedAt DateTime?
  author      User      @relation(fields: [authorId], references: [id])
  authorId    Int
}
`;

// facts is sent as a STRING holding JSON; the page builds it with kit.js facts().
const FACTS = `{
  "provider": "postgresql",
  "generator": "prisma-client",
  "client_api": "prisma-orm-7 (prisma-client generator)",
  "capabilities": {"provider": "postgresql", "mode_insensitive": true, "and_return": true, "skip_duplicates": true, "json_filters": "array path like ['a','b']", "scalar_lists": true, "is_set": false},
  "models": [
    {"model": "User", "accessor": "user", "fields": ["id:Int", "email:String", "name:String?", "posts:Post[](relation, list)"], "unique": ["id", "email"]},
    {"model": "Post", "accessor": "post", "fields": ["id:Int", "title:String", "published:Boolean", "publishedAt:DateTime?", "author:User(relation)", "authorId:Int"], "unique": ["id"]}
  ],
  "enums": {},
  "schema_problems": []
}`;

const writeInput = {
  task: "write",
  schema: SCHEMA,
  request: "Published posts whose title contains a search term, ignoring case, newest first by publish date, 20 per page, with the author's name.",
  facts: FACTS,
};

const est = await call("POST", "/estimate", writeInput); // the body IS the input object
console.log("hold_credits:", est.hold_credits, "min_credits:", est.min_credits);

schema := `generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id          Int       @id @default(autoincrement())
  title       String
  published   Boolean   @default(false)
  publishedAt DateTime?
  author      User      @relation(fields: [authorId], references: [id])
  authorId    Int
}
`

// facts is sent as a STRING holding JSON; the page builds it with kit.js facts().
facts := `{
  "provider": "postgresql",
  "generator": "prisma-client",
  "client_api": "prisma-orm-7 (prisma-client generator)",
  "capabilities": {"provider": "postgresql", "mode_insensitive": true, "and_return": true, "skip_duplicates": true, "json_filters": "array path like ['a','b']", "scalar_lists": true, "is_set": false},
  "models": [
    {"model": "User", "accessor": "user", "fields": ["id:Int", "email:String", "name:String?", "posts:Post[](relation, list)"], "unique": ["id", "email"]},
    {"model": "Post", "accessor": "post", "fields": ["id:Int", "title:String", "published:Boolean", "publishedAt:DateTime?", "author:User(relation)", "authorId:Int"], "unique": ["id"]}
  ],
  "enums": {},
  "schema_problems": []
}`

input := map[string]any{
	"task":    "write",
	"schema":  schema,
	"request": "Published posts whose title contains a search term, ignoring case, newest first by publish date, 20 per page, with the author's name.",
	"facts":   facts,
}

var est map[string]any
if err := call("POST", "/estimate", input, nil, &est); err != nil { // the body IS the input object
	panic(err)
}
fmt.Println("hold_credits:", est["hold_credits"], "min_credits:", est["min_credits"])

String schema = """
generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id          Int       @id @default(autoincrement())
  title       String
  published   Boolean   @default(false)
  publishedAt DateTime?
  author      User      @relation(fields: [authorId], references: [id])
  authorId    Int
}
""";

// facts is sent as a STRING holding JSON; the page builds it with kit.js facts().
String facts = """
{
  "provider": "postgresql",
  "generator": "prisma-client",
  "client_api": "prisma-orm-7 (prisma-client generator)",
  "capabilities": {"provider": "postgresql", "mode_insensitive": true, "and_return": true, "skip_duplicates": true, "json_filters": "array path like ['a','b']", "scalar_lists": true, "is_set": false},
  "models": [
    {"model": "User", "accessor": "user", "fields": ["id:Int", "email:String", "name:String?", "posts:Post[](relation, list)"], "unique": ["id", "email"]},
    {"model": "Post", "accessor": "post", "fields": ["id:Int", "title:String", "published:Boolean", "publishedAt:DateTime?", "author:User(relation)", "authorId:Int"], "unique": ["id"]}
  ],
  "enums": {},
  "schema_problems": []
}""";

// A LinkedHashMap keeps the key order (and so the step 5 hash) stable across runs.
Map<String, Object> input = new LinkedHashMap<>();
input.put("task", "write");
input.put("schema", schema);
input.put("request", "Published posts whose title contains a search term, ignoring case, newest first by publish date, 20 per page, with the author's name.");
input.put("facts", facts);

JsonNode est = call("POST", "/estimate", input, null); // the body IS the input object
System.out.println("hold_credits: " + est.path("hold_credits") + " min_credits: " + est.path("min_credits"));

SCHEMA = <<~'PRISMA'
generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id          Int       @id @default(autoincrement())
  title       String
  published   Boolean   @default(false)
  publishedAt DateTime?
  author      User      @relation(fields: [authorId], references: [id])
  authorId    Int
}
PRISMA

# facts is sent as a STRING holding JSON; the page builds it with kit.js facts().
FACTS = <<~'JSON'.strip
{
  "provider": "postgresql",
  "generator": "prisma-client",
  "client_api": "prisma-orm-7 (prisma-client generator)",
  "capabilities": {"provider": "postgresql", "mode_insensitive": true, "and_return": true, "skip_duplicates": true, "json_filters": "array path like ['a','b']", "scalar_lists": true, "is_set": false},
  "models": [
    {"model": "User", "accessor": "user", "fields": ["id:Int", "email:String", "name:String?", "posts:Post[](relation, list)"], "unique": ["id", "email"]},
    {"model": "Post", "accessor": "post", "fields": ["id:Int", "title:String", "published:Boolean", "publishedAt:DateTime?", "author:User(relation)", "authorId:Int"], "unique": ["id"]}
  ],
  "enums": {},
  "schema_problems": []
}
JSON

write_input = {
  task: "write",
  schema: SCHEMA,
  request: "Published posts whose title contains a search term, ignoring case, newest first by publish date, 20 per page, with the author's name.",
  facts: FACTS
}

est = call("POST", "/estimate", write_input) # the body IS the input object
puts "hold_credits: #{est["hold_credits"]} min_credits: #{est["min_credits"]}"

$schema = <<<'PRISMA'
generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id          Int       @id @default(autoincrement())
  title       String
  published   Boolean   @default(false)
  publishedAt DateTime?
  author      User      @relation(fields: [authorId], references: [id])
  authorId    Int
}

PRISMA;

// facts is sent as a STRING holding JSON; the page builds it with kit.js facts().
$facts = <<<'JSON'
{
  "provider": "postgresql",
  "generator": "prisma-client",
  "client_api": "prisma-orm-7 (prisma-client generator)",
  "capabilities": {"provider": "postgresql", "mode_insensitive": true, "and_return": true, "skip_duplicates": true, "json_filters": "array path like ['a','b']", "scalar_lists": true, "is_set": false},
  "models": [
    {"model": "User", "accessor": "user", "fields": ["id:Int", "email:String", "name:String?", "posts:Post[](relation, list)"], "unique": ["id", "email"]},
    {"model": "Post", "accessor": "post", "fields": ["id:Int", "title:String", "published:Boolean", "publishedAt:DateTime?", "author:User(relation)", "authorId:Int"], "unique": ["id"]}
  ],
  "enums": {},
  "schema_problems": []
}
JSON;

$writeInput = [
    "task" => "write",
    "schema" => $schema,
    "request" => "Published posts whose title contains a search term, ignoring case, newest first by publish date, 20 per page, with the author's name.",
    "facts" => $facts,
];

$est = call("POST", "/estimate", $writeInput); // the body IS the input object
echo "hold_credits: " . ($est["hold_credits"] ?? "?") . " min_credits: " . ($est["min_credits"] ?? "?") . "\n";

var schema = """
generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id          Int       @id @default(autoincrement())
  title       String
  published   Boolean   @default(false)
  publishedAt DateTime?
  author      User      @relation(fields: [authorId], references: [id])
  authorId    Int
}

""";

// facts is sent as a STRING holding JSON; the page builds it with kit.js facts().
var facts = """
{
  "provider": "postgresql",
  "generator": "prisma-client",
  "client_api": "prisma-orm-7 (prisma-client generator)",
  "capabilities": {"provider": "postgresql", "mode_insensitive": true, "and_return": true, "skip_duplicates": true, "json_filters": "array path like ['a','b']", "scalar_lists": true, "is_set": false},
  "models": [
    {"model": "User", "accessor": "user", "fields": ["id:Int", "email:String", "name:String?", "posts:Post[](relation, list)"], "unique": ["id", "email"]},
    {"model": "Post", "accessor": "post", "fields": ["id:Int", "title:String", "published:Boolean", "publishedAt:DateTime?", "author:User(relation)", "authorId:Int"], "unique": ["id"]}
  ],
  "enums": {},
  "schema_problems": []
}
""";

var input = new JsonObject
{
    ["task"] = "write",
    ["schema"] = schema,
    ["request"] = "Published posts whose title contains a search term, ignoring case, newest first by publish date, 20 per page, with the author's name.",
    ["facts"] = facts,
};

var est = (await Call(HttpMethod.Post, "/estimate", input))!; // the body IS the input object
Console.WriteLine($"hold_credits: {est["hold_credits"]} min_credits: {est["min_credits"]}");

# orm-query-check:<lane>:<hash of the exact input>:a<attempt>
KEY="orm-query-check:write:$(printf '%s' "$INPUT" | shasum -a 256 | cut -c1-16):a1"

RUN=$(api POST /run "$INPUT" -H "Idempotency-Key: $KEY")
JOB_ID=$(echo "$RUN" | jq -r '.data.job_id // empty')
[ -n "$JOB_ID" ] || { echo "$RUN" | jq '.error'; exit 1; }   # 401: sign in again, 402: top up

while :; do
  JOB=$(api GET "/jobs/$JOB_ID")
  STATUS=$(echo "$JOB" | jq -r '.data.status')
  case "$STATUS" in succeeded|failed) break ;; esac
  sleep 1
done

echo "$JOB" | jq '.data | {status, charged_credits, truncated, error}'
# The model's reply is a JSON object serialised as text in job.output.output:
echo "$JOB" | jq -r '.data.output.output' | jq '{headline, method, model, code}'

import hashlib
import time
from urllib.parse import quote


def idem_key(lane, inp, attempt=1):
    """The app's format: orm-query-check:<lane>:<hash of the exact input>:a<attempt>."""
    digest = hashlib.sha256(json.dumps(inp).encode()).hexdigest()[:16]
    return f"orm-query-check:{lane}:{digest}:a{attempt}"


def wait_for_job(job_id, interval=1.0, timeout=180):
    start = time.time()
    while True:
        job = call("GET", "/jobs/" + quote(job_id, safe=""))
        if job["status"] in ("succeeded", "failed"):
            return job
        if time.time() - start > timeout:
            raise TimeoutError("job timed out")
        time.sleep(interval)


try:
    started = call("POST", "/run", write_input,
                   headers={"Idempotency-Key": idem_key("write", write_input)})
except ApiError as e:
    if e.status == 402:
        raise SystemExit("Not enough credits for this run - top up.")
    if e.status == 401:
        raise SystemExit("The token expired or is not signed in - get a new one.")
    raise

job = wait_for_job(started["job_id"])
if job["status"] == "failed":
    raise RuntimeError(f"job failed: {job.get('error')}")
reply = json.loads(job["output"]["output"])  # the reply text is one JSON object
print(reply["headline"])
print(reply["code"])
print("charged_credits:", job.get("charged_credits"), "truncated:", job.get("truncated") is True)

// The app's format: orm-query-check:<lane>:<hash of the exact input>:a<attempt>.
async function idemKey(lane, input, attempt = 1) {
  const bytes = new TextEncoder().encode(JSON.stringify(input));
  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
  const hex = Array.from(digest.slice(0, 8), (b) => b.toString(16).padStart(2, "0")).join("");
  return `orm-query-check:${lane}:${hex}:a${attempt}`;
}

async function waitForJob(jobId, intervalMs = 1000, timeoutMs = 180000) {
  const start = Date.now();
  for (;;) {
    const job = await call("GET", "/jobs/" + encodeURIComponent(jobId));
    if (job.status === "succeeded" || job.status === "failed") return job;
    if (Date.now() - start > timeoutMs) throw new Error("job timed out");
    await new Promise((r) => setTimeout(r, intervalMs));
  }
}

let started;
try {
  started = await call("POST", "/run", writeInput, { "Idempotency-Key": await idemKey("write", writeInput) });
} catch (err) {
  if (err.status === 402) throw new Error("Not enough credits for this run - top up.");
  if (err.status === 401) throw new Error("The token expired or is not signed in - get a new one.");
  throw err;
}

const job = await waitForJob(started.job_id);
if (job.status === "failed") throw new Error("job failed: " + JSON.stringify(job.error));
const reply = JSON.parse(job.output.output); // the reply text is one JSON object
console.log(reply.headline);
console.log(reply.code);
console.log("charged_credits:", job.charged_credits, "truncated:", job.truncated === true);

// --- package level ---

// idemKey is the app's format: orm-query-check:<lane>:<hash of the exact input>:a<attempt>.
func idemKey(lane string, input map[string]any, attempt int) string {
	b, _ := json.Marshal(input) // map keys marshal sorted, so the hash is stable
	sum := sha256.Sum256(b)
	return fmt.Sprintf("orm-query-check:%s:%x:a%d", lane, sum[:8], attempt)
}

func waitForJob(jobID string) (map[string]any, error) {
	deadline := time.Now().Add(3 * time.Minute)
	for {
		var job map[string]any
		if err := call("GET", "/jobs/"+url.PathEscape(jobID), nil, nil, &job); err != nil {
			return nil, err
		}
		if s, _ := job["status"].(string); s == "succeeded" || s == "failed" {
			return job, nil
		}
		if time.Now().After(deadline) {
			return nil, fmt.Errorf("job %s timed out", jobID)
		}
		time.Sleep(time.Second)
	}
}

// replyOf reads the reply text at job.output.output and parses the JSON object in it.
func replyOf(job map[string]any) (map[string]any, error) {
	if s, _ := job["status"].(string); s == "failed" {
		return nil, fmt.Errorf("job failed: %v", job["error"])
	}
	out, _ := job["output"].(map[string]any)
	text, _ := out["output"].(string)
	var reply map[string]any
	err := json.Unmarshal([]byte(text), &reply)
	return reply, err
}

// --- in main ---
var started struct {
	JobID string `json:"job_id"`
}
if err := call("POST", "/run", input, map[string]string{"Idempotency-Key": idemKey("write", input, 1)}, &started); err != nil {
	panic(err) // *APIError: Status 401 = sign in again, 402 = not enough credits
}
job, err := waitForJob(started.JobID)
if err != nil {
	panic(err)
}
reply, err := replyOf(job)
if err != nil {
	panic(err)
}
fmt.Println(reply["headline"])
fmt.Println(reply["code"])
fmt.Println("charged_credits:", job["charged_credits"], "truncated:", job["truncated"] == true)

// --- static methods in class Api ---

/** The app's format: orm-query-check:<lane>:<hash of the exact input>:a<attempt>. */
static String idemKey(String lane, Object input, int attempt) throws Exception {
    byte[] d = MessageDigest.getInstance("SHA-256").digest(JSON.writeValueAsBytes(input));
    return "orm-query-check:" + lane + ":" + HexFormat.of().formatHex(d, 0, 8) + ":a" + attempt;
}

static JsonNode waitForJob(String jobId) throws Exception {
    long deadline = System.currentTimeMillis() + 180_000;
    while (true) {
        JsonNode job = call("GET", "/jobs/" + URLEncoder.encode(jobId, StandardCharsets.UTF_8), null, null);
        String status = job.path("status").asText();
        if (status.equals("succeeded") || status.equals("failed")) return job;
        if (System.currentTimeMillis() > deadline) throw new IllegalStateException("job timed out");
        Thread.sleep(1000);
    }
}

// --- in main ---
JsonNode started;
try {
    started = call("POST", "/run", input, Map.of("Idempotency-Key", idemKey("write", input, 1)));
} catch (ApiException e) {
    if (e.status == 402) throw new IllegalStateException("Not enough credits for this run - top up.", e);
    if (e.status == 401) throw new IllegalStateException("The token expired or is not signed in.", e);
    throw e;
}
JsonNode job = waitForJob(started.path("job_id").asText());
if (job.path("status").asText().equals("failed")) {
    throw new IllegalStateException("job failed: " + job.path("error"));
}
JsonNode reply = JSON.readTree(job.path("output").path("output").asText()); // one JSON object
System.out.println(reply.path("headline").asText());
System.out.println(reply.path("code").asText());
System.out.println("charged_credits: " + job.path("charged_credits")
    + " truncated: " + job.path("truncated").asBoolean(false));

require "digest"

# The app's format: orm-query-check:<lane>:<hash of the exact input>:a<attempt>.
def idem_key(lane, input, attempt = 1)
  "orm-query-check:#{lane}:#{Digest::SHA256.hexdigest(JSON.generate(input))[0, 16]}:a#{attempt}"
end

def wait_for_job(job_id, interval: 1, timeout: 180)
  start = Time.now
  loop do
    job = call("GET", "/jobs/#{URI.encode_www_form_component(job_id)}")
    return job if %w[succeeded failed].include?(job["status"])
    raise "job timed out" if Time.now - start > timeout
    sleep interval
  end
end

begin
  started = call("POST", "/run", write_input, { "Idempotency-Key" => idem_key("write", write_input) })
rescue ApiError => e
  abort "Not enough credits for this run - top up." if e.status == 402
  abort "The token expired or is not signed in - get a new one." if e.status == 401
  raise
end

job = wait_for_job(started["job_id"])
raise "job failed: #{job["error"]}" if job["status"] == "failed"
reply = JSON.parse(job["output"]["output"]) # the reply text is one JSON object
puts reply["headline"], reply["code"]
puts "charged_credits: #{job["charged_credits"]} truncated: #{job["truncated"] == true}"

// The app's format: orm-query-check:<lane>:<hash of the exact input>:a<attempt>.
function idemKey(string $lane, array $input, int $attempt = 1): string {
    $hash = substr(hash("sha256", json_encode($input, JSON_UNESCAPED_SLASHES)), 0, 16);
    return "orm-query-check:$lane:$hash:a$attempt";
}

function waitForJob(string $jobId, int $timeout = 180): array {
    $start = time();
    while (true) {
        $job = call("GET", "/jobs/" . rawurlencode($jobId));
        if (in_array($job["status"] ?? "", ["succeeded", "failed"], true)) return $job;
        if (time() - $start > $timeout) throw new RuntimeException("job timed out");
        sleep(1);
    }
}

try {
    $started = call("POST", "/run", $writeInput, ["Idempotency-Key" => idemKey("write", $writeInput)]);
} catch (ApiError $e) {
    if ($e->status === 402) exit("Not enough credits for this run - top up.\n");
    if ($e->status === 401) exit("The token expired or is not signed in - get a new one.\n");
    throw $e;
}

$job = waitForJob($started["job_id"]);
if ($job["status"] === "failed") throw new RuntimeException("job failed: " . json_encode($job["error"] ?? null));
$reply = json_decode($job["output"]["output"], true, 512, JSON_THROW_ON_ERROR); // one JSON object
echo $reply["headline"], "\n", $reply["code"], "\n";
echo "charged_credits: " . ($job["charged_credits"] ?? "?") . " truncated: " . (($job["truncated"] ?? false) === true ? "yes" : "no") . "\n";

// The app's format: orm-query-check:<lane>:<hash of the exact input>:a<attempt>.
string IdemKey(string lane, JsonNode input, int attempt = 1)
{
    var hash = SHA256.HashData(Encoding.UTF8.GetBytes(input.ToJsonString()));
    return $"orm-query-check:{lane}:{Convert.ToHexString(hash, 0, 8).ToLowerInvariant()}:a{attempt}";
}

async Task<JsonNode> WaitForJob(string jobId)
{
    var deadline = DateTime.UtcNow.AddMinutes(3);
    while (true)
    {
        var j = (await Call(HttpMethod.Get, "/jobs/" + Uri.EscapeDataString(jobId)))!;
        if (j["status"]?.GetValue<string>() is "succeeded" or "failed") return j;
        if (DateTime.UtcNow > deadline) throw new TimeoutException("job timed out");
        await Task.Delay(1000);
    }
}

JsonNode started;
try
{
    started = (await Call(HttpMethod.Post, "/run", input,
        new Dictionary<string, string> { ["Idempotency-Key"] = IdemKey("write", input) }))!;
}
catch (ApiException e) when (e.Status is 401 or 402)
{
    throw new Exception(e.Status == 402 ? "Not enough credits for this run - top up."
        : "The token expired or is not signed in - get a new one.", e);
}

var job = await WaitForJob(started["job_id"]!.GetValue<string>());
if (job["status"]?.GetValue<string>() == "failed") throw new Exception($"job failed: {job["error"]?.ToJsonString()}");
var reply = JsonNode.Parse(job["output"]!["output"]!.GetValue<string>())!; // one JSON object
Console.WriteLine(reply["headline"]);
Console.WriteLine(reply["code"]);
Console.WriteLine($"charged_credits: {job["charged_credits"]} truncated: {job["truncated"]}");

KEY="orm-query-check:write:$(printf '%s' "$INPUT" | shasum -a 256 | cut -c1-16):a1"

# -N turns off buffering. A replay of a key already used answers with a plain {"data": ...} JSON body.
curl -sS -N -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  --data-binary "$INPUT" |
while IFS= read -r line; do
  case "$line" in
    "{"*) echo "$line" | jq -r '.data.output.output // .error' ;;   # plain JSON: replay or error
    "event:"*) EVENT="${line#event:}"; EVENT="${EVENT# }" ;;
    "data:"*) DATA="${DATA-}${line#data:}" ;;
    "")
      if [ -n "${DATA-}" ]; then
        case "${EVENT-message}" in
          delta) printf '%s' "$DATA" | jq -j '.text // ""' ;;
          job) printf '%s' "$DATA" | jq -c '{job: .}' >&2 ;;
          done|pending) printf '%s' "$DATA" | jq -c '{status, job_id, charged_credits, truncated}' >&2
                        printf '%s' "$DATA" | jq -r '.output.output // empty' ;;
          error) printf '%s' "$DATA" | jq -c '{error: .}' >&2 ;;
        esac
      fi
      EVENT=message; DATA="" ;;
  esac
done
# A "pending" payload has no output yet: poll /jobs/{job_id} as in step 5.

def run_stream(inp, key, on_delta=lambda text: None):
    """POST /run-stream; returns the final payload {job_id, status, charged_credits, output, truncated}."""
    body = json.dumps(inp)
    headers = {"Content-Type": "application/json", "Authorization": "Bearer " + TOKEN, "Idempotency-Key": key}
    with requests.post(BASE + "/run-stream", data=body, headers=headers, stream=True, timeout=300) as r:
        if "text/event-stream" not in r.headers.get("content-type", ""):
            # An idempotent replay (or an error) comes back as a plain {data} / {error} envelope.
            try:
                env = r.json()
            except ValueError:
                env = {}
            if not r.ok:
                err = env.get("error") or {}
                raise ApiError(r.status_code, err.get("code"), err.get("message") or r.reason, err.get("details"))
            return env.get("data")
        final, failure, event, data = None, None, "message", ""
        for line in r.iter_lines(decode_unicode=True):
            if line.startswith("event:"):
                event = line[6:].strip()
            elif line.startswith("data:"):
                data += line[5:].strip()
            elif line == "":
                if data:
                    payload = json.loads(data)
                    if event == "delta":
                        on_delta(payload.get("text", ""))
                    elif event == "job":
                        print("job:", payload)
                    elif event in ("done", "pending"):
                        final = payload
                    elif event == "error":
                        failure = payload
                event, data = "message", ""
    if failure:
        raise RuntimeError(f"{failure.get('code')}: {failure.get('message')} (job {failure.get('job_id')})")
    if final is None:
        raise RuntimeError("the stream ended without a done event")
    if final.get("status") not in ("succeeded", "failed") and final.get("job_id"):
        final = wait_for_job(final["job_id"])  # "pending": the job outlived the stream
    return final


streamed = []
final = run_stream(write_input, idem_key("write", write_input), streamed.append)
if final.get("status") == "failed":
    raise RuntimeError(f"job failed: {final.get('error')}")
# Browsers may get only heartbeats and the final payload, so read its output first.
text = ((final.get("output") or {}).get("output")) or "".join(streamed)
reply = json.loads(text)
print(reply["headline"], "| charged_credits:", final.get("charged_credits"), "| truncated:", final.get("truncated") is True)

async function runStream(input, key, onDelta = () => {}) {
  const res = await fetch(BASE + "/run-stream", {
    method: "POST",
    headers: { "Content-Type": "application/json", "Authorization": "Bearer " + token, "Idempotency-Key": key },
    body: JSON.stringify(input),
  });
  if (!(res.headers.get("content-type") || "").includes("text/event-stream")) {
    // An idempotent replay (or an error) comes back as a plain {data} / {error} envelope.
    const env = await res.json().catch(() => ({}));
    if (!res.ok) {
      throw Object.assign(new Error((env.error && env.error.message) || res.statusText),
        { status: res.status, code: env.error && env.error.code, details: env.error && env.error.details });
    }
    return env.data;
  }
  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "", result = null, failure = null;
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    let idx;
    while ((idx = buffer.indexOf("\n\n")) >= 0) {
      const raw = buffer.slice(0, idx);
      buffer = buffer.slice(idx + 2);
      let event = "message", data = "";
      for (const line of raw.split("\n")) {
        if (line.startsWith("event:")) event = line.slice(6).trim();
        else if (line.startsWith("data:")) data += line.slice(5).trim();
      }
      if (!data) continue;
      let payload;
      try { payload = JSON.parse(data); } catch { continue; }
      if (event === "delta") onDelta(payload.text || "");
      else if (event === "job") console.log("job:", payload);
      else if (event === "done" || event === "pending") result = payload;
      else if (event === "error") failure = payload;
    }
  }
  if (failure) throw Object.assign(new Error(failure.message || "job failed"), { code: failure.code, job_id: failure.job_id });
  if (!result) throw new Error("the stream ended without a done event");
  if (result.status !== "succeeded" && result.status !== "failed" && result.job_id) {
    return waitForJob(result.job_id); // "pending": the job outlived the stream
  }
  return result;
}

let streamed = "";
const result = await runStream(writeInput, await idemKey("write", writeInput), (t) => { streamed += t; });
if (result.status === "failed") throw new Error("job failed: " + JSON.stringify(result.error));
// Browsers may get only heartbeats and the final payload, so read its output first.
const streamReply = JSON.parse((result.output && result.output.output) || streamed);
console.log(streamReply.headline, "| charged_credits:", result.charged_credits, "| truncated:", result.truncated === true);

// --- package level ---

// runStream posts to /run-stream and returns the final payload
// {job_id, status, charged_credits, output, truncated}.
func runStream(input map[string]any, key string) (map[string]any, error) {
	b, err := json.Marshal(input)
	if err != nil {
		return nil, err
	}
	req, err := http.NewRequest("POST", base+"/run-stream", bytes.NewReader(b))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Idempotency-Key", key)
	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	if !strings.Contains(resp.Header.Get("Content-Type"), "text/event-stream") {
		// An idempotent replay (or an error) comes back as a plain {data} / {error} envelope.
		var env struct {
			Data  map[string]any `json:"data"`
			Error *APIError      `json:"error"`
		}
		_ = json.NewDecoder(resp.Body).Decode(&env)
		if resp.StatusCode < 200 || resp.StatusCode > 299 {
			if env.Error == nil {
				env.Error = &APIError{Message: resp.Status}
			}
			env.Error.Status = resp.StatusCode
			return nil, env.Error
		}
		return env.Data, nil
	}
	var final, failure map[string]any
	event, data := "message", ""
	sc := bufio.NewScanner(resp.Body)
	sc.Buffer(make([]byte, 0, 64*1024), 16*1024*1024) // the done payload carries the whole reply
	for sc.Scan() {
		line := sc.Text()
		switch {
		case strings.HasPrefix(line, "event:"):
			event = strings.TrimSpace(line[6:])
		case strings.HasPrefix(line, "data:"):
			data += strings.TrimSpace(line[5:])
		case line == "":
			if data != "" {
				var p map[string]any
				if json.Unmarshal([]byte(data), &p) == nil {
					switch event {
					case "delta":
						text, _ := p["text"].(string)
						fmt.Print(text)
					case "job":
						fmt.Fprintln(os.Stderr, "job:", p)
					case "done", "pending":
						final = p
					case "error":
						failure = p
					}
				}
			}
			event, data = "message", ""
		}
	}
	if err := sc.Err(); err != nil {
		return nil, err
	}
	if failure != nil {
		return nil, fmt.Errorf("%v: %v (job %v)", failure["code"], failure["message"], failure["job_id"])
	}
	if final == nil {
		return nil, fmt.Errorf("the stream ended without a done event")
	}
	if s, _ := final["status"].(string); s != "succeeded" && s != "failed" {
		if id, ok := final["job_id"].(string); ok {
			return waitForJob(id) // "pending": the job outlived the stream
		}
	}
	return final, nil
}

// --- in main ---
final, err := runStream(input, idemKey("write", input, 1))
if err != nil {
	panic(err)
}
streamReply, err := replyOf(final) // reads final.output.output, as in step 5
if err != nil {
	panic(err)
}
fmt.Println("\n", streamReply["headline"], "| charged_credits:", final["charged_credits"], "| truncated:", final["truncated"] == true)

// --- static method in class Api ---

/** POST /run-stream; returns the final payload {job_id, status, charged_credits, output, truncated}. */
static JsonNode runStream(Object input, String key) throws Exception {
    HttpRequest req = request("POST", "/run-stream", input, Map.of("Idempotency-Key", key)).build();
    HttpResponse<Stream<String>> res = HTTP.send(req, HttpResponse.BodyHandlers.ofLines());
    if (!res.headers().firstValue("content-type").orElse("").contains("text/event-stream")) {
        // An idempotent replay (or an error) comes back as a plain {data} / {error} envelope.
        String raw = res.body().collect(Collectors.joining("\n"));
        JsonNode env;
        try { env = JSON.readTree(raw); } catch (Exception e) { env = null; }
        if (res.statusCode() < 200 || res.statusCode() > 299) throw apiError(res.statusCode(), env);
        return env == null ? JSON.missingNode() : env.path("data");
    }
    JsonNode fin = null, failure = null;
    String event = "message";
    StringBuilder data = new StringBuilder();
    Iterator<String> lines = res.body().iterator();
    while (lines.hasNext()) {
        String line = lines.next();
        if (line.startsWith("event:")) {
            event = line.substring(6).trim();
        } else if (line.startsWith("data:")) {
            data.append(line.substring(5).trim());
        } else if (line.isEmpty()) {
            if (data.length() > 0) {
                JsonNode p = JSON.readTree(data.toString());
                switch (event) {
                    case "delta" -> System.out.print(p.path("text").asText(""));
                    case "job" -> System.err.println("job: " + p);
                    case "done", "pending" -> fin = p;
                    case "error" -> failure = p;
                    default -> { }
                }
            }
            event = "message";
            data.setLength(0);
        }
    }
    if (failure != null) {
        throw new IllegalStateException(failure.path("code").asText() + ": "
            + failure.path("message").asText("job failed") + " (job " + failure.path("job_id").asText() + ")");
    }
    if (fin == null) throw new IllegalStateException("the stream ended without a done event");
    String st = fin.path("status").asText("");
    if (!st.equals("succeeded") && !st.equals("failed") && fin.hasNonNull("job_id")) {
        fin = waitForJob(fin.path("job_id").asText()); // "pending": the job outlived the stream
    }
    return fin;
}

// --- in main ---
JsonNode fin = runStream(input, idemKey("write", input, 1));
if (fin.path("status").asText().equals("failed")) throw new IllegalStateException("job failed: " + fin.path("error"));
JsonNode streamReply = JSON.readTree(fin.path("output").path("output").asText());
System.out.println();
System.out.println(streamReply.path("headline").asText() + " | charged_credits: " + fin.path("charged_credits")
    + " | truncated: " + fin.path("truncated").asBoolean(false));

# POST /run-stream; returns the final payload {job_id, status, charged_credits, output, truncated}.
def run_stream(input, key)
  uri, req = build_request("POST", "/run-stream", input, { "Idempotency-Key" => key })
  final = failure = nil
  Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 300) do |h|
    h.request(req) do |res|
      unless res["content-type"].to_s.include?("text/event-stream")
        # An idempotent replay (or an error) comes back as a plain {data} / {error} envelope.
        env = (JSON.parse(res.read_body.to_s) rescue {})
        unless res.is_a?(Net::HTTPSuccess)
          err = env["error"] || {}
          raise ApiError.new(res.code.to_i, err["code"], err["message"] || res.message, err["details"])
        end
        final = env["data"]
        next
      end
      buffer = +""
      res.read_body do |chunk|
        buffer << chunk
        while (i = buffer.index("\n\n"))
          raw = buffer.slice!(0, i + 2)
          event = "message"
          data = +""
          raw.split("\n").each do |line|
            if line.start_with?("event:")
              event = line[6..].strip
            elsif line.start_with?("data:")
              data << line[5..].strip
            end
          end
          next if data.empty?
          payload = JSON.parse(data)
          case event
          when "delta" then print payload["text"].to_s
          when "job" then warn "job: #{payload}"
          when "done", "pending" then final = payload
          when "error" then failure = payload
          end
        end
      end
    end
  end
  raise "#{failure["code"]}: #{failure["message"]} (job #{failure["job_id"]})" if failure
  raise "the stream ended without a done event" unless final
  if !%w[succeeded failed].include?(final["status"]) && final["job_id"]
    final = wait_for_job(final["job_id"]) # "pending": the job outlived the stream
  end
  final
end

final = run_stream(write_input, idem_key("write", write_input))
raise "job failed: #{final["error"]}" if final["status"] == "failed"
stream_reply = JSON.parse(final.dig("output", "output").to_s)
puts "", "#{stream_reply["headline"]} | charged_credits: #{final["charged_credits"]} | truncated: #{final["truncated"] == true}"

/** POST /run-stream; returns the final payload {job_id, status, charged_credits, output, truncated}. */
function runStream(array $input, string $key): array {
    global $token;
    $buffer = ""; $plain = ""; $isSse = null; $final = null; $failure = null;
    $ch = curl_init(BASE . "/run-stream");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => ["Content-Type: application/json", "Authorization: Bearer $token", "Idempotency-Key: $key"],
        CURLOPT_POSTFIELDS => json_encode($input, JSON_UNESCAPED_SLASHES),
        CURLOPT_TIMEOUT => 300,
        CURLOPT_WRITEFUNCTION => function ($ch, string $chunk) use (&$buffer, &$plain, &$isSse, &$final, &$failure): int {
            $isSse ??= str_contains((string) curl_getinfo($ch, CURLINFO_CONTENT_TYPE), "text/event-stream");
            if (!$isSse) { $plain .= $chunk; return strlen($chunk); }
            $buffer .= $chunk;
            while (($i = strpos($buffer, "\n\n")) !== false) {
                $raw = substr($buffer, 0, $i);
                $buffer = substr($buffer, $i + 2);
                $event = "message"; $data = "";
                foreach (explode("\n", $raw) as $line) {
                    if (str_starts_with($line, "event:")) $event = trim(substr($line, 6));
                    elseif (str_starts_with($line, "data:")) $data .= trim(substr($line, 5));
                }
                $payload = $data === "" ? null : json_decode($data, true);
                if (!is_array($payload)) continue;
                switch ($event) {
                    case "delta": echo $payload["text"] ?? ""; break;
                    case "job": fwrite(STDERR, "job: " . json_encode($payload) . "\n"); break;
                    case "done": case "pending": $final = $payload; break;
                    case "error": $failure = $payload; break;
                }
            }
            return strlen($chunk);
        },
    ]);
    if (curl_exec($ch) === false) throw new RuntimeException(curl_error($ch));
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    if (!$isSse) { // an idempotent replay (or an error) is a plain {data} / {error} envelope
        $env = json_decode($plain, true) ?: [];
        if ($status < 200 || $status > 299) throw apiError($status, $env);
        $final = $env["data"] ?? null;
    }
    if ($failure) {
        throw new RuntimeException(($failure["code"] ?? "") . ": " . ($failure["message"] ?? "job failed") . " (job " . ($failure["job_id"] ?? "") . ")");
    }
    if (!$final) throw new RuntimeException("the stream ended without a done event");
    if (!in_array($final["status"] ?? "", ["succeeded", "failed"], true) && isset($final["job_id"])) {
        $final = waitForJob($final["job_id"]); // "pending": the job outlived the stream
    }
    return $final;
}

$final = runStream($writeInput, idemKey("write", $writeInput));
if (($final["status"] ?? "") === "failed") throw new RuntimeException("job failed: " . json_encode($final["error"] ?? null));
$streamReply = json_decode($final["output"]["output"] ?? "", true, 512, JSON_THROW_ON_ERROR);
echo "\n", $streamReply["headline"], " | charged_credits: ", $final["charged_credits"] ?? "?", "\n";

// POST /run-stream; returns the final payload {job_id, status, charged_credits, output, truncated}.
async Task<JsonNode> RunStream(JsonNode input, string key)
{
    using var req = Build(HttpMethod.Post, "/run-stream", input,
        new Dictionary<string, string> { ["Idempotency-Key"] = key });
    using var res = await http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead);
    if (res.Content.Headers.ContentType?.MediaType != "text/event-stream")
    {
        // An idempotent replay (or an error) comes back as a plain {data} / {error} envelope.
        JsonNode? env = null;
        try { env = JsonNode.Parse(await res.Content.ReadAsStringAsync()); } catch (JsonException) { }
        if (!res.IsSuccessStatusCode) throw ApiErr((int)res.StatusCode, env, res.ReasonPhrase);
        return env!["data"]!;
    }
    using var reader = new StreamReader(await res.Content.ReadAsStreamAsync());
    JsonNode? fin = null, failure = null;
    var ev = "message";
    var data = new StringBuilder();
    string? line;
    while ((line = await reader.ReadLineAsync()) != null)
    {
        if (line.StartsWith("event:")) ev = line[6..].Trim();
        else if (line.StartsWith("data:")) data.Append(line[5..].Trim());
        else if (line.Length == 0)
        {
            if (data.Length > 0)
            {
                var p = JsonNode.Parse(data.ToString());
                switch (ev)
                {
                    case "delta": Console.Write(p?["text"]?.GetValue<string>()); break;
                    case "job": Console.Error.WriteLine($"job: {p?.ToJsonString()}"); break;
                    case "done": case "pending": fin = p; break;
                    case "error": failure = p; break;
                }
            }
            ev = "message";
            data.Clear();
        }
    }
    if (failure != null) throw new Exception($"{failure["code"]}: {failure["message"]} (job {failure["job_id"]})");
    if (fin == null) throw new Exception("the stream ended without a done event");
    if (fin["status"]?.GetValue<string>() is not ("succeeded" or "failed") && fin["job_id"] != null)
        fin = await WaitForJob(fin["job_id"]!.GetValue<string>()); // "pending": the job outlived the stream
    return fin;
}

var streamResult = await RunStream(input, IdemKey("write", input));
if (streamResult["status"]?.GetValue<string>() == "failed") throw new Exception($"job failed: {streamResult["error"]?.ToJsonString()}");
var streamReply = JsonNode.Parse(streamResult["output"]!["output"]!.GetValue<string>())!;
Console.WriteLine();
Console.WriteLine($"{streamReply["headline"]} | charged_credits: {streamResult["charged_credits"]} | truncated: {streamResult["truncated"]}");