@ekanos/harness 0.1.4 → 0.2.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.
Files changed (42) hide show
  1. package/README.md +286 -174
  2. package/dist/api.d.ts +42 -0
  3. package/dist/api.js +17 -0
  4. package/dist/internal/components/dev-toolbar.js +4 -2
  5. package/dist/internal/components/harness-providers.js +5 -2
  6. package/dist/internal/components/local-oauth-panel.d.ts +29 -0
  7. package/dist/internal/components/local-oauth-panel.js +355 -0
  8. package/dist/internal/lib/harness-fetch-interceptor.d.ts +33 -13
  9. package/dist/internal/lib/harness-fetch-interceptor.js +10 -0
  10. package/dist/internal/lib/oauth-setup-guide.d.ts +43 -0
  11. package/dist/internal/lib/oauth-setup-guide.js +28 -0
  12. package/dist/internal/lib/original-fetch.d.ts +36 -0
  13. package/dist/internal/lib/original-fetch.js +23 -0
  14. package/dist/internal/lib/run-activation-hook.d.ts +2 -8
  15. package/dist/internal/lib/toolbar-context.d.ts +7 -3
  16. package/dist/internal/lib/toolbar-context.js +10 -5
  17. package/dist/internal/lib/trigger-contract.d.ts +99 -0
  18. package/dist/internal/lib/trigger-contract.js +25 -0
  19. package/dist/internal/lib/trigger-runner.d.ts +55 -0
  20. package/dist/internal/lib/trigger-runner.js +153 -0
  21. package/dist/internal/routes/activation-page.js +51 -28
  22. package/dist/internal/routes/integration-layout.js +5 -1
  23. package/dist/internal/routes/triggers-page.js +130 -149
  24. package/dist/internal/server/api-router.d.ts +42 -0
  25. package/dist/internal/server/api-router.js +465 -0
  26. package/dist/internal/server/live-context.d.ts +93 -0
  27. package/dist/internal/server/live-context.js +93 -0
  28. package/dist/internal/server/local-secrets.d.ts +84 -0
  29. package/dist/internal/server/local-secrets.js +144 -0
  30. package/dist/internal/server/loopback-guard.d.ts +33 -0
  31. package/dist/internal/server/loopback-guard.js +38 -0
  32. package/dist/internal/server/nonce-store.d.ts +38 -0
  33. package/dist/internal/server/nonce-store.js +40 -0
  34. package/dist/internal/server/oauth-loop.d.ts +114 -0
  35. package/dist/internal/server/oauth-loop.js +141 -0
  36. package/dist/internal/server/project-root.d.ts +29 -0
  37. package/dist/internal/server/project-root.js +31 -0
  38. package/dist/internal/server/storage-read.d.ts +34 -0
  39. package/dist/internal/server/storage-read.js +53 -0
  40. package/dist/registry.d.ts +103 -13
  41. package/dist/registry.js +21 -1
  42. package/package.json +13 -7
