Integration shape

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

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:

The host’s build process, when your package is added to the platform
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 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:

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:

// 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 — what ctx every handler receives
Explore Declarable surfaces — each feature you can declare
Check Naming and validation for all the rules in one table

Getting started

Fundamentals

Declarable surfaces

Development

Basic structure

Required fields

Export name

Schema is strict

Type the storage

Validation timing

Next steps

​Basic structure

​Required fields

​Export name

​Schema is strict

​Type the storage

​Validation timing

​Next steps

Basic structure

Required fields

Export name

Schema is strict

Type the storage

Validation timing

Next steps