@ekanos/harness 0.1.4 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +286 -174
  2. package/dist/api.d.ts +42 -0
  3. package/dist/api.js +17 -0
  4. package/dist/internal/components/dev-toolbar.js +4 -2
  5. package/dist/internal/components/harness-providers.js +5 -2
  6. package/dist/internal/components/local-oauth-panel.d.ts +29 -0
  7. package/dist/internal/components/local-oauth-panel.js +355 -0
  8. package/dist/internal/lib/harness-fetch-interceptor.d.ts +33 -13
  9. package/dist/internal/lib/harness-fetch-interceptor.js +10 -0
  10. package/dist/internal/lib/oauth-setup-guide.d.ts +43 -0
  11. package/dist/internal/lib/oauth-setup-guide.js +28 -0
  12. package/dist/internal/lib/original-fetch.d.ts +36 -0
  13. package/dist/internal/lib/original-fetch.js +23 -0
  14. package/dist/internal/lib/run-activation-hook.d.ts +2 -8
  15. package/dist/internal/lib/toolbar-context.d.ts +7 -3
  16. package/dist/internal/lib/toolbar-context.js +10 -5
  17. package/dist/internal/lib/trigger-contract.d.ts +99 -0
  18. package/dist/internal/lib/trigger-contract.js +25 -0
  19. package/dist/internal/lib/trigger-runner.d.ts +55 -0
  20. package/dist/internal/lib/trigger-runner.js +153 -0
  21. package/dist/internal/routes/activation-page.js +51 -28
  22. package/dist/internal/routes/integration-layout.js +5 -1
  23. package/dist/internal/routes/triggers-page.js +130 -149
  24. package/dist/internal/server/api-router.d.ts +42 -0
  25. package/dist/internal/server/api-router.js +465 -0
  26. package/dist/internal/server/live-context.d.ts +93 -0
  27. package/dist/internal/server/live-context.js +93 -0
  28. package/dist/internal/server/local-secrets.d.ts +84 -0
  29. package/dist/internal/server/local-secrets.js +144 -0
  30. package/dist/internal/server/loopback-guard.d.ts +33 -0
  31. package/dist/internal/server/loopback-guard.js +38 -0
  32. package/dist/internal/server/nonce-store.d.ts +38 -0
  33. package/dist/internal/server/nonce-store.js +40 -0
  34. package/dist/internal/server/oauth-loop.d.ts +114 -0
  35. package/dist/internal/server/oauth-loop.js +141 -0
  36. package/dist/internal/server/project-root.d.ts +29 -0
  37. package/dist/internal/server/project-root.js +31 -0
  38. package/dist/internal/server/storage-read.d.ts +34 -0
  39. package/dist/internal/server/storage-read.js +53 -0
  40. package/dist/registry.d.ts +103 -13
  41. package/dist/registry.js +21 -1
  42. package/package.json +13 -7
