> ## 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.

# Integration shape

> The structure of a defineIntegration() call and its required vs optional fields.

An integration is a single call to `defineIntegration()` that declares everything your package does. The function validates at import time and returns a deep-frozen definition.

## Basic structure

```ts theme={null}
import { defineIntegration } from '@ekanos/sdk/integration';
import type { StorageSchemas } from '@ekanos/sdk';
import { z } from 'zod';

export const myStorage = {
  account: {
    settings: z.object({ region: z.string() }),
  },
  user: {},
} satisfies StorageSchemas;

export type MyStorage = typeof myStorage;

// Define your integration
export const integration = defineIntegration<MyStorage>({
  // Identity — all four required
  slug: 'acme-payments', // kebab-case; the route segment and MCP namespace
  name: 'Acme Payments', // Display name
  description: 'What it does.', // One-liner summary
  version: '1.0.0', // semver

  // Marketing copy for the detail page (optional)
  capabilities: [/* … */],
  permissions: [/* … */],

  // What renders (optional)
  components: {
    widgets: [/* … */],
    marketplaceTile: TileComponent,
    activationForm: FormComponent,
  },

  // What runs (optional)
  tools: [/* … */],
  webhooks: [/* … */],
  schedules: [/* … */],
  oauth: {/* … */},
  actions: {/* … */},
  onActivate: async (ctx) => {
    /* … */
  },

  // What it may touch (optional)
  storage: myStorage,
  egress: ['https://api.acme.example'],

  // What you propose to a reviewer (optional)
  proposes: {/* … */},
});
```

## Required fields

Only four are strictly required:

* **`slug`** — kebab-case identifier, used as the route segment and MCP namespace
* **`name`** — display name for the marketplace and dashboard
* **`description`** — one-line summary (the marketplace's generic card uses it when you ship no tile)
* **`version`** — semver, used by the platform to diff definitions on promotion

Everything else is optional. An integration with only a marketplace tile and no tools is valid. An integration with only tools and no widgets is valid.

## Export name

The export **must be named `integration`**. Two things import it by that name:

1. The host's build process, when your package is added to the platform
2. `ekanos.json`, the small project file the CLI keeps at your root

## Schema is strict

Every key is validated, and unrecognized keys are rejected. You cannot declare fields the platform assigns at runtime:

* `productId`, `kind`, trust tier, `credentialModel`, per-tool `effect`/`sensitivity` — the closest you get is the [`proposes`](/sdk/surfaces/proposes) block
* Widget fields `productId`, `widgetConfigId`, `workspaceId`, `collapsed`, `isPinned`, `health`, `integrationMetadata` — these are set by the host

An extra key is a hard error, not silently ignored. This prevents accidents where you thought you declared something but actually didn't.

## Type the storage

Pass your storage schema as a generic to lock in the types:

```ts theme={null}
export const myStorage = {
  account: {/* … */},
  user: {/* … */},
} satisfies StorageSchemas;

export type MyStorage = typeof myStorage;

export const integration = defineIntegration<MyStorage>({
  storage: myStorage,
  // Now ctx.storage.account.get('key') is typed to your schema
});
```

## Validation timing

Validation happens **at import time**, and the host re-parses the same object against the same schema when it registers you:

```ts theme={null}
// The slug is not kebab-case, so this line throws as soon as the module loads
export const integration = defineIntegration({
  slug: 'invalid slug',
  name: 'Example',
  description: 'Example.',
  version: '1.0.0',
});
```

You get feedback as soon as the module loads, without a separate CLI step.

## Next steps

* Learn about [Capability context](/sdk/capability-context) — what `ctx` every handler receives
* Explore [Declarable surfaces](/sdk/surfaces/storage) — each feature you can declare
* Check [Naming and validation](/sdk/naming-and-validation) for all the rules in one table


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