@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 +68 -0
- package/dist/internal/components/harness-providers.d.ts +8 -2
- package/dist/internal/components/harness-providers.js +3 -1
- package/dist/internal/lib/actions-transport.d.ts +30 -0
- package/dist/internal/lib/actions-transport.js +6 -0
- package/dist/internal/lib/harness-fetch-interceptor.d.ts +20 -1
- package/dist/internal/lib/harness-fetch-interceptor.js +87 -1
- package/dist/internal/routes/integration-layout.js +1 -0
- package/dist/internal/server/actions-fixtures-context.d.ts +57 -0
- package/dist/internal/server/actions-fixtures-context.js +52 -0
- package/dist/internal/server/api-router.d.ts +13 -1
- package/dist/internal/server/api-router.js +113 -3
- package/package.json +5 -6
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";
|
|
@@ -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
|
|
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
|
};
|
|
@@ -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
|
-
*
|
|
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 {
|
|
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
|
|
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.
|
|
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.
|
|
66
|
-
"@ekanos/ui": "^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.
|
|
76
|
-
"@ekanos/ui": "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",
|