Java SDK API Reference¶

`KiketSDK`¶

The SDK bootstraps a Spring Boot application and wires authentication, manifest parsing, and telemetry.

KiketSDK sdk = KiketSDK.builder()
    .webhookSecret("sh_test")
    .workspaceToken("wk_test")
    .baseUrl("https://kiket.dev")
    .settings(Map.of("retries", 3))
    .extensionId("com.example.integration")
    .extensionVersion("1.2.0")
    .manifestPath(".kiket/manifest.yaml")
    .autoEnvSecrets(true)
    .telemetryEnabled(true)
    .feedbackHook(record -> { /* ... */ })
    .telemetryUrl(System.getenv("KIKET_SDK_TELEMETRY_URL"))
    .build();

Core methods¶

Method	Description
`register(String event, String version, WebhookHandler handler)`	Registers a handler.
`run(String host, int port)`	Starts the embedded server.
`stop()`	Shuts down the application context.
`telemetryReporter()`	Returns the shared `TelemetryReporter`.

`WebhookHandler`¶

Functional interface:

@FunctionalInterface
public interface WebhookHandler {
    Object handle(Map<String, Object> payload, HandlerContext context) throws Exception;
}

Handlers may return any JSON-serializable object. Throwing an exception results in a 500 response and an error telemetry record.

`HandlerContext`¶

Method	Description
`getEvent()` / `getEventVersion()`	Event metadata.
`getHeaders()`	Case-insensitive header map.
`getClient()`	Low-level `KiketClient` with `get/post/put/patch/delete`.
`getEndpoints()`	High-level helpers for secrets, notifications, logs, custom data, SLA events.
`getSettings()`	Manifest settings merged with env overrides.
`getExtensionId()` / `getExtensionVersion()`	Convenience metadata.
`getSecrets()`	Shortcut for `getEndpoints().getSecrets()`.

Endpoint helpers¶

logEvent(String name, Map<String, Object> payload)
notify(String title, String message, String level)
customData(String projectId) → provides list/get/create/update/delete
slaEvents(String projectId) → exposes list & get
secrets → get, set, delete, rotate, list

Custom data example¶

var client = context.getEndpoints().customData(projectId);
client.create("com.example.crm", "automation_records", Map.of("email", "lead@example.com"));
client.update("com.example.crm", "automation_records", recordId, Map.of("status", "closed"));

Telemetry reporter¶

TelemetryReporter posts JSON payloads to /api/v1/ext/telemetry using the runtime token from webhook payloads.

telemetryReporter.record(
    "issue.created",
    "v1",
    "ok",
    42.5,
    "optional message"
);

Fields:

event, version
status (ok or error)
durationMs
errorMessage / errorClass
extensionId / extensionVersion
timestamp
metadata map

Testing utilities¶

dev.kiket.sdk.test exposes builders for signed payloads and mock contexts:

SignedPayloadFactory.create(secret, body) returns body & headers.
MockHandlerContextBuilder creates a context with fake clients/endpoints.

Use them with JUnit/MockMvc to exercise handlers without starting the web server.

Health endpoints¶

The Spring Boot app exposes:

POST /webhooks/{event}
POST /v/{version}/webhooks/{event}
GET /health

Combine with kiket extensions replay to validate signature handling in CI.