package/dist/api.d.ts ADDED
@@ -0,0 +1,42 @@
1
+ import { type HarnessApiDeps, type HarnessRouteParams } from './internal/server/api-router.js';
2
+ import type { HarnessIntegration } from './registry.js';
3
+ /**
4
+ * `@ekanos/harness/api` — the SERVER half of the harness.
5
+ *
6
+ * The shell's one API file injects the registry here, exactly as
7
+ * `app/harness-shell.tsx` and `app/page.tsx` inject it into the pages:
8
+ *
9
+ * ```ts
10
+ * import { createHarnessApiHandlers } from '@ekanos/harness/api';
11
+ * // …plus the registry, imported from the partner's config at the project root.
12
+ * const handlers = createHarnessApiHandlers(harnessIntegrations);
13
+ * export const GET = handlers.GET;
14
+ * export const POST = handlers.POST;
15
+ * export const PUT = handlers.PUT;
16
+ * ```
17
+ *
18
+ * Everything under `/api/integrations/[slug]/…` in live mode is answered by
19
+ * these handlers over one server-held context per integration — the real
20
+ * OAuth loop, the storage bridge partner widgets read, and the trigger route
21
+ * the Triggers/Activation surfaces post to. See `internal/server/api-router.ts`
22
+ * for the route table and how it mirrors the hosted transport.
23
+ *
24
+ * Server-only by nature (it reads `.ekanos/local-secrets.json` and holds
25
+ * tokens). Never import this from a `'use client'` module.
26
+ */
27
+ export type { HarnessApiDeps, HarnessRouteParams };
28
+ export interface HarnessApiHandlers {
29
+ GET: NextRouteHandler;
30
+ POST: NextRouteHandler;
31
+ /** `local-setup` saves credentials with PUT. */
32
+ PUT: NextRouteHandler;
33
+ }
34
+ /**
35
+ * The shape Next calls a route-handler export with: the `Request`, plus the
36
+ * dynamic segments as a promise (Next 15+). Spelled out here rather than
37
+ * imported from `next` so this module has no runtime dependency on it.
38
+ */
39
+ export type NextRouteHandler = (request: Request, context: {
40
+ params: Promise<HarnessRouteParams>;
41
+ }) => Promise<Response>;
42
+ export declare function createHarnessApiHandlers(integrations: readonly HarnessIntegration[], deps?: Partial<HarnessApiDeps>): HarnessApiHandlers;
package/dist/api.js ADDED
@@ -0,0 +1,17 @@
1
+ import {
2
+ createHarnessApiRouter
3
+ } from "./internal/server/api-router.js";
4
+ function createHarnessApiHandlers(integrations, deps = {}) {
5
+ const route = createHarnessApiRouter(integrations, deps);
6
+ const handler = async (request, context) => {
7
+ const params = await context.params;
8
+ return route(request, {
9
+ slug: params.slug,
10
+ path: Array.isArray(params.path) ? params.path : []
11
+ });
12
+ };
13
+ return { GET: handler, POST: handler, PUT: handler };
14
+ }
15
+ export {
16
+ createHarnessApiHandlers
17
+ };
@@ -18,6 +18,7 @@ import {
18
18
  DATA_MODES,
19
19
  FIXTURE_VARIANTS,
20
20
  findIntegration,
21
+ resolveEffectiveDataMode,
21
22
  resolveEgress,
22
23
  supportsLiveMode
23
24
  } from "../../registry.js";
