Ruby SDK API Reference¶

Use this guide to understand the primary entry points exposed by the kiket-sdk gem.

`KiketSDK`¶

sdk = KiketSDK.new(
  webhook_secret: nil,        # defaults to env/manifest
  workspace_token: nil,
  base_url: 'https://kiket.dev',
  settings: {},
  extension_id: nil,
  extension_version: nil,
  manifest_path: '.kiket/manifest.yaml',
  auto_env_secrets: true,
  telemetry_enabled: true,
  feedback_hook: nil,
  telemetry_url: nil
)

Methods¶

Method	Description
`register(event, version:, &block)`	Registers a handler immediately.
`webhook(event, version:) { \|payload, context\| ... }`	Decorator that returns the handler after registration.
`run!(host:, port:)`	Starts the embedded Puma/Sinatra server.
`load(module)`	Scans a module for `webhook`-decorated handlers.

Handler context¶

Handlers receive two arguments: the parsed JSON payload and a context hash. The context includes:

Key	Description
`:event` / `:event_version`	Metadata resolved during dispatch.
`:headers`	Rack-style header hash.
`:client`	Low-level REST client with `get/post/put/patch/delete` methods.
`:endpoints`	High-level helpers (see below).
`:settings`	Manifest configuration merged with env overrides.
`:extension_id` / `:extension_version`	Values derived from manifest or constructor.
`:secrets`	Shortcut for `context[:endpoints].secrets`.

Endpoint helpers¶

Helper	Methods
`log_event(name, payload)`	Track structured analytics.
`notify(title, body, level = 'info')`	Trigger notifications.
`custom_data(project_id)`	Returns a client with `list/get/create/update/delete`.
`sla_events(project_id)`	Provides `list` and `get` for SLA monitoring.
`secrets`	`get`, `set`, `delete`, `rotate`, `list`.

Telemetry reporter¶

KiketSDK::Telemetry dispatches telemetry for each handler invocation.

sdk.telemetry.record(
  event,
  version,
  'ok',
  duration_ms,
  'optional error message',
  error_class: 'RuntimeError',
  metadata: { attempt: 2 }
)

When telemetry_enabled is true, the reporter automatically POSTs to /api/v1/ext/telemetry using the runtime token from webhook payloads. Provide feedback_hook to mirror or enrich records locally.

Secret manager¶

context[:secrets].get('API_TOKEN')
context[:secrets].set('API_TOKEN', 'value')
context[:secrets].rotate('API_TOKEN', SecureRandom.hex(16))
context[:secrets].list # => %w[API_TOKEN ACCESS_KEY]

Secrets are scoped per installation/project. The SDK queues writes through the REST API, which stores values in secure secret storage.

Custom data client¶

client = context[:endpoints].custom_data(project_id)

client.create('com.example.crm', 'deals', amount: 10_000, status: 'open')
client.update('com.example.crm', 'deals', record_id, status: 'won')
client.list('com.example.crm', 'deals', limit: 20, filters: { status: 'open' })

Make sure the manifest declares the relevant custom_data.permissions. The SDK automatically uses the runtime token from webhook payloads to authenticate API calls.

Health endpoints¶

The Sinatra wrapper exposes:

POST /webhooks/:event
POST /v/:version/webhooks/:event
GET /health

Use kiket extensions replay to fire signed payloads at your local server and validate signature/permission issues before pushing to production.