@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/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,23 +592,42 @@ 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: {
594
604
  // No `egress` here: the harness reads it off `definition`.
595
- FetchProvider: AcmeFetchProvider,
596
605
  seeds: [{ queryKey: settingsKey, data: acmeSettingsFixture }],
597
606
  },
598
607
  ```
599
608
 
609
+ **No partner wiring required.** As of harness 0.1.5, `HarnessProviders` mounts
610
+ `@ekanos/sdk/hooks`'s `IntegrationFetchProvider`/`IntegrationActivationDataProvider`
611
+ unconditionally. A widget that calls `useIntegrationFetch()` gets back a fetch
612
+ that is already correctly gated for whichever mode the toolbar is in — the
613
+ fixtures-mode refusal or the live-mode allowlist — with nothing declared
614
+ beyond the `live` block above. The hand-written `FetchProvider` field still
615
+ works (see "The legacy seam" below), but a new integration does not need to
616
+ write one.
617
+
600
618
  **The guarantee: live mode enforces the egress your definition declares — not
601
619
  a second list you maintain beside it.** A request to an origin your definition
602
620
  did not declare throws `EgressDeniedError` on your laptop, carrying the message
603
621
  a reviewer would have seen at promotion. Flipping the toolbar to live is
604
622
  therefore a real test of the declaration under review, not of a convenience
605
- copy that happens to sit next to it.
623
+ copy that happens to sit next to it. **This is a harness convenience, not a
624
+ preview of production enforcement:** the check runs one layer below
625
+ `useIntegrationFetch()`, at a patched `globalThis.fetch` that can verify an
626
+ origin and a redirect target the way a browser genuinely can — which is not
627
+ the same as what `ctx.fetch` does on the server (DNS pinning, real redirect
628
+ re-vetting), and production runs no egress check on the client path, at any
629
+ layer, today. See the "Network model" note in a scaffolded project's
630
+ `AGENTS.md` for the fuller statement partners see.
606
631
 
607
632
  **So when you set `definition`, do not set `live.egress`.** Supplying both is a
608
633
  hard error naming your slug, not a silent preference — a silent preference is
@@ -624,110 +649,88 @@ listed runs its real query function. That one line is the whole boundary the
624
649
  design draws: Fusion mocked, vendor real.
625
650
 
626
651
  An integration with no `live` block is fixtures-only; the toolbar control is
627
- 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.
628
656
 
629
657
  ### Knowing the mode, and the activation-data channel
630
658
 
631
- Two things a live-mode widget routinely needs and could not get before:
632
- **which mode is actually running**, and **a credential to authenticate with**.
633
-
634
- `FetchProvider` — where you already have one — receives both as props, no
635
- extra plumbing required:
636
-
637
- ```tsx
638
- import type { ReactNode } from 'react';
639
-
640
- import type { IntegrationFetch } from '@ekanos/sdk';
641
- import type { DataMode } from '@ekanos/harness/registry';
642
-
643
- export function AcmeFetchProvider({
644
- fetch,
645
- mode,
646
- activationData,
647
- children,
648
- }: {
649
- fetch: IntegrationFetch;
650
- mode: DataMode;
651
- activationData: unknown;
652
- children: ReactNode;
653
- }) {
654
- return <AcmeFetchContext value={fetch}>{children}</AcmeFetchContext>;
655
- }
656
- ```
657
-
658
- `mode` is `'fixtures' | 'live'` — the EFFECTIVE mode, already accounting for an
659
+ Two things a live-mode widget routinely needs: **which mode is actually
660
+ running**, and **a credential to authenticate with**.
661
+
662
+ For the credential, call `useActivationData()` from `@ekanos/sdk/hooks`. The
663
+ harness mounts `IntegrationActivationDataProvider` unconditionally, so this
664
+ returns whatever was last submitted to this integration's activation form —
665
+ `null` before any submission or after Disconnect — with no provider of your
666
+ own required. It is held **in memory only**: never written to `localStorage`,
667
+ a fixture, or the registry, and cleared on reload and on disconnect. It is a
668
+ dev-only convenience standing in for `ctx.secrets`, which is what production
669
+ actually hands your server-side handlers.
670
+
671
+ For the mode itself, call `useHarnessDataMode()` from `@ekanos/harness/hooks`.
672
+ This one has no SDK equivalent and stays harness-only — production runs
673
+ exactly one mode, so there is nothing for a host-side hook to report. It
674
+ returns the EFFECTIVE mode (`'fixtures' | 'live'`), already accounting for an
659
675
  integration with no `live` block or a `live.egress`/definition mismatch (both
660
- force `'fixtures'`, whatever the toolbar says). `activationData` is whatever
661
- was last submitted to this integration's activation form — `null` before any
662
- submission or after Disconnect — held **in memory only**: never written to
663
- `localStorage`, a fixture, or the registry, and cleared on reload and on
664
- disconnect. It is a dev-only convenience standing in for `ctx.secrets`, which
665
- is what production actually hands your server-side handlers.
666
-
667
- Threading a submitted API token into a live request looks like this:
676
+ force `'fixtures'`, whatever the toolbar says):
668
677
 
669
678
  ```tsx
