@bridgewise/embed-sdk-web 0.0.0-stage → 0.1.0-beta.1
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 +248 -2
- package/dist/index.cjs +544 -0
- package/dist/index.d.cts +357 -0
- package/dist/index.d.ts +357 -0
- package/dist/index.js +510 -0
- package/package.json +51 -4
package/README.md
CHANGED
|
@@ -1,3 +1,249 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @bridgewise/embed-sdk-web
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The SDK for web apps that embed Bridgewise widgets. Create one `EmbedClient`
|
|
4
|
+
on your page and it will:
|
|
5
|
+
|
|
6
|
+
- **Authenticate every Bridgewise widget on the page**, so widgets load
|
|
7
|
+
already signed in. Give it the user's access token, or let it sign the
|
|
8
|
+
user in through the Bridgewise login page.
|
|
9
|
+
- **Tell you what happens inside the widgets** (a security was selected, a
|
|
10
|
+
link was clicked, ...).
|
|
11
|
+
- **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
|
+
accessToken: "<the user's Bridgewise access token>",
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
embed.widgets.on({
|
|
32
|
+
onSecuritySelect: (security) => openSecurity(security),
|
|
33
|
+
onNavigate: ({ href }) => router.push(href),
|
|
34
|
+
});
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Widgets are ordinary iframes that you add to the page yourself, using the
|
|
38
|
+
widget URLs Bridgewise gave you:
|
|
39
|
+
|
|
40
|
+
```html
|
|
41
|
+
<iframe src="<widget URL>" style="width: 100%; border: 0"></iframe>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
There is nothing to register. The SDK finds the Bridgewise widgets on the
|
|
45
|
+
page, gives them the access token, and sizes them.
|
|
46
|
+
|
|
47
|
+
## Configuration
|
|
48
|
+
|
|
49
|
+
Every field is optional.
|
|
50
|
+
|
|
51
|
+
| Field | Type | Default | Description |
|
|
52
|
+
| -------------- | --------- | ------------ | ----------- |
|
|
53
|
+
| `accessToken` | `string` | none | The user's Bridgewise access token, if you already have one. See [Use your own access token](#use-your-own-access-token). |
|
|
54
|
+
| `clientId` | `string` | none | Your Bridgewise client ID. Only needed for [Bridgewise sign-in](#let-bridgewise-sign-the-user-in). |
|
|
55
|
+
| `redirectPath` | `string` | current page | Bridgewise sign-in only: the path in your app the user returns to after signing in, e.g. `"/dashboard"`. |
|
|
56
|
+
| `autoLogin` | `boolean` | `false` | Bridgewise sign-in only: when true, `auth.init()` sends the user to the login page straight away if they aren't signed in. |
|
|
57
|
+
| `autoResize` | `boolean` | `true` | Keeps each widget iframe as tall as its content. |
|
|
58
|
+
|
|
59
|
+
## `EmbedClient`
|
|
60
|
+
|
|
61
|
+
### `new EmbedClient(config?)`
|
|
62
|
+
Creates the client and starts listening to the widgets on the page. Create
|
|
63
|
+
it before the widgets load so none of their first messages are missed.
|
|
64
|
+
|
|
65
|
+
### `embed.auth`
|
|
66
|
+
The user's access token. See [Authenticating the widgets](#authenticating-the-widgets-embedauth).
|
|
67
|
+
|
|
68
|
+
### `embed.widgets`
|
|
69
|
+
Events from the widgets. See [Widget events](#widget-events-embedwidgets).
|
|
70
|
+
|
|
71
|
+
### `embed.destroy(): void`
|
|
72
|
+
Stops listening to the widgets and stops refreshing the session. Call it
|
|
73
|
+
when your app tears the SDK down, e.g. in a component's cleanup.
|
|
74
|
+
|
|
75
|
+
## Authenticating the widgets (`embed.auth`)
|
|
76
|
+
|
|
77
|
+
Widgets need the user's Bridgewise access token. There are two ways to give
|
|
78
|
+
it to them; pick the one that fits your app.
|
|
79
|
+
|
|
80
|
+
### Use your own access token
|
|
81
|
+
|
|
82
|
+
If your app already has a Bridgewise access token for the user, hand it to
|
|
83
|
+
the SDK and it shares it with every widget on the page, including widgets
|
|
84
|
+
added later.
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
const embed = new EmbedClient({ accessToken });
|
|
88
|
+
|
|
89
|
+
// Whenever you get a newer token, pass it on. Widgets receive it immediately.
|
|
90
|
+
embed.auth.setAccessToken(newAccessToken);
|
|
91
|
+
|
|
92
|
+
// When the user signs out of your app:
|
|
93
|
+
embed.auth.logout();
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
You can also create the client first and call `setAccessToken()` once the
|
|
97
|
+
token is available.
|
|
98
|
+
|
|
99
|
+
#### `auth.setAccessToken(accessToken, options?): void`
|
|
100
|
+
Sets or replaces the access token and sends it to the widgets. The SDK does
|
|
101
|
+
not renew a token you supply; call this again before it expires.
|
|
102
|
+
|
|
103
|
+
| Option | Type | Description |
|
|
104
|
+
| ----------------------- | -------- | ----------- |
|
|
105
|
+
| `expiresAtEpochSeconds` | `number` | When the token expires. Read from the token itself when omitted, so you normally don't need it. |
|
|
106
|
+
| `userId` | `string` | The user's Bridgewise user ID, if you have it. |
|
|
107
|
+
| `tenantId` | `string` | Your Bridgewise tenant ID, if you have it. |
|
|
108
|
+
|
|
109
|
+
### Let Bridgewise sign the user in
|
|
110
|
+
|
|
111
|
+
If you don't have a token, the SDK can sign the user in through the
|
|
112
|
+
Bridgewise login page. This needs your `clientId`.
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
const embed = new EmbedClient({ clientId: "<your client ID>" });
|
|
116
|
+
|
|
117
|
+
embed.auth.onError((error) => console.error(error.reason, error));
|
|
118
|
+
|
|
119
|
+
// Call once on page load. Completes the sign-in if the user has just come
|
|
120
|
+
// back from the login page; otherwise resolves to null.
|
|
121
|
+
await embed.auth.init();
|
|
122
|
+
|
|
123
|
+
if (!embed.auth.hasSession()) {
|
|
124
|
+
embed.auth.login(); // sends the user to the Bridgewise login page
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Sign-in is a redirect: `login()` sends the user to the Bridgewise login
|
|
129
|
+
page, and the login page sends them back to your app. `init()` then
|
|
130
|
+
completes the sign-in. From there the SDK renews the access token by itself
|
|
131
|
+
and keeps the widgets signed in.
|
|
132
|
+
|
|
133
|
+
#### `auth.init(): Promise<TokenResult | null>`
|
|
134
|
+
Call once on every page load.
|
|
135
|
+
|
|
136
|
+
- If the user has just come back from the login page, it completes the
|
|
137
|
+
sign-in, cleans the sign-in parameters out of the URL, and calls your
|
|
138
|
+
`onSuccess` listeners. Resolves to the tokens.
|
|
139
|
+
- If the login page reported a problem, it calls your `onError` listeners
|
|
140
|
+
and resolves to `null`.
|
|
141
|
+
- Otherwise it resolves to `null`. With `autoLogin: true` it sends the user
|
|
142
|
+
to the login page first.
|
|
143
|
+
|
|
144
|
+
#### `auth.login(path?: string): void`
|
|
145
|
+
Sends the user to the Bridgewise login page. Afterwards they return to
|
|
146
|
+
`path` if you pass one, else `redirectPath`, else the page they were on.
|
|
147
|
+
|
|
148
|
+
#### `auth.onSuccess(listener)`, `auth.onTokenRefresh(listener)`, `auth.onError(listener)`
|
|
149
|
+
Subscribe to a completed sign-in, a renewed token, and any sign-in failure.
|
|
150
|
+
Each returns a function that unsubscribes.
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
interface TokenResult {
|
|
154
|
+
accessToken: string;
|
|
155
|
+
refreshToken?: string;
|
|
156
|
+
userId?: string;
|
|
157
|
+
tenantId?: string;
|
|
158
|
+
expiresAtEpochSeconds: number;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
class EmbedError extends Error {
|
|
162
|
+
reason:
|
|
163
|
+
| "auth_callback_error" // the login page reported a problem
|
|
164
|
+
| "token_exchange_failed" // the sign-in could not be completed
|
|
165
|
+
| "token_refresh_failed"; // the session could not be renewed and has ended
|
|
166
|
+
cause?: unknown;
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
After `token_refresh_failed` the user is signed out; call `login()` to start
|
|
171
|
+
a new session.
|
|
172
|
+
|
|
173
|
+
### With either approach
|
|
174
|
+
|
|
175
|
+
#### `auth.logout(): void`
|
|
176
|
+
Ends the session on your page and in every widget.
|
|
177
|
+
|
|
178
|
+
#### `auth.getAccessToken(): Promise<string | null>`
|
|
179
|
+
The current access token. `null` if there is none, or if it has expired and
|
|
180
|
+
could not be renewed.
|
|
181
|
+
|
|
182
|
+
#### `auth.hasSession(): boolean`
|
|
183
|
+
Whether the SDK currently holds an access token.
|
|
184
|
+
|
|
185
|
+
### Sessions and security
|
|
186
|
+
|
|
187
|
+
- **Tokens are kept in memory only.** The SDK never writes them to
|
|
188
|
+
`localStorage`, `sessionStorage` or cookies. After a full page reload,
|
|
189
|
+
pass your access token again, or, with Bridgewise sign-in, send the user
|
|
190
|
+
through `login()` again (automatic with `autoLogin`).
|
|
191
|
+
- **Only Bridgewise widgets receive the access token.** The browser delivers
|
|
192
|
+
it only to iframes served from Bridgewise, and the SDK ignores messages
|
|
193
|
+
from anywhere else. With Bridgewise sign-in, the refresh token never
|
|
194
|
+
leaves your page.
|
|
195
|
+
|
|
196
|
+
## Widget events (`embed.widgets`)
|
|
197
|
+
|
|
198
|
+
### `widgets.on(callbacks): () => void`
|
|
199
|
+
Registers callbacks for the events the widgets send. Pass only the ones you
|
|
200
|
+
need. Returns a function that unsubscribes.
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
const unsubscribe = embed.widgets.on({
|
|
204
|
+
onLoad: ({ height, width }, { widget }) => { /* ... */ },
|
|
205
|
+
onClick: (data, context) => { /* ... */ },
|
|
206
|
+
});
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
Every callback receives the event's data and a context saying which widget
|
|
210
|
+
sent it:
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
interface WidgetEventContext {
|
|
214
|
+
widget: string; // name of the widget that sent the event
|
|
215
|
+
event: string; // legacy event name: on-<type>-<widget>
|
|
216
|
+
source: Window; // the widget's iframe window
|
|
217
|
+
}
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
| Callback | When | Data |
|
|
221
|
+
| ------------------------ | ------------------------------------------------- | ---- |
|
|
222
|
+
| `onLoad` | The widget has loaded | `{ height, width }` |
|
|
223
|
+
| `onResize` | The widget's content changed size | `{ height }` |
|
|
224
|
+
| `onSuccess` | The widget loaded its data | `{ height }` |
|
|
225
|
+
| `onError` | The widget failed to load its data | `{ message, status, height }` |
|
|
226
|
+
| `onSecuritySelect` | The user selected a security | `{ id }` plus the security's identifiers: `type`, `ticker`, `exchange`, `isin`, `tase`, `tradingItemId` |
|
|
227
|
+
| `onNavigate` | The user followed a link that your app should open | `{ href, meta? }` |
|
|
228
|
+
| `onTradingItemIdChange` | The widget switched to another trading item | `{ tradingItemId? }` |
|
|
229
|
+
| `onBridgetTeaserTrigger` | The user opened a Bridget teaser | `{ companyId, message, query, primaryTickerSymbol }` |
|
|
230
|
+
| `onRestrictedTrigger` | The user reached content their plan restricts | `{ type, assetName?, ticker?, exchange?, isin?, tase? }` |
|
|
231
|
+
| `onClick` | The user clicked an action in the widget | `{ id, ... }` |
|
|
232
|
+
| `onHover` | The user hovered an action in the widget | `{ id, ... }` |
|
|
233
|
+
| `onTrigger` | The widget triggered an action itself | `{ id, ... }` |
|
|
234
|
+
|
|
235
|
+
For `onClick`, `onHover` and `onTrigger`, `id` names the action (for example
|
|
236
|
+
`"instrument"`, `"trade_now"` or `"info_action"`) and the remaining fields
|
|
237
|
+
depend on the widget.
|
|
238
|
+
|
|
239
|
+
### Sizing
|
|
240
|
+
|
|
241
|
+
By default the SDK sets each widget iframe's height to match its content, so
|
|
242
|
+
widgets never show an inner scrollbar. Set the iframe's width yourself. To
|
|
243
|
+
control the height yourself as well, pass `autoResize: false` and use the
|
|
244
|
+
`height` from `onLoad` and `onResize`.
|
|
245
|
+
|
|
246
|
+
## Support
|
|
247
|
+
|
|
248
|
+
For a client ID, widget URLs, or help with your integration, contact your
|
|
249
|
+
Bridgewise representative.
|