@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 +218 -2
- package/dist/index.cjs +508 -0
- package/dist/index.d.cts +326 -0
- package/dist/index.d.ts +326 -0
- package/dist/index.js +474 -0
- package/package.json +51 -4
package/README.md
CHANGED
|
@@ -1,3 +1,219 @@
|
|
|
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
|
+
- **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.
|