@qontinui/ui-bridge-wrapper 0.1.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 (44) hide show
  1. package/README.md +52 -0
  2. package/dist/base-transport.d.ts +54 -0
  3. package/dist/base-transport.d.ts.map +1 -0
  4. package/dist/create-transport.d.ts +12 -0
  5. package/dist/create-transport.d.ts.map +1 -0
  6. package/dist/handler-registry.d.ts +42 -0
  7. package/dist/handler-registry.d.ts.map +1 -0
  8. package/dist/helpers/auth.d.ts +18 -0
  9. package/dist/helpers/auth.d.ts.map +1 -0
  10. package/dist/helpers/retry.d.ts +28 -0
  11. package/dist/helpers/retry.d.ts.map +1 -0
  12. package/dist/helpers/schema.d.ts +35 -0
  13. package/dist/helpers/schema.d.ts.map +1 -0
  14. package/dist/index.cjs +655 -0
  15. package/dist/index.cjs.map +1 -0
  16. package/dist/index.d.ts +52 -0
  17. package/dist/index.d.ts.map +1 -0
  18. package/dist/index.js +641 -0
  19. package/dist/index.js.map +1 -0
  20. package/dist/manifest-only.d.ts +100 -0
  21. package/dist/manifest-only.d.ts.map +1 -0
  22. package/dist/react/WrapperAppShell.d.ts +25 -0
  23. package/dist/react/WrapperAppShell.d.ts.map +1 -0
  24. package/dist/react/index.cjs +63 -0
  25. package/dist/react/index.cjs.map +1 -0
  26. package/dist/react/index.d.ts +13 -0
  27. package/dist/react/index.d.ts.map +1 -0
  28. package/dist/react/index.js +59 -0
  29. package/dist/react/index.js.map +1 -0
  30. package/dist/react/useTransportSelector.d.ts +30 -0
  31. package/dist/react/useTransportSelector.d.ts.map +1 -0
  32. package/dist/react/useWrapperStatus.d.ts +11 -0
  33. package/dist/react/useWrapperStatus.d.ts.map +1 -0
  34. package/dist/transports/api.d.ts +39 -0
  35. package/dist/transports/api.d.ts.map +1 -0
  36. package/dist/transports/headed.d.ts +15 -0
  37. package/dist/transports/headed.d.ts.map +1 -0
  38. package/dist/transports/headless.d.ts +69 -0
  39. package/dist/transports/headless.d.ts.map +1 -0
  40. package/dist/transports/live.d.ts +97 -0
  41. package/dist/transports/live.d.ts.map +1 -0
  42. package/dist/types.d.ts +102 -0
  43. package/dist/types.d.ts.map +1 -0
  44. package/package.json +70 -0
