@ekanos/harness 0.1.5 → 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.
Files changed (47) hide show
  1. package/README.md +243 -79
  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.d.ts +8 -2
  6. package/dist/internal/components/harness-providers.js +4 -1
  7. package/dist/internal/components/local-oauth-panel.d.ts +29 -0
  8. package/dist/internal/components/local-oauth-panel.js +355 -0
  9. package/dist/internal/lib/actions-transport.d.ts +30 -0
  10. package/dist/internal/lib/actions-transport.js +6 -0
  11. package/dist/internal/lib/harness-fetch-interceptor.d.ts +53 -14
  12. package/dist/internal/lib/harness-fetch-interceptor.js +96 -0
  13. package/dist/internal/lib/oauth-setup-guide.d.ts +43 -0
  14. package/dist/internal/lib/oauth-setup-guide.js +28 -0
  15. package/dist/internal/lib/original-fetch.d.ts +36 -0
  16. package/dist/internal/lib/original-fetch.js +23 -0
  17. package/dist/internal/lib/run-activation-hook.d.ts +2 -8
  18. package/dist/internal/lib/toolbar-context.d.ts +7 -3
  19. package/dist/internal/lib/toolbar-context.js +10 -5
  20. package/dist/internal/lib/trigger-contract.d.ts +99 -0
  21. package/dist/internal/lib/trigger-contract.js +25 -0
  22. package/dist/internal/lib/trigger-runner.d.ts +55 -0
  23. package/dist/internal/lib/trigger-runner.js +153 -0
  24. package/dist/internal/routes/activation-page.js +42 -28
  25. package/dist/internal/routes/integration-layout.js +6 -1
  26. package/dist/internal/routes/triggers-page.js +121 -147
  27. package/dist/internal/server/actions-fixtures-context.d.ts +57 -0
  28. package/dist/internal/server/actions-fixtures-context.js +52 -0
  29. package/dist/internal/server/api-router.d.ts +54 -0
  30. package/dist/internal/server/api-router.js +575 -0
  31. package/dist/internal/server/live-context.d.ts +93 -0
  32. package/dist/internal/server/live-context.js +93 -0
  33. package/dist/internal/server/local-secrets.d.ts +84 -0
  34. package/dist/internal/server/local-secrets.js +144 -0
  35. package/dist/internal/server/loopback-guard.d.ts +33 -0
  36. package/dist/internal/server/loopback-guard.js +38 -0
  37. package/dist/internal/server/nonce-store.d.ts +38 -0
  38. package/dist/internal/server/nonce-store.js +40 -0
  39. package/dist/internal/server/oauth-loop.d.ts +114 -0
  40. package/dist/internal/server/oauth-loop.js +141 -0
  41. package/dist/internal/server/project-root.d.ts +29 -0
  42. package/dist/internal/server/project-root.js +31 -0
  43. package/dist/internal/server/storage-read.d.ts +34 -0
  44. package/dist/internal/server/storage-read.js +53 -0
  45. package/dist/registry.d.ts +73 -1
  46. package/dist/registry.js +21 -1
  47. package/package.json +13 -7
package/README.md CHANGED
@@ -15,7 +15,7 @@ renders those surfaces.
15
15
  > `@ekanos/integration-schema` are (`0.1.2`), and everything in the SDK README
16
16
  > works without this package — `defineIntegration()` validates at import and
17
17
  > the testing helpers need only vitest. What you cannot do until this ships is
18
- > *see* your surfaces rendered. This document describes what will ship.
18
+ > _see_ your surfaces rendered. This document describes what will ship.
19
19
 
20
20
  You do not normally install this by hand. `ekanos dev` scaffolds a shell around
21
21
  it and adds it to your `package.json`.
@@ -49,12 +49,12 @@ So that a harness bugfix reaches you as a version bump you pick up with
49
49
  `pnpm up`, with zero edits to any file you own. The harness is a dependency,
50
50
  not code you copied.
