@ekanos/harness 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -980,6 +980,74 @@ triggerMocks: {
980
980
  There is no Supabase and no network in here either way. Keep the values fake —
981
981
  see the bundle note below.
982
982
 
983
+ ## Actions — invoking declared server handlers from a widget
984
+
985
+ `useIntegrationAction()` (`@ekanos/sdk/hooks`) is the write counterpart to
986
+ `useIntegrationFetch()`/`fetchIntegrationStorage()`: a widget's Save button
987
+ posts the user's own typed values straight to a declared `actions[name]`
988
+ handler — deterministic, no assistant, no natural-language round trip.
989
+ Unlike a widget's read path, there is no client-side mock to short-circuit —
990
+ the hook always makes a real `fetch()` — so the harness answers
991
+ `POST /api/integrations/<slug>/actions/<actionName>` itself, in BOTH modes,
992
+ over the same local API router that already serves storage, OAuth, webhooks
993
+ and schedules (`createHarnessApiHandlers`). What differs between modes is
994
+ which context resolves the call, exactly as it does for Triggers above:
995
+
996
+ - **Fixtures (default).** The route validates the posted input against the
997
+ action's declared `input` schema exactly like production, then runs
998
+ `handler(ctx, input)` against one `createMockContext()` — the identical
999
+ mechanism `invokeWebhook`/`invokeSchedule` already use. An action is
1000
+ executed the same way a trigger is; it's just invoked from a rendered
1001
+ widget's own Save button instead of the Triggers page's "Run now".
1002
+ - **Live (opt-in).** The route runs the handler against the same
1003
+ **server-held live context** per integration that OAuth and live schedules
1004
+ already use — its `ctx.fetch` reaches your real vendor under the
1005
+ definition's declared `egress`, with credentials from
1006
+ `.ekanos/local-secrets.json` or whatever `onTokens`/the activation form
1007
+ stored. Requires the entry's `live` block, same as every other live
1008
+ surface — an integration with no `live` block stays on fixtures for its
1009
+ actions exactly as it does for triggers.
1010
+
1011
+ ### The session confirm
1012
+
1013
+ An action is a write, and unlike Triggers' dedicated "Run now" button, it
1014
+ fires from **ordinary widget interaction** — a partner debugging an
1015
+ unrelated CSS issue on the same widget while the toolbar happens to be on
1016
+ Live could otherwise trigger a real vendor write without meaning to touch
1017
+ data at all. So the first `useIntegrationAction()` call in a dev-server
1018
+ session while the toolbar's **Data** mode is Live raises a confirmation
1019
+ ("This will run against real `<vendor>` data") before it reaches the live
1020
+ context; acknowledging it ("allow for this session") lets every subsequent
1021
+ action call that session proceed without asking again. Reloading the page or
1022
+ restarting the dev server resets it, same as the live connection itself.
1023
+
1024
+ **This is a harness convenience for accidental clicks during iteration, not
1025
+ a production security boundary.** Production runs exactly one mode — there
1026
+ is no fixtures/live toggle and no per-session confirmation to bypass — and
1027
+ enforces the real thing through `ctx.fetch`'s egress allowlist regardless of
1028
+ anything the toolbar or this confirm ever did. Do not describe the
1029
+ per-session confirm to a partner as protection that carries over once the
1030
+ integration is published.
1031
+
1032
+ ### Pinned error codes
1033
+
1034
+ The route answers the same fixed `code`s the production host route does, so
1035
+ a widget's error handling written against the harness behaves identically
1036
+ once it ships for real: `action_not_found` (404, unknown action name),
1037
+ `invalid_input` (400, with the partner's own zod `issues`), `rate_limited`
1038
+ (429), and `handler_error` (500 — a handler threw, or its result failed the
1039
+ optional `output` schema; opaque by default). A handler that throws
1040
+ `PublicActionError` (`@ekanos/sdk/integration`) gets its own `message` shown
1041
+ verbatim under that same `handler_error` code — the one escape hatch from
1042
+ the generic message. `useIntegrationAction()`'s rejected mutation always
1043
+ surfaces these as a typed `IntegrationActionError` (`status`, `code`,
1044
+ `issues?`), plus two transport-only codes the hook assigns itself —
1045
+ `network_error` / `invalid_response` — for a request that never reached a
1046
+ valid envelope at all. The harness does not itself enforce the production
1047
+ rate limiter (there is exactly one developer hitting this route locally);
1048
+ it recognizes and can answer `rate_limited` the same way, but nothing here
1049
+ exercises it under normal use.
1050
+
983
1051
  ## What ends up in the browser bundle
984
1052
 
985
1053
  **Everything in your registry does, including `triggerMocks.secrets`.**
@@ -1,10 +1,16 @@
1
1
  import { type ReactNode } from 'react';
2
- import type { DataMode, FixtureSeed, HarnessLiveMode } from '../../registry.js';
2
+ import type { DataMode, FixtureSeed, FixtureVariant, HarnessLiveMode } from '../../registry.js';
3
3
  import type { CompiledFixture } from '../lib/http-fixtures.js';
4
- export declare function HarnessProviders({ seeds, mode, live, egress, httpFixtures, slug, children, }: {
4
+ export declare function HarnessProviders({ seeds, mode, variant, live, egress, httpFixtures, slug, children, }: {
5
5
  seeds: FixtureSeed[];
6
6
  /** `fixtures` (default) or `live`. See `lib/harness-query-client.ts`. */
7
7
  mode?: DataMode;
8
+ /**
9
+ * The active fixture variant — forwarded to the routing table so a
10
+ * server-reached `actions/` call (see `harness-fetch-interceptor.ts`) can
11
+ * read the SAME `HttpFixture[]` the rest of this render is using.
12
+ */
13
+ variant?: FixtureVariant;
8
14
  /** The integration's live-mode descriptor, when it declares one. */
9
15
  live?: HarnessLiveMode;
10
16
  /** Origins live mode may reach — resolved centrally, see `resolveEgress`. */
@@ -51,6 +51,7 @@ const fixtureActivationActions = {
51
51
  function HarnessProviders({
52
52
  seeds,
53
53
  mode = "fixtures",
54
+ variant = "default",
54
55
  live,
55
56
  egress,
56
57
  httpFixtures,
@@ -77,6 +78,7 @@ function HarnessProviders({
77
78
  publishHarnessRouting({
78
79
  mode,
79
80
  slug,
81
+ variant,
80
82
  fixtures: httpFixtures,
81
83
  egress: mode === "live" ? egress : [],
82
84
  onCall: ({ url, method, outcome }) => {
@@ -87,7 +89,7 @@ function HarnessProviders({
87
89
  console.info(`[harness:${slug}] ${outcome} ${method} ${url}`);
88
90
  }
89
91
  });
90
- }, [mode, httpFixtures, egress, slug]);
92
+ }, [mode, variant, httpFixtures, egress, slug]);
91
93
  const FetchProvider = live?.FetchProvider;
92
94
  const tree = /* @__PURE__ */ jsx(IntegrationFetchProvider, { fetch: harnessFetch, children: /* @__PURE__ */ jsx(IntegrationActivationDataProvider, { value: activationData, children: /* @__PURE__ */ jsx(QueryClientProvider, { client: queryClient, children: /* @__PURE__ */ jsx(TeamAccountWorkspaceContextProvider, { children: /* @__PURE__ */ jsx(IntegrationActivationProvider, { actions: fixtureActivationActions, children: /* @__PURE__ */ jsx(WidgetEventProvider, { children: /* @__PURE__ */ jsxs(AskAssistantProvider, { children: [
93
95
  /* @__PURE__ */ jsx(AskAssistantBridge, {}),
@@ -0,0 +1,30 @@
1
+ /**
2
+ * ─────────────────────────────────────────────────────────────────────────────
3
+ * THE ONE THING THE BROWSER TELLS THE SERVER ABOUT ITSELF, FOR ACTIONS ONLY
4
+ * ─────────────────────────────────────────────────────────────────────────────
5
+ *
6
+ * Every other harness surface (`storage`, `trigger`, `oauth/*`) decides
7
+ * fixtures vs. live BEFORE it ever reaches the network: fixtures-mode
8
+ * triggers run entirely in the browser (`createLocalTriggerRunner` +
9
+ * `useDefinitionMockContext`), and the server route only exists for the
10
+ * live half of that split, so it never needed to ask which mode is active —
11
+ * being reached at all meant live.
12
+ *
13
+ * `useIntegrationAction` breaks that pattern on purpose (the widget-actions
14
+ * design decision): it always makes a real `fetch()`, in both modes, because a
15
+ * production widget has no browser-side execution path to fall back to —
16
+ * there is no admin-secret-bearing context in a browser tab. So the
17
+ * harness's actions route is reached in BOTH modes, and unlike every route
18
+ * before it, has to be told which one is live right now.
19
+ *
20
+ * These two headers are that seam. They are written by
21
+ * `harness-fetch-interceptor.ts`, which already holds `active.mode` and
22
+ * `active.variant` at the exact moment it decides to let an actions request
23
+ * through, and read by `internal/server/api-router.ts`'s action handler.
24
+ * Neither is a production concept — they never leave this process, an
25
+ * absent or garbled value on the server side falls back to fixtures (never
26
+ * to live), and no real Fusion host route reads either header because a
27
+ * real host route has no "mode" to be told.
28
+ */
29
+ export declare const HARNESS_ACTIONS_MODE_HEADER = "x-ekanos-harness-data-mode";
30
+ export declare const HARNESS_ACTIONS_VARIANT_HEADER = "x-ekanos-harness-fixture-variant";
@@ -0,0 +1,6 @@
1
+ const HARNESS_ACTIONS_MODE_HEADER = "x-ekanos-harness-data-mode";
2
+ const HARNESS_ACTIONS_VARIANT_HEADER = "x-ekanos-harness-fixture-variant";
3
+ export {
4
+ HARNESS_ACTIONS_MODE_HEADER,
5
+ HARNESS_ACTIONS_VARIANT_HEADER
6
+ };
@@ -1,4 +1,4 @@
1
- import type { HttpFixture } from '../../registry.js';
1
+ import type { FixtureVariant, HttpFixture } from '../../registry.js';
2
2
  import { type CompiledFixture, NoRecordedResponseError } from './http-fixtures.js';
3
3
  /**
4
4
  * ─────────────────────────────────────────────────────────────────────────────
@@ -88,6 +88,13 @@ export interface HarnessRoutingTable {
88
88
  * absent (the fail-closed default), nothing passes.
89
89
  */
90
90
  slug?: string;
91
+ /**
92
+ * The active fixture variant. Forwarded to the server on an `actions/`
93
+ * call (see below) so the harness's fixtures-mode actions context reads
94
+ * the same `HttpFixture[]` the rest of the surface is rendering from.
95
+ * Meaningless outside that one path. Defaults to `'default'` when absent.
96
+ */
97
+ variant?: FixtureVariant;
91
98
  /** Compiled fixtures for the active variant. */
92
99
  fixtures: readonly CompiledFixture[];
93
100
  /** Origins live mode may reach. Empty in fixtures mode. */
@@ -98,6 +105,18 @@ export interface HarnessRoutingTable {
98
105
  method: string;
99
106
  outcome: 'fixture' | 'network' | 'refused';
100
107
  }) => void;
108
+ /**
109
+ * Test seam for the live-actions confirmation prompt (see
110
+ * `confirmLiveAction` below). Defaults to `globalThis.confirm`.
111
+ */
112
+ confirm?: (message: string) => boolean;
113
+ }
114
+ /** Test seam: forget every live-actions confirmation, as a fresh session would. */
115
+ export declare function resetLiveActionConfirmations(): void;
116
+ export declare class LiveActionNotConfirmedError extends Error {
117
+ readonly slug: string;
118
+ readonly actionName: string;
119
+ constructor(slug: string, actionName: string);
101
120
  }
102
121
  /**
103
122
  * Publish the table the interceptor answers from.
@@ -1,5 +1,9 @@
1
1
  "use client";
2
2
  import { EgressDeniedError, isEgressAllowed } from "@ekanos/sdk/context";
3
+ import {
4
+ HARNESS_ACTIONS_MODE_HEADER,
5
+ HARNESS_ACTIONS_VARIANT_HEADER
6
+ } from "./actions-transport.js";
3
7
  import {
4
8
  NoRecordedResponseError,
5
9
  fixtureResponse,
@@ -13,6 +17,62 @@ const CLOSED = {
13
17
  };
14
18
  let active = CLOSED;
15
19
  let installed = false;
20
+ const CONFIRMED_KEY_PREFIX = "ekanos-harness-live-action-confirmed:";
21
+ const confirmedInMemory = /* @__PURE__ */ new Set();
22
+ function readSessionStorage() {
23
+ try {
24
+ return globalThis.sessionStorage;
25
+ } catch {
26
+ return void 0;
27
+ }
28
+ }
29
+ function isLiveActionConfirmed(slug) {
30
+ if (confirmedInMemory.has(slug)) return true;
31
+ try {
32
+ return readSessionStorage()?.getItem(CONFIRMED_KEY_PREFIX + slug) === "1";
33
+ } catch {
34
+ return false;
35
+ }
36
+ }
37
+ function markLiveActionConfirmed(slug) {
38
+ confirmedInMemory.add(slug);
39
+ try {
40
+ readSessionStorage()?.setItem(CONFIRMED_KEY_PREFIX + slug, "1");
41
+ } catch {
42
+ }
43
+ }
44
+ function resetLiveActionConfirmations() {
45
+ confirmedInMemory.clear();
46
+ const storage = readSessionStorage();
47
+ if (!storage) return;
48
+ try {
49
+ for (let index = storage.length - 1; index >= 0; index--) {
50
+ const key = storage.key(index);
51
+ if (key?.startsWith(CONFIRMED_KEY_PREFIX)) storage.removeItem(key);
52
+ }
53
+ } catch {
54
+ }
55
+ }
56
+ class LiveActionNotConfirmedError extends Error {
57
+ constructor(slug, actionName) {
58
+ super(
59
+ `Live action "${actionName}" on "${slug}" was not confirmed, so the request was never sent. Run it again and accept the "this runs against real data" prompt \u2014 declining or dismissing it answers no.`
60
+ );
61
+ this.slug = slug;
62
+ this.actionName = actionName;
63
+ this.name = "LiveActionNotConfirmedError";
64
+ }
65
+ }
66
+ function confirmLiveAction(slug, actionName, ask) {
67
+ if (isLiveActionConfirmed(slug)) return true;
68
+ const accepted = ask(
69
+ `"${slug}" wants to run "${actionName}" against REAL, live ${slug} data \u2014 this is not a fixture.
70
+
71
+ Choose OK to allow this action, and every other action on this integration, for the rest of this browser session.`
72
+ );
73
+ if (accepted) markLiveActionConfirmed(slug);
74
+ return accepted;
75
+ }
16
76
  let originalFetch;
17
77
  let patchedFetch;
18
78
  function redact(url) {
@@ -57,8 +117,31 @@ function installHarnessFetch() {
57
117
  }
58
118
  if (isSameOrigin) {
59
119
  if (active.slug !== void 0) {
60
- const own = `/api/integrations/${active.slug}/`;
120
+ const slug = active.slug;
121
+ const own = `/api/integrations/${slug}/`;
61
122
  const isLocalSetup = url.pathname === `${own}local-setup`;
123
+ const actionsPrefix = `${own}actions/`;
124
+ const isActionsCall = url.pathname.startsWith(actionsPrefix);
125
+ if (isActionsCall) {
126
+ const actionName = url.pathname.slice(actionsPrefix.length);
127
+ if (active.mode === "live") {
128
+ const ask = active.confirm ?? ((message) => globalThis.confirm(message));
129
+ if (!confirmLiveAction(slug, actionName, ask)) {
130
+ notify(url, method, "refused");
131
+ throw new LiveActionNotConfirmedError(slug, actionName);
132
+ }
133
+ }
134
+ notify(url, method, "network");
135
+ const headers = new Headers(
136
+ init?.headers ?? (input instanceof Request ? input.headers : void 0)
137
+ );
138
+ headers.set(HARNESS_ACTIONS_MODE_HEADER, active.mode);
139
+ headers.set(
140
+ HARNESS_ACTIONS_VARIANT_HEADER,
141
+ active.variant ?? "default"
142
+ );
143
+ return original(input, { ...init, headers });
144
+ }
62
145
  if (isLocalSetup || active.mode === "live" && url.pathname.startsWith(own)) {
63
146
  notify(url, method, "network");
64
147
  return original(input, init);
@@ -111,11 +194,14 @@ function uninstallHarnessFetch(original) {
111
194
  originalFetch = void 0;
112
195
  patchedFetch = void 0;
113
196
  closeHarnessRouting();
197
+ resetLiveActionConfirmations();
114
198
  }
115
199
  export {
200
+ LiveActionNotConfirmedError,
116
201
  NoRecordedResponseError,
117
202
  closeHarnessRouting,
118
203
  installHarnessFetch,
119
204
  publishHarnessRouting,
205
+ resetLiveActionConfirmations,
120
206
  uninstallHarnessFetch
121
207
  };
@@ -55,6 +55,7 @@ function IntegrationLayout({ children }) {
55
55
  {
56
56
  seeds,
57
57
  mode,
58
+ variant: state.variant,
58
59
  ...integration.live && !egressMismatch ? { live: integration.live } : {},
59
60
  egress,
60
61
  httpFixtures,
@@ -0,0 +1,57 @@
1
+ import type { IntegrationDefinition } from '@ekanos/sdk/integration';
2
+ import { type MockIntegrationContext } from '@ekanos/sdk/testing';
3
+ import { type FixtureVariant, type HarnessIntegration } from '../../registry.js';
4
+ /**
5
+ * ─────────────────────────────────────────────────────────────────────────────
6
+ * THE FIXTURES-MODE ACTIONS CONTEXT — one per (slug, variant), held server-side
7
+ * ─────────────────────────────────────────────────────────────────────────────
8
+ *
9
+ * `useIntegrationAction` always makes a real `fetch()` (the widget-actions
10
+ * design decision) — there is no browser-side execution path the way
11
+ * fixtures-mode triggers have (`createLocalTriggerRunner` +
12
+ * `useDefinitionMockContext`, both browser-only, built from a `useState`
13
+ * initializer that never runs on the server). So fixtures-mode ACTIONS need
14
+ * a server-side mock context of their own, built the identical way — same
15
+ * `createMockContext`, same fetchHandlers dispatch order (a partner's own
16
+ * `triggerMocks.fetchHandlers` first, then the fixture-compiled catch-all)
17
+ * — just reachable from `api-router.ts`'s action handler instead of from a
18
+ * React hook.
19
+ *
20
+ * Kept on `globalThis` under a `Symbol.for` key, exactly like
21
+ * `live-context.ts`'s `LiveState` store, so a dev-server recompile of the
22
+ * route module does not drop storage a previous action call wrote in the
23
+ * same variant. Keyed by `slug:variant` rather than just `slug` —
24
+ * switching the toolbar's fixture variant is already a deliberate "start
25
+ * over" (`IntegrationLayout` keys its whole provider subtree on it), so the
26
+ * actions context resets with it too, rather than leaking state seeded
27
+ * under one variant into another.
28
+ *
29
+ * NEVER carries a network-passthrough handler — that is the entire
30
+ * difference from `live-context.ts`'s `LiveState`. An action's `ctx.fetch`
31
+ * in fixtures mode can only ever resolve to a partner's own
32
+ * `triggerMocks.fetchHandlers` or a compiled `HttpFixture`; anything else is
33
+ * `NoRecordedResponseError`, never the real network — fixtures mode's whole
34
+ * promise, held for actions exactly as it already is for widgets and
35
+ * triggers.
36
+ */
37
+ export interface FixturesActionsState {
38
+ key: string;
39
+ ctx: MockIntegrationContext;
40
+ }
41
+ /** Test seam: forget every fixtures-mode actions context. */
42
+ export declare function resetFixturesActionsStore(): void;
43
+ export interface FixturesActionsStateInput {
44
+ integration: HarnessIntegration;
45
+ definition: IntegrationDefinition;
46
+ variant: FixtureVariant;
47
+ }
48
+ /**
49
+ * One context per `slug:variant`, built on first use and reused after —
50
+ * state (storage, secrets, logs) accumulates across action calls within the
51
+ * same variant, like a real account across a visit.
52
+ *
53
+ * Can throw `FixtureRequestError` (from `compileFixtures`) when a declared
54
+ * `HttpFixture`'s request line is malformed — the caller's job to turn that
55
+ * into a clear response, not this function's.
56
+ */
57
+ export declare function getFixturesActionsState(input: FixturesActionsStateInput): FixturesActionsState;
@@ -0,0 +1,52 @@
1
+ import {
2
+ createMockContext
3
+ } from "@ekanos/sdk/testing";
4
+ import {
5
+ HARNESS_ACCOUNT_ID,
6
+ resolveEgress
7
+ } from "../../registry.js";
8
+ import { compileFixtures, fixturesToMockHandlers } from "../lib/http-fixtures.js";
9
+ const STORE = /* @__PURE__ */ Symbol.for("ekanos.harness.fixtures-actions-state");
10
+ function getStore() {
11
+ const carrier = globalThis;
12
+ carrier[STORE] ??= /* @__PURE__ */ new Map();
13
+ return carrier[STORE];
14
+ }
15
+ function resetFixturesActionsStore() {
16
+ getStore().clear();
17
+ }
18
+ function getFixturesActionsState(input) {
19
+ const key = `${input.integration.slug}:${input.variant}`;
20
+ const store = getStore();
21
+ const existing = store.get(key);
22
+ if (existing) return existing;
23
+ const definition = input.definition;
24
+ const mocks = input.integration.triggerMocks ?? {};
25
+ const egress = resolveEgress(input.integration);
26
+ const declaredFixtures = input.integration.fixtures?.[input.variant] ?? [];
27
+ const ctx = createMockContext({
28
+ accountId: HARNESS_ACCOUNT_ID,
29
+ integration: { slug: definition.slug },
30
+ ...definition.storage ? { storageSchemas: definition.storage } : {},
31
+ egress: definition.egress ?? [],
32
+ ...mocks.storage ? {
33
+ storage: mocks.storage
34
+ } : {},
35
+ ...mocks.secrets ? { secrets: mocks.secrets } : {},
36
+ fetchHandlers: [
37
+ ...mocks.fetchHandlers ?? [],
38
+ // No selfOrigin: an action handler's `ctx.fetch` calls the partner's
39
+ // OWN vendor, never the harness's own `/api/…` namespace, so the
40
+ // `/api/` host-route fixture shape (the only one that needs an
41
+ // origin to resolve against) never applies here.
42
+ ...fixturesToMockHandlers(compileFixtures(declaredFixtures, egress))
43
+ ]
44
+ });
45
+ const state = { key, ctx };
46
+ store.set(key, state);
47
+ return state;
48
+ }
49
+ export {
50
+ getFixturesActionsState,
51
+ resetFixturesActionsStore
52
+ };
@@ -4,7 +4,7 @@ import { type HarnessIntegration } from '../../registry.js';
4
4
  * THE HARNESS API — `/api/integrations/[slug]/…`, served by the shell
5
5
  * ─────────────────────────────────────────────────────────────────────────────
6
6
  *
7
- * Six routes per registered integration, behind one catch-all the CLI
7
+ * Seven routes per registered integration, behind one catch-all the CLI
8
8
  * scaffolds (`app/api/integrations/[slug]/[...path]/route.ts`):
9
9
  *
10
10
  * GET oauth/connect start the real authorize → callback → exchange loop
@@ -13,6 +13,18 @@ import { type HarnessIntegration } from '../../registry.js';
13
13
  * GET storage the SDK's generic storage bridge, over the live ctx
14
14
  * POST trigger run a webhook / schedule / onActivate on the live ctx
15
15
  * GET local-setup what to fill in and what to register — never values
16
+ * POST actions/:name run a declared `actions[name]` handler — see below
17
+ *
18
+ * `actions/:name` is the one route reached in BOTH fixtures and live mode
19
+ * (every other route only exists for live — fixtures-mode triggers run
20
+ * entirely in the browser). `useIntegrationAction` always makes a real
21
+ * `fetch()` (the widget-actions design), so
22
+ * `harness-fetch-interceptor.ts` lets it through unconditionally and tags
23
+ * the request with the active mode/variant via two harness-only headers
24
+ * (`internal/lib/actions-transport.ts`) — this router reads them to decide
25
+ * whether to run the handler against the live ctx (`getLiveState`, same as
26
+ * `trigger`) or a dedicated per-variant fixtures ctx
27
+ * (`getFixturesActionsState`, network-free).
16
28
  *
17
29
  * Contracts mirror the Fusion host's own partner routes — the hosted OAuth
18
30
  * transport and the generic storage route — so the SDK's client
@@ -1,10 +1,19 @@
1
1
  import { invokeSchedule, invokeWebhook } from "@ekanos/sdk/testing";
2
- import { findIntegration } from "../../registry.js";
2
+ import {
3
+ DATA_MODES,
4
+ FIXTURE_VARIANTS,
5
+ findIntegration
6
+ } from "../../registry.js";
7
+ import {
8
+ HARNESS_ACTIONS_MODE_HEADER,
9
+ HARNESS_ACTIONS_VARIANT_HEADER
10
+ } from "../lib/actions-transport.js";
3
11
  import { runOnActivateHook } from "../lib/run-activation-hook.js";
4
12
  import {
5
13
  isLocalSetupWriteRequest,
6
14
  isTriggerRequest
7
15
  } from "../lib/trigger-contract.js";
16
+ import { getFixturesActionsState } from "./actions-fixtures-context.js";
8
17
  import {
9
18
  WARMUP_BUDGET_MS,
10
19
  getLiveState,
@@ -65,7 +74,8 @@ function createHarnessApiRouter(registry, deps = {}) {
65
74
  const refusal = loopbackRefusal(request, env);
66
75
  if (refusal) return refusal;
67
76
  const routeKey = params.path.join("/");
68
- const route = ROUTES[routeKey];
77
+ const actionName = params.path.length === 2 && params.path[0] === "actions" ? params.path[1] : void 0;
78
+ const route = actionName !== void 0 ? { methods: ["POST"], handle: (ctx) => actionInvoke(ctx, actionName) } : ROUTES[routeKey];
69
79
  if (!route) {
70
80
  if (routeKey === "connect") {
71
81
  return json(
@@ -81,7 +91,7 @@ function createHarnessApiRouter(registry, deps = {}) {
81
91
  {
82
92
  error: "not_found",
83
93
  message: `No harness API route at /api/integrations/${params.slug}/${routeKey}.`,
84
- routes: Object.keys(ROUTES)
94
+ routes: [...Object.keys(ROUTES), "actions/:actionName"]
85
95
  },
86
96
  { status: 404 }
87
97
  );
@@ -393,6 +403,106 @@ async function trigger(ctx) {
393
403
  }
394
404
  }
395
405
  }
406
+ function isDataMode(value) {
407
+ return value !== null && DATA_MODES.includes(value);
408
+ }
409
+ function isFixtureVariant(value) {
410
+ return value !== null && FIXTURE_VARIANTS.includes(value);
411
+ }
412
+ async function actionInvoke(ctx, actionName) {
413
+ const action = ctx.definition.actions?.[actionName];
414
+ if (!action) {
415
+ return json(
416
+ {
417
+ success: false,
418
+ error: `"${ctx.slug}" declares no action named "${actionName}".`,
419
+ code: "action_not_found"
420
+ },
421
+ { status: 404 }
422
+ );
423
+ }
424
+ let body;
425
+ try {
426
+ body = await ctx.request.json();
427
+ } catch {
428
+ return json(
429
+ {
430
+ success: false,
431
+ error: "Request body must be JSON.",
432
+ code: "invalid_input"
433
+ },
434
+ { status: 400 }
435
+ );
436
+ }
437
+ const parsed = action.input.safeParse(
438
+ body?.input
439
+ );
440
+ if (!parsed.success) {
441
+ return json(
442
+ {
443
+ success: false,
444
+ error: "Input failed validation.",
445
+ code: "invalid_input",
446
+ issues: parsed.error.issues
447
+ },
448
+ { status: 400 }
449
+ );
450
+ }
451
+ const modeHeader = ctx.request.headers.get(HARNESS_ACTIONS_MODE_HEADER);
452
+ const mode = isDataMode(modeHeader) ? modeHeader : "fixtures";
453
+ try {
454
+ const executionCtx = mode === "live" ? ctx.state.ctx : getFixturesActionsState({
455
+ integration: ctx.integration,
456
+ definition: ctx.definition,
457
+ variant: resolveActionsVariant(ctx)
458
+ }).ctx;
459
+ const data = await action.handler(executionCtx, parsed.data);
460
+ if (action.output) {
461
+ const validated = action.output.safeParse(data);
462
+ if (!validated.success) {
463
+ console.error(
464
+ `[harness:${ctx.slug}] action "${actionName}" resolved a value that fails its own declared \`output\` schema:`,
465
+ validated.error.issues
466
+ );
467
+ return json(
468
+ {
469
+ success: false,
470
+ error: "Action failed.",
471
+ code: "handler_error",
472
+ devError: {
473
+ message: "The handler resolved successfully, but the value does not match the `output` schema declared alongside it. This is a dev-only field \u2014 production's host route never returns it.",
474
+ issues: validated.error.issues
475
+ }
476
+ },
477
+ { status: 500 }
478
+ );
479
+ }
480
+ return json({ success: true, data: validated.data });
481
+ }
482
+ return json({ success: true, data });
483
+ } catch (error) {
484
+ console.error(
485
+ `[harness:${ctx.slug}] action "${actionName}" handler threw (mode: ${mode}):`,
486
+ error
487
+ );
488
+ return json(
489
+ {
490
+ success: false,
491
+ error: "Action failed.",
492
+ code: "handler_error",
493
+ devError: {
494
+ message: describeError(error),
495
+ stack: error instanceof Error ? error.stack : void 0
496
+ }
497
+ },
498
+ { status: 500 }
499
+ );
500
+ }
501
+ }
502
+ function resolveActionsVariant(ctx) {
503
+ const variantHeader = ctx.request.headers.get(HARNESS_ACTIONS_VARIANT_HEADER);
504
+ return isFixtureVariant(variantHeader) ? variantHeader : "default";
505
+ }
396
506
  function localSetupResponse(ctx, secrets, connected) {
397
507
  const names = declaredSecretNames(ctx.definition);
398
508
  const missing = new Set(secrets.missing);
package/package.json CHANGED
@@ -1,7 +1,6 @@
1
1
  {
2
2
  "name": "@ekanos/harness",
3
- "version": "0.2.0",
4
- "private": false,
3
+ "version": "0.3.0",
5
4
  "type": "module",
6
5
  "description": "The Ekanos integration dev harness — every surface of an integration rendered in real Fusion chrome, from fixtures, with no Supabase or auth; and, in live mode, a real localhost OAuth loop over your own dev-app credentials.",
7
6
  "license": "MIT",
@@ -62,8 +61,8 @@
62
61
  "tw-animate-css": "1.4.0"
63
62
  },
64
63
  "peerDependencies": {
65
- "@ekanos/sdk": "^0.2.0",
66
- "@ekanos/ui": "^0.2.0",
64
+ "@ekanos/sdk": "^0.3.0",
65
+ "@ekanos/ui": "^0.3.0",
67
66
  "@tanstack/react-query": "^5.101.4",
68
67
  "next": "^16.0.0",
69
68
  "react": "^19.2.8",
@@ -72,8 +71,8 @@
72
71
  "tailwindcss": "^4.0.0"
73
72
  },
74
73
  "devDependencies": {
75
- "@ekanos/sdk": "0.2.0",
76
- "@ekanos/ui": "0.2.0",
74
+ "@ekanos/sdk": "0.3.0",
75
+ "@ekanos/ui": "0.3.0",
77
76
  "@kit/eslint-config": "0.2.0",
78
77
  "@kit/prettier-config": "0.1.0",
79
78
  "@kit/tsconfig": "0.1.0",