@@ -52,7 +53,8 @@ function DevToolbar() {
52
53
  const { resolvedTheme, setTheme } = useTheme();
53
54
  const integration = useCurrentIntegration();
54
55
  const liveAvailable = supportsLiveMode(integration);
55
- const live = liveAvailable && state.dataMode === "live";
56
+ const effectiveMode = resolveEffectiveDataMode(integration, state.dataMode);
57
+ const live = liveAvailable && effectiveMode === "live";
56
58
  return /* @__PURE__ */ jsx("div", { className: "bg-card sticky top-0 z-40 border-b", children: /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-end gap-5 px-6 py-3", children: [
57
59
  /* @__PURE__ */ jsx(Field, { label: "Render state", children: /* @__PURE__ */ jsxs(
58
60
  Select,
@@ -68,7 +70,7 @@ function DevToolbar() {
68
70
  /* @__PURE__ */ jsx(Field, { label: "Data", children: /* @__PURE__ */ jsxs(
69
71
  Select,
70
72
  {
71
- value: liveAvailable ? state.dataMode : "fixtures",
73
+ value: effectiveMode,
72
74
  onValueChange: (value) => setState({ dataMode: value }),
73
75
  disabled: !liveAvailable,
74
76
  children: [
@@ -6,6 +6,8 @@ import {
6
6
  } from "@ekanos/sdk/hooks";
7
7
  import { AskAssistantProvider } from "@ekanos/sdk/hooks";
8
8
  import { WidgetEventProvider } from "@ekanos/sdk/hooks";
9
+ import { IntegrationFetchProvider } from "@ekanos/sdk/hooks";
10
+ import { IntegrationActivationDataProvider } from "@ekanos/sdk/hooks";
9
11
  import { QueryClientProvider } from "@tanstack/react-query";
10
12
  import { TeamAccountWorkspaceContextProvider } from "../../mocks/team-account-workspace.js";
11
13
  import {
@@ -74,6 +76,7 @@ function HarnessProviders({
74
76
  installHarnessFetch();
75
77
  publishHarnessRouting({
76
78
  mode,
79
+ slug,
77
80
  fixtures: httpFixtures,
78
81
  egress: mode === "live" ? egress : [],
79
82
  onCall: ({ url, method, outcome }) => {
@@ -86,10 +89,10 @@ function HarnessProviders({
86
89
  });
87
90
  }, [mode, httpFixtures, egress, slug]);
88
91
  const FetchProvider = live?.FetchProvider;
89
- const tree = /* @__PURE__ */ jsx(QueryClientProvider, { client: queryClient, children: /* @__PURE__ */ jsx(TeamAccountWorkspaceContextProvider, { children: /* @__PURE__ */ jsx(IntegrationActivationProvider, { actions: fixtureActivationActions, children: /* @__PURE__ */ jsx(WidgetEventProvider, { children: /* @__PURE__ */ jsxs(AskAssistantProvider, { children: [
92
+ 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: [
90
93
  /* @__PURE__ */ jsx(AskAssistantBridge, {}),
91
94
  /* @__PURE__ */ jsx(Suspense, { fallback: null, children })
92
- ] }) }) }) }) });
95
+ ] }) }) }) }) }) }) });
93
96
  return FetchProvider ? /* @__PURE__ */ jsx(
94
97
  FetchProvider,
95
98
  {
@@ -0,0 +1,29 @@
1
+ import type { IntegrationDefinition } from '@ekanos/sdk/integration';
2
+ import { type DataMode, type FixtureVariant, type HarnessIntegration } from '../../registry.js';
3
+ /**
4
+ * ─────────────────────────────────────────────────────────────────────────────
5
+ * LOCAL OAUTH — register one URI, paste your keys, click Connect
6
+ * ─────────────────────────────────────────────────────────────────────────────
7
+ *
8
+ * The thing a partner most needs to know about the localhost OAuth loop is
9
+ * not how it works but what THEY have to do — and the answer should be "type
10
+ * it here", not "open this JSON file". So this panel is a form: one password
11
+ * field per secret name the definition declares, saved through the shell's
12
+ * own `PUT /api/integrations/<slug>/local-setup` route, which writes
13
+ * `.ekanos/local-secrets.json` server-side. Values leave the browser once,
14
+ * over loopback; the route answers filled/missing and never a value, so a
15
+ * saved key shows as `filled` beside an EMPTY field. Leave a field blank to
16
+ * keep what is saved.
17
+ *
18
+ * Mode-independent: configuring credentials is a harness matter, not a
19
+ * data-mode one, so the panel reads and saves in fixtures mode too (the
20
+ * interceptor passes exactly this route through). What the mode changes is
21
+ * what the STATUS means — real in live, `oauth.connected` in fixtures — and
22
+ * the panel says which.
23
+ */
24
+ export declare function LocalOAuthPanel({ integration, definition, mode, variant, }: {
25
+ integration: HarnessIntegration;
26
+ definition: IntegrationDefinition;
27
+ mode: DataMode;
28
+ variant: FixtureVariant;
29
+ }): import("react").JSX.Element | null;
@@ -0,0 +1,355 @@
1
+ "use client";
2
+ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
3
+ import { useState } from "react";
4
+ import { Alert, AlertDescription, AlertTitle } from "@ekanos/ui/alert";
5
+ import { Badge } from "@ekanos/ui/badge";
6
+ import { Button } from "@ekanos/ui/button";
7
+ import {
8
+ Form,
9
+ FormControl,
10
+ FormField,
11
+ FormItem,
12
+ FormLabel,
13
+ FormMessage
14
+ } from "@ekanos/ui/form";
15
+ import { Input } from "@ekanos/ui/input";
16
+ import { useQuery, useQueryClient } from "@tanstack/react-query";
17
+ import { useForm } from "react-hook-form";
18
+ import {
19
+ resolveOAuthConnected
20
+ } from "../../registry.js";
21
+ import {
22
+ buildOAuthSetupGuide
23
+ } from "../lib/oauth-setup-guide.js";
24
+ import { fetchLocalSetup, saveLocalSetup } from "../lib/trigger-runner.js";
25
+ function LocalOAuthPanel({
26
+ integration,
27
+ definition,
28
+ mode,
29
+ variant
30
+ }) {
31
+ const oauth = definition.oauth;
32
+ const live = mode === "live";
33
+ const queryClient = useQueryClient();
34
+ const queryKey = ["ekanos-harness", "local-setup", integration.slug];
35
+ const setup = useQuery({
36
+ queryKey,
37
+ queryFn: () => fetchLocalSetup(integration.slug),
38
+ enabled: oauth !== void 0,
39
+ staleTime: 0
40
+ });
41
+ if (!oauth) return null;
42
+ return /* @__PURE__ */ jsxs(
43
+ "div",
44
+ {
45
+ className: "bg-card flex flex-col gap-5 rounded-lg border p-6",
46
+ "data-test": "local-oauth",
47
+ children: [
48
+ /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-center gap-3", children: [
49
+ /* @__PURE__ */ jsx("h3", { className: "font-heading text-lg tracking-tight", children: "Local OAuth" }),
50
+ /* @__PURE__ */ jsx(Badge, { variant: "outline", children: live ? "live" : "fixtures" }),
51
+ live && setup.data ? /* @__PURE__ */ jsx(Badge, { variant: setup.data.connected ? "default" : "secondary", children: setup.data.connected ? "connected" : "not connected" }) : null
52
+ ] }),
53
+ setup.isPending ? /* @__PURE__ */ jsx("p", { className: "text-muted-foreground text-sm", children: "Reading local setup\u2026" }) : setup.isError ? /* @__PURE__ */ jsxs(Alert, { variant: "destructive", children: [
54
+ /* @__PURE__ */ jsx(AlertTitle, { children: "The harness API did not answer" }),
55
+ /* @__PURE__ */ jsxs(AlertDescription, { children: [
56
+ /* @__PURE__ */ jsx("p", { children: setup.error.message }),
57
+ /* @__PURE__ */ jsxs("p", { children: [
58
+ "The API routes live in the generated shell. If you upgraded",
59
+ " ",
60
+ /* @__PURE__ */ jsx("code", { children: "@ekanos/harness" }),
61
+ ", re-run ",
62
+ /* @__PURE__ */ jsx("code", { children: "ekanos dev" }),
63
+ " so the shell is regenerated with them."
64
+ ] })
65
+ ] })
66
+ ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
67
+ /* @__PURE__ */ jsxs("ol", { className: "flex flex-col gap-5 text-sm", children: [
68
+ /* @__PURE__ */ jsxs("li", { className: "flex flex-col gap-2", children: [
69
+ /* @__PURE__ */ jsx("span", { className: "font-medium", children: "1. Set up the OAuth app at your provider \u2014 this part is yours" }),
70
+ setup.data.redirectUri ? /* @__PURE__ */ jsx(
71
+ SetupChecklist,
72
+ {
73
+ guide: buildOAuthSetupGuide({
74
+ definition,
75
+ entry: integration,
76
+ redirectUri: setup.data.redirectUri
77
+ })
78
+ }
79
+ ) : null
80
+ ] }),
81
+ /* @__PURE__ */ jsxs("li", { className: "flex flex-col gap-3", children: [
82
+ /* @__PURE__ */ jsx("span", { className: "font-medium", children: "2. Paste the credentials from that app" }),
83
+ /* @__PURE__ */ jsx(
84
+ CredentialsForm,
85
+ {
86
+ slug: integration.slug,
87
+ keys: setup.data.keys,
88
+ onSaved: (next) => queryClient.setQueryData(queryKey, next)
89
+ }
90
+ ),
91
+ /* @__PURE__ */ jsxs("span", { className: "text-muted-foreground text-xs", children: [
92
+ "Saved to ",
93
+ /* @__PURE__ */ jsx("code", { children: setup.data.file }),
94
+ " in your project \u2014 gitignored, never packed, read on every request. A saved key shows as filled beside an empty field; leave a field blank to keep it. Saving forgets any current connection."
95
+ ] })
96
+ ] }),
97
+ /* @__PURE__ */ jsxs("li", { className: "flex flex-col gap-1", children: [
98
+ /* @__PURE__ */ jsx("span", { className: "font-medium", children: "3. Open the connect dialog (above) and click Connect" }),
99
+ /* @__PURE__ */ jsxs("span", { className: "text-muted-foreground text-xs", children: [
100
+ "The browser goes to the provider, comes back to the redirect URI above, the shell exchanges the code through your declared egress and calls ",
101
+ /* @__PURE__ */ jsx("code", { children: "onTokens" }),
102
+ " on a server-held context. Widgets then read what your handlers wrote through the normal storage route."
103
+ ] })
104
+ ] })
105
+ ] }),
106
+ live ? /* @__PURE__ */ jsxs(
107
+ "p",
108
+ {
109
+ className: "text-muted-foreground text-xs",
110
+ "data-test": "local-oauth-connection",
111
+ children: [
112
+ setup.data.connection ? `Connected since ${setup.data.connection.obtainedAt}` + (setup.data.connection.expiresAt ? `; access token expires ${setup.data.connection.expiresAt}` : "") + ". " : "Not connected on this server. ",
113
+ "The connection lives in the dev server's memory only \u2014 a restart forgets it, and you Connect again."
114
+ ]
115
+ }
116
+ ) : /* @__PURE__ */ jsx(
117
+ FixturesModeNotice,
118
+ {
119
+ integration,
120
+ variant,
121
+ supportsLive: integration.live !== void 0
122
+ }
123
+ )
124
+ ] })
125
+ ]
126
+ }
127
+ );
128
+ }
129
+ function SetupChecklist({ guide }) {
130
+ if (!guide) return null;
131
+ return /* @__PURE__ */ jsxs(
132
+ "ul",
133
+ {
134
+ className: "text-muted-foreground flex flex-col gap-2 text-sm",
135
+ "data-test": "local-oauth-checklist",
136
+ children: [
137
+ /* @__PURE__ */ jsx("li", { children: guide.console ? /* @__PURE__ */ jsxs(Fragment, { children: [
138
+ "Open",
139
+ " ",
140
+ /* @__PURE__ */ jsx(
141
+ "a",
142
+ {
143
+ href: guide.console.url,
144
+ target: "_blank",
145
+ rel: "noreferrer",
146
+ className: "text-foreground underline underline-offset-2",
147
+ "data-test": "local-oauth-console-link",
148
+ children: guide.console.label
149
+ }
150
+ ),
151
+ " ",
152
+ "and create an OAuth app, or open the one you use for development."
153
+ ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
154
+ "In ",
155
+ /* @__PURE__ */ jsx("code", { children: guide.providerHost }),
156
+ "'s developer console, create an OAuth app, or open the one you use for development."
157
+ ] }) }),
158
+ /* @__PURE__ */ jsxs("li", { className: "flex flex-col gap-1", children: [
159
+ /* @__PURE__ */ jsx("span", { children: "Add this redirect URI to the app, exactly:" }),
160
+ /* @__PURE__ */ jsx(
161
+ CopyableCode,
162
+ {
163
+ value: guide.redirectUri,
164
+ testId: "local-oauth-redirect-uri"
165
+ }
166
+ )
167
+ ] }),
168
+ guide.scopes.length > 0 ? /* @__PURE__ */ jsxs("li", { children: [
169
+ "Enable these scopes:",
170
+ " ",
171
+ guide.scopes.map((scope) => /* @__PURE__ */ jsx("code", { className: "mr-1 text-xs", children: scope }, scope))
172
+ ] }) : null,
173
+ /* @__PURE__ */ jsx("li", { children: guide.pkce ? "The app must allow the Authorization Code grant with PKCE (S256) \u2014 the loop sends a code challenge." : "The app must allow the Authorization Code grant." }),
174
+ /* @__PURE__ */ jsxs("li", { children: [
175
+ "Copy the app's client id into",
176
+ " ",
177
+ /* @__PURE__ */ jsx("code", { children: guide.credentials.clientId }),
178
+ " and its client secret into",
179
+ " ",
180
+ /* @__PURE__ */ jsx("code", { children: guide.credentials.clientSecret }),
181
+ " below."
182
+ ] }),
183
+ guide.notes.map((note) => /* @__PURE__ */ jsx("li", { "data-test": "local-oauth-note", children: note }, note))
184
+ ]
185
+ }
186
+ );
187
+ }
188
+ function CopyableCode({ value, testId }) {
189
+ const [copied, setCopied] = useState(false);
190
+ return /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
191
+ /* @__PURE__ */ jsx(
192
+ "code",
193
+ {
194
+ className: "bg-muted flex-1 rounded-md px-3 py-2 text-xs break-all",
195
+ "data-test": testId,
196
+ children: value
197
+ }
198
+ ),
199
+ /* @__PURE__ */ jsx(
200
+ Button,
201
+ {
202
+ type: "button",
203
+ variant: "outline",
204
+ size: "sm",
205
+ onClick: async () => {
206
+ try {
207
+ await navigator.clipboard.writeText(value);
208
+ setCopied(true);
209
+ setTimeout(() => setCopied(false), 1500);
210
+ } catch (error) {
211
+ console.warn("[harness] could not copy to the clipboard:", error);
212
+ }
213
+ },
214
+ "data-test": `${testId}-copy`,
215
+ children: copied ? "Copied" : "Copy"
216
+ }
217
+ )
218
+ ] });
219
+ }
220
+ function CredentialsForm({
221
+ slug,
222
+ keys,
223
+ onSaved
224
+ }) {
225
+ const blank = () => Object.fromEntries(keys.map((key) => [key.name, ""]));
226
+ const form = useForm({ defaultValues: blank() });
227
+ const [status, setStatus] = useState({ kind: "idle" });
228
+ const submit = form.handleSubmit(async (values) => {
229
+ const typed = Object.fromEntries(
230
+ Object.entries(values).filter(([, value]) => value.trim().length > 0)
231
+ );
232
+ if (Object.keys(typed).length === 0) {
233
+ setStatus({
234
+ kind: "error",
235
+ message: "Nothing to save \u2014 every field is blank."
236
+ });
237
+ return;
238
+ }
239
+ try {
240
+ const next = await saveLocalSetup(slug, { values: typed });
241
+ onSaved(next);
242
+ form.reset(blank());
243
+ setStatus({ kind: "saved", count: Object.keys(typed).length });
244
+ } catch (error) {
245
+ setStatus({
246
+ kind: "error",
247
+ message: error instanceof Error ? error.message : String(error)
248
+ });
249
+ }
250
+ });
251
+ if (keys.length === 0) {
252
+ return /* @__PURE__ */ jsx("p", { className: "text-muted-foreground text-xs", children: "This definition declares no secret names, so there is nothing to save." });
253
+ }
254
+ return /* @__PURE__ */ jsx(Form, { ...form, children: /* @__PURE__ */ jsxs(
255
+ "form",
256
+ {
257
+ onSubmit: submit,
258
+ className: "flex flex-col gap-3",
259
+ "data-test": "local-oauth-form",
260
+ autoComplete: "off",
261
+ children: [
262
+ keys.map((key) => /* @__PURE__ */ jsx(
263
+ FormField,
264
+ {
265
+ control: form.control,
266
+ name: key.name,
267
+ render: ({ field }) => /* @__PURE__ */ jsxs(FormItem, { children: [
268
+ /* @__PURE__ */ jsxs(FormLabel, { className: "flex items-center gap-2", children: [
269
+ /* @__PURE__ */ jsx("code", { className: "text-xs", children: key.name }),
270
+ /* @__PURE__ */ jsx(Badge, { variant: key.filled ? "secondary" : "destructive", children: key.filled ? "filled" : "missing" })
271
+ ] }),
272
+ /* @__PURE__ */ jsx(FormControl, { children: /* @__PURE__ */ jsx(
273
+ Input,
274
+ {
275
+ ...field,
276
+ type: "password",
277
+ autoComplete: "off",
278
+ spellCheck: false,
279
+ placeholder: key.filled ? "saved \u2014 leave blank to keep" : "paste the value",
280
+ "data-test": `local-oauth-input-${key.name}`
281
+ }
282
+ ) }),
283
+ /* @__PURE__ */ jsx(FormMessage, {})
284
+ ] })
285
+ },
286
+ key.name
287
+ )),
288
+ /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-3", children: [
289
+ /* @__PURE__ */ jsx(
290
+ Button,
291
+ {
292
+ type: "submit",
293
+ size: "sm",
294
+ disabled: form.formState.isSubmitting,
295
+ "data-test": "local-oauth-save",
296
+ children: form.formState.isSubmitting ? "Saving\u2026" : "Save credentials"
297
+ }
298
+ ),
299
+ status.kind === "saved" ? /* @__PURE__ */ jsxs(
300
+ "span",
301
+ {
302
+ className: "text-muted-foreground text-xs",
303
+ "data-test": "local-oauth-saved",
304
+ children: [
305
+ "Saved ",
306
+ status.count,
307
+ " ",
308
+ status.count === 1 ? "value" : "values",
309
+ "."
310
+ ]
311
+ }
312
+ ) : status.kind === "error" ? /* @__PURE__ */ jsx(
313
+ "span",
314
+ {
315
+ className: "text-destructive text-xs",
316
+ "data-test": "local-oauth-error",
317
+ children: status.message
318
+ }
319
+ ) : null
320
+ ] })
321
+ ]
322
+ }
323
+ ) });
324
+ }
325
+ function FixturesModeNotice({
326
+ integration,
327
+ variant,
328
+ supportsLive
329
+ }) {
330
+ const connected = resolveOAuthConnected(integration, variant);
331
+ return /* @__PURE__ */ jsxs(
332
+ "p",
333
+ {
334
+ className: "text-muted-foreground text-xs",
335
+ "data-test": "local-oauth-fixtures",
336
+ children: [
337
+ "Fixtures mode: the status route is answered from",
338
+ " ",
339
+ /* @__PURE__ */ jsx("code", { children: "oauth.connected" }),
340
+ " in your harness entry \u2014 currently",
341
+ " ",
342
+ /* @__PURE__ */ jsx("strong", { children: connected ? "connected" : "not connected" }),
343
+ " for the",
344
+ " ",
345
+ /* @__PURE__ */ jsx("code", { children: variant }),
346
+ " variant \u2014 and Connect still runs the real loop above.",
347
+ " ",
348
+ supportsLive ? "Switch the toolbar\u2019s Data dropdown to Live API to have widgets and Triggers use the real connection." : "Add a `live` block to this entry in your harness config to enable the Live API switch."
349
+ ]
350
+ }
351
+ );
352
+ }
353
+ export {
354
+ LocalOAuthPanel
355
+ };
@@ -33,7 +33,7 @@ import { type CompiledFixture, NoRecordedResponseError } from './http-fixtures.j
33
33
  * framework's own plumbing, none of it the integration talking to an API.
