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

# Changelog

> Release notes for all Ekanos packages

# Changelog

`@ekanos/sdk`, `@ekanos/ui`, and `@ekanos/integration-schema` release in lockstep at the same version. `@ekanos/cli` and `@ekanos/harness` version independently.

<Update label="0.4 release train" description="October 2026 — zod 4, signed-webhook schemes, shared widget chrome, next-intl">
  ### @ekanos/sdk 0.4.0

  * **zod 4 support.** The `zod` peer range is now `^3.25.76 || ^4.0.0`. Partner-facing schema generics (`StorageKeyDeclaration`, `PartnerActionDeclaration`, a webhook's `payloadSchema`) are constrained by Standard Schema instead of `z.ZodType`, so a schema from either zod major satisfies them. `StandardSchemaV1` is exported. Existing definitions compile unchanged. Webhook payloads are validated through `~standard.validate` in the host and in `@ekanos/sdk/testing`. A record key that fails its key schema (an action name, a storage key) reports the key schema's own message again under zod 4, instead of "Invalid key in record".
  * **New: `signature.scheme` for webhooks.** `WebhookSignatureScheme` is re-exported from `@ekanos/sdk/integration`. See [Webhooks](/sdk/surfaces/webhooks).
  * **New: shared widget chrome.** `Widget.Header` renders a ⋯ menu ("Open in workspace", "Refresh", "Pin to board" / "Unpin from board"), takes a new `menu` prop and `Widget.MenuItem` for your own items, the error boundary inside `Widget.Active` offers "Try again", and `Widget.HealthFooter` says when the integration last synced. `Widget.DataState` takes `onRefresh`, `refreshing` and `updatedAt`. New in `@ekanos/sdk/components`: the `WidgetData` type and the optional `WidgetContextValue.data` and `WidgetMeta.openHref` fields. See [Widgets](/sdk/surfaces/widgets).
  * **Changed (breaking outside Ekanos and the harness):** `@ekanos/ui/trans` resolves through next-intl instead of react-i18next. A `NextIntlClientProvider` is now required, `next-intl` (`^4.14.7`) is a new peer, and the `@ekanos/sdk/eslint` preset now bans importing `i18next` and `react-i18next` altogether. See [Runtime notes](/ui/runtime-notes).
  * `PartnerActionDeclaration` is now exported from `@ekanos/sdk/integration`, so you can name the type of an action handler you share with a tool.
  * `partnerOAuthErrorParam` has copy for three more error codes: `app_not_set_up`, `organization_access` and `wrong_workspace`. See [OAuth](/sdk/surfaces/oauth).

  ### @ekanos/integration-schema 0.4.0

  * **New: `webhooks[].signature.scheme`** with `algorithm` (`sha256` | `sha1`), `format` (`digest` | `keyed`), `digestKey`, `timestampKey`, `timestampHeader`, `signedPayload` and `toleranceSeconds`. Cross-field rules are enforced at parse time. Omitting `scheme` keeps the previous behaviour: a bare or `sha256=`-labelled HMAC-SHA256 of the raw body. New exported type `WebhookSignatureScheme`.
  * **zod 4 support**, with the same peer range and Standard Schema constraints as the SDK. `StandardSchemaV1` is exported.

  ### @ekanos/ui 0.4.0

  * **New: `@ekanos/ui/page`** with `PageBody`, `PageRail`, `PageTitleSection`, `PageToolbar` / `PageToolbarActions`, `PageRailTabs`, `PageRailSubTabs`, `PageBackButton`, `PageRangeSwitch` and `PageViewModeToggle`.
  * **New: `@ekanos/ui/status-badge`** (`StatusBadge`) and **`@ekanos/ui/stat`** (`Stat` and its parts).
  * **Changed:** `@ekanos/ui/trans` resolves through next-intl; see the SDK entry above. It is now a client entry (it carries `'use client'`) and no longer accepts an `i18n` instance prop. `i18next` and `react-i18next` are no longer dependencies.
  * **Tokens:** `tokens.css` is generated from Ekanos's design system and checked by value in the build. This fixes a stale `--destructive-strong` and adds the missing `--warning-strong`, `--info-strong` and `--favorite` tokens, with their `text-warning-strong`, `text-info-strong` and `text-favorite` utilities.
  * Overlays use the elevation tiers (dialogs `shadow-modal`, select and dropdown menus `shadow-popover`), and inputs, textareas and select triggers fill with `bg-card`. `@base-ui/react` is bumped to 1.8.0.

  ### @ekanos/harness 0.4.0

  * **Fixed: fixtures-mode actions.** A registry that declared a host-route fixture such as `GET /api/integrations/<slug>/storage` made every `useIntegrationAction()` call answer `500 handler_error` before the handler ran. Host-route fixtures are now skipped on that path. See [Harness actions](/harness/actions).
  * The Triggers tab shows a declared `signature.scheme` as a badge (algorithm, signed payload, keyed pairs, timestamp source and replay window).
  * `RootLayout` mounts a `NextIntlClientProvider`, and `next-intl` (`^4.14.7`) is a new peer dependency. Supports zod 4.

  ### @ekanos/cli 0.3.3

  * The `ekanos init` scaffold pins `@ekanos/sdk`, `@ekanos/ui` and `@ekanos/harness` to `^0.4.0` and `@ekanos/cli` to `^0.3.3`. On 0.x semver `^0.3.0` excludes 0.4.0, so without this a fresh scaffold would install the previous toolchain.
  * The scaffold installs `next-intl` (`^4.14.7`).
  * The scaffold includes a `pnpm-workspace.yaml` approving `esbuild`'s build script (`allowBuilds: { esbuild: true }`). Under pnpm 10+, a project without it fails every `ekanos dev` / `ekanos test` with `ERR_PNPM_IGNORED_BUILDS`, with `ekanos test` blaming the green tests. npm and yarn ignore the file.
  * The generated `AGENTS.md` mentions `signature.scheme` and points at the SDK README's provider table.
  * `ekanos validate`'s "did you mean" suggestions read definitions built with either zod major. The CLI bundles `@ekanos/integration-schema` 0.4.0.
</Update>

<Update label="0.3 release train" description="September 2026 — widget actions">
  ### @ekanos/sdk 0.3.0

  * **New: `useIntegrationAction<TInput, TOutput>(slug, actionName, options)`** in `@ekanos/sdk/hooks` — a react-query mutation that posts to `POST /api/integrations/<slug>/actions/<actionName>`. Also exports the `integrationActionUrl` URL builder.
  * **New: `IntegrationActionError`** — the typed error a rejected action mutation always throws, with `status`, `code`, and (for a 400 `invalid_input`) your zod `issues`.
  * **New: `PublicActionError`** in `@ekanos/sdk/integration` — throw it from an action handler to show its `message` to the user verbatim. Any other throw becomes a generic `"Action failed."` response under the `handler_error` code.

  ### @ekanos/integration-schema 0.3.0

  * **New: `actions`** — a record of widget-invoked, deterministic server handlers keyed by kebab-case name: `{ description, input, output?, handler }`, where `input` (and optional `output`) are real zod schemas.
  * **New: `proposes.scope`** (`'user' | 'team'`) — your declared intent for the integration's scope.

  ### @ekanos/ui 0.3.0

  * Version-lockstep release, no changes.

  ### @ekanos/harness 0.3.0

  * **Actions endpoint** — `ekanos dev` serves `POST /api/integrations/<slug>/actions/<actionName>`, so a widget calling `useIntegrationAction()` runs its declared handler with no extra wiring. Fixtures mode runs it against a mock context and never the real network; live mode uses the same server-held context as live webhooks and schedules.
  * **Live-mode confirmation** — the first action call on an integration while the toolbar is set to Live raises a one-time confirmation for the session. Fixtures mode never prompts.
  * README documents the actions surface and its pinned response codes: `action_not_found`, `invalid_input`, `rate_limited`, `handler_error`.

  ### @ekanos/cli 0.3.2

  * Fixed the `ekanos init` scaffold pinning `@ekanos/sdk`/`@ekanos/ui`/`@ekanos/harness` to `^0.2.0`, which excluded 0.3.0. The template now pins them to `^0.3.0` and `@ekanos/cli` to `^0.3.1`.

  ### @ekanos/cli 0.3.1

  * The scaffold documents the `actions` surface: a new "Actions" section in `AGENTS.md` and a commented example `actions['create-record']` in `src/integration.ts`. Docs and scaffold text only.

  ### @ekanos/cli 0.3.0

  * **Shell contract 2** — `ekanos dev` scaffolds `app/api/integrations/[slug]/[...path]/route.ts`, which serves the live-mode OAuth loop, storage bridge, and trigger route through `@ekanos/harness/api`. Pair with `@ekanos/harness` 0.2.0 or later.
  * `ekanos dev --host <non-loopback>` now sets `EKANOS_HARNESS_EXPOSED=1` after a warning, and `dev` prints where the harness generates `.ekanos/local-secrets.json`.
</Update>

<Update label="0.2 release train" description="September 2026 — client-side fetch, partner OAuth, live-mode OAuth loop">
  ### @ekanos/sdk 0.2.0

  * **New: `useIntegrationFetch()` / `IntegrationFetchProvider`** and **`useActivationData()` / `IntegrationActivationDataProvider`** in `@ekanos/sdk/hooks` — the client-side counterpart to `ctx.fetch`. Outside a provider, `useIntegrationFetch()` is a plain `globalThis.fetch` passthrough and `useActivationData()` returns `null`.
  * **New: `createMockFetchProvider()`** in `@ekanos/sdk/testing`, sharing its fixture matching with `createMockContext`.
  * The `@ekanos/sdk/eslint` preset now names `useIntegrationFetch()` as the remediation for a bare `fetch` in client code.

  ### @ekanos/sdk 0.1.6

  * **Partner OAuth client helpers** in `@ekanos/sdk/hooks`: `partnerOAuthConnectPath`, `partnerOAuthStatusUrl`, `createPartnerConnectionCheck`, and `partnerOAuthErrorParam`, for use with `OAuthActivationForm`.
  * The host now runs the OAuth flow at `/api/integrations/<slug>/oauth/{connect,callback,status}`, and the submission gate accepts `oauth` declarations. Known gaps: no host-driven token refresh, no disconnect hook, HTTP Basic token-endpoint auth only.

  ### @ekanos/sdk 0.1.5

  * **New: `Widget.Body`** — a padded body container for use inside `Widget.Active`, whose content area is flush by design.

  ### @ekanos/sdk and @ekanos/integration-schema 0.1.4

  * **New: `onActivate`** — an optional `(ctx) => Promise<void>` hook that runs after an activation is first persisted and again after activation data is updated. Errors are non-fatal. The production host does not call it yet.
  * **New: `invokeActivate()`** in `@ekanos/sdk/testing`.

  ### @ekanos/ui and @ekanos/integration-schema 0.2.0, 0.1.6, 0.1.5

  * Version-lockstep releases, no changes.

  ### @ekanos/harness 0.2.0

  * **Local OAuth loop** — live mode runs the real authorize → callback → `onTokens` loop on localhost through the new `@ekanos/harness/api` entry (`createHarnessApiHandlers(registry)`), with admin-tier credentials in a gitignored `.ekanos/local-secrets.json` filled in from the Activation surface.
  * Fixtures mode answers `oauth/status` from a new `oauth.connected` entry field (connected by default).
  * New `live.default: 'live'` opens an integration in Live API mode.
  * API routes refuse non-loopback `Host` headers unless `EKANOS_HARNESS_EXPOSED=1`.

  ### @ekanos/harness 0.1.5

  * `HarnessProviders` mounts the SDK's `IntegrationFetchProvider` and `IntegrationActivationDataProvider` around every widget, so `useIntegrationFetch()` works with no partner-written `FetchProvider`. `HarnessLiveMode.FetchProvider` is now `@deprecated` but still works.

  ### @ekanos/harness 0.1.4

  * The Triggers surface's OAuth card explains the hosted OAuth transport and the host-derived redirect URI.

  ### @ekanos/harness 0.1.3

  * Same-origin `/api/…` requests are answered from fixtures in every toolbar mode; a miss throws `NoRecordedResponseError` in both modes.
  * `HarnessLiveMode.FetchProvider` receives `mode` and `activationData` props.
  * **New entry point `@ekanos/harness/hooks`**, exporting `useHarnessDataMode()` and `useLiveActivationData()`.

  ### @ekanos/cli 0.2.3

  * Fixed the `ekanos init` template pinning the old `^0.1.0` toolchain, which made a fresh scaffold's install fail with ERESOLVE.

  ### @ekanos/cli 0.2.2

  * Scaffolded `AGENTS.md` names `useIntegrationFetch()`/`useActivationData()` as the widget networking seam and adds a "Network model" note. Template text only.

  ### @ekanos/cli 0.2.0

  * **Redesigned findings output** for `validate`, `publish`'s gate refusal, and `status --findings`: grouped by check, severity-ordered, with codeframes where a source line can be resolved. `ekanos test` adds a `FAILURES` appendix for vitest; `--raw` skips it.
  * **Project-scoped `ekanos status`** — shows this project's versions, with other integrations in the source summarized (`--all` expands them).
  * **Line numbers and "did you mean" suggestions** on `validate` findings.
  * **Interactive `init` and `login`** in a real terminal; CI, `--json`, and piped output are unaffected.
  * **Scaffold hardening** — `tsconfig.json` sets `noUncheckedIndexedAccess`; `validate` warns when it is missing (`project.host-compiler-rules`) and `publish` refuses. A pre-commit hook runs `ekanos validate` (skip with `SKIP_EKANOS_HOOK=1`).
  * `--json` output is unchanged apart from additive fields on `status` and `test`.
</Update>

<Update label="0.1 releases" description="August–September 2026">
  ### @ekanos/cli 0.1.10

  * `ekanos publish` now packs root-level `tsconfig*.json` and vitest/vite config files, which the hosted gate's `checks/typecheck` and `checks/tests` stages need. Upgrade and republish for the fix to take effect.

  ### @ekanos/cli 0.1.9

  * The `ekanos init` scaffold declares `@ekanos/harness`, `tailwindcss`, and `@tailwindcss/postcss` as devDependencies, so the first `ekanos dev` works.
  * **New advisory check `icons/pro-only`** — warns on Font Awesome names not in the Free set.

  ### @ekanos/cli 0.1.8

  * `ekanos status` shows the gate's verdict per version; `--findings` lists every finding; `--watch` blocks until the current version reaches `gated`/`dev` (exit 0) or `rejected` (exit 10).

  ### @ekanos/cli 0.1.7

  * `ekanos.json` accepts an optional `docs` array, written by the repeatable `ekanos init --docs <value>` flag. `init` also scaffolds `docs/api-notes.md` and `.mcp.json`. `validate` warns with `docs/missing-file` for a listed local doc that does not exist.

  ### @ekanos/sdk and @ekanos/ui 0.1.1

  * `BaseMarketplaceTile` imports `next/link.js`, so the SDK loads under plain Node and vitest.
  * `Trans` renders its `defaults` string when no i18next instance is registered.
  * Package metadata: dead `repository`/`homepage` links removed; `bugs` is `npm@govastly.com`.
</Update>

## Migration guide

### 0.3 → 0.4

Run `npm i -g @ekanos/cli@latest`, then `ekanos upgrade` in the project. On 0.x semver `^0.3.0` excludes 0.4.0, so the pins must move. What to check:

1. **Add `next-intl`.** `@ekanos/ui` and `@ekanos/harness` now require `next-intl` (`^4.14.7`) as a peer. Projects from `ekanos init` 0.3.3 already have it.
2. **`<Trans>` outside Ekanos and the harness** needs a `NextIntlClientProvider` above it (for a Storybook or a bare unit test: `<NextIntlClientProvider locale="en" messages={{}} timeZone="UTC">`). Remove any `i18n` prop passed to `Trans`, and any `i18next` / `react-i18next` imports, which the ESLint preset now bans.
3. **zod**: nothing to do. Zod 3 (`^3.25.76`) keeps working; zod 4 is now accepted.
4. **pnpm 10+**: add `pnpm-workspace.yaml` with `allowBuilds: { esbuild: true }` if the project predates CLI 0.3.3.
5. Everything else is additive: `signature.scheme`, `Widget.MenuItem`, `Widget.DataState`'s `onRefresh` / `refreshing` / `updatedAt`, `@ekanos/ui/page`, `status-badge` and `stat`.

### 0.2 → 0.3

No breaking changes. The `actions` surface is optional. To add an action:

1. Declare it under `actions` in `defineIntegration()`
2. Call it from your widget with `useIntegrationAction()`
3. Handle `IntegrationActionError` in the mutation's error path

For a project scaffolded by CLI 0.3.0 or 0.3.1, make sure `@ekanos/sdk`, `@ekanos/ui`, and `@ekanos/harness` resolve to `^0.3.0` — `ekanos upgrade` does this. (Current projects move on to `^0.4.0`; see 0.3 → 0.4 above.)

### Existing projects from before CLI 0.2.0

Add `"noUncheckedIndexedAccess": true` to `compilerOptions` in `tsconfig.json` — `ekanos publish` refuses to submit until it is set.

## Support

* **Report bugs** — Email [npm@govastly.com](mailto:npm@govastly.com) with details
* **Check version** — `ekanos --version`
* **Upgrade safely** — `ekanos upgrade` verifies and rolls back automatically


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