51
51
 
52
- | Path | Who owns it |
53
- |---|---|
54
- | `harness.config.ts` | **you** — the registry, and the only file you have to edit |
55
- | your integration source | **you** |
56
- | the generated `app/**`, `styles/globals.css`, `next.config.mjs` | the CLI; regenerated on upgrade |
57
- | `@ekanos/harness` | us |
52
+ | Path | Who owns it |
53
+ | --------------------------------------------------------------- | ---------------------------------------------------------- |
54
+ | `harness.config.ts` | **you** — the registry, and the only file you have to edit |
55
+ | your integration source | **you** |
56
+ | the generated `app/**`, `styles/globals.css`, `next.config.mjs` | the CLI; regenerated on upgrade |
57
+ | `@ekanos/harness` | us |
58
58
 
59
59
  ## The registry is injected, never imported
60
60
 
@@ -107,30 +107,30 @@ nothing else.
107
107
 
108
108
  ### `HarnessIntegration`
109
109
 
110
- | Field | Required | What it does |
111
- |---|---|---|
112
- | `slug` | yes | URL segment, and the id you would ship as your product slug |
113
- | `name`, `description` | yes | Header chrome and the index page |
114
- | `widgets` | yes | `HarnessWidget[]` — may be empty |
115
- | `fixtures` | no | `Partial<Record<FixtureVariant, HttpFixture[]>>` — the recorded HTTP exchanges, per variant. **This is how data gets in** |
116
- | `tile` | no | `ComponentType<MarketplaceTileProps>` — the marketplace card |
117
- | `activationForm` | no | `ComponentType<ActivationFormProps>`, rendered with `inline` so it does not open a dialog |
118
- | `definition` | no | Your validated `defineIntegration()` output. Powers Triggers |
119
- | `triggerMocks` | no | Seeds for the Triggers surface's mock context |
120
- | `live` | no | Opt in to real third-party requests |
110
+ | Field | Required | What it does |
111
+ | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
112
+ | `slug` | yes | URL segment, and the id you would ship as your product slug |
113
+ | `name`, `description` | yes | Header chrome and the index page |
114
+ | `widgets` | yes | `HarnessWidget[]` — may be empty |
115
+ | `fixtures` | no | `Partial<Record<FixtureVariant, HttpFixture[]>>` — the recorded HTTP exchanges, per variant. **This is how data gets in** |
116
+ | `tile` | no | `ComponentType<MarketplaceTileProps>` — the marketplace card |
117
+ | `activationForm` | no | `ComponentType<ActivationFormProps>`, rendered with `inline` so it does not open a dialog |
118
+ | `definition` | no | Your validated `defineIntegration()` output. Powers Triggers |
119
+ | `triggerMocks` | no | Seeds for the Triggers surface's mock context |
120
+ | `live` | no | Opt in to real third-party requests |
121
121
 
122
122
  ### `HarnessWidget`
123
123
 