@@ -0,0 +1,31 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ const PROJECT_ROOT_ENV = "EKANOS_PROJECT_ROOT";
4
+ function resolveProjectRoot(args) {
5
+ const exists = args.exists ?? fs.existsSync;
6
+ const configured = args.env[PROJECT_ROOT_ENV]?.trim();
7
+ if (configured) {
8
+ const root = path.resolve(configured);
9
+ if (exists(path.join(root, "ekanos.json"))) {
10
+ return { ok: true, root, source: "env" };
11
+ }
12
+ return {
13
+ ok: false,
14
+ message: `${PROJECT_ROOT_ENV}=${configured} does not contain an ekanos.json.`,
15
+ hint: 'Point it at the directory that holds ekanos.json, or unset it and start the harness with "ekanos dev".'
16
+ };
17
+ }
18
+ const fromCwd = path.resolve(args.cwd, "..", "..");
19
+ if (exists(path.join(fromCwd, "ekanos.json"))) {
20
+ return { ok: true, root: fromCwd, source: "cwd" };
21
+ }
22
+ return {
23
+ ok: false,
24
+ message: `Could not find the project root: no ekanos.json at ${fromCwd} (two directories above the server's cwd, ${args.cwd}).`,
25
+ hint: `Start the harness with "ekanos dev" so it runs from .ekanos/harness, or set ${PROJECT_ROOT_ENV} to the directory that holds ekanos.json.`
26
+ };
27
+ }
28
+ export {
29
+ PROJECT_ROOT_ENV,
30
+ resolveProjectRoot
31
+ };
@@ -0,0 +1,34 @@
1
+ import type { IntegrationContext } from '@ekanos/sdk';
2
+ import type { IntegrationDefinition } from '@ekanos/sdk/integration';
3
+ /**
4
+ * The read half of `GET /api/integrations/[slug]/storage`, mirroring the
5
+ * Fusion host's generic storage route so `fetchIntegrationStorage()` in `@ekanos/sdk` — and therefore every
6
+ * partner widget built on it — works against the harness unchanged:
7
+ *
8
+ * - `?accountId=…&keys=a,b`, at most 20 keys, 400 on a malformed request;
9
+ * - the response is `{ [key]: value }` with no envelope;
10
+ * - a key is served only when its declaration says `clientReadable: true`.
11
+ * An undeclared key, a declared-but-private key, and a key with no stored
12
+ * row are all simply ABSENT — the route must not become an existence
13
+ * oracle over a partner's private key names;
14
+ * - one key whose stored row no longer parses against its schema is omitted
15
+ * and logged, and does not take the other keys down with it.
16
+ */
17
+ /** Mirrors the host route's own per-request cap. */
18
+ export declare const MAX_KEYS_PER_REQUEST = 20;
19
+ export type StorageQuery = {
20
+ ok: true;
21
+ accountId: string;
22
+ keys: string[];
23
+ } | {
24
+ ok: false;
25
+ error: string;
26
+ };
27
+ export declare function parseStorageQuery(url: URL): StorageQuery;
28
+ export declare function readClientReadableStorage(args: {
29
+ ctx: Pick<IntegrationContext, 'storage'>;
30
+ definition: Pick<IntegrationDefinition, 'storage' | 'slug'>;
31
+ keys: readonly string[];
32
+ /** Test seam; defaults to `console.warn`. */
33
+ warn?: (message: string, error: unknown) => void;
34
+ }): Promise<Record<string, unknown>>;
@@ -0,0 +1,53 @@
1
+ import { isStorageKeyClientReadable } from "@ekanos/sdk/context";
2
+ const MAX_KEYS_PER_REQUEST = 20;
3
+ function parseStorageQuery(url) {
4
+ const accountId = url.searchParams.get("accountId");
5
+ if (!accountId) {
6
+ return { ok: false, error: "accountId query parameter is required" };
7
+ }
8
+ const keys = Array.from(
9
+ new Set(
10
+ (url.searchParams.get("keys") ?? "").split(",").map((key) => key.trim()).filter((key) => key.length > 0)
11
+ )
12
+ );
13
+ if (keys.length === 0) {
14
+ return {
15
+ ok: false,
16
+ error: "keys query parameter is required (comma-separated)"
17
+ };
18
+ }
19
+ if (keys.length > MAX_KEYS_PER_REQUEST) {
20
+ return {
21
+ ok: false,
22
+ error: `A single request may read at most ${MAX_KEYS_PER_REQUEST} storage keys`
23
+ };
24
+ }
25
+ return { ok: true, accountId, keys };
26
+ }
27
+ async function readClientReadableStorage(args) {
28
+ const warn = args.warn ?? ((message, error) => console.warn(message, error));
29
+ const schemas = args.definition.storage?.account;
30
+ const readable = args.keys.filter(
31
+ (key) => isStorageKeyClientReadable({ key, schemas })
32
+ );
33
+ const entries = await Promise.all(
34
+ readable.map(async (key) => {
35
+ try {
36
+ const entry = await args.ctx.storage.account.get(key);
37
+ return entry ? [key, entry.data] : null;
38
+ } catch (error) {
39
+ warn(
40
+ `[harness:${args.definition.slug}] storage: declared clientReadable key "${key}" failed to read`,
41
+ error
42
+ );
43
+ return null;
44
+ }
45
+ })
46
+ );
47
+ return Object.fromEntries(entries.filter((entry) => entry !== null));
48
+ }
49
+ export {
50
+ MAX_KEYS_PER_REQUEST,
51
+ parseStorageQuery,
52
+ readClientReadableStorage
53
+ };
@@ -146,22 +146,51 @@ export interface HarnessLiveMode {
146
146
  */
147
147
  egress?: readonly string[];
148
148
  /**
149
- * OPTIONAL, and no longer needed for the harness to work.
149
+ * The mode this integration STARTS in, before the person at the toolbar has
150
+ * picked one. `'fixtures'` (the default) keeps the harness's promise that
151
+ * opening it never fires a request at a vendor. Declare `'live'` when your
152
+ * widgets never call the vendor from the browser — they talk only to the
153
+ * harness's own `/api/integrations/<slug>/…` routes and every vendor call
154
+ * runs server-side behind `ctx.fetch`, the OAuth shape — so starting live
155
+ * costs nothing and saves hunting for the switch. A choice made at the
156
+ * toolbar always wins over this, and is remembered.
157
+ */
158
+ default?: DataMode;
159
+ /**
160
+ * @deprecated The SDK now ships this pattern: `useIntegrationFetch()` /
161
+ * `useActivationData()` from `@ekanos/sdk/hooks`. A NEW integration should
162
+ * reach for those directly rather than writing a `FetchProvider` — the
163
+ * harness mounts both unconditionally around every widget (see
164
+ * `HarnessProviders` in `internal/components/harness-providers.tsx`), fed
165
+ * the exact same `harnessFetch`/`activationData` this field receives, so
166
+ * there is nothing left for a hand-written provider to do for a widget
167
+ * that only needs its own vendor's fetch.
150
168
  *
151
- * The harness patches `globalThis.fetch`, so it reaches your requests
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.
169
+ * This field stays supported, unchanged in shape, for two reasons:
156
170
  *
157
- * It is still worth having in YOUR code, for a reason that has nothing to do
158
- * with the harness: it lets one code path serve `ctx.fetch` on the server and
159
- * a browser fetch on the client, instead of a query function reaching for a
160
- * global and behaving differently in each. If you supply it, the harness
161
- * hands it the same fetch it would have used anyway.
171
+ * 1. Existing code that already wrote one keeps working — nesting is
172
+ * additive, not a breaking swap. A partner's own `FetchProvider` still
173
+ * wraps OUTSIDE the SDK's providers, establishing its own, separate
174
+ * context for a widget still calling the partner's own
175
+ * `useAcmeFetch()`.
176
+ * 2. It still earns its keep for the one case `useIntegrationFetch()`
177
+ * alone does not cover: composing `activationData` into an
178
+ * authenticated fetch ONCE, at a single seam, rather than in every
179
+ * query function. `useIntegrationFetch()`'s value carries no
180
+ * `Authorization` header of its own — attaching one from
181
+ * `useActivationData()` is now the widget's/query-function's own job,
182
+ * unless a `FetchProvider` like this one does it centrally instead.
183
+ *
184
+ * The harness patches `globalThis.fetch` regardless, so it reaches your
185
+ * requests whether or not you supply this — which is the point: an
186
+ * interception a partner can decline to wire is not really an
187
+ * interception. It used to be the only seam through which live mode could
188
+ * hand you an allowlisted fetch, and omitting it was an unintentional
189
+ * escape hatch.
162
190
  *
163
191
  * The pattern is a ~20-line React context whose default is the browser's
164
- * `fetch`:
192
+ * `fetch` — reach for `useIntegrationFetch()` instead unless you need
193
+ * reason 2 above:
165
194
  *
166
195
  * ```tsx
167
196
  * 'use client';
@@ -322,6 +351,51 @@ export interface HarnessIntegration {
322
351
  definition?: IntegrationDefinition;
323
352
  /** Seeds for the Triggers surface's mock context. */
324
353
  triggerMocks?: HarnessTriggerMocks;
354
+ /**
355
+ * The OAuth CONNECTION STATE fixtures mode presents, for an integration
356
+ * whose definition declares `oauth`.
357
+ *
358
+ * The SDK's `OAuthActivationForm` and `useOAuthWidgetGate` poll
359
+ * `GET /api/integrations/<slug>/oauth/status`; in fixtures mode the harness
360
+ * answers that route itself from this field, so you do not hand-write a
361
+ * status fixture. Connected by default — fixtures mode exists to render
362
+ * widgets, and an unconnected integration renders a Connect prompt instead.
363
+ * Set `false`, or per variant (`{ empty: false }`), to see that prompt.
364
+ *
365
+ * Live mode ignores this: there the status is real — whether the loop has
366
+ * actually run on this server since it started.
367
+ */
368
+ oauth?: {
369
+ connected?: boolean | Partial<Record<FixtureVariant, boolean>>;
370
+ /**
371
+ * What a HUMAN has to do in the provider's developer console before the
372
+ * loop can run — the part no code can do for them. The harness already
373
+ * derives the checklist it can from the declaration (provider host,
374
+ * redirect URI, scopes, PKCE, which secret name is which); this adds the
375
+ * two things it cannot: where the console is, and the provider's own
376
+ * words for each step.
377
+ *
378
+ * ```ts HarnessIntegration
379
+ * oauth: {
380
+ * setup: {
381
+ * consoleUrl: 'https://admindemo.docusign.com/apps-and-keys',
382
+ * consoleLabel: 'DocuSign Admin (demo) → Apps and Keys',
383
+ * notes: [
384
+ * 'Integration Key is the client id; add a Secret Key under Authentication — it is shown once.',
385
+ * ],
386
+ * },
387
+ * },
388
+ * ```
389
+ */
390
+ setup?: {
391
+ /** Where to create or open the OAuth app. Rendered as a link. */
392
+ consoleUrl?: string;
393
+ /** Link text. Defaults to the console URL's host. */
394
+ consoleLabel?: string;
395
+ /** Provider-specific steps, one per line, in the provider's own terms. */
396
+ notes?: string[];
397
+ };
398
+ };
325
399
  }
