@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.
- package/README.md +243 -79
- 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.d.ts +8 -2
- package/dist/internal/components/harness-providers.js +4 -1
- 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/actions-transport.d.ts +30 -0
- package/dist/internal/lib/actions-transport.js +6 -0
- package/dist/internal/lib/harness-fetch-interceptor.d.ts +53 -14
- package/dist/internal/lib/harness-fetch-interceptor.js +96 -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 +42 -28
- package/dist/internal/routes/integration-layout.js +6 -1
- package/dist/internal/routes/triggers-page.js +121 -147
- package/dist/internal/server/actions-fixtures-context.d.ts +57 -0
- package/dist/internal/server/actions-fixtures-context.js +52 -0
- package/dist/internal/server/api-router.d.ts +54 -0
- package/dist/internal/server/api-router.js +575 -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 +73 -1
- 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,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.
|
|
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: {
|
|
@@ -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({
|
|
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(
|
|
778
|
-
|
|
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({
|
|
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
|
|
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
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
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
|
-
|
|
841
|
-
shows the outcome — ran / skipped (not declared) /
|
|
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
|
|
922
|
-
|
|
923
|
-
| `@ekanos/harness/registry`
|
|
924
|
-
| `@ekanos/harness/config`
|
|
925
|
-
| `@ekanos/harness/app`
|
|
926
|
-
| `@ekanos/harness/routes`
|
|
927
|
-
| `@ekanos/harness/hooks`
|
|
928
|
-
| `@ekanos/harness/
|
|
929
|
-
| `@ekanos/harness/
|
|
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
|
|
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
|
|
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:
|
|
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, {}),
|