34
34
  * Intercepting it would break the app to no purpose.
35
35
  *
36
- * ── `/api/` is answered from fixtures in EVERY mode ──────────────────────────
36
+ * ── `/api/` — fixtures in fixtures mode, the shell's own routes in live ──────
37
37
  *
38
38
  * `/api/` is the one same-origin exception, because it is the integration's
39
39
  * own namespace. A first-party integration's widgets call
@@ -41,18 +41,32 @@ import { type CompiledFixture, NoRecordedResponseError } from './http-fixtures.j
41
41
  * call happens server-side, where the credential lives — and our own Acme
42
42
  * example is shaped exactly that way.
43
43
  *
44
- * This is answered from the registry's `fixtures` REGARDLESS of the toolbar's
45
- * fixtures/live switch. The harness serves no backend in either mode, so there
46
- * is nothing "live" to run for this traffic even when live mode is on: passing
47
- * it through would guarantee a 404 whichever mode asked for it, and the useful
48
- * answer — a fixture, or a refusal that names the URL and says to add one — is
49
- * the one fixtures mode already gives. A miss is `NoRecordedResponseError`,
50
- * unconditionally, so the failure a partner sees does not change out from
51
- * under them when they flip the toolbar.
52
- *
53
- * Only genuinely third-party traffic — a different origin — is what "live"
54
- * actually means: reaching the real vendor under the egress allowlist below,
55
- * instead of a recorded response.
44
+ * In FIXTURES mode this is answered from the registry's `fixtures`, and a miss
45
+ * is `NoRecordedResponseError` — a refusal that names the URL and says to add
46
+ * one.
47
+ *
48
+ * In LIVE mode, requests under `/api/integrations/<active slug>/` PASS THROUGH
49
+ * to the shell's own API routes (`@ekanos/harness/api`, scaffolded by
50
+ * `ekanos dev`). Those routes serve, over one server-held context per
51
+ * integration: the real OAuth loop (`oauth/connect|callback|status`), the
52
+ * storage bridge partner widgets read (`storage`), and the trigger route the
53
+ * Triggers/Activation surfaces post to. That is what "live" means for this
54
+ * traffic — the data `onTokens` and the partner's schedules actually wrote.
55
+ * Every OTHER `/api/` path stays on fixtures in live mode too: the harness
56
+ * serves nothing else, so passing it through would only trade a named
57
+ * refusal for a 404.
58
+ *
59
+ * Third-party traffic — a different origin — is unchanged: in live mode it
60
+ * reaches the real vendor under the egress allowlist below; in fixtures mode
61
+ * it is answered from fixtures or refused by name.
62
+ *
63
+ * ── The server sees this patch too ───────────────────────────────────────────
64
+ *
65
+ * `harness-providers.tsx` installs this at import, and Next evaluates that
66
+ * module during the SERVER render as well — in the same process the API route
67
+ * handlers run in. The wrapper is therefore tagged with the fetch it wraps
68
+ * (`original-fetch.ts`), and server code that must reach the network unwraps
69
+ * it at call time rather than trusting `globalThis.fetch`.
56
70
  *
