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

# Exports

> Reference for all @ekanos/harness entry points.

## Main entries

### `@ekanos/harness/registry`

Types and helpers for building your `harness.config.ts`. Server-safe.

<ParamField body="HarnessIntegration" type="interface">
  Your registry entry: `slug`, `name`, `description`, `widgets`, plus optional
  `fixtures`, `tile`, `activationForm`, `definition`, `triggerMocks`, `live`,
  `oauth`.
</ParamField>

<ParamField body="HarnessWidget" type="interface">
  One widget to render: `id`, `title`, `component`, plus optional `width`,
  `isCollapsible`, `isPinnable`, `aiFooterEnabled`, `seeds`.
</ParamField>

<ParamField body="HttpFixture" type="interface">
  One recorded HTTP exchange: `request` (method + URL), `response`, `status`,
  `headers`.
</ParamField>

<ParamField body="FixtureSeed" type="interface">
  React-query cache seed: `queryKey`, and either `data` or `error`.
</ParamField>

<ParamField body="FixtureVariant" type="'default' | 'empty' | 'error'">
  The three fixture variants switchable from the toolbar.
</ParamField>

<ParamField body="HarnessLiveMode" type="interface">
  Live mode config: `seeds` (react-query keys that stay mocked in live mode),
  `default` (`'live'` to open in live mode until the toolbar is changed),
  `egress` (only for an entry with no `definition`), `FetchProvider`
  (deprecated; for composing an authenticated fetch once).
</ParamField>

<ParamField body="HarnessTriggerMocks" type="interface">
  Fixtures-mode mock context for triggers and actions: `storage`
  (`account`/`user` rows), `secrets` (`account`/`admin` tiers), `fetchHandlers`
  (dynamic or stateful responses).
</ParamField>

<ParamField body="HARNESS_ACCOUNT_ID" type="string">
  Plausible UUID for `accountId` context.
</ParamField>

<ParamField body="HARNESS_SOURCE_ID" type="string">
  Plausible UUID for `sourceId` context.
</ParamField>

<ParamField body="HARNESS_ACCOUNT_SLUG" type="string">
  Plausible slug for account context.
</ParamField>

<ParamField body="FIXTURE_VARIANTS" type="readonly string[]">
  `['default', 'empty', 'error']` — all valid variant names.
</ParamField>

<ParamField body="DataMode / DATA_MODES" type="'fixtures' | 'live'">
  The two toolbar data modes.
</ParamField>

<ParamField body="harnessWidgetsFromDefinition(definition, overrides?)" type="function">
  Derive `HarnessWidget[]` from your definition to avoid duplication. The
  overrides map, keyed by widget id, supplies harness-only fields (`width`,
  `seeds`); an unknown key throws.
</ParamField>

<ParamField body="asHarnessDefinition(definition)" type="function">
  Erase the storage generic so your `IntegrationDefinition<S>` fits in the heterogeneous registry array.
</ParamField>

### `@ekanos/harness/config`

<ParamField body="defineHarnessConfig(integrations)" type="function">
  Identity function that exists for type inference. Also throws if a slug or
  widget id is not URL-safe, or if one is duplicated.
</ParamField>

### `@ekanos/harness/app`

Components and metadata mounted by the generated shell. The entry itself carries no `'use client'` directive.

<ParamField body="RootLayout" type="component">
  The client boundary of the whole harness; mounts the providers and the
  registry context. Props: `integrations: HarnessIntegration[]`, `children`.
</ParamField>

<ParamField body="IndexPage" type="component">
  Landing page listing all integrations. Props: `integrations:
      HarnessIntegration[]`.
</ParamField>

<ParamField body="harnessMetadata" type="Metadata">
  A Next.js `Metadata` object for the shell's layout.
</ParamField>

### `@ekanos/harness/routes`

Client page components (the entry is `'use client'`) re-exported by the shell's one-line route files, for example `export { WidgetsPage as default } from '@ekanos/harness/routes';`.

<ParamField body="IntegrationLayout" type="component">
  Wrapper for integration pages (`/<slug>/`). Renders tabs and nav.
</ParamField>

<ParamField body="WidgetsPage" type="component">
  Dashboard grid with all widgets.