326
400
  /** The two data sources a surface can render from. */
327
401
  export declare const DATA_MODES: readonly ["fixtures", "live"];
@@ -399,6 +473,20 @@ export declare function collectSeeds(integration: HarnessIntegration, variant: F
399
473
  * difference is the whole fixtures ⇄ live switch.
400
474
  */
401
475
  export declare function seedsForMode(integration: HarnessIntegration, variant: FixtureVariant, mode: DataMode): FixtureSeed[];
476
+ /**
477
+ * Whether fixtures mode presents `integration` as OAuth-connected in
478
+ * `variant`. See `HarnessIntegration.oauth`. Default: connected.
479
+ */
480
+ export declare function resolveOAuthConnected(integration: Pick<HarnessIntegration, 'oauth'>, variant: FixtureVariant): boolean;
481
+ /**
482
+ * The SYNTHESIZED status fixture for an OAuth-declaring integration — the
483
+ * `ConnectionCheckResult` shape `createPartnerConnectionCheck()` in
484
+ * `@ekanos/sdk` expects, at the path it requests. Appended AFTER the partner's
485
+ * own fixtures by the layout, so a hand-written status fixture still wins
486
+ * (first declaration wins in `matchHttpFixture`). Empty when the definition
487
+ * declares no `oauth`: there is nothing to be connected to.
488
+ */
489
+ export declare function oauthStatusFixtures(integration: Pick<HarnessIntegration, 'slug' | 'definition' | 'oauth'>, variant: FixtureVariant): HttpFixture[];
402
490
  /**
403
491
  * A `live.egress` that does not match the integration's own
404
492
  * `defineIntegration({ egress })` declaration.
@@ -478,4 +566,6 @@ export declare function supportsLiveMode(integration: HarnessIntegration | null)
478
566
  * each recomputing it, so there is exactly one place that decides and the
479
567
  * hook can never report a mode other than the one that actually rendered.
480
568
  */
481
- export declare function resolveEffectiveDataMode(integration: HarnessIntegration | null, toolbarMode: DataMode): DataMode;
569
+ export declare function resolveEffectiveDataMode(integration: HarnessIntegration | null,
570
+ /** The toolbar's choice, or `null` when nobody has picked one yet. */
571
+ toolbarMode: DataMode | null): DataMode;
package/dist/registry.js CHANGED
@@ -43,6 +43,24 @@ function collectSeeds(integration, variant) {
43
43
  function seedsForMode(integration, variant, mode) {
44
44
  return mode === "live" ? integration.live?.seeds ?? [] : collectSeeds(integration, variant);
45
45
  }
46
+ function resolveOAuthConnected(integration, variant) {
47
+ const connected = integration.oauth?.connected;
48
+ if (connected === void 0) return true;
49
+ if (typeof connected === "boolean") return connected;
50
+ return connected[variant] ?? true;
51
+ }
52
+ function oauthStatusFixtures(integration, variant) {
53
+ if (!integration.definition?.oauth) return [];
54
+ return [
55
+ {
56
+ request: `GET /api/integrations/${integration.slug}/oauth/status`,
57
+ response: resolveOAuthConnected(integration, variant) ? {
58
+ success: true,
59
+ data: { obtainedAt: "2026-01-01T00:00:00.000Z" }
60
+ } : { success: false, error: "Not connected" }
61
+ }
62
+ ];
63
+ }
46
64
  function findEgressMismatch(integration) {
47
65
  const live = integration.live?.egress;
48
66
  const declared = integration.definition?.egress;
@@ -67,7 +85,7 @@ function supportsLiveMode(integration) {
67
85
  function resolveEffectiveDataMode(integration, toolbarMode) {
68
86
  if (!supportsLiveMode(integration)) return "fixtures";
69
87
  if (findEgressMismatch(integration)) return "fixtures";
70
- return toolbarMode;
88
+ return toolbarMode ?? integration.live.default ?? "fixtures";
71
89
  }
72
90
  export {
73
91
  DATA_MODES,
@@ -81,8 +99,10 @@ export {
81
99
  findIntegration,
82
100
  findWidget,
83
101
  harnessWidgetsFromDefinition,
102
+ oauthStatusFixtures,
84
103
  resolveEffectiveDataMode,
85
104
  resolveEgress,
105
+ resolveOAuthConnected,
86
106
  seedsForMode,
87
107
  supportsLiveMode
88
108
  };
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "@ekanos/harness",
3
- "version": "0.1.4",
3
+ "version": "0.2.0",
4
4
  "private": false,
5
5
  "type": "module",
6
- "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
+ "description": "The Ekanos integration dev harness — every surface of an integration rendered in real Fusion chrome, from fixtures, with no Supabase or auth; and, in live mode, a real localhost OAuth loop over your own dev-app credentials.",
7
7
  "license": "MIT",
8
8
  "bugs": {
9
9
  "email": "npm@govastly.com"
@@ -13,7 +13,7 @@
13
13
  "**/i18n.js"
14
14
  ],
15
15
  "ekanos": {
16
- "shellContract": 1
16
+ "shellContract": 2
17
17
  },
18
18
  "files": [
19
19
  "dist",
@@ -41,6 +41,10 @@
41
41
  "types": "./dist/hooks.d.ts",
42
42
  "default": "./dist/hooks.js"
43
43
  },
44
+ "./api": {
45
+ "types": "./dist/api.d.ts",
46
+ "default": "./dist/api.js"
47
+ },
44
48
  "./styles.css": "./dist/styles.css",
45
49
  "./mocks/team-account-workspace": {
46
50
  "types": "./dist/mocks/team-account-workspace.d.ts",
@@ -58,17 +62,18 @@
58
62
  "tw-animate-css": "1.4.0"
59
63
  },
60
64
  "peerDependencies": {
61
- "@ekanos/sdk": "^0.1.6",
62
- "@ekanos/ui": "^0.1.6",
65
+ "@ekanos/sdk": "^0.2.0",
66
+ "@ekanos/ui": "^0.2.0",
63
67
  "@tanstack/react-query": "^5.101.4",
64
68
  "next": "^16.0.0",
65
69
  "react": "^19.2.8",
66
70
  "react-dom": "^19.2.8",
71
+ "react-hook-form": "^7.68.0",
67
72
  "tailwindcss": "^4.0.0"
68
73
  },
69
74
  "devDependencies": {
70
- "@ekanos/sdk": "0.1.6",
71
- "@ekanos/ui": "0.1.6",
75
+ "@ekanos/sdk": "0.2.0",
76
+ "@ekanos/ui": "0.2.0",
72
77
  "@kit/eslint-config": "0.2.0",
73
78
  "@kit/prettier-config": "0.1.0",
74
79
  "@kit/tsconfig": "0.1.0",
@@ -80,6 +85,7 @@
80
85
  "next": "16.3.3",
81
86
  "react": "19.2.8",
82
87
  "react-dom": "19.2.8",
88
+ "react-hook-form": "^7.87.0",
83
89
  "tailwindcss": "4.3.3",
84
90
  "tsup": "8.5.1",
85
91
  "typescript": "^5.9.3",