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

# Entrypoints

> The SDK's six published entrypoints, the workspace-only /mcp entrypoint, and what each exports.

The SDK is split across seven entrypoints. Six are published; `@ekanos/sdk/mcp` is workspace-only and not in the published package.

## Root: `@ekanos/sdk`

**Types only.** Every export is a type, so it is importable from client and server code. Contains the integration contract and capability context types.

**Exports** include:

* `IntegrationMetadata` — host-resolved integration metadata (product id, slug, name, category)
* `IntegrationContext` — the `ctx` type
* `StorageSchemas` — schema map types
* Component prop types: `IntegrationComponentProps`, `MarketplaceTileProps`, `ActivationFormProps`
* Data types: `HealthCheckResult`, `ActivationResult`, `IntegrationConfig`

```ts theme={null}
import type { IntegrationMetadata, IntegrationContext } from '@ekanos/sdk';
```

## Components: `@ekanos/sdk/components`

**Client only.** UI components for widgets, forms, and marketplace tiles.

**Exports** include:

* `Widget` — compound component API for dashboard widgets
* `BaseActivationForm` — form wrapper with dialog chrome
* `OAuthActivationForm` — OAuth variant
* `BaseMarketplaceTile` — generic marketplace card
* Context providers: `WidgetContext`, `WidgetPreviewProvider`
* Utilities: `AiPromptChip`, `WidgetAskBar`, `currentReturnPath()`

```tsx theme={null}
import { Widget, WidgetContext } from '@ekanos/sdk/components';
import { BaseActivationForm } from '@ekanos/sdk/components';
```

## Hooks: `@ekanos/sdk/hooks`

**Client only.** Hooks for forms, activation, OAuth, and storage access.

**Exports** include:

* `useActivateIntegration()` — submit the activation form
* `useDeactivateIntegration()` — disconnect
* `useOAuthConnectionStatus()` — check OAuth state
* `useIntegrationAction()` — call widget actions
* `useIntegrationFetch()` / `IntegrationFetchProvider` — the fetch a widget's queries should use (defaults to `globalThis.fetch` outside a provider; no client-side egress enforcement)
* `useActivationData()` / `IntegrationActivationDataProvider` — activation data in widgets (`null` outside a provider)
* `fetchIntegrationStorage()` — read `clientReadable` storage keys
* `partnerOAuthConnectPath()`, `partnerOAuthStatusUrl()` — OAuth flow helpers
* Event bus: `useWidgetEventBus()`, `useWidgetEvents()`

```ts theme={null}
import {
  useActivateIntegration,
  fetchIntegrationStorage,
} from '@ekanos/sdk/hooks';
```

## Context: `@ekanos/sdk/context`

**Isomorphic, dependency-pure.** Error types, validation, and matcher utilities.

**Exports** include:

* Error classes: `EgressDeniedError`, `SecretAccessError`, `StorageValidationError`
* Validators: `assertStorageKeyDeclared()`, `parseStorageValue()`
* Matchers: `isEgressAllowed()`, `isStorageKeyClientReadable()`
* Utilities: `requireContext()`, `resolveStorageKeyDeclaration()`

```ts theme={null}
import { EgressDeniedError, isEgressAllowed } from '@ekanos/sdk/context';
```

## Testing: `@ekanos/sdk/testing`

**Test only.** Mock context and invocation helpers.

**Exports** include:

* `createMockContext()` — in-memory context with schema validation and egress enforcement
* `invokeWebhook()` — run a webhook handler with payload validation
* `invokeSchedule()` — run a schedule handler
* `invokeActivate()` — run an activation hook
* `createMockFetchProvider()` — fixture-backed fetch for widget tests
* Types for recording fetch calls and logs

```ts theme={null}
import { createMockContext, invokeWebhook } from '@ekanos/sdk/testing';
```

## Integration: `@ekanos/sdk/integration`

**Isomorphic, dependency-pure.** Definition authoring, validation, and types.

**Exports** include:

* `defineIntegration()` — define your integration (validates at import time)
* `validateIntegrationDefinitions()` — batch validation and collision detection
* `IntegrationDefinitionSchema` — the canonical zod schema
* Definition types: `PartnerToolModule`, `PartnerWidgetDeclaration`, `PartnerWebhookDeclaration`, `PartnerScheduleDeclaration`, `PartnerOAuthDeclaration`, `PartnerActionDeclaration`, `WebhookSignatureScheme`, `OnActivateHandler`, and related types
* `parseCronExpression()` — validate 5-field cron syntax
* `PublicActionError` — throw from an action handler to show its message to the user verbatim

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

## MCP: `@ekanos/sdk/mcp` — NOT PUBLISHED

**Workspace only, not in the tarball.** This entrypoint is excluded from the published package and cannot be imported from an installed `@ekanos/sdk`.

Tools are declared as `PartnerToolModule` from `@ekanos/sdk/integration`, whose `run` receives only the capability `IntegrationContext`. `/mcp` holds host machinery, not an authoring contract.

<Tip>
  **You do not need this entrypoint to write tools.** Partner tools are declared
  with `tools[]` on your integration definition.
</Tip>

## Import patterns

```ts theme={null}
// Types only — safe from client code
import type { IntegrationContext, IntegrationMetadata } from '@ekanos/sdk';

// Client components
import { Widget } from '@ekanos/sdk/components';

// Client hooks
import { useActivateIntegration } from '@ekanos/sdk/hooks';

// Error classes and matchers (isomorphic)
import { EgressDeniedError } from '@ekanos/sdk/context';

// Authoring (isomorphic)
import { defineIntegration } from '@ekanos/sdk/integration';

// Testing
import { createMockContext } from '@ekanos/sdk/testing';
```

## Summary table

| Entrypoint | Runs on | Main exports | Exports |
| - | - | - | - |
| `@ekanos/sdk` | Anywhere (types) | Integration contract, context types | 32 |
| `/components` | Client | Widget, form, tile components | 24 |
| `/hooks` | Client | useActivateIntegration, useOAuthConnectionStatus, etc. | 43 |
| `/context` | Isomorphic | Errors, validators, matchers | 11 |
| `/testing` | Tests | createMockContext, invokeWebhook, etc. | 17 |
| `/integration` | Isomorphic | defineIntegration, validation, types | 27 |
| `/mcp` | Workspace only | Host machinery (not published) | 13 |

**Total: 167 exported names across 7 entrypoints.**

## Next steps

* [Storage](/sdk/surfaces/storage) — schema-validated state
* [Tools](/sdk/surfaces/tools) — assistant-callable functions
* [Widgets](/sdk/surfaces/widgets) — dashboard components
* [Testing](/sdk/testing) — write unit tests


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