> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.ekanos.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> The official SDK for building Ekanos integrations that add widgets, tools, and event handlers to Ekanos.

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

```ts theme={null}
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.