124
- | Field | Required | What it does |
125
- |---|---|---|
126
- | `id` | yes | Stable id; the URL segment on `/<slug>/widgets/<widgetId>` |
127
- | `title` | yes | Rendered in the widget header chrome |
128
- | `component` | yes | `ComponentType<IntegrationComponentProps>` |
129
- | `width` | no | `'half'` (default) or `'full'`. Runs of `half` balance across two columns |
130
- | `isCollapsible` | no | Renders the collapse button. Off unless set |
131
- | `isPinnable` | no | Reaches `WidgetContext`; nothing draws a pin — see below |
132
- | `aiFooterEnabled` | no | Renders the "Ask about this" AI footer bar. Off unless set |
133
- | `seeds` | no | `Partial<Record<FixtureVariant, FixtureSeed[]>>` — react-query cache seeds for this widget, per variant. The fast path, not the default; see [Fixtures](#fixtures) |
124
+ | Field | Required | What it does |
125
+ | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
126
+ | `id` | yes | Stable id; the URL segment on `/<slug>/widgets/<widgetId>` |
127
+ | `title` | yes | Rendered in the widget header chrome |
128
+ | `component` | yes | `ComponentType<IntegrationComponentProps>` |
129
+ | `width` | no | `'half'` (default) or `'full'`. Runs of `half` balance across two columns |
130
+ | `isCollapsible` | no | Renders the collapse button. Off unless set |
131
+ | `isPinnable` | no | Reaches `WidgetContext`; nothing draws a pin — see below |
132
+ | `aiFooterEnabled` | no | Renders the "Ask about this" AI footer bar. Off unless set |
133
+ | `seeds` | no | `Partial<Record<FixtureVariant, FixtureSeed[]>>` — react-query cache seeds for this widget, per variant. The fast path, not the default; see [Fixtures](#fixtures) |
134
134
 
135
135
  All three chrome flags are opt-in and behave as the type reads: omit one and
136
136
  you get nothing. The harness applies the host's own default (`?? false`) in its
@@ -145,16 +145,18 @@ pin control.
145
145
 
146
146
  **This is faithful, not a harness gap.** The real dashboard does not render a
147
147
  pin in widget chrome either; it drives pinning from its own loader and
148
- customize panel, outside the widget. So if you want a pin *inside* your widget,
148
+ customize panel, outside the widget. So if you want a pin _inside_ your widget,
149
149
  it is yours to build, in the harness and in production alike:
150
150
 
151
151
  ```tsx
152
152
  const ctx = use(WidgetContext);
153
- {ctx?.meta.isPinnable && (
154
- <button onClick={ctx.actions.togglePinned}>
155
- {ctx.state.pinned ? 'Unpin' : 'Pin'}
156
- </button>
157
- )}
153
+ {
154
+ ctx?.meta.isPinnable && (
155
+ <button onClick={ctx.actions.togglePinned}>
156
+ {ctx.state.pinned ? 'Unpin' : 'Pin'}
157
+ </button>
158
+ );
159
+ }
158
160
  ```
159
161
 
160
162
  ### Derive the widget list — don't write it twice
@@ -202,7 +204,7 @@ Two properties worth knowing, both deliberate:
202
204
  supported and `widgets` is still an ordinary `HarnessWidget[]` — the helper
203
205
  just returns one, so you can spread it and add entries. That is the reason to
204
206
  reach for the manual form: a scratch widget or a variant you are trying out
205
- that is deliberately *not* in your definition yet. The harness is exactly where
207
+ that is deliberately _not_ in your definition yet. The harness is exactly where
206
208
  you should be able to try something before declaring it.
207
209
 
208
210
  ```ts HarnessIntegration
@@ -216,7 +218,7 @@ widgets: [
216
218
  `definition.components.widgets`.** It touches your definition in four places —
217
219
  the egress cross-check, twice in the Triggers surface, and once on the
218
220
  activation page for `capabilities`/`permissions`. Widgets are not among them,
219
- so on this surface the registry is the *only* declaration and the definition's
221
+ so on this surface the registry is the _only_ declaration and the definition's
220
222
  widget flags are inert. The helper is how you make the definition the source
221
223
  anyway.
222
224
 
@@ -277,7 +279,11 @@ export const tidepool: HarnessIntegration = {
277
279
 
278
280
  widgets: [
279
281
  { id: 'tidepool-now', title: 'Tide Now', component: NowWidget },
280
- { id: 'tidepool-forecast', title: 'Tide Forecast', component: ForecastWidget },
282
+ {
283
+ id: 'tidepool-forecast',
284
+ title: 'Tide Forecast',
285
+ component: ForecastWidget,
286
+ },
281
287
  ],
282
288
  };
283
289
  ```
@@ -290,11 +296,11 @@ schedule handler resolves against the fixtures your widgets already use.
290
296
 
291
297
  There are exactly three variants, switched from the dev toolbar:
292
298
 
293
- | Variant | For |
294
- |---|---|
295
- | `default` | the populated happy path — declare this one |
296
- | `empty` | the zero-rows state |
297
- | `error` | the failure state, as ordinary responses with a failure `status` |
299
+ | Variant | For |
300
+ | --------- | ---------------------------------------------------------------- |
301
+ | `default` | the populated happy path — declare this one |
302
+ | `empty` | the zero-rows state |
303
+ | `error` | the failure state, as ordinary responses with a failure `status` |
298
304
 
299
305
  `empty` and `error` are optional, and an omitted variant is **not** a fallback
300
306
  to `default`: the list for that variant is empty, so every request is refused
@@ -358,11 +364,11 @@ interface HttpFixture {
358
364
  case-insensitive and must be one of `GET`, `HEAD`, `POST`, `PUT`, `PATCH`,
359
365
  `DELETE`, `OPTIONS`. The target is one of three forms:
360
366
 
361
- | Form | Example | Resolves against |
362
- |---|---|---|
363
- | Absolute URL | `GET https://api.acme.com/v1/payouts` | itself — always unambiguous |
364
- | Path only | `GET /v1/payouts` | your `defineIntegration({ egress })` origin |
365
- | Host route | `GET /api/integrations/acme/summary` | the harness's own origin |
367
+ | Form | Example | Resolves against |
368
+ | ------------ | ------------------------------------- | ------------------------------------------- |
369
+ | Absolute URL | `GET https://api.acme.com/v1/payouts` | itself — always unambiguous |
370
+ | Path only | `GET /v1/payouts` | your `defineIntegration({ egress })` origin |
371
+ | Host route | `GET /api/integrations/acme/summary` | the harness's own origin |
366
372
 
367
373
  The path-only form exists so you do not maintain a second `baseUrl` beside your
368
374
  egress declaration, and it is allowed **only when your definition declares
@@ -381,7 +387,7 @@ Matching, in the order the rules apply:
381
387
 
382
388
  - **Method and origin must be equal.**
383
389
  - **Path segments must agree in count.** `:param` matches exactly one segment,
384
- `*` matches the rest (including nothing). So `/v1/payouts` does *not* match
390
+ `*` matches the rest (including nothing). So `/v1/payouts` does _not_ match
385
391
  `/v1/payouts/42`, but `/v1/payouts/:id` and `/v1/payouts/*` both do.
386
392
  - **Query is a subset match, or ignored entirely.** If your request line has a
387
393
  `?`, every param in it must be present on the real request with the same
@@ -560,7 +566,7 @@ Both of the problems it fixes are ones you would otherwise hit on your first
560
566
  integration:
561
567
 
562
568
  - **You authored the same vendor data twice, in two shapes, with nothing
563
- relating them.** A seed takes `data` in the shape your hook *returns* —
569
+ relating them.** A seed takes `data` in the shape your hook _returns_ —
564
570
  domain-shaped, post-parse. A `triggerMocks.fetchHandlers` entry returns a
565
571
  `Response`, so it is wire-shaped. The shipped Acme example used to carry both:
566
572
  one export feeding the handler's JSON envelope, separate exports feeding the
@@ -586,8 +592,12 @@ on it to write a fixture.
586
592
  The harness mocks Fusion, not your vendor. Declare a `live` block and the
587
593
  toolbar grows a fixtures ⇄ live switch: in live mode the harness stops seeding
588
594
  your data keys, your widgets' own query functions run, and their requests reach
589
- the real API. Fusion stays mocked either way — still no Supabase, no auth, no
590
- server actions.
595
+ the real API. There is still no Supabase, no auth and no server actions in
596
+ either mode — but live mode is no longer browser-only. The generated shell
597
+ serves `/api/integrations/<slug>/…` itself (`@ekanos/harness/api`) over one
598
+ **server-held context** per integration: the real OAuth loop, the storage
599
+ bridge your widgets read, and a trigger route the Triggers and Activation
600
+ surfaces run handlers through. See "Local OAuth" below.
591
601
 
592
602
  ```ts HarnessIntegration
593
603
  live: {
@@ -639,7 +649,10 @@ listed runs its real query function. That one line is the whole boundary the
639
649
  design draws: Fusion mocked, vendor real.
640
650
 
641
651
  An integration with no `live` block is fixtures-only; the toolbar control is
642
- disabled for it and says why.
652
+ disabled for it and says why. One WITH a `live` block still opens in fixtures
653
+ mode unless it declares `live: { default: 'live' }` — reserve that for an
654
+ integration whose widgets only talk to the harness's own routes, so opening
655
+ it fires nothing at a vendor.
643
656
 
644
657
  ### Knowing the mode, and the activation-data channel
645
658
 
@@ -717,8 +730,8 @@ plumbing required — this is, in miniature, the same ~twenty-line pattern
717
730
 
718
731
  import { type ReactNode, createContext, use } from 'react';
719
732
 
720
- import type { IntegrationFetch } from '@ekanos/sdk';
721
733
  import type { DataMode } from '@ekanos/harness/registry';
734
+ import type { IntegrationFetch } from '@ekanos/sdk';
722
735
 
723
736
  const browserFetch: IntegrationFetch = (input, init) =>
724
737
  globalThis.fetch(input as RequestInfo, init);
@@ -746,7 +759,11 @@ export function useAcmeFetch(): IntegrationFetch {
746
759
  Composing the token onto every request, the one case this seam is still for:
747
760
 
748
761
  ```tsx
749
- export function AcmeFetchProvider({ fetch, activationData, children }: {
762
+ export function AcmeFetchProvider({
763
+ fetch,
764
+ activationData,
765
+ children,
766
+ }: {
750
767
  fetch: IntegrationFetch;
751
768
  mode: DataMode;
752
769
  activationData: unknown;
@@ -774,18 +791,26 @@ global:
774
791
  ```ts
775
792
  import type { IntegrationFetch } from '@ekanos/sdk';
776
793
 
777
- export async function fetchAcmeSummary(fetch: IntegrationFetch, accountId: string) {
778
- const response = await fetch(`https://api.acme.example/v1/summary?a=${accountId}`);
794
+ export async function fetchAcmeSummary(
795
+ fetch: IntegrationFetch,
796
+ accountId: string,
797
+ ) {
798
+ const response = await fetch(
799
+ `https://api.acme.example/v1/summary?a=${accountId}`,
800
+ );
779
801
  if (!response.ok) throw new Error(`Acme returned ${response.status}.`);
780
802
  return response.json();
781
803
  }
782
804
 
783
805
  // in the hook
784
806
  const fetch = useIntegrationFetch(); // or useAcmeFetch() for the legacy seam
785
- useQuery({ queryKey: acmeKeys.summary(accountId), queryFn: () => fetchAcmeSummary(fetch, accountId) });
807
+ useQuery({
808
+ queryKey: acmeKeys.summary(accountId),
809
+ queryFn: () => fetchAcmeSummary(fetch, accountId),
810
+ });
786
811
  ```
787
812
 
788
- That is the value of the pattern, beyond the harness: the *same* code path
813
+ That is the value of the pattern, beyond the harness: the _same_ code path
789
814
  serves `ctx.fetch` on the server and this hook's fetch on the client — gated
790
815
  by the harness's own check in dev, and a plain, unmediated browser fetch in
791
816
  production today (see "Network model" in `AGENTS.md`).
@@ -827,19 +852,87 @@ What the surface then does:
827
852
  logged as skipped — it is the transport's job in every environment.
828
853
  - **Schedules** get a "Run now" button, which invokes the handler with
829
854
  `trigger: 'manual'`.
830
- - **OAuth** gets a read-only declaration readout plus an egress-coverage check
831
- on both endpoint origins. There is no local authorize→callback loop yet; unit
832
- test `onTokens` directly with `createMockContext()` until there is.
833
-
834
- Every invocation runs against **one** `createMockContext()` per visit, so state
835
- accumulates across invocations the way it would in a real account. Leaving the
836
- page resets it.
855
+ - **OAuth** gets the declaration readout, an egress-coverage check on both
856
+ endpoint origins, and the **Local OAuth** panel — in live mode, the real
857
+ authorize → callback → `onTokens` loop runs through the shell against your
858
+ own developer app. See the next section.
859
+
860
+ In **fixtures** mode every invocation runs in the browser against **one**
861
+ `createMockContext()` per visit, seeded from `triggerMocks`, so state
862
+ accumulates across invocations the way it would in a real account and leaving
863
+ the page resets it. In **live** mode the same buttons post to
864
+ `/api/integrations/<slug>/trigger` and the handlers run on the **server-held
865
+ live context** — the one the OAuth loop stored tokens in, whose `ctx.fetch`
866
+ reaches your vendor under the declared egress. Same result panel either way.
837
867
 
838
868
  **`onActivate` runs on the Activation surface, not here.** Submitting the
839
869
  activation form there runs your real `onActivate` hook (if declared) against
840
- its own `createMockContext()`, seeded from the same `triggerMocks` below, and
841
- shows the outcome — ran / skipped (not declared) / threw with the message —
842
- right under the connect dialog.
870
+ the same context the mode above selects — the browser mock in fixtures, the
871
+ live context in live — and shows the outcome — ran / skipped (not declared) /
872
+ threw with the message — right under the connect dialog.
873
+
874
+ ### Local OAuth — the loop runs here, in live mode
875
+
876
+ For an integration whose definition declares `oauth`:
877
+
878
+ 1. Switch the toolbar's **Data** dropdown to **Live API** (the entry needs a
879
+ `live` block). If your widgets never call the vendor from the browser — the
880
+ OAuth shape, where every vendor call is server-side behind `ctx.fetch` —
881
+ declare `live: { default: 'live' }` and the harness starts there; a choice
882
+ made at the toolbar still wins and is remembered.
883
+ 2. The **Local OAuth** panel on the Activation and Triggers surfaces opens
884
+ with the part only a human can do: a checklist for your provider's developer
885
+ console — create the app, add the redirect URI
886
+ `http://localhost:3100/api/integrations/<slug>/oauth/callback` (Copy button),
887
+ enable the declared scopes, allow the code grant (with PKCE when declared),
888
+ copy the client id and secret. Everything there is derived from your
889
+ declaration; add `oauth.setup` to the harness entry for the two things it
890
+ cannot know — where the console is and what the provider calls each key:
891
+
892
+ ```ts HarnessIntegration
893
+ oauth: {
894
+ setup: {
895
+ consoleUrl: 'https://admindemo.docusign.com/apps-and-keys',
896
+ consoleLabel: 'DocuSign Admin → Apps and Keys',
897
+ notes: ['Integration Key is the client id; add a Secret Key — shown once.'],
898
+ },
899
+ },
900
+ ```
901
+
902
+ Below the checklist is a form with one field per secret name your
903
+ definition declares
904
+ (`oauth.credentials.clientIdSecretName`, `clientSecretSecretName`, and every
905
+ signed webhook's `secretName`). Paste the values and **Save credentials**.
906
+ The shell writes them to **`.ekanos/local-secrets.json`** at your project
907
+ root (gitignored, never packed by `ekanos publish`, read on every request)
908
+ and never echoes them back — a saved key shows as `filled` beside an empty
909
+ field; a blank field keeps what is saved. The panel works in fixtures mode
910
+ too, so you can set up before switching.
911
+ 3. Click **Connect** in the activation dialog. The shell's `oauth/connect`
912
+ route builds the authorize URL (PKCE when declared) and sends the browser
913
+ to your provider; `oauth/callback` verifies the single-use `state`,
914
+ exchanges the code through `ctx.fetch` — an undeclared token-endpoint origin
915
+ fails with `EgressDeniedError` exactly as on the host — and awaits your
916
+ `onTokens` on the live context. `oauth/status` then answers connected, the
917
+ SDK's `OAuthActivationForm` auto-activates, and `onActivate` runs on that
918
+ same context.
919
+ 4. Your widgets read what those handlers wrote through the ordinary
920
+ `fetchIntegrationStorage` route, unchanged; an empty read runs your declared
921
+ schedules once first, as the host does.
922
+
923
+ The connection is **memory-only**: restarting the dev server forgets it and you
924
+ Connect again. Editing a value in the secrets file rebuilds the context and
925
+ forgets it too. The API routes refuse any request whose `Host` is not loopback
926
+ unless `EKANOS_HARNESS_EXPOSED=1` — `ekanos dev --host` sets that, after its
927
+ warning.
928
+
929
+ In **fixtures** mode none of this runs. The harness answers `oauth/status`
930
+ from the entry's `oauth.connected` — connected by default, so an OAuth widget
931
+ renders with zero traffic and you do not hand-write that fixture:
932
+
933
+ ```ts HarnessIntegration
934
+ oauth: { connected: { empty: false } }, // show the Connect prompt on `empty`
935
+ ```
843
936
 
844
937
  ### `triggerMocks`
845
938
 
@@ -887,6 +980,74 @@ triggerMocks: {
887
980
  There is no Supabase and no network in here either way. Keep the values fake —
888
981
  see the bundle note below.
889
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
+
890
1051
  ## What ends up in the browser bundle
891
1052
 
892
1053
  **Everything in your registry does, including `triggerMocks.secrets`.**
@@ -918,15 +1079,16 @@ API token predictably appears on screen.
918
1079
 
919
1080
  ## Exports
920
1081
 
921
- | Subpath | Contents |
922
- |---|---|
923
- | `@ekanos/harness/registry` | `HarnessIntegration`, `HarnessWidget`, `HttpFixture`, `FixtureSeed`, `FixtureVariant`, `HarnessLiveMode`, `HarnessTriggerMocks`, the `HARNESS_*` ids and the pure helpers. Server-safe; this is the type surface you author against. |
924
- | `@ekanos/harness/config` | `defineHarnessConfig()` — an identity function that exists for the inference. |
925
- | `@ekanos/harness/app` | `RootLayout`, `IndexPage`, `harnessMetadata`. |
926
- | `@ekanos/harness/routes` | `IntegrationLayout`, `WidgetsPage`, `SingleWidgetPage`, `TilePage`, `ActivationPage`, `TriggersPage`. |
927
- | `@ekanos/harness/hooks` | `useHarnessDataMode()`, `useLiveActivationData()` — see "Knowing the mode, and the activation-data channel" above. Prefer `FetchProvider`'s own `mode`/`activationData` props where you can; reach for these only from code that runs nowhere but inside the dev harness. |
928
- | `@ekanos/harness/styles.css` | The harness's Tailwind layer: the Tailwind entry, the `@ekanos/ui` token preset, the Font Awesome repairs, and the `@source` globs covering everything the chrome renders. |
929
- | `@ekanos/harness/mocks/team-account-workspace` | The stand-in for the host's `useTeamAccountWorkspace()`. The generated `next.config.mjs` aliases `@kit/team-accounts/hooks/use-team-account-workspace` onto it, so unmodified widget source runs unchanged. |
1082
+ | Subpath | Contents |
1083
+ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1084
+ | `@ekanos/harness/registry` | `HarnessIntegration`, `HarnessWidget`, `HttpFixture`, `FixtureSeed`, `FixtureVariant`, `HarnessLiveMode`, `HarnessTriggerMocks`, the `HARNESS_*` ids and the pure helpers. Server-safe; this is the type surface you author against. |
1085
+ | `@ekanos/harness/config` | `defineHarnessConfig()` — an identity function that exists for the inference. |
1086
+ | `@ekanos/harness/app` | `RootLayout`, `IndexPage`, `harnessMetadata`. |
1087
+ | `@ekanos/harness/routes` | `IntegrationLayout`, `WidgetsPage`, `SingleWidgetPage`, `TilePage`, `ActivationPage`, `TriggersPage`. |
1088
+ | `@ekanos/harness/hooks` | `useHarnessDataMode()`, `useLiveActivationData()` — see "Knowing the mode, and the activation-data channel" above. Prefer `FetchProvider`'s own `mode`/`activationData` props where you can; reach for these only from code that runs nowhere but inside the dev harness. |
1089
+ | `@ekanos/harness/api` | `createHarnessApiHandlers(registry)` — the SERVER entry the shell's one API route injects your registry into. Serves `oauth/{connect,callback,status}`, `storage`, `trigger` and `local-setup` per integration in live mode. Never import it from a `'use client'` module. |
1090
+ | `@ekanos/harness/styles.css` | The harness's Tailwind layer: the Tailwind entry, the `@ekanos/ui` token preset, the Font Awesome repairs, and the `@source` globs covering everything the chrome renders. |
1091
+ | `@ekanos/harness/mocks/team-account-workspace` | The stand-in for the host's `useTeamAccountWorkspace()`. The generated `next.config.mjs` aliases `@kit/team-accounts/hooks/use-team-account-workspace` onto it, so unmodified widget source runs unchanged. |
930
1092
 
931
1093
  ## The shell contract
932
1094
 
@@ -938,7 +1100,9 @@ Bump it when the SHELL this package requires changes — an export renamed or
938
1100
  moved between `/app` and `/routes`, the props of `RootLayout` or `IndexPage`,
939
1101
  the server/client split, the alias specifier, the stylesheet's ownership of the
940
1102
  Tailwind import, or the set of files the shell must contain. A release that only
941
- fixes a bug inside the package leaves it alone.
1103
+ fixes a bug inside the package leaves it alone. History: **1** the original
1104
+ ten-file shell; **2** (0.2.0) adds `app/api/integrations/[slug]/[...path]/route.ts`
1105
+ injecting the registry into `@ekanos/harness/api`.
942
1106
 
943
1107
  **A shell change also needs a `@ekanos/cli` release.** The templates live there;
944
1108
  only the code they import lives here. `ekanos dev` rewrites a generated file
@@ -967,7 +1131,7 @@ pnpm --filter @ekanos/harness build
967
1131
 
968
1132
  The build compiles **per file** rather than bundling (`bundle: false` in
969
1133
  `tsup.config.ts`), and that is load-bearing in three separate ways: the
970
- server/client boundary runs *through* the `/app` entry rather than around it,
1134
+ server/client boundary runs _through_ the `/app` entry rather than around it,
971
1135
  `next/font/google` requires its call to survive as a `const` (esbuild's bundler
972
1136
  rewrites top-level `const` to `var`, which Next rejects outright), and there is
973
1137
  nothing to inline in the first place. Each of those is a bug we have already
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: [
@@ -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,
@@ -76,6 +77,8 @@ function HarnessProviders({
76
77
  installHarnessFetch();
77
78
  publishHarnessRouting({
78
79
  mode,
80
+ slug,
81
+ variant,
79
82
  fixtures: httpFixtures,
80
83
  egress: mode === "live" ? egress : [],
81
84
  onCall: ({ url, method, outcome }) => {
@@ -86,7 +89,7 @@ function HarnessProviders({
86
89
  console.info(`[harness:${slug}] ${outcome} ${method} ${url}`);
87
90
  }
88
91
  });
89
- }, [mode, httpFixtures, egress, slug]);
92
+ }, [mode, variant, httpFixtures, egress, slug]);
90
93
  const FetchProvider = live?.FetchProvider;
91
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: [
92
95
  /* @__PURE__ */ jsx(AskAssistantBridge, {}),