Overview

The @ekanos/sdk is the official toolkit for building integrations — packages that extend Ekanos dashboards with custom widgets, assistant tools, webhooks, schedules, and more.

What is an integration?

An integration is a single call to defineIntegration() that declares everything your package can do:

Widgets — dashboard cards that display data and interact with users
Tools — assistant-callable functions that perform actions or fetch information
Webhooks — inbound event handlers from external services
Schedules — cron-driven background jobs
OAuth — secure third-party authentication and token management
Storage — schema-validated per-account and per-user state
Actions — widget-invoked server handlers
Activation hook — onActivate, run after an account connects

Secrets are not declared in the definition — they are named and read back through ctx.secrets. The whole definition is validated by defineIntegration() and re-validated by the host against the same schema.

The three layers

Layer	Purpose	Version on npm
@ekanos/sdk	Integration authoring contract & types	0.4.0
@ekanos/cli	Toolchain: `init`, `validate`, `dev`, `test`, `publish`	0.3.3
@ekanos/harness	Local dev harness: renders your surfaces in Ekanos chrome	0.4.0

You can define, validate, and unit-test an integration against the SDK alone. Seeing widgets and other surfaces rendered locally takes the harness (ekanos dev).

Your first integration

import { defineIntegration } from '@ekanos/sdk/integration';
import { z } from 'zod';

export const integration = defineIntegration({
  // Required identity
  slug: 'my-integration',
  name: 'My Integration',
  description: 'What it does.',
  version: '1.0.0',

  // Optional surfaces
  tools: [
    {
      name: 'example_tool',
      description: 'An example tool.',
      async run(ctx, args) {
        return { message: 'Hello' };
      },
    },
  ],

  storage: {
    account: {
      settings: z.object({ region: z.string() }),
    },
    user: {},
  },

  egress: ['https://api.example.com'],
});

Run defineIntegration() and the SDK validates the entire definition at import time. If anything is wrong, you get a remediation message immediately — no separate validation step needed.

Documentation structure

Fundamentals cover the core concepts:

The shape of an integration definition
The capability context (ctx) every handler receives
The six published entrypoints (plus one workspace-only entrypoint) and what each exports

Declarable Surfaces detail each feature you can declare, with examples:

Storage schemas, egress allowlists, secrets
Tools, widgets, forms, marketplace tiles
Webhooks, schedules, OAuth, activation hooks
Capability declarations and workspace targets

Development covers testing, styling, naming rules, and known edges.

Getting help

Errors and validation: defineIntegration() throws immediately with a remediation message. The schema is strict — unrecognized keys and malformed values are hard errors, not silent skips. Support: Questions or bugs? Email npm@govastly.com.

Getting started

Fundamentals

Declarable surfaces

Development

What is an integration?

The three layers

Your first integration

Documentation structure

Getting help

​What is an integration?

​The three layers

​Your first integration

​Documentation structure

​Getting help

What is an integration?

The three layers

Your first integration

Documentation structure

Getting help