@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 CHANGED
@@ -1,3 +1,249 @@
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
+ - **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.