@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.
- package/README.md +286 -174
- package/dist/api.d.ts +42 -0
- package/dist/api.js +17 -0
- package/dist/internal/components/dev-toolbar.js +4 -2
- package/dist/internal/components/harness-providers.js +5 -2
- package/dist/internal/components/local-oauth-panel.d.ts +29 -0
- package/dist/internal/components/local-oauth-panel.js +355 -0
- package/dist/internal/lib/harness-fetch-interceptor.d.ts +33 -13
- package/dist/internal/lib/harness-fetch-interceptor.js +10 -0
- package/dist/internal/lib/oauth-setup-guide.d.ts +43 -0
- package/dist/internal/lib/oauth-setup-guide.js +28 -0
- package/dist/internal/lib/original-fetch.d.ts +36 -0
- package/dist/internal/lib/original-fetch.js +23 -0
- package/dist/internal/lib/run-activation-hook.d.ts +2 -8
- package/dist/internal/lib/toolbar-context.d.ts +7 -3
- package/dist/internal/lib/toolbar-context.js +10 -5
- package/dist/internal/lib/trigger-contract.d.ts +99 -0
- package/dist/internal/lib/trigger-contract.js +25 -0
- package/dist/internal/lib/trigger-runner.d.ts +55 -0
- package/dist/internal/lib/trigger-runner.js +153 -0
- package/dist/internal/routes/activation-page.js +51 -28
- package/dist/internal/routes/integration-layout.js +5 -1
- package/dist/internal/routes/triggers-page.js +130 -149
- package/dist/internal/server/api-router.d.ts +42 -0
- package/dist/internal/server/api-router.js +465 -0
- package/dist/internal/server/live-context.d.ts +93 -0
- package/dist/internal/server/live-context.js +93 -0
- package/dist/internal/server/local-secrets.d.ts +84 -0
- package/dist/internal/server/local-secrets.js +144 -0
- package/dist/internal/server/loopback-guard.d.ts +33 -0
- package/dist/internal/server/loopback-guard.js +38 -0
- package/dist/internal/server/nonce-store.d.ts +38 -0
- package/dist/internal/server/nonce-store.js +40 -0
- package/dist/internal/server/oauth-loop.d.ts +114 -0
- package/dist/internal/server/oauth-loop.js +141 -0
- package/dist/internal/server/project-root.d.ts +29 -0
- package/dist/internal/server/project-root.js +31 -0
- package/dist/internal/server/storage-read.d.ts +34 -0
- package/dist/internal/server/storage-read.js +53 -0
- package/dist/registry.d.ts +103 -13
- package/dist/registry.js +21 -1
- 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
|
-
>
|
|
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
|
|
53
|
-
|
|
54
|
-
| `harness.config.ts`
|
|
55
|
-
| your integration source
|
|
56
|
-
| the generated `app/**`, `styles/globals.css`, `next.config.mjs` | the CLI; regenerated on upgrade
|
|
57
|
-
| `@ekanos/harness`
|
|
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
|
|
111
|
-
|
|
112
|
-
| `slug`
|
|
113
|
-
| `name`, `description` | yes
|
|
114
|
-
| `widgets`
|
|
115
|
-
| `fixtures`
|
|
116
|
-
| `tile`
|
|
117
|
-
| `activationForm`
|
|
118
|
-
| `definition`
|
|
119
|
-
| `triggerMocks`
|
|
120
|
-
| `live`
|
|
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
|
|
125
|
-
|
|
126
|
-
| `id`
|
|
127
|
-
| `title`
|
|
128
|
-
| `component`
|
|
129
|
-
| `width`
|
|
130
|
-
| `isCollapsible`
|
|
131
|
-
| `isPinnable`
|
|
132
|
-
| `aiFooterEnabled` | no
|
|
133
|
-
| `seeds`
|
|
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
|
|
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
|
-
{
|
|
154
|
-
|
|
155
|
-
{ctx.
|
|
156
|
-
|
|
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
|
|
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
|
|
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
|
-
{
|
|
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
|
|
294
|
-
|
|
295
|
-
| `default` | the populated happy path — declare this one
|
|
296
|
-
| `empty`
|
|
297
|
-
| `error`
|
|
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
|
|
362
|
-
|
|
363
|
-
| Absolute URL | `GET https://api.acme.com/v1/payouts` | itself — always unambiguous
|
|
364
|
-
| Path only
|
|
365
|
-
| Host route
|
|
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
|
|
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
|
|
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.
|
|
590
|
-
|
|
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
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
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)
|
|
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
|
|
679
|
+
import { useHarnessDataMode } from '@ekanos/harness/hooks';
|
|
680
|
+
import { useActivationData, useIntegrationFetch } from '@ekanos/sdk/hooks';
|
|
671
681
|
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
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
|
-
|
|
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
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
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
|
|
705
|
-
|
|
706
|
-
> **
|
|
707
|
-
>
|
|
708
|
-
>
|
|
709
|
-
>
|
|
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
|
-
>
|
|
712
|
-
>
|
|
713
|
-
>
|
|
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
|
-
|
|
717
|
-
|
|
718
|
-
|
|
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
|
-
|
|
755
|
-
|
|
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(
|
|
761
|
-
|
|
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({
|
|
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
|
|
772
|
-
serves `ctx.fetch` on the server and
|
|
773
|
-
|
|
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 (
|
|
778
|
-
|
|
779
|
-
host routes: those are answered from fixtures (record them
|
|
780
|
-
EVERY toolbar mode, live included — there is no Supabase
|
|
781
|
-
execute a route with, so there is nothing "live" to run for
|
|
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
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
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
|
-
|
|
825
|
-
shows the outcome — ran / skipped (not declared) /
|
|
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
|
|
906
|
-
|
|
907
|
-
| `@ekanos/harness/registry`
|
|
908
|
-
| `@ekanos/harness/config`
|
|
909
|
-
| `@ekanos/harness/app`
|
|
910
|
-
| `@ekanos/harness/routes`
|
|
911
|
-
| `@ekanos/harness/hooks`
|
|
912
|
-
| `@ekanos/harness/
|
|
913
|
-
| `@ekanos/harness/
|
|
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
|
|
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
|