infrai-sdk (Java)

Unified online infrastructure SDK for the AI-agent era — one key, one wallet, one bill across the 14 GA business modules.

Group	Modules
AI & content	ai_runtime, ai_video, pdf, image_process, realtime
Messaging	email, sms
Integrity	captcha
Storage & billing	storage, billing
Ops	scheduling, observability, analytics, public_url

auth / db / deploy are not part of the current GA surface.

Install

<dependency>
  <groupId>io.infrailab</groupId>
  <artifactId>infrai-sdk</artifactId>
  <version>0.2.0</version>
</dependency>

Requires Java 17+.

Quick start

import io.infrailab.Client;
import io.infrailab.Infrai;
import com.fasterxml.jackson.databind.JsonNode;

Client client = Infrai.builder()
    .apiKey(System.getenv("INFRAI_API_KEY"))
    .build();

JsonNode resp = client.aiRuntime().chat()
    .model("gpt-4o-mini")
    .system("Be terse.")
    .user("Hello, infrai!")
    .send();
System.out.println(resp);

Features

• Java 17 records + pattern matching throughout.
• Byte-exact canonical JSON in io.infrailab.canonical.CanonicalSerializer — interoperable with the Python / TS / Go / Rust SDKs.
• 267 server-side error codes baked in (ErrorCatalog.ERROR_CODES, ErrorCatalog.ERROR_REGISTRY). Per the "errors never deleted" axiom the generated catalog may still embed archived code strings; the active SSOT count is 267.
• 98 enums generated from infrai-spec/enums/*.yaml.
• Idempotency-Key auto-UUID on every write request.
• Streaming via io.infrailab.streaming.SseParser + StreamChunk (works with any HTTP body source).
• BYOK — attach a vendor key via defaultByok() or per-request header.
• Retry with exponential backoff + ±20 % jitter, gated on the registry.
• Thread-safe: Client holds an immutable ClientConfig plus a single java.net.http.HttpClient (itself thread-safe). Zero mutable state.

Examples

See examples/:

• BasicChat.java — one-shot LLM completion
• StreamChat.java — build a streaming request body + parse mocked SSE
• UploadImage.java — image_process pipeline
• SendEmail.java — transactional email
• ByokSetup.java — attach a BYOK credential
• WebhookHandler.java — verify webhook signatures with CanonicalSerializer
• CanonicalDemo.java — canonical JSON + idempotency hash
• SpringBootApp/ — a minimal Spring Boot REST gateway

Spring Boot

The examples/SpringBootApp/README.md shows a 3-file skeleton: an @Configuration bean for Client, an @RestController that proxies to two modules, and an @ExceptionHandler mapping InfraiException to Spring's ProblemDetail.

Thread safety

Client is safe to share across threads / async pipelines. Every per-call state (idempotency key, BYOK override) lives on the immutable RequestSpec, not on the client itself.

Generated artifacts

src/main/java/io/infrailab/enums/Enums.java and src/main/java/io/infrailab/errors/ErrorCatalog.java are machine-generated from infrai-spec/enums/*.yaml and infrai-spec/errors/registry.yaml. Refresh with:

python3 infrai-spec/codegen/generate.py --langs java

License

MIT.