package/README.md ADDED
@@ -0,0 +1,52 @@
1
+ # `@qontinui/ui-bridge-wrapper`
2
+
3
+ Runtime library for building UI Bridge **wrapper apps** — tiny apps that
4
+ expose a set of semantic actions against a target system (a SaaS API, a
5
+ web UI, a running qontinui app) and let the same action code run against
6
+ any of four interchangeable transports:
7
+
8
+ | Kind | What it does | Typical use |
9
+ | ---------- | ---------------------------------------------------- | --------------------- |
10
+ | `api` | Delegates to user-defined handlers. No browser. | Direct SDK/REST calls |
11
+ | `headless` | Launches Playwright Chromium with no visible window. | CI, background tests |
12
+ | `headed` | Launches Playwright Chromium with a visible window. | Local debugging |
13
+ | `live` | Connects to a qontinui runner over WebSocket. | Live orchestration |
14
+
15
+ See `src/index.ts` for the full exported surface. React helpers ship
16
+ under the `./react` subpath so Node-only wrappers don't pay the React
17
+ import cost.
18
+
19
+ ## Quick start
20
+
21
+ ```ts
22
+ import { createTransport } from '@qontinui/ui-bridge-wrapper';
23
+
24
+ const transport = createTransport({
25
+ kind: 'headless',
26
+ options: { targetUrl: 'http://localhost:3001/vga/builder' },
27
+ });
28
+
29
+ transport.handlerRegistry.register('login', async (params, ctx) => {
30
+ const { email, password } = params as { email: string; password: string };
31
+ const { page } = ctx as { page: import('playwright').Page };
32
+ await page.fill('#email', email);
33
+ await page.fill('#password', password);
34
+ await page.click('button[type=submit]');
35
+ });
36
+
37
+ await transport.ready();
38
+ await transport.dispatch('login', { email: 'a@b.c', password: '...' });
39
+ await transport.close();
40
+ ```
41
+
42
+ ## Package layout
43
+
44
+ - `src/index.ts` — public surface (transports, helpers, types).
45
+ - `src/base-transport.ts` — `BaseTransport` with status/listeners/ready gating.
46
+ - `src/handler-registry.ts` — shared action registry used by every transport.
47
+ - `src/transports/{api,headless,headed,live}.ts` — the four concrete transports.
48
+ - `src/helpers/{retry,auth,schema}.ts` — `withRetry`, `withAuthRefresh`, `paramSchemaOf`.
49
+ - `src/react/*` — React hooks (`useWrapperStatus`, `useTransportSelector`) and the default `WrapperAppShell` layout.
50
+
51
+ Phase 3 of the wrapper plan adds a scaffold CLI on top of this package;
52
+ Phase 4 ships reference wrappers that exercise all four transports.
@@ -0,0 +1,54 @@
1
+ /**
2
+ * BaseTransport
3
+ *
4
+ * Abstract base class for every transport. Owns the shared `HandlerRegistry`
5
+ * plus a small status + listener state machine. Subclasses implement:
6
+ *
7
+ * - `kind` — static identifier
8
+ * - `onReady()` — async setup (browser launch, ws handshake...)
9
+ * - `onClose()` — async teardown
10
+ * - `buildContext(actionId, params)` — per-dispatch context passed to the
11
+ * registered handler (e.g. `{ page }`)
12
+ *
13
+ * `dispatch` is final; it coordinates `ready()` gating, then routes through
14
+ * the registry. Subclasses that need to marshal dispatches over the wire
15
+ * (like `LiveSessionTransport`) can override `dispatch` directly.
16
+ */
17
+ import { HandlerRegistry, type WrapperHandler } from './handler-registry.js';
18
+ import type { WrapperTransport, WrapperTransportKind, WrapperTransportStatus } from './types.js';
19
+ export declare abstract class BaseTransport implements WrapperTransport {
20
+ abstract readonly kind: WrapperTransportKind;
21
+ protected _status: WrapperTransportStatus;
22
+ protected readonly listeners: Set<(s: WrapperTransportStatus) => void>;
23
+ protected readonly registry: HandlerRegistry;
24
+ private readyPromise;
25
+ constructor(registry?: HandlerRegistry);
26
+ get status(): WrapperTransportStatus;
27
+ /** Expose the underlying registry so wrappers can register handlers. */
28
+ get handlerRegistry(): HandlerRegistry;
29
+ /** Convenience: register a handler on the transport's registry. */
30
+ register<TParams = unknown, TResult = unknown, TCtx = unknown>(actionId: string, fn: WrapperHandler<TParams, TResult, TCtx>): void;
31
+ /**
32
+ * Idempotent async setup. First call runs `onReady()`; subsequent calls
33
+ * share the same promise until it settles, after which further calls
34
+ * are no-ops if `status === 'ready'`, or re-run setup if it errored.
35
+ */
36
+ ready(): Promise<void>;
37
+ /** Default dispatch — waits for ready, builds ctx, delegates to registry. */
38
+ dispatch<TResult = unknown>(actionId: string, params?: unknown): Promise<TResult>;
39
+ close(): Promise<void>;
40
+ onStatusChange(listener: (s: WrapperTransportStatus) => void): () => void;
41
+ /** Update status and notify listeners. Safe to call from subclasses. */
42
+ protected setStatus(next: WrapperTransportStatus): void;
43
+ /** Subclass hook: perform async setup. */
44
+ protected abstract onReady(): Promise<void>;
45
+ /** Subclass hook: tear down async resources. */
46
+ protected abstract onClose(): Promise<void>;
47
+ /**
48
+ * Subclass hook: build the context object passed to handlers. Default is
49
+ * `undefined` (api transport). Headless/headed override to provide the
50
+ * Playwright `page`; live overrides to provide a response helper.
51
+ */
52
+ protected buildContext(_actionId: string, _params: unknown): Promise<unknown>;
53
+ }
54
+ //# sourceMappingURL=base-transport.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"base-transport.d.ts","sourceRoot":"","sources":["../src/base-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAGjG,8BAAsB,aAAc,YAAW,gBAAgB;IAC7D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAE7C,SAAS,CAAC,OAAO,EAAE,sBAAsB,CAAU;IACnD,SAAS,CAAC,QAAQ,CAAC,SAAS,UAAe,sBAAsB,KAAK,IAAI,EAAI;IAC9E,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAC7C,OAAO,CAAC,YAAY,CAA8B;gBAEtC,QAAQ,CAAC,EAAE,eAAe;IAItC,IAAI,MAAM,IAAI,sBAAsB,CAEnC;IAED,wEAAwE;IACxE,IAAI,eAAe,IAAI,eAAe,CAErC;IAED,mEAAmE;IACnE,QAAQ,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,EAC3D,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,GACzC,IAAI;IAIP;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5B,6EAA6E;IACvE,QAAQ,CAAC,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAMjF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,cAAc,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,sBAAsB,KAAK,IAAI,GAAG,MAAM,IAAI;IAOzE,wEAAwE;IACxE,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI;IAYvD,0CAA0C;IAC1C,SAAS,CAAC,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAE3C,gDAAgD;IAChD,SAAS,CAAC,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAE3C;;;;OAIG;cACa,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAGpF"}
@@ -0,0 +1,12 @@
1
+ /**
2
+ * `createTransport` factory
3
+ *
4
+ * Pulls the transport class out of `TransportConfig.kind` and wires it up.
5
+ * Kept as a separate module so tree-shaking can drop unused transports
6
+ * (e.g. an api-only wrapper won't bundle headless / live code paths if the
7
+ * user imports `ApiTransport` directly instead of routing through
8
+ * `createTransport`).
9
+ */
10
+ import type { TransportConfig, WrapperTransport } from './types.js';
11
+ export declare function createTransport(config: TransportConfig): WrapperTransport;
12
+ //# sourceMappingURL=create-transport.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"create-transport.d.ts","sourceRoot":"","sources":["../src/create-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGpE,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAwBzE"}
@@ -0,0 +1,42 @@
1
+ /**
2
+ * HandlerRegistry
3
+ *
4
+ * Shared by every concrete transport. The transport's `dispatch` method
5
+ * looks up a handler by `actionId`, invokes it with `(params, ctx)`, and
6
+ * awaits the (possibly async) result.
7
+ *
8
+ * The registry deliberately knows nothing about the transport — transports
9
+ * build their own `ctx` object (e.g. `{ page }` for headless, `{ send }` for
10
+ * live) and hand it to the handler. This keeps action code transport-aware
11
+ * only when it explicitly reads `ctx`, and transport-agnostic otherwise.
12
+ */
13
+ /** Generic async handler signature used by every transport. */
14
+ export type WrapperHandler<TParams = unknown, TResult = unknown, TCtx = unknown> = (params: TParams | undefined, ctx: TCtx) => TResult | Promise<TResult>;
15
+ /**
16
+ * Map of `actionId` -> handler. Consumers register handlers during wrapper
17
+ * setup, before the transport starts accepting dispatches.
18
+ */
19
+ export declare class HandlerRegistry {
20
+ private readonly handlers;
21
+ /**
22
+ * Register (or replace) a handler for `actionId`. Replacement is explicit
23
+ * rather than throwing because live reloading / hot module scenarios need
24
+ * to update handlers without tearing the whole transport down.
25
+ */
26
+ register<TParams = unknown, TResult = unknown, TCtx = unknown>(actionId: string, fn: WrapperHandler<TParams, TResult, TCtx>): void;
27
+ /** Remove a handler. Returns `true` if a handler was removed. */
28
+ unregister(actionId: string): boolean;
29
+ /** All registered action ids. Stable iteration order (insertion order). */
30
+ list(): string[];
31
+ /** Check whether a handler is registered for `actionId`. */
32
+ has(actionId: string): boolean;
33
+ /**
34
+ * Invoke the handler registered under `actionId`.
35
+ *
36
+ * Throws `WrapperTransportError("NO_HANDLER")` if no handler is registered.
37
+ * Propagates handler errors wrapped as `WrapperTransportError("HANDLER_ERROR")`
38
+ * so callers can uniformly check `err.code`.
39
+ */
40
+ dispatch<TResult = unknown>(actionId: string, params?: unknown, ctx?: unknown): Promise<TResult>;
41
+ }
42
+ //# sourceMappingURL=handler-registry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"handler-registry.d.ts","sourceRoot":"","sources":["../src/handler-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,+DAA+D;AAC/D,MAAM,MAAM,cAAc,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,IAAI,CACjF,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,GAAG,EAAE,IAAI,KACN,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAE9D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,EAC3D,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,GACzC,IAAI;IAIP,iEAAiE;IACjE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIrC,2EAA2E;IAC3E,IAAI,IAAI,MAAM,EAAE;IAIhB,4DAA4D;IAC5D,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;;;OAMG;IACG,QAAQ,CAAC,OAAO,GAAG,OAAO,EAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,OAAO,EAChB,GAAG,CAAC,EAAE,OAAO,GACZ,OAAO,CAAC,OAAO,CAAC;CAiBpB"}
@@ -0,0 +1,18 @@
1
+ /**
2
+ * `withAuthRefresh`
3
+ *
4
+ * Runs `fn` once; if it throws an auth-expired error, invokes `refresh`
5
+ * (expected to refresh tokens / re-authenticate) and re-runs `fn` exactly
6
+ * once. Designed for wrappers whose `api` transport handlers call
7
+ * third-party APIs with short-lived access tokens.
8
+ *
9
+ * Consumers can override the detector via `isAuthError`. The default
10
+ * treats `WrapperTransportError` with codes matching `/^(AUTH|UNAUTH|401)/i`
11
+ * as auth errors, and errors with a numeric `status === 401` property.
12
+ */
13
+ export interface WithAuthRefreshOptions {
14
+ /** Custom detector for "this error means we need to refresh auth". */
15
+ isAuthError?: (err: unknown) => boolean;
16
+ }
17
+ export declare function withAuthRefresh<T>(fn: () => Promise<T>, refresh: () => Promise<void>, opts?: WithAuthRefreshOptions): Promise<T>;
18
+ //# sourceMappingURL=auth.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/helpers/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAaD,wBAAsB,eAAe,CAAC,CAAC,EACrC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAC5B,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,CAAC,CAAC,CASZ"}
@@ -0,0 +1,28 @@
1
+ /**
2
+ * `withRetry`
3
+ *
4
+ * Exponential-backoff retry helper. Transports surface retryable errors
5
+ * with `err.retryable === true` (see `WrapperTransportError`); wrappers
6
+ * can pass their own predicate via `shouldRetry` when the default
7
+ * retry-every-error behavior is too aggressive.
8
+ *
9
+ * Defaults: 3 attempts, 200 ms base, doubling delay (200 / 400 / 800).
10
+ */
11
+ export interface WithRetryOptions {
12
+ /** Total attempt count, including the first call. Defaults to 3. */
13
+ attempts?: number;
14
+ /** Base delay in ms. Defaults to 200. Doubles between attempts. */
15
+ baseMs?: number;
16
+ /** Max cap on any single backoff wait. Defaults to 5 000 ms. */
17
+ maxDelayMs?: number;
18
+ /**
19
+ * Predicate that decides whether to retry a given error. Defaults to
20
+ * `err.retryable === true` for `WrapperTransportError`, `true`
21
+ * otherwise (network/unknown errors are presumed transient).
22
+ */
23
+ shouldRetry?: (err: unknown, attempt: number) => boolean;
24
+ /** Sleep implementation hook — defaults to `setTimeout`. Overridden in tests. */
25
+ sleep?: (ms: number) => Promise<void>;
26
+ }
27
+ export declare function withRetry<T>(fn: () => Promise<T>, opts?: WithRetryOptions): Promise<T>;
28
+ //# sourceMappingURL=retry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/helpers/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACzD,iFAAiF;IACjF,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAYD,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC,CAsBhG"}
@@ -0,0 +1,35 @@
1
+ /**
2
+ * `paramSchemaOf`
3
+ *
4
+ * Tiny helper that produces a JSON-Schema-subset object from a plain
5
+ * descriptor, matching the shape `useUIComponent` already exposes on its
6
+ * `actions[].paramSchema` field. The existing SDK contract says "no
7
+ * runtime validation is performed" — this helper's only job is to surface
8
+ * parameter names and types on the runner's `/control/component/:id`
9
+ * endpoint so callers can discover the action signature.
10
+ *
11
+ * Accepted descriptor values:
12
+ * - a JSON-Schema type name string (`"string"`, `"number"`, ...)
13
+ * - an object already shaped like JSON Schema (`{ type: "string", enum: [...] }`)
14
+ * - `null` / `undefined` → field omitted
15
+ *
16
+ * Example:
17
+ *
18
+ * ```ts
19
+ * paramSchemaOf({ email: 'string', password: 'string', remember: 'boolean' })
20
+ * // => {
21
+ * // type: 'object',
22
+ * // properties: {
23
+ * // email: { type: 'string' },
24
+ * // password: { type: 'string' },
25
+ * // remember: { type: 'boolean' },
26
+ * // },
27
+ * // required: ['email', 'password', 'remember'],
28
+ * // additionalProperties: false,
29
+ * // }
30
+ * ```
31
+ */
32
+ type SchemaValue = string | Record<string, unknown> | null | undefined;
33
+ export declare function paramSchemaOf<T extends Record<string, SchemaValue>>(shape: T): Record<string, unknown>;
34
+ export {};
35
+ //# sourceMappingURL=schema.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/helpers/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAYH,KAAK,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;AAkBvE,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACjE,KAAK,EAAE,CAAC,GACP,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBzB"}