@capybara-hq/plugin-client 0.1.0-rc.2 → 0.1.0-rc.3

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
@@ -4,7 +4,7 @@ The client SDK for writing plugin UI for [Capybara](https://github.com/capybara-
4
4
  open-source enterprise agent platform. A plugin's client entry (`src/client.tsx`) imports from this
5
5
  package: `defineClientExtension`, `defineComponent`, the hooks (`useView`, `useAction`, `useAccess`,
6
6
  `useLocale`, `useRunState`, `useCapybaraEvents`, `usePrefersReducedMotion`, `useTheme`,
7
- `useClientStorage`, `useAssetUrl`) and a versioned subset of the design components (`Button`,
7
+ `useClientStorage`, `useAssetUrl`, `useSignIn`) and a versioned subset of the design components (`Button`,
8
8
  `Badge`, `Icon`, `KeyValue`, `Kbd`, `Logo`, `Spinner`, `Stack`, `Text`, `Tooltip`,
9
9
  `PropertySection`, `ViewBlocks`).
10
10
 
@@ -15,8 +15,14 @@ npm install @capybara-hq/plugin-client
15
15
  In the browser the specifier `@capybara-hq/plugin-client` resolves to the host's own implementation
16
16
  of this interface (through an import map); `react` is provided by the host too. The package's own
17
17
  runtime serves tests and type checking: `@capybara-hq/plugin-client/testing` has
18
- `renderWithFakeHost(element, { slot, args?, role?, locale?, runState?, view?, onAction?, events? })`,
19
- which renders a component inside a fake host (jsdom needed).
18
+ `renderWithFakeHost(element, { slot, args?, role?, locale?, runState?, view?, onAction?, events?,
19
+ reducedMotion?, signInId? })`, which renders a component inside a fake host (jsdom needed).
20
+
21
+ `useSignIn().id` (and `api.signIn.id` in `events` listeners) is an opaque id that stays the same
22
+ for one sign-in and changes on the next one: to do something once per sign-in, store the id you
23
+ acted on with `useClientStorage` and act again when it differs. It is no credential. It is a
24
+ different string per plugin, but not a secret between plugins: client code runs with full trust in
25
+ the page.
20
26
 
21
27
  `CLIENT_API_VERSION` (1) is bumped only when a name is removed or its props change; the host
22
28
  accepts a bundle built against its own version.
package/dist/context.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { ComponentSlotId } from "./slots.generated.js";
2
- import type { CapybaraEvent, ClientRole, ClientStorage, JsonValue, RunState, UiView } from "./types.js";
2
+ import type { CapybaraEvent, ClientRole, ClientStorage, JsonValue, RunState, SignIn, UiView } from "./types.js";
3
3
  /** Thrown by a hook used outside a component the host rendered. */
4
4
  export declare class PluginClientContextError extends Error {
5
5
  constructor(hook: string);
@@ -36,6 +36,7 @@ export interface HostApi {
36
36
  };
37
37
  storage: ClientStorage;
38
38
  assetUrl(path: string): string;
39
+ signIn: SignIn;
39
40
  /** Subscribes to client events; returns the unsubscribe function. */
40
41
  subscribe(handler: (e: CapybaraEvent) => void): () => void;
41
42
  }
package/dist/hooks.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { type ActionFn, type ViewState } from "./context.js";
2
- import type { CapybaraEvent, CapybaraEventType, ClientStorage, RunState } from "./types.js";
2
+ import type { CapybaraEvent, CapybaraEventType, ClientStorage, RunState, SignIn } from "./types.js";
3
3
  /** The view the extension registered under this component's id, refreshed like any view. */
4
4
  export declare function useView(): ViewState;
5
5
  /** Calls the `ctx.ui.action` registered under this component's id. */
@@ -32,3 +32,8 @@ export declare function useTheme(): {
32
32
  export declare function useClientStorage(): ClientStorage;
33
33
  /** URL of a file under dist/client/assets/ of this plugin's build. */
34
34
  export declare function useAssetUrl(): (path: string) => string;
35
+ /**
36
+ * The viewer's sign-in for this plugin: `id` stays the same for one sign-in and changes on the
37
+ * next one (once per sign-in: compare it with the id stored when the thing last ran).
38
+ */
39
+ export declare function useSignIn(): SignIn;
package/dist/hooks.js CHANGED
@@ -54,3 +54,10 @@ export function useClientStorage() {
54
54
  export function useAssetUrl() {
55
55
  return useHost("useAssetUrl").api.assetUrl;
56
56
  }
57
+ /**
58
+ * The viewer's sign-in for this plugin: `id` stays the same for one sign-in and changes on the
59
+ * next one (once per sign-in: compare it with the id stored when the thing last ran).
60
+ */
61
+ export function useSignIn() {
62
+ return useHost("useSignIn").api.signIn;
63
+ }
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  export { type ActionFn, PluginClientContextError, type ViewState } from "./context.js";
2
2
  export { CLIENT_API_VERSION, type ClientComponent, type ClientExtension, type ClientExtensionDefinition, type ComponentProps, defineClientExtension, defineComponent, } from "./define.js";
3
3
  export { Badge, type BadgeProps, Button, type ButtonProps, Icon, type IconProps, Kbd, type KbdProps, KeyValue, type KeyValueProps, Logo, type LogoProps, PropertySection, type PropertySectionProps, Spinner, type SpinnerProps, Stack, type StackProps, Text, type TextProps, Tooltip, type TooltipProps, ViewBlocks, type ViewBlocksProps, } from "./design.js";
4
- export { useAccess, useAction, useAssetUrl, useCapybaraEvents, useClientStorage, useLocale, usePrefersReducedMotion, useRunState, useTheme, useView, } from "./hooks.js";
4
+ export { useAccess, useAction, useAssetUrl, useCapybaraEvents, useClientStorage, useLocale, usePrefersReducedMotion, useRunState, useSignIn, useTheme, useView, } from "./hooks.js";
5
5
  export type { ComponentSlotId } from "./slots.generated.js";
6
- export type { BaseComponentProps, CapybaraEvent, CapybaraEventOf, CapybaraEventType, ClientApi, ClientRole, ClientStorage, EventBase, JsonValue, RunState, SlotComponentProps, UiView, } from "./types.js";
6
+ export type { BaseComponentProps, CapybaraEvent, CapybaraEventOf, CapybaraEventType, ClientApi, ClientRole, ClientStorage, EventBase, JsonValue, RunState, SignIn, SlotComponentProps, UiView, } from "./types.js";
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
1
  export { PluginClientContextError } from "./context.js";
2
2
  export { CLIENT_API_VERSION, defineClientExtension, defineComponent, } from "./define.js";
3
3
  export { Badge, Button, Icon, Kbd, KeyValue, Logo, PropertySection, Spinner, Stack, Text, Tooltip, ViewBlocks, } from "./design.js";
4
- export { useAccess, useAction, useAssetUrl, useCapybaraEvents, useClientStorage, useLocale, usePrefersReducedMotion, useRunState, useTheme, useView, } from "./hooks.js";
4
+ export { useAccess, useAction, useAssetUrl, useCapybaraEvents, useClientStorage, useLocale, usePrefersReducedMotion, useRunState, useSignIn, useTheme, useView, } from "./hooks.js";
@@ -20,6 +20,8 @@ export interface FakeHostOptions {
20
20
  /** Listeners of a client extension's `events`, called on `emit` like in the real host. */
21
21
  events?: ClientExtension["events"];
22
22
  reducedMotion?: boolean;
23
+ /** The id `useSignIn()` and the listeners' `api.signIn` carry; default "test-sign-in". */
24
+ signInId?: string;
23
25
  }
24
26
  export interface FakeHost {
25
27
  emit(e: CapybaraEvent): void;
@@ -29,6 +31,6 @@ export interface FakeHost {
29
31
  }
30
32
  /**
31
33
  * Renders `element` inside a fake host (what the real host provides per component): the slot, the
32
- * role, the locale, the run state, the view and the design stand-ins. Needs a DOM (jsdom).
34
+ * role, the locale, the run state, the sign-in, the view and the design stand-ins. Needs a DOM (jsdom).
33
35
  */
34
36
  export declare function renderWithFakeHost(element: ReactElement, options: FakeHostOptions): FakeHost;
@@ -12,7 +12,7 @@ function fakeDesign() {
12
12
  }
13
13
  /**
14
14
  * Renders `element` inside a fake host (what the real host provides per component): the slot, the
15
- * role, the locale, the run state, the view and the design stand-ins. Needs a DOM (jsdom).
15
+ * role, the locale, the run state, the sign-in, the view and the design stand-ins. Needs a DOM (jsdom).
16
16
  */
17
17
  export function renderWithFakeHost(element, options) {
18
18
  globalThis.IS_REACT_ACT_ENVIRONMENT = true;
@@ -24,11 +24,13 @@ export function renderWithFakeHost(element, options) {
24
24
  const storage = createPrefixedStorage(plugin);
25
25
  const locale = options.locale ?? "en";
26
26
  const assetUrl = (path) => `/api/v1/client/${plugin}/test-build/assets/${path}`;
27
+ const signIn = { id: options.signInId ?? "test-sign-in" };
27
28
  const clientApi = {
28
29
  locale,
29
30
  reducedMotion: options.reducedMotion ?? false,
30
31
  storage,
31
32
  assetUrl,
33
+ signIn,
32
34
  };
33
35
  const previousHost = clientHost();
34
36
  setClientHost({ design: fakeDesign() });
@@ -57,6 +59,7 @@ export function renderWithFakeHost(element, options) {
57
59
  theme: { key: null, scheme: "dark" },
58
60
  storage,
59
61
  assetUrl,
62
+ signIn,
60
63
  subscribe,
61
64
  };
62
65
  const value = {
package/dist/types.d.ts CHANGED
@@ -59,12 +59,23 @@ export type CapybaraEvent = ({
59
59
  export type CapybaraEventOf<K extends CapybaraEventType> = Extract<CapybaraEvent, {
60
60
  type: K;
61
61
  }>;
62
+ /**
63
+ * The viewer's sign-in as this plugin sees it. `id` is opaque: the same for one sign-in (every
64
+ * page and tab of it, across token refreshes) and new after the next sign-in, so client code can
65
+ * do something once per sign-in (store the last id it acted on). It is never empty, is no
66
+ * credential and reveals nothing else about the session. It is a different string per plugin, but
67
+ * that is no isolation boundary: client code runs with full trust and can read other plugins' ids.
68
+ */
69
+ export interface SignIn {
70
+ id: string;
71
+ }
62
72
  /** What `events` listeners get (no React context there). */
63
73
  export interface ClientApi {
64
74
  locale: "zh" | "en";
65
75
  reducedMotion: boolean;
66
76
  storage: ClientStorage;
67
77
  assetUrl(path: string): string;
78
+ signIn: SignIn;
68
79
  }
69
80
  /** Props every component receives, plus its slot's own. */
70
81
  export interface BaseComponentProps {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@capybara-hq/plugin-client",
3
- "version": "0.1.0-rc.2",
3
+ "version": "0.1.0-rc.3",
4
4
  "description": "Capybara plugin client SDK: the types, hooks and design re-exports a plugin's client entry is written against",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {