# Ekanos SDK

> Build, test, and publish Ekanos integrations with the @ekanos/* packages.

- [Ekanos Integration SDK](https://sdk.ekanos.dev/index.md): Build Ekanos integrations with widgets, tools, webhooks, and more
- [Quickstart](https://sdk.ekanos.dev/quickstart.md): Zero to a running integration in minutes using the Ekanos CLI
- [How integrations are structured](https://sdk.ekanos.dev/concepts/structure.md): The anatomy of an Ekanos integration and how it's organized
- [Surfaces at a glance](https://sdk.ekanos.dev/concepts/surfaces.md): Quick reference for widgets, tools, webhooks, schedules, and actions
- [The development lifecycle](https://sdk.ekanos.dev/concepts/lifecycle.md): From scaffolding through publishing your integration
- [Common errors and how to fix them](https://sdk.ekanos.dev/troubleshooting/common-errors.md): Real errors you might hit and their solutions
- [Frequently asked questions](https://sdk.ekanos.dev/troubleshooting/faq.md): Answers to common questions about building Ekanos integrations
- [Overview](https://sdk.ekanos.dev/sdk/overview.md): The official SDK for building Ekanos integrations that add widgets, tools, and event handlers to Ekanos.
- [Installation](https://sdk.ekanos.dev/sdk/installation.md): Install @ekanos/sdk and declare its required peer dependencies.
- [What is published](https://sdk.ekanos.dev/sdk/what-is-published.md): The @ekanos packages on npm and what each one is for.
- [Integration shape](https://sdk.ekanos.dev/sdk/integration-shape.md): The structure of a defineIntegration() call and its required vs optional fields.
- [Capability context (ctx)](https://sdk.ekanos.dev/sdk/capability-context.md): The platform surface every server-side handler receives — storage, secrets, fetch, logging, and actor info.
- [Entrypoints](https://sdk.ekanos.dev/sdk/entrypoints.md): The SDK's six published entrypoints, the workspace-only /mcp entrypoint, and what each exports.
- [Storage](https://sdk.ekanos.dev/sdk/surfaces/storage.md): Schema-validated per-account and per-user state with client-readable opt-in and expiry support.
- [Egress](https://sdk.ekanos.dev/sdk/surfaces/egress.md): The HTTPS origin allowlist that ctx.fetch enforces before opening a socket.
- [Secrets](https://sdk.ekanos.dev/sdk/surfaces/secrets.md): Credential management with tier-based access control (account, source, global).
- [Tools](https://sdk.ekanos.dev/sdk/surfaces/tools.md): Assistant-callable functions with JSON Schema parameters and structured error responses.
- [Actions](https://sdk.ekanos.dev/sdk/surfaces/actions.md): Widget-invoked server handlers: declare actions, call them with useIntegrationAction, handle IntegrationActionError, and call vendors from the browser with useIntegrationFetch.
- [Widgets](https://sdk.ekanos.dev/sdk/surfaces/widgets.md): Dashboard cards that render through the Widget compound API with automatic data state handling.
- [Marketplace tile](https://sdk.ekanos.dev/sdk/surfaces/marketplace-tile.md): The card users see in the integration marketplace before connecting.
- [Activation form](https://sdk.ekanos.dev/sdk/surfaces/activation-form.md): Connect form where users provide credentials and configuration data.
- [Capabilities and permissions](https://sdk.ekanos.dev/sdk/surfaces/capabilities-and-permissions.md): Marketing copy for the integration detail page read by users and security reviewers.
- [Webhooks](https://sdk.ekanos.dev/sdk/surfaces/webhooks.md): Inbound event handlers from external services with signature validation and schema validation.
- [Schedules](https://sdk.ekanos.dev/sdk/surfaces/schedules.md): Cron-driven handlers that run on a schedule with proper idempotency and skip handling.
- [On-activate](https://sdk.ekanos.dev/sdk/surfaces/on-activate.md): Hook that runs after activation for cache seeding and eager validation — not a connect gate.
- [OAuth](https://sdk.ekanos.dev/sdk/surfaces/oauth.md): Declare OAuth provider details; the transport owns the flow and calls onTokens to persist tokens.
- [Proposes](https://sdk.ekanos.dev/sdk/surfaces/proposes.md): Suggest security classifications that a reviewer confirms during promotion.
- [Workspace targets](https://sdk.ekanos.dev/sdk/surfaces/workspace-targets.md): Named dashboard sections that integrations ship with (a first-party surface; partners should not set it).
- [Testing](https://sdk.ekanos.dev/sdk/testing.md): Write unit tests for handlers using createMockContext, invokeWebhook, invokeSchedule, and invokeActivate.
- [Styling](https://sdk.ekanos.dev/sdk/styling.md): Load the @ekanos/ui token layer and use semantic Tailwind tokens so your components match Ekanos.
- [Naming and validation](https://sdk.ekanos.dev/sdk/naming-and-validation.md): Naming rules for all fields with exact regex patterns and examples.
- [Known limitations](https://sdk.ekanos.dev/sdk/known-limitations.md): Current rough edges in the SDK, with workarounds where available.
- [CLI Overview](https://sdk.ekanos.dev/cli/overview.md): Ekanos CLI scaffolds, validates, tests, and publishes Ekanos integrations from any Node project.
- [Commands Reference](https://sdk.ekanos.dev/cli/commands.md): Complete reference for every ekanos CLI command with flags and examples.
- [ekanos.json Configuration](https://sdk.ekanos.dev/cli/ekanos-json.md): Complete reference for ekanos.json configuration file fields and structure.
- [JSON Output & Exit Codes](https://sdk.ekanos.dev/cli/json-output-and-exit-codes.md): JSON envelope format and exit code taxonomy for the ekanos CLI.
- [Authentication](https://sdk.ekanos.dev/cli/authentication.md): Ekanos CLI authentication flow, credential storage, and host resolution.
- [Publishing & Target Verification](https://sdk.ekanos.dev/cli/publishing.md): Safe publish workflows with seat verification to prevent publishing to wrong sources.
- [Keeping the Toolchain Current](https://sdk.ekanos.dev/cli/updating.md): Updating the CLI and SDK packages to coherent versions with safety guarantees.
- [Overview](https://sdk.ekanos.dev/harness/overview.md): Render your integration's surfaces locally in real Ekanos chrome, with fixtures or live requests to your own API.
- [Configuration](https://sdk.ekanos.dev/harness/configuration.md): Build your harness.config.ts registry entry, defining widgets, fixtures, and live mode behavior.
- [Fixtures](https://sdk.ekanos.dev/harness/fixtures.md): Record HTTP exchanges to mock vendor APIs without network requests.
- [Live Mode](https://sdk.ekanos.dev/harness/live-mode.md): Run real requests against your own API with a localhost OAuth loop and live credentials.
- [Triggers](https://sdk.ekanos.dev/harness/triggers.md): Test webhooks, schedules, and OAuth handlers locally.
- [Actions](https://sdk.ekanos.dev/harness/actions.md): Invoke declared action handlers from a widget's Save button.
- [Exports](https://sdk.ekanos.dev/harness/exports.md): Reference for all @ekanos/harness entry points.
- [Overview](https://sdk.ekanos.dev/ui/overview.md): Ekanos-styled UI primitives for building integrations outside the Ekanos monorepo.
- [Components](https://sdk.ekanos.dev/ui/components.md): Complete list of all exported UI components.
- [Styling](https://sdk.ekanos.dev/ui/styling.md): Configure component styling, themes, and design tokens.
- [Fonts & Icons](https://sdk.ekanos.dev/ui/fonts-and-icons.md): Set up typography and Font Awesome for your integration.
- [Runtime Notes](https://sdk.ekanos.dev/ui/runtime-notes.md): Client/server boundaries, next-intl integration, and other implementation details.
- [Schema Overview](https://sdk.ekanos.dev/schema/overview.md): The canonical dependency-pure contract for Ekanos integration definitions.
- [Schema Reference](https://sdk.ekanos.dev/schema/reference.md): Complete reference of exported types, schemas, and utilities from @ekanos/integration-schema.
- [Changelog](https://sdk.ekanos.dev/changelog.md): Release notes for all Ekanos packages


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