@ekanos/harness 0.1.3 → 0.1.5
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
CHANGED
|
@@ -592,17 +592,32 @@ server actions.
|
|
|
592
592
|
```ts HarnessIntegration
|
|
593
593
|
live: {
|
|
594
594
|
// No `egress` here: the harness reads it off `definition`.
|
|
595
|
-
FetchProvider: AcmeFetchProvider,
|
|
596
595
|
seeds: [{ queryKey: settingsKey, data: acmeSettingsFixture }],
|
|
597
596
|
},
|
|
598
597
|
```
|
|
599
598
|
|
|
599
|
+
**No partner wiring required.** As of harness 0.1.5, `HarnessProviders` mounts
|
|
600
|
+
`@ekanos/sdk/hooks`'s `IntegrationFetchProvider`/`IntegrationActivationDataProvider`
|
|
601
|
+
unconditionally. A widget that calls `useIntegrationFetch()` gets back a fetch
|
|
602
|
+
that is already correctly gated for whichever mode the toolbar is in — the
|
|
603
|
+
fixtures-mode refusal or the live-mode allowlist — with nothing declared
|
|
604
|
+
beyond the `live` block above. The hand-written `FetchProvider` field still
|
|
605
|
+
works (see "The legacy seam" below), but a new integration does not need to
|
|
606
|
+
write one.
|
|
607
|
+
|
|
600
608
|
**The guarantee: live mode enforces the egress your definition declares — not
|
|
601
609
|
a second list you maintain beside it.** A request to an origin your definition
|
|
602
610
|
did not declare throws `EgressDeniedError` on your laptop, carrying the message
|
|
603
611
|
a reviewer would have seen at promotion. Flipping the toolbar to live is
|
|
604
612
|
therefore a real test of the declaration under review, not of a convenience
|
|
605
|
-
copy that happens to sit next to it.
|
|
613
|
+
copy that happens to sit next to it. **This is a harness convenience, not a
|
|
614
|
+
preview of production enforcement:** the check runs one layer below
|
|
615
|
+
`useIntegrationFetch()`, at a patched `globalThis.fetch` that can verify an
|
|
616
|
+
origin and a redirect target the way a browser genuinely can — which is not
|
|
617
|
+
the same as what `ctx.fetch` does on the server (DNS pinning, real redirect
|
|
618
|
+
re-vetting), and production runs no egress check on the client path, at any
|
|
619
|
+
layer, today. See the "Network model" note in a scaffolded project's
|
|
620
|
+
`AGENTS.md` for the fuller statement partners see.
|
|
606
621
|
|
|
607
622
|
**So when you set `definition`, do not set `live.egress`.** Supplying both is a
|
|
608
623
|
hard error naming your slug, not a silent preference — a silent preference is
|
|
@@ -628,22 +643,90 @@ disabled for it and says why.
|
|
|
628
643
|
|
|
629
644
|
### Knowing the mode, and the activation-data channel
|
|
630
645
|
|
|
631
|
-
Two things a live-mode widget routinely needs
|
|
632
|
-
|
|
646
|
+
Two things a live-mode widget routinely needs: **which mode is actually
|
|
647
|
+
running**, and **a credential to authenticate with**.
|
|
648
|
+
|
|
649
|
+
For the credential, call `useActivationData()` from `@ekanos/sdk/hooks`. The
|
|
650
|
+
harness mounts `IntegrationActivationDataProvider` unconditionally, so this
|
|
651
|
+
returns whatever was last submitted to this integration's activation form —
|
|
652
|
+
`null` before any submission or after Disconnect — with no provider of your
|
|
653
|
+
own required. It is held **in memory only**: never written to `localStorage`,
|
|
654
|
+
a fixture, or the registry, and cleared on reload and on disconnect. It is a
|
|
655
|
+
dev-only convenience standing in for `ctx.secrets`, which is what production
|
|
656
|
+
actually hands your server-side handlers.
|
|
657
|
+
|
|
658
|
+
For the mode itself, call `useHarnessDataMode()` from `@ekanos/harness/hooks`.
|
|
659
|
+
This one has no SDK equivalent and stays harness-only — production runs
|
|
660
|
+
exactly one mode, so there is nothing for a host-side hook to report. It
|
|
661
|
+
returns the EFFECTIVE mode (`'fixtures' | 'live'`), already accounting for an
|
|
662
|
+
integration with no `live` block or a `live.egress`/definition mismatch (both
|
|
663
|
+
force `'fixtures'`, whatever the toolbar says):
|
|
664
|
+
|
|
665
|
+
```tsx
|
|
666
|
+
import { useHarnessDataMode } from '@ekanos/harness/hooks';
|
|
667
|
+
import { useActivationData, useIntegrationFetch } from '@ekanos/sdk/hooks';
|
|
668
|
+
|
|
669
|
+
function useAcmeSummary(accountId: string) {
|
|
670
|
+
const fetch = useIntegrationFetch();
|
|
671
|
+
const mode = useHarnessDataMode();
|
|
672
|
+
const activationData = useActivationData<{ apiToken?: string }>();
|
|
633
673
|
|
|
634
|
-
|
|
635
|
-
|
|
674
|
+
// ...
|
|
675
|
+
}
|
|
676
|
+
```
|
|
677
|
+
|
|
678
|
+
A hand-written `FetchProvider` — where one already exists — receives all
|
|
679
|
+
three (`fetch`, `mode`, `activationData`) as props too, no extra plumbing
|
|
680
|
+
required; see "The legacy seam" below for when writing one is still the
|
|
681
|
+
better call over the hooks above (and for the same token-threading example,
|
|
682
|
+
written the `FetchProvider` way).
|
|
683
|
+
|
|
684
|
+
Reach for `useHarnessDataMode()`/`useActivationData()` directly (as above)
|
|
685
|
+
rather than the props on a `FetchProvider` wherever you can — they need no
|
|
686
|
+
`FetchProvider` of your own, and `useIntegrationFetch()`/`useActivationData()`
|
|
687
|
+
behave identically whether or not `@ekanos/harness` is even installed at the
|
|
688
|
+
call site (a plain fetch and `null`, outside the harness, until a host mounts
|
|
689
|
+
its own provider). `useHarnessDataMode()` is the one exception with no SDK
|
|
690
|
+
equivalent — call it only from code that runs nowhere but inside the dev
|
|
691
|
+
harness.
|
|
692
|
+
|
|
693
|
+
### `FetchProvider` — the legacy seam, still supported
|
|
694
|
+
|
|
695
|
+
> **No longer the default for a new integration.** `useIntegrationFetch()`
|
|
696
|
+
> from `@ekanos/sdk/hooks` already returns a fetch gated correctly for
|
|
697
|
+
> whichever mode the harness toolbar is in, with nothing to write — see
|
|
698
|
+
> "No partner wiring required" above. Reach for a hand-written
|
|
699
|
+
> `FetchProvider` only for the one case it still earns its keep: composing an
|
|
700
|
+
> authenticated fetch ONCE, at a single seam (e.g. attaching an
|
|
701
|
+
> `Authorization` header derived from `activationData` to every request your
|
|
702
|
+
> query functions make), instead of repeating that composition in every query
|
|
703
|
+
> function. If that is not a problem you have, skip this section.
|
|
704
|
+
>
|
|
705
|
+
> The harness patches `globalThis.fetch` underneath either path, so a
|
|
706
|
+
> `FetchProvider` is not an escape hatch from the harness's live-mode egress
|
|
707
|
+
> check — see "Network model" in a scaffolded project's `AGENTS.md` for what
|
|
708
|
+
> that check does and does not mean once you leave the harness.
|
|
709
|
+
|
|
710
|
+
The provider receives `fetch`, `mode`, and `activationData` as props, no extra
|
|
711
|
+
plumbing required — this is, in miniature, the same ~twenty-line pattern
|
|
712
|
+
`@ekanos/sdk/hooks` now ships as `IntegrationFetchProvider`/
|
|
713
|
+
`useIntegrationFetch()`:
|
|
636
714
|
|
|
637
715
|
```tsx
|
|
638
|
-
|
|
716
|
+
'use client';
|
|
717
|
+
|
|
718
|
+
import { type ReactNode, createContext, use } from 'react';
|
|
639
719
|
|
|
640
720
|
import type { IntegrationFetch } from '@ekanos/sdk';
|
|
641
721
|
import type { DataMode } from '@ekanos/harness/registry';
|
|
642
722
|
|
|
723
|
+
const browserFetch: IntegrationFetch = (input, init) =>
|
|
724
|
+
globalThis.fetch(input as RequestInfo, init);
|
|
725
|
+
|
|
726
|
+
const AcmeFetchContext = createContext<IntegrationFetch>(browserFetch);
|
|
727
|
+
|
|
643
728
|
export function AcmeFetchProvider({
|
|
644
729
|
fetch,
|
|
645
|
-
mode,
|
|
646
|
-
activationData,
|
|
647
730
|
children,
|
|
648
731
|
}: {
|
|
649
732
|
fetch: IntegrationFetch;
|
|
@@ -653,25 +736,16 @@ export function AcmeFetchProvider({
|
|
|
653
736
|
}) {
|
|
654
737
|
return <AcmeFetchContext value={fetch}>{children}</AcmeFetchContext>;
|
|
655
738
|
}
|
|
656
|
-
```
|
|
657
739
|
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
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.
|
|
740
|
+
/** The fetch this integration's query functions should use. */
|
|
741
|
+
export function useAcmeFetch(): IntegrationFetch {
|
|
742
|
+
return use(AcmeFetchContext);
|
|
743
|
+
}
|
|
744
|
+
```
|
|
666
745
|
|
|
667
|
-
|
|
746
|
+
Composing the token onto every request, the one case this seam is still for:
|
|
668
747
|
|
|
669
748
|
```tsx
|
|
670
|
-
import type { ReactNode } from 'react';
|
|
671
|
-
|
|
672
|
-
import type { IntegrationFetch } from '@ekanos/sdk';
|
|
673
|
-
import type { DataMode } from '@ekanos/harness/registry';
|
|
674
|
-
|
|
675
749
|
export function AcmeFetchProvider({ fetch, activationData, children }: {
|
|
676
750
|
fetch: IntegrationFetch;
|
|
677
751
|
mode: DataMode;
|
|
@@ -693,66 +767,9 @@ export function AcmeFetchProvider({ fetch, activationData, children }: {
|
|
|
693
767
|
}
|
|
694
768
|
```
|
|
695
769
|
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
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
|
|
702
|
-
harness.
|
|
703
|
-
|
|
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.
|
|
710
|
-
>
|
|
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.
|
|
714
|
-
|
|
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:
|
|
725
|
-
|
|
726
|
-
```tsx
|
|
727
|
-
'use client';
|
|
728
|
-
|
|
729
|
-
import { type ReactNode, createContext, use } from 'react';
|
|
730
|
-
|
|
731
|
-
import type { IntegrationFetch } from '@ekanos/sdk';
|
|
732
|
-
|
|
733
|
-
const browserFetch: IntegrationFetch = (input, init) =>
|
|
734
|
-
globalThis.fetch(input as RequestInfo, init);
|
|
735
|
-
|
|
736
|
-
const AcmeFetchContext = createContext<IntegrationFetch>(browserFetch);
|
|
737
|
-
|
|
738
|
-
export function AcmeFetchProvider({
|
|
739
|
-
fetch,
|
|
740
|
-
children,
|
|
741
|
-
}: {
|
|
742
|
-
fetch: IntegrationFetch;
|
|
743
|
-
children: ReactNode;
|
|
744
|
-
}) {
|
|
745
|
-
return <AcmeFetchContext value={fetch}>{children}</AcmeFetchContext>;
|
|
746
|
-
}
|
|
747
|
-
|
|
748
|
-
/** The fetch this integration's query functions should use. */
|
|
749
|
-
export function useAcmeFetch(): IntegrationFetch {
|
|
750
|
-
return use(AcmeFetchContext);
|
|
751
|
-
}
|
|
752
|
-
```
|
|
753
|
-
|
|
754
|
-
Then have your query functions **take an `IntegrationFetch` as an argument**
|
|
755
|
-
rather than reaching for a global:
|
|
770
|
+
Either way — the SDK's hook or a hand-rolled one — have your query functions
|
|
771
|
+
**take an `IntegrationFetch` as an argument** rather than reaching for a
|
|
772
|
+
global:
|
|
756
773
|
|
|
757
774
|
```ts
|
|
758
775
|
import type { IntegrationFetch } from '@ekanos/sdk';
|
|
@@ -764,24 +781,23 @@ export async function fetchAcmeSummary(fetch: IntegrationFetch, accountId: strin
|
|
|
764
781
|
}
|
|
765
782
|
|
|
766
783
|
// in the hook
|
|
767
|
-
const fetch = useAcmeFetch()
|
|
784
|
+
const fetch = useIntegrationFetch(); // or useAcmeFetch() for the legacy seam
|
|
768
785
|
useQuery({ queryKey: acmeKeys.summary(accountId), queryFn: () => fetchAcmeSummary(fetch, accountId) });
|
|
769
786
|
```
|
|
770
787
|
|
|
771
788
|
That is the value of the pattern, beyond the harness: the *same* code path
|
|
772
|
-
serves `ctx.fetch` on the server and
|
|
773
|
-
|
|
789
|
+
serves `ctx.fetch` on the server and this hook's fetch on the client — gated
|
|
790
|
+
by the harness's own check in dev, and a plain, unmediated browser fetch in
|
|
791
|
+
production today (see "Network model" in `AGENTS.md`).
|
|
774
792
|
|
|
775
793
|
The provider's props are fixed by the type — `{ fetch: IntegrationFetch; mode:
|
|
776
794
|
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.
|
|
795
|
+
mounts it, alongside (not instead of) the SDK's own providers, whenever an
|
|
796
|
+
entry declares one. Omit `FetchProvider` entirely if your widgets fetch only
|
|
797
|
+
through your own host routes: those are answered from fixtures (record them
|
|
798
|
+
under `/api/…`) in EVERY toolbar mode, live included — there is no Supabase
|
|
799
|
+
and no `ctx` to execute a route with, so there is nothing "live" to run for
|
|
800
|
+
that traffic either way.
|
|
785
801
|
|
|
786
802
|
## Triggers — running webhooks, schedules and OAuth locally
|
|
787
803
|
|
|
@@ -6,6 +6,8 @@ import {
|
|
|
6
6
|
} from "@ekanos/sdk/hooks";
|
|
7
7
|
import { AskAssistantProvider } from "@ekanos/sdk/hooks";
|
|
8
8
|
import { WidgetEventProvider } from "@ekanos/sdk/hooks";
|
|
9
|
+
import { IntegrationFetchProvider } from "@ekanos/sdk/hooks";
|
|
10
|
+
import { IntegrationActivationDataProvider } from "@ekanos/sdk/hooks";
|
|
9
11
|
import { QueryClientProvider } from "@tanstack/react-query";
|
|
10
12
|
import { TeamAccountWorkspaceContextProvider } from "../../mocks/team-account-workspace.js";
|
|
11
13
|
import {
|
|
@@ -86,10 +88,10 @@ function HarnessProviders({
|
|
|
86
88
|
});
|
|
87
89
|
}, [mode, httpFixtures, egress, slug]);
|
|
88
90
|
const FetchProvider = live?.FetchProvider;
|
|
89
|
-
const tree = /* @__PURE__ */ jsx(QueryClientProvider, { client: queryClient, children: /* @__PURE__ */ jsx(TeamAccountWorkspaceContextProvider, { children: /* @__PURE__ */ jsx(IntegrationActivationProvider, { actions: fixtureActivationActions, children: /* @__PURE__ */ jsx(WidgetEventProvider, { children: /* @__PURE__ */ jsxs(AskAssistantProvider, { children: [
|
|
91
|
+
const tree = /* @__PURE__ */ jsx(IntegrationFetchProvider, { fetch: harnessFetch, children: /* @__PURE__ */ jsx(IntegrationActivationDataProvider, { value: activationData, children: /* @__PURE__ */ jsx(QueryClientProvider, { client: queryClient, children: /* @__PURE__ */ jsx(TeamAccountWorkspaceContextProvider, { children: /* @__PURE__ */ jsx(IntegrationActivationProvider, { actions: fixtureActivationActions, children: /* @__PURE__ */ jsx(WidgetEventProvider, { children: /* @__PURE__ */ jsxs(AskAssistantProvider, { children: [
|
|
90
92
|
/* @__PURE__ */ jsx(AskAssistantBridge, {}),
|
|
91
93
|
/* @__PURE__ */ jsx(Suspense, { fallback: null, children })
|
|
92
|
-
] }) }) }) }) });
|
|
94
|
+
] }) }) }) }) }) }) });
|
|
93
95
|
return FetchProvider ? /* @__PURE__ */ jsx(
|
|
94
96
|
FetchProvider,
|
|
95
97
|
{
|
|
@@ -55,15 +55,24 @@ function ActivationPage() {
|
|
|
55
55
|
children: [
|
|
56
56
|
/* @__PURE__ */ jsxs(Alert, { children: [
|
|
57
57
|
/* @__PURE__ */ jsx(AlertTitle, { children: "Submissions go nowhere" }),
|
|
58
|
-
/* @__PURE__ */
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
58
|
+
/* @__PURE__ */ jsxs(AlertDescription, { children: [
|
|
59
|
+
/* @__PURE__ */ jsxs("p", { children: [
|
|
60
|
+
"The harness has no backend. Submitting shows you the",
|
|
61
|
+
" ",
|
|
62
|
+
/* @__PURE__ */ jsx("code", { children: "ActivationResult" }),
|
|
63
|
+
" your form handed back instead of posting it \u2014 which is the part worth checking, since that payload is what the real activation action would persist. The dialog, the capability and permission sections and the connected state are the real ones, rendered from your ",
|
|
64
|
+
/* @__PURE__ */ jsx("code", { children: "defineIntegration()" }),
|
|
65
|
+
" ",
|
|
66
|
+
"declaration."
|
|
67
|
+
] }),
|
|
68
|
+
/* @__PURE__ */ jsxs("p", { children: [
|
|
69
|
+
/* @__PURE__ */ jsx("code", { children: "onActivate" }),
|
|
70
|
+
" below always runs against this mock context, live toggle or not \u2014 its network calls never leave your machine here. A widget on this integration is different: it already reaches real vendors through",
|
|
71
|
+
" ",
|
|
72
|
+
/* @__PURE__ */ jsx("code", { children: "useIntegrationFetch()" }),
|
|
73
|
+
" once you flip the toolbar to Live API. Both reach real systems for real only after you publish to the dev host."
|
|
74
|
+
] })
|
|
75
|
+
] })
|
|
67
76
|
] }),
|
|
68
77
|
/* @__PURE__ */ jsxs("div", { className: "bg-card flex flex-wrap items-center justify-between gap-3 rounded-lg border p-5", children: [
|
|
69
78
|
/* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1", children: [
|
|
@@ -266,13 +266,24 @@ function OAuthCard({ definition }) {
|
|
|
266
266
|
/* @__PURE__ */ jsx("p", { children: /* @__PURE__ */ jsxs("code", { children: [
|
|
267
267
|
"https://<your-fusion-host>/api/integrations/",
|
|
268
268
|
definition.slug,
|
|
269
|
-
"/callback"
|
|
269
|
+
"/oauth/callback"
|
|
270
270
|
] }) }),
|
|
271
271
|
/* @__PURE__ */ jsxs("p", { children: [
|
|
272
|
-
"The harness does not serve that route, so you cannot complete a round trip here. What you CAN check is above: that the endpoints you declared are inside your egress list.
|
|
272
|
+
"The harness does not serve that route, so you cannot complete a round trip here. What you CAN check is above: that the endpoints you declared are inside your egress list. For a real round trip, run the hosted transport against a local Fusion host \u2014 register",
|
|
273
|
+
" ",
|
|
274
|
+
/* @__PURE__ */ jsxs("code", { children: [
|
|
275
|
+
"http://localhost:3000/api/integrations/",
|
|
276
|
+
definition.slug,
|
|
277
|
+
"/oauth/callback"
|
|
278
|
+
] }),
|
|
279
|
+
" ",
|
|
280
|
+
"with your provider and click Connect from the marketplace; the host exchanges the code through your declared egress and calls",
|
|
281
|
+
" ",
|
|
282
|
+
/* @__PURE__ */ jsx("code", { children: "onTokens" }),
|
|
283
|
+
". For unit coverage, call ",
|
|
273
284
|
/* @__PURE__ */ jsx("code", { children: "onTokens" }),
|
|
274
|
-
" directly with",
|
|
275
285
|
" ",
|
|
286
|
+
"directly with ",
|
|
276
287
|
/* @__PURE__ */ jsx("code", { children: "createMockContext()" }),
|
|
277
288
|
" \u2014 it is an ordinary async function."
|
|
278
289
|
] })
|
|
@@ -302,12 +313,19 @@ function TriggersPage() {
|
|
|
302
313
|
children: [
|
|
303
314
|
/* @__PURE__ */ jsxs(Alert, { children: [
|
|
304
315
|
/* @__PURE__ */ jsx(AlertTitle, { children: "The local transport for declared event surfaces" }),
|
|
305
|
-
/* @__PURE__ */
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
316
|
+
/* @__PURE__ */ jsxs(AlertDescription, { children: [
|
|
317
|
+
/* @__PURE__ */ jsxs("p", { children: [
|
|
318
|
+
"Webhooks and schedules below run their REAL handlers against one in-memory mock context (state accumulates until you leave the page). Payloads are validated against each webhook's",
|
|
319
|
+
" ",
|
|
320
|
+
/* @__PURE__ */ jsx("code", { children: "payloadSchema" }),
|
|
321
|
+
", signature checks are logged as skipped, and egress is enforced from the definition \u2014 the same declarations the host's ingress, scheduler, and hosted OAuth callback bind to later."
|
|
322
|
+
] }),
|
|
323
|
+
/* @__PURE__ */ jsxs("p", { children: [
|
|
324
|
+
"This is fixtures every time, whatever the toolbar says \u2014 nothing below reaches a real system until you publish to the dev host. A widget on this integration is different: it already reaches real vendors through ",
|
|
325
|
+
/* @__PURE__ */ jsx("code", { children: "useIntegrationFetch()" }),
|
|
326
|
+
" once you flip the toolbar to Live API."
|
|
327
|
+
] })
|
|
328
|
+
] })
|
|
311
329
|
] }),
|
|
312
330
|
!definition ? /* @__PURE__ */ jsxs("p", { className: "text-muted-foreground text-sm", children: [
|
|
313
331
|
"This harness entry does not link its ",
|
package/dist/registry.d.ts
CHANGED
|
@@ -146,22 +146,40 @@ export interface HarnessLiveMode {
|
|
|
146
146
|
*/
|
|
147
147
|
egress?: readonly string[];
|
|
148
148
|
/**
|
|
149
|
-
*
|
|
149
|
+
* @deprecated The SDK now ships this pattern: `useIntegrationFetch()` /
|
|
150
|
+
* `useActivationData()` from `@ekanos/sdk/hooks`. A NEW integration should
|
|
151
|
+
* reach for those directly rather than writing a `FetchProvider` — the
|
|
152
|
+
* harness mounts both unconditionally around every widget (see
|
|
153
|
+
* `HarnessProviders` in `internal/components/harness-providers.tsx`), fed
|
|
154
|
+
* the exact same `harnessFetch`/`activationData` this field receives, so
|
|
155
|
+
* there is nothing left for a hand-written provider to do for a widget
|
|
156
|
+
* that only needs its own vendor's fetch.
|
|
150
157
|
*
|
|
151
|
-
*
|
|
152
|
-
* whether or not you supply this — which is the point: an interception a
|
|
153
|
-
* partner can decline to wire is not really an interception. It used to be
|
|
154
|
-
* the only seam through which live mode could hand you an allowlisted fetch,
|
|
155
|
-
* and omitting it was an unintentional escape hatch.
|
|
158
|
+
* This field stays supported, unchanged in shape, for two reasons:
|
|
156
159
|
*
|
|
157
|
-
*
|
|
158
|
-
*
|
|
159
|
-
*
|
|
160
|
-
*
|
|
161
|
-
*
|
|
160
|
+
* 1. Existing code that already wrote one keeps working — nesting is
|
|
161
|
+
* additive, not a breaking swap. A partner's own `FetchProvider` still
|
|
162
|
+
* wraps OUTSIDE the SDK's providers, establishing its own, separate
|
|
163
|
+
* context for a widget still calling the partner's own
|
|
164
|
+
* `useAcmeFetch()`.
|
|
165
|
+
* 2. It still earns its keep for the one case `useIntegrationFetch()`
|
|
166
|
+
* alone does not cover: composing `activationData` into an
|
|
167
|
+
* authenticated fetch ONCE, at a single seam, rather than in every
|
|
168
|
+
* query function. `useIntegrationFetch()`'s value carries no
|
|
169
|
+
* `Authorization` header of its own — attaching one from
|
|
170
|
+
* `useActivationData()` is now the widget's/query-function's own job,
|
|
171
|
+
* unless a `FetchProvider` like this one does it centrally instead.
|
|
172
|
+
*
|
|
173
|
+
* The harness patches `globalThis.fetch` regardless, so it reaches your
|
|
174
|
+
* requests whether or not you supply this — which is the point: an
|
|
175
|
+
* interception a partner can decline to wire is not really an
|
|
176
|
+
* interception. It used to be the only seam through which live mode could
|
|
177
|
+
* hand you an allowlisted fetch, and omitting it was an unintentional
|
|
178
|
+
* escape hatch.
|
|
162
179
|
*
|
|
163
180
|
* The pattern is a ~20-line React context whose default is the browser's
|
|
164
|
-
* `fetch
|
|
181
|
+
* `fetch` — reach for `useIntegrationFetch()` instead unless you need
|
|
182
|
+
* reason 2 above:
|
|
165
183
|
*
|
|
166
184
|
* ```tsx
|
|
167
185
|
* 'use client';
|
package/dist/styles.css
CHANGED
|
@@ -199,7 +199,7 @@ i.fa-sparkles {
|
|
|
199
199
|
}
|
|
200
200
|
|
|
201
201
|
/* Reported by a partner build (2026-09-08): all seven are real Font Awesome
|
|
202
|
-
* PRO names (verified against
|
|
202
|
+
* PRO names (verified against the host's Font Awesome Pro subset) that Free does not
|
|
203
203
|
* ship, so every one of them was rendering the bare circle-question fallback
|
|
204
204
|
* with no indication why. `fa-circle-question` itself was also reported, but
|
|
205
205
|
* it is NOT Free-missing — Free ships it natively at the same codepoint
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ekanos/harness",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "The Ekanos integration dev harness — every surface of an integration rendered in real Fusion chrome, from fixtures, with no Supabase, auth or network.",
|
|
6
6
|
"license": "MIT",
|
|
@@ -57,8 +57,8 @@
|
|
|
57
57
|
"tw-animate-css": "1.4.0"
|
|
58
58
|
},
|
|
59
59
|
"peerDependencies": {
|
|
60
|
-
"@ekanos/sdk": "^0.
|
|
61
|
-
"@ekanos/ui": "^0.
|
|
60
|
+
"@ekanos/sdk": "^0.2.0",
|
|
61
|
+
"@ekanos/ui": "^0.2.0",
|
|
62
62
|
"@tanstack/react-query": "^5.101.4",
|
|
63
63
|
"next": "^16.0.0",
|
|
64
64
|
"react": "^19.2.8",
|
|
@@ -66,8 +66,8 @@
|
|
|
66
66
|
"tailwindcss": "^4.0.0"
|
|
67
67
|
},
|
|
68
68
|
"devDependencies": {
|
|
69
|
-
"@ekanos/sdk": "0.
|
|
70
|
-
"@ekanos/ui": "0.
|
|
69
|
+
"@ekanos/sdk": "0.2.0",
|
|
70
|
+
"@ekanos/ui": "0.2.0",
|
|
71
71
|
"@kit/eslint-config": "0.2.0",
|
|
72
72
|
"@kit/prettier-config": "0.1.0",
|
|
73
73
|
"@kit/tsconfig": "0.1.0",
|