Skip to content

Node.js SDK API Reference

This document covers the key types exposed by @kiket/sdk, how configuration is resolved, and which helper clients are available inside webhook handlers.

SDK configuration

import { KiketSDK, TelemetryRecord } from '@kiket/sdk';

const sdk = new KiketSDK({
  webhookSecret: 'sh_test',              // optional – falls back to env/manifest
  workspaceToken: 'wk_test',             // optional – falls back to env
  baseUrl: 'https://kiket.dev',          // defaults to prod
  settings: { retries: 3 },              // merged with manifest defaults
  extensionId: 'com.example.app',
  extensionVersion: '1.4.2',
  manifestPath: '.kiket/manifest.yaml',  // auto-discovered if omitted
  autoEnvSecrets: true,                  // read KIKET_SECRET_* (default true)
  telemetryEnabled: true,                // opt out with false or env var
  feedbackHook: async (record: TelemetryRecord) => { /* ... */ },
  telemetryUrl: process.env.KIKET_SDK_TELEMETRY_URL,
});

All options are optional if the manifest + environment variables are in place. The SDK resolves them in the following order: explicit value → manifest → environment variable → default.

Handler registration

sdk.webhook(eventName: string, version: string)(
  handler: (payload: Record<string, unknown>, context: HandlerContext) => unknown
);

Handlers can also be bulk-loaded by calling sdk.load(require('./handlers')), which scans for functions decorated via handler.__kiket_event__ metadata (exported by @kiket/sdk/decorators).

HandlerContext

Property Description
event / eventVersion Event metadata resolved during dispatch.
headers Read-only copy of the inbound HTTP headers.
client Low-level KiketHttpClient for calling REST endpoints with strongly typed methods (get/post/put/patch/delete).
endpoints High-level helper covering secrets, notifications, custom data, SLA events, and logging.
settings Manifest-driven settings merged with environment overrides.
extensionId / extensionVersion Values from the manifest or KiketSDK constructor.
secrets Convenience alias for context.endpoints.secrets.

context.endpoints helpers

Helper Purpose
logEvent(name, payload) Append structured analytics/usage events.
notify(title, body, level) Trigger notifications (Slack, email, etc.).
customData(projectId) Returns a client with list/get/create/update/delete for manifest-authorised modules.
slaEvents(projectId) Fetch SLA events via /api/v1/ext/sla/events.
secrets CRUD operations against the extension’s secret store (scoped per installation).

Custom data client

const records = await context.endpoints
  .customData(projectId)
  .list('com.example.crm', 'automation_records', { limit: 20, filters: { status: 'active' } });

await context.endpoints
  .customData(projectId)
  .update('com.example.crm', 'automation_records', recordId, { status: 'closed' });

The helper automatically injects the X-Kiket-Runtime-Token header using the runtime token from webhook payloads.

Telemetry reporter

sdk.telemetry is an instance of TelemetryReporter:

await sdk.telemetry.record(event, version, 'ok', durationMs, {
  metadata: { attempt: 2 },
});

Records include:

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

When telemetry is enabled, the reporter automatically posts to /api/v1/ext/telemetry using the runtime token from webhook payloads. You can override the URL via telemetryUrl or supply a feedbackHook for additional reporting.

Testing utilities

@kiket/sdk/test exports helpers such as:

  • createSignedPayload(secret, body) – Generates body/headers for request simulation.
  • createTestContext(overrides) – Builds a fake HandlerContext.
  • mockEndpoints() – Returns mock implementations for context.endpoints.

Use them with Jest, Vitest, or your preferred framework to test handlers without running an HTTP server.

Health & diagnostics

The Express app exposed via sdk.app automatically mounts:

  • GET /health – reports status, version, registered events.
  • POST /webhooks/:event – default webhook route (requires X-Kiket-Event-Version).
  • POST /v/:version/webhooks/:event – explicit version path.

Combine these with the CLI (kiket extensions replay) to exercise handlers locally and record Golden payloads for regression tests.