</ParamField>

<ParamField body="SingleWidgetPage" type="component">
  Single widget in isolation at `/<slug>/widgets/<widgetId>`.
</ParamField>

<ParamField body="TilePage" type="component">
  Marketplace tile, rendered in the catalogue grid.
</ParamField>

<ParamField body="ActivationPage" type="component">
  Activation form and OAuth panel.
</ParamField>

<ParamField body="TriggersPage" type="component">
  Webhooks, schedules, OAuth declaration, and Local OAuth panel.
</ParamField>

### `@ekanos/harness/hooks`

Hooks for code that only ever runs inside the harness (a debug banner, a dev-only branch), never a widget's shipped data path. For activation data in widget code, prefer `useActivationData()` from `@ekanos/sdk/hooks`.

<ParamField body="useHarnessDataMode()" type="'fixtures' | 'live'">
  Returns the EFFECTIVE data mode (accounting for a missing `live` block or
  egress mismatch forcing fixtures).
</ParamField>

<ParamField body="useLiveActivationData()" type="unknown">
  Returns the activation data last submitted for this integration. Held in
  memory only, never written to `localStorage`, a fixture, or the registry;
  cleared on reload and on Disconnect.
</ParamField>

### `@ekanos/harness/api`

Server-only entry. Never import from a `'use client'` module.

<ParamField body="createHarnessApiHandlers(integrations, deps?)" type="function">
  Returns `{ GET, POST, PUT }` route handlers for the shell's one API route. Serves `oauth/{connect,callback,status}`, `storage`, `trigger`, `local-setup`, and `actions/<actionName>` under `/api/integrations/[slug]/`. See [Live Mode](/harness/live-mode#api-routes-available).
</ParamField>

<ParamField body="HarnessApiHandlers" type="interface">
  `{ GET: NextRouteHandler, POST: NextRouteHandler, PUT: NextRouteHandler }`
</ParamField>

<ParamField body="NextRouteHandler" type="type">
  `(request: Request, context: { params: Promise<HarnessRouteParams> }) => Promise<Response>`
</ParamField>

### `@ekanos/harness/styles.css`

Tailwind layer, design tokens, Font Awesome repairs, and `@source` globs covering the harness chrome.

### `@ekanos/harness/mocks/team-account-workspace`

Stand-in for the host's `useTeamAccountWorkspace()`. The generated `next.config.mjs` aliases `@kit/team-accounts/hooks/use-team-account-workspace` onto it, so unmodified widget source runs unchanged.

## Data modes

### `DataMode`

```ts theme={null}
type DataMode = 'fixtures' | 'live';
```

Exported from `@ekanos/harness/registry`. Returned by `useHarnessDataMode()` and passed as the `mode` prop to a `live.FetchProvider`.

## Errors you will see

These are not exported by `@ekanos/harness`; match them by `error.name`.

### `NoRecordedResponseError`

Thrown (as a rejected `fetch`) when a request has no matching fixture. Carries `method` and `url` (credentials redacted), and its message includes the fixture line to paste. See [Fixtures](/harness/fixtures#no-fixture-found).

### `MissingFixtureError`

Thrown when a react-query query has neither a seed nor a `queryFn` of its own.

### `EgressDeniedError`

From `@ekanos/sdk/context`. Thrown in live mode when a request targets an origin outside the declared `egress`. Carries `origin`, an optional `reason`, and `code: 'EGRESS_DENIED'`.

### `LiveActionNotConfirmedError`

Thrown when a live-mode action's confirmation prompt is declined. See [Actions](/harness/actions#session-confirmation).

## Handler context

Webhook, schedule, action, `onActivate`, and `onTokens` handlers receive the SDK's `IntegrationContext` (exported as a type from `@ekanos/sdk`): `accountId`, `accountSlug`, `userId`, `actor`, `sourceId`, `integration`, `timezone`, `storage`, `secrets`, `fetch`, and `logger`. In fixtures mode it is a `createMockContext()` context; in live mode, the server-held live context.

## TypeScript

The published package ships its types in `dist/*.d.ts`. To check your `harness.config.ts`, run `npx tsc --noEmit` in your project.


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