670
- import type { ReactNode } from 'react';
679
+ import { useHarnessDataMode } from '@ekanos/harness/hooks';
680
+ import { useActivationData, useIntegrationFetch } from '@ekanos/sdk/hooks';
671
681
 
672
- import type { IntegrationFetch } from '@ekanos/sdk';
673
- import type { DataMode } from '@ekanos/harness/registry';
674
-
675
- export function AcmeFetchProvider({ fetch, activationData, children }: {
676
- fetch: IntegrationFetch;
677
- mode: DataMode;
678
- activationData: unknown;
679
- children: ReactNode;
680
- }) {
681
- const token = (activationData as { apiToken?: string } | null)?.apiToken;
682
+ function useAcmeSummary(accountId: string) {
683
+ const fetch = useIntegrationFetch();
684
+ const mode = useHarnessDataMode();
685
+ const activationData = useActivationData<{ apiToken?: string }>();
682
686
 
683
- const authedFetch: IntegrationFetch = (input, init) =>
684
- fetch(input, {
685
- ...init,
686
- headers: {
687
- ...(init?.headers as Record<string, string> | undefined),
688
- ...(token ? { Authorization: `Bearer ${token}` } : {}),
689
- },
690
- });
691
-
692
- return <AcmeFetchContext value={authedFetch}>{children}</AcmeFetchContext>;
687
+ // ...
693
688
  }
694
689
  ```
695
690
 
696
- No `FetchProvider` mounted, or need the answer somewhere else entirely? Two
697
- hooks answer the same two questions from `@ekanos/harness/hooks`:
698
- `useHarnessDataMode()` and `useLiveActivationData()`. Prefer the props above
699
- wherever you can — they need no import from this package, and behave
700
- identically whether or not `@ekanos/harness` is even installed at the call
701
- site. Reach for the hooks only from code that runs nowhere but inside the dev
691
+ A hand-written `FetchProvider` — where one already exists — receives all
692
+ three (`fetch`, `mode`, `activationData`) as props too, no extra plumbing
693
+ required; see "The legacy seam" below for when writing one is still the
694
+ better call over the hooks above (and for the same token-threading example,
695
+ written the `FetchProvider` way).
696
+
697
+ Reach for `useHarnessDataMode()`/`useActivationData()` directly (as above)
698
+ rather than the props on a `FetchProvider` wherever you can — they need no
699
+ `FetchProvider` of your own, and `useIntegrationFetch()`/`useActivationData()`
700
+ behave identically whether or not `@ekanos/harness` is even installed at the
701
+ call site (a plain fetch and `null`, outside the harness, until a host mounts
702
+ its own provider). `useHarnessDataMode()` is the one exception with no SDK
703
+ equivalent — call it only from code that runs nowhere but inside the dev
702
704
  harness.
703
705
 
704
- ### `FetchProvider` — the part you have to write yourself
705
-
706
- > **Optional.** The harness patches `globalThis.fetch`, so it reaches your
707
- > requests whether or not you supply this — and if you do supply one, your
708
- > fetch still gets wrapped, because the patch sits underneath it. It is not an
709
- > escape hatch in either direction.
706
+ ### `FetchProvider` — the legacy seam, still supported
707
+
708
+ > **No longer the default for a new integration.** `useIntegrationFetch()`
709
+ > from `@ekanos/sdk/hooks` already returns a fetch gated correctly for
710
+ > whichever mode the harness toolbar is in, with nothing to write — see
711
+ > "No partner wiring required" above. Reach for a hand-written
712
+ > `FetchProvider` only for the one case it still earns its keep: composing an
713
+ > authenticated fetch ONCE, at a single seam (e.g. attaching an
714
+ > `Authorization` header derived from `activationData` to every request your
715
+ > query functions make), instead of repeating that composition in every query
716
+ > function. If that is not a problem you have, skip this section.
710
717
  >
711
- > Write it anyway if the shape fits your code: it is how you keep one path
712
- > serving `ctx.fetch` on the server and a browser fetch on the client, which
713
- > is useful well outside the harness.
718
+ > The harness patches `globalThis.fetch` underneath either path, so a
719
+ > `FetchProvider` is not an escape hatch from the harness's live-mode egress
720
+ > check — see "Network model" in a scaffolded project's `AGENTS.md` for what
721
+ > that check does and does not mean once you leave the harness.
714
722
 
715
-
716
- This is the awkward bit, and there is no way around it today. `ctx.fetch` — the
717
- egress-allowlisted fetch — is handed to server-side handlers only. **The SDK
718
- has no client-side equivalent.** So a widget that talks to a vendor API straight
719
- from the browser has nowhere to get one, and needs a seam of its own before
720
- live mode can hand it an allowlisted fetch.
721
-
722
- The seam is a React context whose default is the browser's own `fetch`, so
723
- nothing changes for a consumer that never mounts the provider. It is about
724
- twenty lines, and this is all of them:
723
+ The provider receives `fetch`, `mode`, and `activationData` as props, no extra
724
+ plumbing required — this is, in miniature, the same ~twenty-line pattern
725
+ `@ekanos/sdk/hooks` now ships as `IntegrationFetchProvider`/
726
+ `useIntegrationFetch()`:
725
727
 
726
728
  ```tsx
727
729
  'use client';
728
730
 
729
731
  import { type ReactNode, createContext, use } from 'react';
730
732
 
733
+ import type { DataMode } from '@ekanos/harness/registry';
731
734
  import type { IntegrationFetch } from '@ekanos/sdk';
732
735
 
733
736
  const browserFetch: IntegrationFetch = (input, init) =>
@@ -740,6 +743,8 @@ export function AcmeFetchProvider({
740
743
  children,
741
744
  }: {
742
745
  fetch: IntegrationFetch;
746
+ mode: DataMode;
747
+ activationData: unknown;
743
748
  children: ReactNode;
744
749
  }) {
745
750
  return <AcmeFetchContext value={fetch}>{children}</AcmeFetchContext>;
@@ -751,37 +756,73 @@ export function useAcmeFetch(): IntegrationFetch {
751
756
  }
752
757
  ```
753
758
 
754
- Then have your query functions **take an `IntegrationFetch` as an argument**
755
- rather than reaching for a global:
759
+ Composing the token onto every request, the one case this seam is still for:
760
+
761
+ ```tsx
762
+ export function AcmeFetchProvider({
763
+ fetch,
764
+ activationData,
765
+ children,
766
+ }: {
767
+ fetch: IntegrationFetch;
768
+ mode: DataMode;
769
+ activationData: unknown;
770
+ children: ReactNode;
771
+ }) {
772
+ const token = (activationData as { apiToken?: string } | null)?.apiToken;
773
+
774
+ const authedFetch: IntegrationFetch = (input, init) =>
775
+ fetch(input, {
776
+ ...init,
777
+ headers: {
778
+ ...(init?.headers as Record<string, string> | undefined),
779
+ ...(token ? { Authorization: `Bearer ${token}` } : {}),
780
+ },
781
+ });
782
+
783
+ return <AcmeFetchContext value={authedFetch}>{children}</AcmeFetchContext>;
784
+ }
785
+ ```
786
+
787
+ Either way — the SDK's hook or a hand-rolled one — have your query functions
788
+ **take an `IntegrationFetch` as an argument** rather than reaching for a
789
+ global:
756
790
 
757
791
  ```ts
758
792
  import type { IntegrationFetch } from '@ekanos/sdk';
759
793
 
760
- export async function fetchAcmeSummary(fetch: IntegrationFetch, accountId: string) {
761
- 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
+ );
762
801
  if (!response.ok) throw new Error(`Acme returned ${response.status}.`);
763
802
  return response.json();
764
803
  }
765
804
 
766
805
  // in the hook
767
- const fetch = useAcmeFetch();
768
- useQuery({ queryKey: acmeKeys.summary(accountId), queryFn: () => fetchAcmeSummary(fetch, accountId) });
806
+ const fetch = useIntegrationFetch(); // or useAcmeFetch() for the legacy seam
807
+ useQuery({
808
+ queryKey: acmeKeys.summary(accountId),
809
+ queryFn: () => fetchAcmeSummary(fetch, accountId),
810
+ });
769
811
  ```
770
812
 
771
- That is the value of the pattern, beyond the harness: the *same* code path
772
- serves `ctx.fetch` on the server and an allowlisted browser fetch on the
773
- client.
813
+ That is the value of the pattern, beyond the harness: the _same_ code path
814
+ serves `ctx.fetch` on the server and this hook's fetch on the client — gated
815
+ by the harness's own check in dev, and a plain, unmediated browser fetch in
816
+ production today (see "Network model" in `AGENTS.md`).
774
817
 
775
818
  The provider's props are fixed by the type — `{ fetch: IntegrationFetch; mode:
776
819
  DataMode; activationData: unknown; children: ReactNode }` — because the harness
777
- mounts it (see the previous section for what `mode` and `activationData` are
778
- for). Omit `FetchProvider` entirely if your widgets fetch only through your own
779
- host routes: those are answered from fixtures (record them under `/api/…`) in
780
- EVERY toolbar mode, live included — there is no Supabase and no `ctx` to
781
- execute a route with, so there is nothing "live" to run for that traffic
782
- either way.
783
-
784
- This should be SDK surface, not partner surface. It is on the list.
820
+ mounts it, alongside (not instead of) the SDK's own providers, whenever an
821
+ entry declares one. Omit `FetchProvider` entirely if your widgets fetch only
822
+ through your own host routes: those are answered from fixtures (record them
823
+ under `/api/…`) in EVERY toolbar mode, live included — there is no Supabase
824
+ and no `ctx` to execute a route with, so there is nothing "live" to run for
825
+ that traffic either way.
785
826
 
786
827
  ## Triggers — running webhooks, schedules and OAuth locally
787
828
 
@@ -811,19 +852,87 @@ What the surface then does:
811
852
  logged as skipped — it is the transport's job in every environment.
812
853
  - **Schedules** get a "Run now" button, which invokes the handler with
813
854
  `trigger: 'manual'`.
814
- - **OAuth** gets a read-only declaration readout plus an egress-coverage check
815
- on both endpoint origins. There is no local authorize→callback loop yet; unit
816
- test `onTokens` directly with `createMockContext()` until there is.
817
-
818
- Every invocation runs against **one** `createMockContext()` per visit, so state
819
- accumulates across invocations the way it would in a real account. Leaving the
820
- 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.
821
867
 
822
868
  **`onActivate` runs on the Activation surface, not here.** Submitting the
823
869
  activation form there runs your real `onActivate` hook (if declared) against
824
- its own `createMockContext()`, seeded from the same `triggerMocks` below, and
825
- shows the outcome — ran / skipped (not declared) / threw with the message —
826
- 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
+ ```
827
936
 
828
937
  ### `triggerMocks`
829
938
 
@@ -902,15 +1011,16 @@ API token predictably appears on screen.
902
1011
 
903
1012
  ## Exports
904
1013
 
905
- | Subpath | Contents |
906
- |---|---|
907
- | `@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. |
908
- | `@ekanos/harness/config` | `defineHarnessConfig()` — an identity function that exists for the inference. |
909
- | `@ekanos/harness/app` | `RootLayout`, `IndexPage`, `harnessMetadata`. |
910
- | `@ekanos/harness/routes` | `IntegrationLayout`, `WidgetsPage`, `SingleWidgetPage`, `TilePage`, `ActivationPage`, `TriggersPage`. |
911
- | `@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. |
912
- | `@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. |
913
- | `@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. |
1014
+ | Subpath | Contents |
1015
+ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1016
+ | `@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. |
1017
+ | `@ekanos/harness/config` | `defineHarnessConfig()` — an identity function that exists for the inference. |
1018
+ | `@ekanos/harness/app` | `RootLayout`, `IndexPage`, `harnessMetadata`. |
1019
+ | `@ekanos/harness/routes` | `IntegrationLayout`, `WidgetsPage`, `SingleWidgetPage`, `TilePage`, `ActivationPage`, `TriggersPage`. |
1020
+ | `@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. |
1021
+ | `@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. |
1022
+ | `@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. |
1023
+ | `@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. |
914
1024
 
915
1025
  ## The shell contract
916
1026
 
@@ -922,7 +1032,9 @@ Bump it when the SHELL this package requires changes — an export renamed or
922
1032
  moved between `/app` and `/routes`, the props of `RootLayout` or `IndexPage`,
923
1033
  the server/client split, the alias specifier, the stylesheet's ownership of the
924
1034
  Tailwind import, or the set of files the shell must contain. A release that only
925
- fixes a bug inside the package leaves it alone.
1035
+ fixes a bug inside the package leaves it alone. History: **1** the original
1036
+ ten-file shell; **2** (0.2.0) adds `app/api/integrations/[slug]/[...path]/route.ts`
1037
+ injecting the registry into `@ekanos/harness/api`.
926
1038
 
927
1039
  **A shell change also needs a `@ekanos/cli` release.** The templates live there;
928
1040
  only the code they import lives here. `ekanos dev` rewrites a generated file
@@ -951,7 +1063,7 @@ pnpm --filter @ekanos/harness build
951
1063
 
952
1064
  The build compiles **per file** rather than bundling (`bundle: false` in
953
1065
  `tsup.config.ts`), and that is load-bearing in three separate ways: the
954
- server/client boundary runs *through* the `/app` entry rather than around it,
1066
+ server/client boundary runs _through_ the `/app` entry rather than around it,
955
1067
  `next/font/google` requires its call to survive as a `const` (esbuild's bundler
956
1068
  rewrites top-level `const` to `var`, which Next rejects outright), and there is
957
1069
  nothing to inline in the first place. Each of those is a bug we have already