57
71
  * Scoped to `/api/` rather than "everything except `/_next/`" deliberately: a
58
72
  * rule that has to enumerate the framework's internals is a rule that breaks
@@ -68,6 +82,12 @@ import { type CompiledFixture, NoRecordedResponseError } from './http-fixtures.j
68
82
  /** How the interceptor should answer third-party requests right now. */
69
83
  export interface HarnessRoutingTable {
70
84
  mode: 'fixtures' | 'live';
85
+ /**
86
+ * The integration currently rendering. In live mode, same-origin requests
87
+ * under `/api/integrations/<slug>/` pass through to the shell's API routes;
88
+ * absent (the fail-closed default), nothing passes.
89
+ */
90
+ slug?: string;
71
91
  /** Compiled fixtures for the active variant. */
72
92
  fixtures: readonly CompiledFixture[];
73
93
  /** Origins live mode may reach. Empty in fixtures mode. */
@@ -5,6 +5,7 @@ import {
5
5
  fixtureResponse,
6
6
  matchHttpFixture
7
7
  } from "./http-fixtures.js";
8
+ import { tagInterceptor } from "./original-fetch.js";
8
9
  const CLOSED = {
9
10
  mode: "fixtures",
10
11
  fixtures: [],
@@ -55,6 +56,14 @@ function installHarnessFetch() {
55
56
  return original(input, init);
56
57
  }
57
58
  if (isSameOrigin) {
59
+ if (active.slug !== void 0) {
60
+ const own = `/api/integrations/${active.slug}/`;
61
+ const isLocalSetup = url.pathname === `${own}local-setup`;
62
+ if (isLocalSetup || active.mode === "live" && url.pathname.startsWith(own)) {
63
+ notify(url, method, "network");
64
+ return original(input, init);
65
+ }
66
+ }
58
67
  const fixture2 = matchHttpFixture(method, url.toString(), active.fixtures);
59
68
  if (!fixture2) {
60
69
  notify(url, method, "refused");
@@ -91,6 +100,7 @@ function installHarnessFetch() {
91
100
  notify(url, method, "fixture");
92
101
  return fixtureResponse(fixture);
93
102
  };
103
+ tagInterceptor(intercept, original);
94
104
  globalThis.fetch = intercept;
95
105
  patchedFetch = intercept;
96
106
  return original;
@@ -0,0 +1,43 @@
1
+ import type { IntegrationDefinition } from '@ekanos/sdk/integration';
2
+ import type { HarnessIntegration } from '../../registry.js';
3
+ /**
4
+ * ─────────────────────────────────────────────────────────────────────────────
5
+ * WHAT THE HUMAN HAS TO DO — derived from the declaration, plus notes
6
+ * ─────────────────────────────────────────────────────────────────────────────
7
+ *
8
+ * An OAuth loop needs things no code can do: someone signs in to the
9
+ * provider's developer console, creates an app, registers the redirect URI,
10
+ * enables the scopes, and copies two strings out. Most of that checklist is
11
+ * already IN the declaration — the provider is the authorize URL's host, the
12
+ * scopes are `provider.scopes`, PKCE is `provider.pkce`, the redirect URI is
13
+ * the shell's callback — so the harness derives it rather than asking the
14
+ * partner to write it twice. What it cannot derive is where that console
15
+ * lives and what the provider calls each credential, which is what the
16
+ * optional `oauth.setup` on the harness entry adds.
17
+ *
18
+ * Pure, so the checklist is testable without rendering.
19
+ */
20
+ export interface OAuthSetupGuide {
21
+ /** The provider, as the authorize URL's host — `account-d.docusign.com`. */
22
+ providerHost: string;
23
+ /** Where to create the app, when the entry says. */
24
+ console: {
25
+ url: string;
26
+ label: string;
27
+ } | null;
28
+ redirectUri: string;
29
+ scopes: readonly string[];
30
+ pkce: boolean;
31
+ /** The declared credential secret names, in the order the form shows them. */
32
+ credentials: {
33
+ clientId: string;
34
+ clientSecret: string;
35
+ };
36
+ /** Partner-authored, provider-specific steps. */
37
+ notes: readonly string[];
38
+ }
39
+ export declare function buildOAuthSetupGuide(args: {
40
+ definition: Pick<IntegrationDefinition, 'oauth'>;
41
+ entry: Pick<HarnessIntegration, 'oauth'>;
42
+ redirectUri: string;
43
+ }): OAuthSetupGuide | null;