Python SDK API Reference¶

`KiketSDK`¶

from kiket_sdk import KiketSDK, TelemetryRecord

sdk = KiketSDK(
    webhook_secret=os.getenv("KIKET_WEBHOOK_SECRET"),
    workspace_token=os.getenv("KIKET_WORKSPACE_TOKEN"),
    base_url="https://kiket.dev",
    settings={"retries": 3},
    extension_id="com.example.integration",
    extension_version="1.2.0",
    manifest_path=".kiket/manifest.yaml",
    auto_env_secrets=True,
    telemetry_enabled=True,
    feedback_hook=lambda record: print(record),
    telemetry_url=os.getenv("KIKET_SDK_TELEMETRY_URL"),
)

Arguments are optional if the manifest + environment variables are in place. The SDK auto-loads .kiket/manifest.yaml and merges KIKET_SECRET_* overrides when auto_env_secrets=True.

Methods¶

Method	Description
`webhook(event, version)`	Decorator for registering handlers.
`register(event, handler, version=...)`	Manual registration.
`load(module)`	Loads handlers decorated via `@sdk.webhook`.
`run(host="127.0.0.1", port=8000)`	Starts Uvicorn.
`create_test_client()`	Returns a FastAPI TestClient.

`HandlerContext`¶

@dataclass(slots=True)
class HandlerContext:
    event: str
    event_version: str
    headers: Mapping[str, str]
    client: KiketClient
    endpoints: ExtensionEndpoints
    settings: Mapping[str, Any]
    extension_id: str | None
    extension_version: str | None
    secrets: ExtensionSecretManager

client provides low-level get/post/put/patch/delete.
endpoints exposes higher-level helpers (see below).
secrets is a shortcut for endpoints.secrets.

Endpoint helpers¶

Helper	Description
`endpoints.log_event(name, payload)`	Append analytics events.
`endpoints.notify(title, body, level="info")`	Trigger notifications.
`endpoints.custom_data(project_id)`	Returns a client with `list/get/create/update/delete`.
`endpoints.sla_events(project_id)`	Fetch SLA events (`list`, `get`).
`endpoints.secrets`	`get`, `set`, `delete`, `rotate`, `list`.

Custom data usage¶

records = await context.endpoints.custom_data(project_id).list(
    "com.example.crm.contacts",
    "automation_records",
    limit=50,
    filters={"status": "active"},
)

await context.endpoints.custom_data(project_id).create(
    "com.example.crm.contacts",
    "automation_records",
    {"email": payload["lead_email"], "metadata": {"source": "campaign"}},
)

Ensure the manifest grants custom_data.permissions. The SDK automatically uses the runtime token from webhook payloads to authenticate API calls.

Telemetry¶

TelemetryReporter automatically posts records to /api/v1/ext/telemetry. Use the feedback_hook or call sdk.telemetry.record(...) manually:

await sdk.telemetry.record(
  event="issue.created",
  version="v1",
  status="error",
  duration_ms=125.4,
  metadata={"attempt": 2},
  error_message="Validation failed",
)

Fields include event, version, status, duration, timestamp, extension metadata, optional error info, and arbitrary metadata. Set KIKET_SDK_TELEMETRY_OPTOUT=1 to disable, or KIKET_SDK_TELEMETRY_URL to mirror elsewhere.

Secrets API¶

token = await context.secrets.get("API_TOKEN")
await context.secrets.set("API_TOKEN", "value")
await context.secrets.rotate("API_TOKEN", "new-value")
await context.secrets.delete("API_TOKEN")

All operations are scoped to the active installation/project.

Health endpoints¶

FastAPI routes exposed by the SDK:

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

Use kiket extensions replay to send signed payloads to the local server and catch signature/version issues early.

Testing utilities¶

client = sdk.create_test_client()

response = client.post(
    "/v/1/webhooks/issue.created",
    json={"issue": {"id": 123}},
    headers={"X-Kiket-Signature": "...", "X-Kiket-Event-Version": "v1"},
)

Pair with pytest and the CLI replay fixtures for end-to-end coverage.