@bridgewise/embed-sdk-web 0.0.0-stage → 0.1.0-beta.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 CHANGED
@@ -1,3 +1,219 @@
1
- # Temporary Holding Version
1
+ # @bridgewise/embed-sdk-web
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The SDK for web apps that embed Bridgewise widgets. Create one `EmbedClient`
4
+ on your page and it will:
5
+
6
+ - **Sign your user in** through the Bridgewise login page and keep the
7
+ session's access token fresh.
8
+ - **Authenticate every Bridgewise widget on the page**, so widgets load
9
+ already signed in.
10
+ - **Tell you what happens inside the widgets** (a security was selected, a
11
+ link was clicked, ...) and keep each widget's iframe as tall as its content.
12
+
13
+ It has no dependencies and ships with TypeScript types.
14
+
15
+ ## Install
16
+
17
+ ```bash
18
+ npm install @bridgewise/embed-sdk-web
19
+ ```
20
+
21
+ ## Quick start
22
+
23
+ ```ts
24
+ import { EmbedClient } from "@bridgewise/embed-sdk-web";
25
+
26
+ // Create it once, as early as possible on page load.
27
+ const embed = new EmbedClient({
28
+ clientId: "<your client ID>",
29
+ environment: "prod",
30
+ });
31
+
32
+ embed.auth.onError((error) => console.error(error.reason, error));
33
+
34
+ embed.widgets.on({
35
+ onSecuritySelect: (security) => openSecurity(security),
36
+ onNavigate: ({ href }) => router.push(href),
37
+ });
38
+
39
+ // Call once on page load. Completes the sign-in if the user has just come
40
+ // back from the login page; otherwise resolves to null.
41
+ await embed.auth.init();
42
+
43
+ if (!embed.auth.hasSession()) {
44
+ embed.auth.login(); // sends the user to the Bridgewise login page
45
+ }
46
+ ```
47
+
48
+ Widgets are ordinary iframes that you add to the page yourself, using the
49
+ widget URLs Bridgewise gave you:
50
+
51
+ ```html
52
+ <iframe src="<widget URL>" style="width: 100%; border: 0"></iframe>
53
+ ```
54
+
55
+ There is nothing to register. The SDK finds the Bridgewise widgets on the
56
+ page, signs them in, and sizes them.
57
+
58
+ ## Configuration
59
+
60
+ | Field | Type | Default | Description |
61
+ | -------------- | ---------------------------- | ------------ | ----------- |
62
+ | `clientId` | `string` | required | Your Bridgewise client ID. Each environment has its own. |
63
+ | `environment` | `"prod" \| "stage" \| "dev"` | required | The Bridgewise environment your client ID belongs to. Use `"prod"` unless Bridgewise gave you a client ID for another one. |
64
+ | `redirectPath` | `string` | current page | The path in your app the user returns to after signing in, e.g. `"/dashboard"`. |
65
+ | `autoLogin` | `boolean` | `false` | When true, `auth.init()` sends the user to the login page straight away if they aren't signed in. |
66
+ | `autoResize` | `boolean` | `true` | Keeps each widget iframe as tall as its content. |
67
+
68
+ ## `EmbedClient`
69
+
70
+ ### `new EmbedClient(config)`
71
+ Creates the client and starts listening to the widgets on the page. Create
72
+ it before the widgets load so none of their first messages are missed.
73
+
74
+ ### `embed.auth`
75
+ Sign-in and session. See [Signing in](#signing-in-embedauth).
76
+
77
+ ### `embed.widgets`
78
+ Events from the widgets. See [Widget events](#widget-events-embedwidgets).
79
+
80
+ ### `embed.destroy(): void`
81
+ Stops listening to the widgets and stops refreshing the session. Call it
82
+ when your app tears the SDK down, e.g. in a component's cleanup.
83
+
84
+ ## Signing in (`embed.auth`)
85
+
86
+ Sign-in is a redirect: `login()` sends the user to the Bridgewise login
87
+ page, and the login page sends them back to your app. `init()` then
88
+ completes the sign-in. From there the SDK renews the access token by itself
89
+ and keeps the widgets signed in.
90
+
91
+ ### `auth.init(): Promise<TokenResult | null>`
92
+ Call once on every page load.
93
+
94
+ - If the user has just come back from the login page, it completes the
95
+ sign-in, cleans the sign-in parameters out of the URL, and calls your
96
+ `onSuccess` listeners. Resolves to the tokens.
97
+ - If the login page reported a problem, it calls your `onError` listeners
98
+ and resolves to `null`.
99
+ - Otherwise it resolves to `null`. With `autoLogin: true` it sends the user
100
+ to the login page first.
101
+
102
+ ### `auth.login(path?: string): void`
103
+ Sends the user to the Bridgewise login page. Afterwards they return to
104
+ `path` if you pass one, else `redirectPath`, else the page they were on.
105
+
106
+ ### `auth.logout(): void`
107
+ Ends the session on your page and in every widget.
108
+
109
+ ### `auth.getAccessToken(): Promise<string | null>`
110
+ The current access token, renewed first if it has expired. `null` if the
111
+ user isn't signed in.
112
+
113
+ ### `auth.hasSession(): boolean`
114
+ Whether the user is currently signed in.
115
+
116
+ ### `auth.onSuccess(listener)`, `auth.onTokenRefresh(listener)`, `auth.onError(listener)`
117
+ Subscribe to a completed sign-in, a renewed token, and any sign-in failure.
118
+ Each returns a function that unsubscribes.
119
+
120
+ ```ts
121
+ interface TokenResult {
122
+ accessToken: string;
123
+ refreshToken?: string;
124
+ userId?: string;
125
+ tenantId?: string;
126
+ expiresAtEpochSeconds: number;
127
+ }
128
+
129
+ class EmbedError extends Error {
130
+ reason:
131
+ | "auth_callback_error" // the login page reported a problem
132
+ | "token_exchange_failed" // the sign-in could not be completed
133
+ | "token_refresh_failed"; // the session could not be renewed and has ended
134
+ cause?: unknown;
135
+ }
136
+ ```
137
+
138
+ After `token_refresh_failed` the user is signed out; call `login()` to start
139
+ a new session.
140
+
141
+ ### Sessions and security
142
+
143
+ - **Tokens are kept in memory only.** The SDK never writes them to
144
+ `localStorage`, `sessionStorage` or cookies. As a result a full page
145
+ reload ends the session: `init()` resolves to `null` and the user goes
146
+ through `login()` again (or automatically, with `autoLogin`).
147
+ - **Only Bridgewise widgets receive the access token.** The browser delivers
148
+ it only to iframes served from Bridgewise, and the SDK ignores messages
149
+ from anywhere else. The refresh token never leaves your page.
150
+
151
+ ## Widget events (`embed.widgets`)
152
+
153
+ ### `widgets.on(callbacks): () => void`
154
+ Registers callbacks for the events the widgets send. Pass only the ones you
155
+ need. Returns a function that unsubscribes.
156
+
157
+ ```ts
158
+ const unsubscribe = embed.widgets.on({
159
+ onLoad: ({ height, width }, { widget }) => { /* ... */ },
160
+ onClick: (data, context) => { /* ... */ },
161
+ });
162
+ ```
163
+
164
+ Every callback receives the event's data and a context saying which widget
165
+ sent it:
166
+
167
+ ```ts
168
+ interface WidgetEventContext {
169
+ widget: string; // name of the widget that sent the event
170
+ event: string; // legacy event name: on-<type>-<widget>
171
+ source: Window; // the widget's iframe window
172
+ }
173
+ ```
174
+
175
+ | Callback | When | Data |
176
+ | ------------------------ | ------------------------------------------------- | ---- |
177
+ | `onLoad` | The widget has loaded | `{ height, width }` |
178
+ | `onResize` | The widget's content changed size | `{ height }` |
179
+ | `onSuccess` | The widget loaded its data | `{ height }` |
180
+ | `onError` | The widget failed to load its data | `{ message, status, height }` |
181
+ | `onSecuritySelect` | The user selected a security | `{ id }` plus the security's identifiers: `type`, `ticker`, `exchange`, `isin`, `tase`, `tradingItemId` |
182
+ | `onNavigate` | The user followed a link that your app should open | `{ href, meta? }` |
183
+ | `onTradingItemIdChange` | The widget switched to another trading item | `{ tradingItemId? }` |
184
+ | `onBridgetTeaserTrigger` | The user opened a Bridget teaser | `{ companyId, message, query, primaryTickerSymbol }` |
185
+ | `onRestrictedTrigger` | The user reached content their plan restricts | `{ type, assetName?, ticker?, exchange?, isin?, tase? }` |
186
+ | `onClick` | The user clicked an action in the widget | `{ id, ... }` |
187
+ | `onHover` | The user hovered an action in the widget | `{ id, ... }` |
188
+ | `onTrigger` | The widget triggered an action itself | `{ id, ... }` |
189
+
190
+ For `onClick`, `onHover` and `onTrigger`, `id` names the action (for example
191
+ `"instrument"`, `"trade_now"` or `"info_action"`) and the remaining fields
192
+ depend on the widget.
193
+
194
+ `isPositionsTradeNow` recognises the "Trade now" action of the
195
+ portfolio-positions widget and types its data:
196
+
197
+ ```ts
198
+ import { isPositionsTradeNow } from "@bridgewise/embed-sdk-web";
199
+
200
+ embed.widgets.on({
201
+ onClick: (data, { widget }) => {
202
+ if (isPositionsTradeNow(data, widget)) {
203
+ openTradeTicket(data.currentAsset, data.targetAsset);
204
+ }
205
+ },
206
+ });
207
+ ```
208
+
209
+ ### Sizing
210
+
211
+ By default the SDK sets each widget iframe's height to match its content, so
212
+ widgets never show an inner scrollbar. Set the iframe's width yourself. To
213
+ control the height yourself as well, pass `autoResize: false` and use the
214
+ `height` from `onLoad` and `onResize`.
215
+
216
+ ## Support
217
+
218
+ For a client ID, widget URLs, or help with your integration, contact your
219
+ Bridgewise representative.