@bridgewise/embed-sdk-web 0.1.0-beta.0 → 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
@@ -3,12 +3,12 @@
3
3
  The SDK for web apps that embed Bridgewise widgets. Create one `EmbedClient`
4
4
  on your page and it will:
5
5
 
6
- - **Sign your user in** through the Bridgewise login page and keep the
7
- session's access token fresh.
8
6
  - **Authenticate every Bridgewise widget on the page**, so widgets load
9
- already signed in.
7
+ already signed in. Give it the user's access token, or let it sign the
8
+ user in through the Bridgewise login page.
10
9
  - **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.
10
+ link was clicked, ...).
11
+ - **Keep each widget's iframe as tall as its content.**
12
12
 
13
13
  It has no dependencies and ships with TypeScript types.
14
14
 
@@ -25,24 +25,13 @@ import { EmbedClient } from "@bridgewise/embed-sdk-web";
25
25
 
26
26
  // Create it once, as early as possible on page load.
27
27
  const embed = new EmbedClient({
28
- clientId: "<your client ID>",
29
- environment: "prod",
28
+ accessToken: "<the user's Bridgewise access token>",
30
29
  });
31
30
 
32
- embed.auth.onError((error) => console.error(error.reason, error));
33
-
34
31
  embed.widgets.on({
35
32
  onSecuritySelect: (security) => openSecurity(security),
36
33
  onNavigate: ({ href }) => router.push(href),
37
34
  });
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
35
  ```
47
36
 
48
37
  Widgets are ordinary iframes that you add to the page yourself, using the
@@ -53,26 +42,28 @@ widget URLs Bridgewise gave you:
53
42
  ```
54
43
 
55
44
  There is nothing to register. The SDK finds the Bridgewise widgets on the
56
- page, signs them in, and sizes them.
45
+ page, gives them the access token, and sizes them.
57
46
 
58
47
  ## Configuration
59
48
 
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. |
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. |
67
58
 
68
59
  ## `EmbedClient`
69
60
 
70
- ### `new EmbedClient(config)`
61
+ ### `new EmbedClient(config?)`
71
62
  Creates the client and starts listening to the widgets on the page. Create
72
63
  it before the widgets load so none of their first messages are missed.
73
64
 
74
65
  ### `embed.auth`
75
- Sign-in and session. See [Signing in](#signing-in-embedauth).
66
+ The user's access token. See [Authenticating the widgets](#authenticating-the-widgets-embedauth).
76
67
 
77
68
  ### `embed.widgets`
78
69
  Events from the widgets. See [Widget events](#widget-events-embedwidgets).
@@ -81,14 +72,65 @@ Events from the widgets. See [Widget events](#widget-events-embedwidgets).
81
72
  Stops listening to the widgets and stops refreshing the session. Call it
82
73
  when your app tears the SDK down, e.g. in a component's cleanup.
83
74
 
84
- ## Signing in (`embed.auth`)
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
+ ```
85
127
 
86
128
  Sign-in is a redirect: `login()` sends the user to the Bridgewise login
87
129
  page, and the login page sends them back to your app. `init()` then
88
130
  completes the sign-in. From there the SDK renews the access token by itself
89
131
  and keeps the widgets signed in.
90
132
 
91
- ### `auth.init(): Promise<TokenResult | null>`
133
+ #### `auth.init(): Promise<TokenResult | null>`
92
134
  Call once on every page load.
93
135
 
94
136
  - If the user has just come back from the login page, it completes the
@@ -99,21 +141,11 @@ Call once on every page load.
99
141
  - Otherwise it resolves to `null`. With `autoLogin: true` it sends the user
100
142
  to the login page first.
101
143
 
102
- ### `auth.login(path?: string): void`
144
+ #### `auth.login(path?: string): void`
103
145
  Sends the user to the Bridgewise login page. Afterwards they return to
104
146
  `path` if you pass one, else `redirectPath`, else the page they were on.
105
147
 
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)`
148
+ #### `auth.onSuccess(listener)`, `auth.onTokenRefresh(listener)`, `auth.onError(listener)`
117
149
  Subscribe to a completed sign-in, a renewed token, and any sign-in failure.
118
150
  Each returns a function that unsubscribes.
119
151
 
@@ -138,15 +170,28 @@ class EmbedError extends Error {
138
170
  After `token_refresh_failed` the user is signed out; call `login()` to start
139
171
  a new session.
140
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
+
141
185
  ### Sessions and security
142
186
 
143
187
  - **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`).
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`).
147
191
  - **Only Bridgewise widgets receive the access token.** The browser delivers
148
192
  it only to iframes served from Bridgewise, and the SDK ignores messages
149
- from anywhere else. The refresh token never leaves your page.
193
+ from anywhere else. With Bridgewise sign-in, the refresh token never
194
+ leaves your page.
150
195
 
151
196
  ## Widget events (`embed.widgets`)
152
197
 
@@ -191,21 +236,6 @@ For `onClick`, `onHover` and `onTrigger`, `id` names the action (for example
191
236
  `"instrument"`, `"trade_now"` or `"info_action"`) and the remaining fields
192
237
  depend on the widget.
193
238
 
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
239
  ### Sizing
210
240
 
211
241
  By default the SDK sets each widget iframe's height to match its content, so
package/dist/index.cjs CHANGED
@@ -73,6 +73,18 @@ function parseTokenResponse(json, previous) {
73
73
  expiresAtEpochSeconds: Math.floor(Date.now() / 1e3) + raw.expires_in
74
74
  };
75
75
  }
76
+ function readJwtExpiry(accessToken) {
77
+ try {
78
+ const payload = accessToken.split(".")[1];
79
+ const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
80
+ const exp = JSON.parse(json).exp;
81
+ if (typeof exp === "number") return exp;
82
+ } catch {
83
+ }
84
+ throw new Error(
85
+ "Could not read the access token's expiry. Pass `expiresAtEpochSeconds` with the token."
86
+ );
87
+ }
76
88
  function isExpired(tokens) {
77
89
  return Math.floor(Date.now() / 1e3) >= tokens.expiresAtEpochSeconds;
78
90
  }
@@ -159,8 +171,8 @@ function isReadyMessage(data) {
159
171
  return typeof data === "object" && data !== null && data.type === SSO_READY_MESSAGE_TYPE;
160
172
  }
161
173
 
162
- // src/auth/SsoAuth.ts
163
- var SsoAuth = class {
174
+ // src/auth/EmbedAuth.ts
175
+ var EmbedAuth = class {
164
176
  /** @internal Created by `EmbedClient`. */
165
177
  constructor(options, channel) {
166
178
  this.options = options;
@@ -171,7 +183,7 @@ var SsoAuth = class {
171
183
  this.successListeners = new Listeners();
172
184
  this.refreshListeners = new Listeners();
173
185
  this.errorListeners = new Listeners();
174
- this.api = new AuthApi(options.apiBaseUrl, options.clientId);
186
+ this.api = options.clientId ? new AuthApi(options.apiBaseUrl, options.clientId) : null;
175
187
  channel.subscribe((data, source) => {
176
188
  if (isReadyMessage(data)) void this.sendTokenTo(source);
177
189
  });
@@ -188,14 +200,29 @@ var SsoAuth = class {
188
200
  onError(listener) {
189
201
  return this.errorListeners.add(listener);
190
202
  }
203
+ /**
204
+ * Uses an access token you already hold for the user, and shares it with
205
+ * the embeds. Call it again whenever you have a newer token. Replaces any
206
+ * existing session; the SDK does not refresh a token supplied this way.
207
+ */
208
+ setAccessToken(accessToken, options = {}) {
209
+ this.setTokens({
210
+ accessToken,
211
+ userId: options.userId,
212
+ tenantId: options.tenantId,
213
+ expiresAtEpochSeconds: options.expiresAtEpochSeconds ?? readJwtExpiry(accessToken)
214
+ });
215
+ }
191
216
  /**
192
217
  * Call once when the app loads. If the URL carries `code`/`state` from the
193
218
  * hosted login page, exchanges them for tokens and removes them from the
194
219
  * URL. Otherwise, when `autoLogin` is true, redirects to the hosted login
195
220
  * page immediately; when false, resolves to null and leaves starting a
196
- * sign-in up to an explicit `login()` call.
221
+ * sign-in up to an explicit `login()` call. Does nothing without a
222
+ * `clientId`.
197
223
  */
198
224
  async init() {
225
+ if (!this.api) return null;
199
226
  const callback = readAuthCallback();
200
227
  if (!callback) {
201
228
  if (this.options.autoLogin) this.login();
@@ -226,9 +253,13 @@ var SsoAuth = class {
226
253
  }
227
254
  /**
228
255
  * Redirects the browser to the hosted login page. After sign-in the user
229
- * returns to `path`, else `redirectPath`, else the current page.
256
+ * returns to `path`, else `redirectPath`, else the current page. Requires
257
+ * a `clientId`.
230
258
  */
231
259
  login(path) {
260
+ if (!this.api) {
261
+ throw new Error("auth.login() needs `clientId` in the EmbedClient config");
262
+ }
232
263
  const returnPath = path ?? this.options.redirectPath ?? window.location.pathname + window.location.search;
233
264
  window.location.assign(this.api.loginUrl(returnPath));
234
265
  }
@@ -238,7 +269,10 @@ var SsoAuth = class {
238
269
  this.clearRefreshTimer();
239
270
  this.channel.broadcast({ type: SSO_LOGOUT_MESSAGE_TYPE });
240
271
  }
241
- /** Returns a valid access token, refreshing first if expired. Null if there is no session. */
272
+ /**
273
+ * Returns a valid access token, refreshing first if expired. Null if there
274
+ * is no session, or the token has expired and can't be refreshed.
275
+ */
242
276
  async getAccessToken() {
243
277
  if (!this.tokens) return null;
244
278
  if (isExpired(this.tokens)) await this.refresh();
@@ -278,7 +312,7 @@ var SsoAuth = class {
278
312
  }
279
313
  async performRefresh() {
280
314
  const session = this.tokens;
281
- if (!session?.refreshToken) {
315
+ if (!this.api || !session?.refreshToken) {
282
316
  this.tokens = null;
283
317
  return null;
284
318
  }
@@ -472,13 +506,14 @@ function setIframeHeight(source, height) {
472
506
 
473
507
  // src/EmbedClient.ts
474
508
  var EmbedClient = class {
475
- constructor(config) {
476
- this.embeddedOrigin = config.embeddedOrigin ?? getEmbeddedOrigin(config.environment);
509
+ constructor(config = {}) {
510
+ const environment = config.environment ?? "prod";
511
+ this.embeddedOrigin = config.embeddedOrigin ?? getEmbeddedOrigin(environment);
477
512
  this.channel = new FrameChannel(this.embeddedOrigin);
478
- this.auth = new SsoAuth(
513
+ this.auth = new EmbedAuth(
479
514
  {
480
515
  clientId: config.clientId,
481
- apiBaseUrl: getApiBaseUrl(config.environment),
516
+ apiBaseUrl: getApiBaseUrl(environment),
482
517
  redirectPath: config.redirectPath,
483
518
  autoLogin: config.autoLogin ?? false
484
519
  },
@@ -488,6 +523,7 @@ var EmbedClient = class {
488
523
  { autoResize: config.autoResize ?? true },
489
524
  this.channel
490
525
  );
526
+ if (config.accessToken) this.auth.setAccessToken(config.accessToken);
491
527
  }
492
528
  /** Stops listening to embeds and stops token refresh. */
493
529
  destroy() {
package/dist/index.d.cts CHANGED
@@ -37,21 +37,31 @@ interface TokenResult {
37
37
  expiresAtEpochSeconds: number;
38
38
  }
39
39
 
40
- interface SsoAuthOptions {
41
- clientId: string;
40
+ interface EmbedAuthOptions {
41
+ clientId?: string;
42
42
  apiBaseUrl: string;
43
43
  redirectPath?: string;
44
44
  autoLogin: boolean;
45
45
  }
46
+ /** Details that can accompany an access token you supply yourself. */
47
+ interface AccessTokenOptions {
48
+ /** When the token expires. Read from the token itself when omitted. */
49
+ expiresAtEpochSeconds?: number;
50
+ userId?: string;
51
+ tenantId?: string;
52
+ }
46
53
  /**
47
- * SSO module of the embed SDK, reached through `EmbedClient.auth`. Signs the
48
- * user in through the hosted login page, keeps the access token fresh, and
49
- * hands it to the embed iframes. Tokens are held in memory only and never
54
+ * Auth module of the embed SDK, reached through `EmbedClient.auth`. Holds
55
+ * the user's access token and hands it to the embed iframes. The token
56
+ * either comes from the host app (`setAccessToken()`), or from signing the
57
+ * user in through the hosted login page (`init()` / `login()`), in which
58
+ * case the SDK also keeps it fresh. Tokens are held in memory only and never
50
59
  * persisted to storage.
51
60
  */
52
- declare class SsoAuth {
61
+ declare class EmbedAuth {
53
62
  private readonly options;
54
63
  private readonly channel;
64
+ /** Null when no `clientId` was configured: the hosted sign-in is unavailable. */
55
65
  private readonly api;
56
66
  private tokens;
57
67
  private refreshTimer;
@@ -60,29 +70,40 @@ declare class SsoAuth {
60
70
  private readonly refreshListeners;
61
71
  private readonly errorListeners;
62
72
  /** @internal Created by `EmbedClient`. */
63
- constructor(options: SsoAuthOptions, channel: FrameChannel);
73
+ constructor(options: EmbedAuthOptions, channel: FrameChannel);
64
74
  /** Fires after `init()` completes a sign-in. Returns an unsubscribe function. */
65
75
  onSuccess(listener: (tokens: TokenResult) => void): () => void;
66
76
  /** Fires after each successful token refresh. Returns an unsubscribe function. */
67
77
  onTokenRefresh(listener: (tokens: TokenResult) => void): () => void;
68
78
  /** Fires when sign-in or refresh fails. Returns an unsubscribe function. */
69
79
  onError(listener: (error: EmbedError) => void): () => void;
80
+ /**
81
+ * Uses an access token you already hold for the user, and shares it with
82
+ * the embeds. Call it again whenever you have a newer token. Replaces any
83
+ * existing session; the SDK does not refresh a token supplied this way.
84
+ */
85
+ setAccessToken(accessToken: string, options?: AccessTokenOptions): void;
70
86
  /**
71
87
  * Call once when the app loads. If the URL carries `code`/`state` from the
72
88
  * hosted login page, exchanges them for tokens and removes them from the
73
89
  * URL. Otherwise, when `autoLogin` is true, redirects to the hosted login
74
90
  * page immediately; when false, resolves to null and leaves starting a
75
- * sign-in up to an explicit `login()` call.
91
+ * sign-in up to an explicit `login()` call. Does nothing without a
92
+ * `clientId`.
76
93
  */
77
94
  init(): Promise<TokenResult | null>;
78
95
  /**
79
96
  * Redirects the browser to the hosted login page. After sign-in the user
80
- * returns to `path`, else `redirectPath`, else the current page.
97
+ * returns to `path`, else `redirectPath`, else the current page. Requires
98
+ * a `clientId`.
81
99
  */
82
100
  login(path?: string): void;
83
101
  /** Drops the in-memory session and tells embedded iframes to drop theirs. */
84
102
  logout(): void;
85
- /** Returns a valid access token, refreshing first if expired. Null if there is no session. */
103
+ /**
104
+ * Returns a valid access token, refreshing first if expired. Null if there
105
+ * is no session, or the token has expired and can't be refreshed.
106
+ */
86
107
  getAccessToken(): Promise<string | null>;
87
108
  /** Whether the SDK currently holds tokens (they don't survive a reload). */
88
109
  hasSession(): boolean;
@@ -129,8 +150,18 @@ interface SsoLogoutMessage {
129
150
 
130
151
  type EmbedEnvironment = "dev" | "stage" | "prod";
131
152
  interface EmbedConfig {
132
- clientId: string;
133
- environment: EmbedEnvironment;
153
+ /**
154
+ * A Bridgewise access token you already hold for the user. The SDK shares
155
+ * it with the embeds. Replace it later with `auth.setAccessToken()`.
156
+ */
157
+ accessToken?: string;
158
+ /**
159
+ * Your Bridgewise client ID. Only needed to sign users in through the
160
+ * Bridgewise login page (`auth.init()` / `auth.login()`).
161
+ */
162
+ clientId?: string;
163
+ /** Bridgewise environment to talk to. Defaults to "prod". */
164
+ environment?: EmbedEnvironment;
134
165
  /**
135
166
  * App-relative path the hosted login page sends the user back to. Defaults
136
167
  * to the page `auth.login()` is called from.
@@ -311,16 +342,16 @@ declare class WidgetEvents {
311
342
  * Bridgewise embeds. Each feature lives on its own module.
312
343
  */
313
344
  declare class EmbedClient {
314
- /** SSO sign-in, token refresh, and handing the token to embeds. */
315
- readonly auth: SsoAuth;
345
+ /** The user's access token: supplying or obtaining it, and handing it to embeds. */
346
+ readonly auth: EmbedAuth;
316
347
  /** Events posted by embedded widgets, and iframe auto-resize. */
317
348
  readonly widgets: WidgetEvents;
318
349
  /** The origin embeds are served from — use it to build iframe URLs. */
319
350
  readonly embeddedOrigin: string;
320
351
  private readonly channel;
321
- constructor(config: EmbedConfig);
352
+ constructor(config?: EmbedConfig);
322
353
  /** Stops listening to embeds and stops token refresh. */
323
354
  destroy(): void;
324
355
  }
325
356
 
326
- export { type AssetType, type BridgetTeaserPayload, type BridgewiseMessage, EmbedClient, type EmbedConfig, type EmbedEnvironment, EmbedError, type EmbedErrorReason, type IdentifiersDataType, type RestrictedPayload, SSO_LOGOUT_MESSAGE_TYPE, SSO_READY_MESSAGE_TYPE, SSO_TOKEN_MESSAGE_TYPE, SsoAuth, type SsoLogoutMessage, type SsoTokenMessage, type TokenResult, type TradeNowPayload, type WidgetActionPayload, type WidgetCallback, type WidgetCallbacks, type WidgetEventContext, type WidgetEventPayloads, type WidgetEventType, WidgetEvents, getApiBaseUrl, getEmbeddedOrigin, isPositionsTradeNow };
357
+ export { type AccessTokenOptions, type AssetType, type BridgetTeaserPayload, type BridgewiseMessage, EmbedAuth, EmbedClient, type EmbedConfig, type EmbedEnvironment, EmbedError, type EmbedErrorReason, type IdentifiersDataType, type RestrictedPayload, SSO_LOGOUT_MESSAGE_TYPE, SSO_READY_MESSAGE_TYPE, SSO_TOKEN_MESSAGE_TYPE, type SsoLogoutMessage, type SsoTokenMessage, type TokenResult, type TradeNowPayload, type WidgetActionPayload, type WidgetCallback, type WidgetCallbacks, type WidgetEventContext, type WidgetEventPayloads, type WidgetEventType, WidgetEvents, getApiBaseUrl, getEmbeddedOrigin, isPositionsTradeNow };
package/dist/index.d.ts CHANGED
@@ -37,21 +37,31 @@ interface TokenResult {
37
37
  expiresAtEpochSeconds: number;
38
38
  }
39
39
 
40
- interface SsoAuthOptions {
41
- clientId: string;
40
+ interface EmbedAuthOptions {
41
+ clientId?: string;
42
42
  apiBaseUrl: string;
43
43
  redirectPath?: string;
44
44
  autoLogin: boolean;
45
45
  }
46
+ /** Details that can accompany an access token you supply yourself. */
47
+ interface AccessTokenOptions {
48
+ /** When the token expires. Read from the token itself when omitted. */
49
+ expiresAtEpochSeconds?: number;
50
+ userId?: string;
51
+ tenantId?: string;
52
+ }
46
53
  /**
47
- * SSO module of the embed SDK, reached through `EmbedClient.auth`. Signs the
48
- * user in through the hosted login page, keeps the access token fresh, and
49
- * hands it to the embed iframes. Tokens are held in memory only and never
54
+ * Auth module of the embed SDK, reached through `EmbedClient.auth`. Holds
55
+ * the user's access token and hands it to the embed iframes. The token
56
+ * either comes from the host app (`setAccessToken()`), or from signing the
57
+ * user in through the hosted login page (`init()` / `login()`), in which
58
+ * case the SDK also keeps it fresh. Tokens are held in memory only and never
50
59
  * persisted to storage.
51
60
  */
52
- declare class SsoAuth {
61
+ declare class EmbedAuth {
53
62
  private readonly options;
54
63
  private readonly channel;
64
+ /** Null when no `clientId` was configured: the hosted sign-in is unavailable. */
55
65
  private readonly api;
56
66
  private tokens;
57
67
  private refreshTimer;
@@ -60,29 +70,40 @@ declare class SsoAuth {
60
70
  private readonly refreshListeners;
61
71
  private readonly errorListeners;
62
72
  /** @internal Created by `EmbedClient`. */
63
- constructor(options: SsoAuthOptions, channel: FrameChannel);
73
+ constructor(options: EmbedAuthOptions, channel: FrameChannel);
64
74
  /** Fires after `init()` completes a sign-in. Returns an unsubscribe function. */
65
75
  onSuccess(listener: (tokens: TokenResult) => void): () => void;
66
76
  /** Fires after each successful token refresh. Returns an unsubscribe function. */
67
77
  onTokenRefresh(listener: (tokens: TokenResult) => void): () => void;
68
78
  /** Fires when sign-in or refresh fails. Returns an unsubscribe function. */
69
79
  onError(listener: (error: EmbedError) => void): () => void;
80
+ /**
81
+ * Uses an access token you already hold for the user, and shares it with
82
+ * the embeds. Call it again whenever you have a newer token. Replaces any
83
+ * existing session; the SDK does not refresh a token supplied this way.
84
+ */
85
+ setAccessToken(accessToken: string, options?: AccessTokenOptions): void;
70
86
  /**
71
87
  * Call once when the app loads. If the URL carries `code`/`state` from the
72
88
  * hosted login page, exchanges them for tokens and removes them from the
73
89
  * URL. Otherwise, when `autoLogin` is true, redirects to the hosted login
74
90
  * page immediately; when false, resolves to null and leaves starting a
75
- * sign-in up to an explicit `login()` call.
91
+ * sign-in up to an explicit `login()` call. Does nothing without a
92
+ * `clientId`.
76
93
  */
77
94
  init(): Promise<TokenResult | null>;
78
95
  /**
79
96
  * Redirects the browser to the hosted login page. After sign-in the user
80
- * returns to `path`, else `redirectPath`, else the current page.
97
+ * returns to `path`, else `redirectPath`, else the current page. Requires
98
+ * a `clientId`.
81
99
  */
82
100
  login(path?: string): void;
83
101
  /** Drops the in-memory session and tells embedded iframes to drop theirs. */
84
102
  logout(): void;
85
- /** Returns a valid access token, refreshing first if expired. Null if there is no session. */
103
+ /**
104
+ * Returns a valid access token, refreshing first if expired. Null if there
105
+ * is no session, or the token has expired and can't be refreshed.
106
+ */
86
107
  getAccessToken(): Promise<string | null>;
87
108
  /** Whether the SDK currently holds tokens (they don't survive a reload). */
88
109
  hasSession(): boolean;
@@ -129,8 +150,18 @@ interface SsoLogoutMessage {
129
150
 
130
151
  type EmbedEnvironment = "dev" | "stage" | "prod";
131
152
  interface EmbedConfig {
132
- clientId: string;
133
- environment: EmbedEnvironment;
153
+ /**
154
+ * A Bridgewise access token you already hold for the user. The SDK shares
155
+ * it with the embeds. Replace it later with `auth.setAccessToken()`.
156
+ */
157
+ accessToken?: string;
158
+ /**
159
+ * Your Bridgewise client ID. Only needed to sign users in through the
160
+ * Bridgewise login page (`auth.init()` / `auth.login()`).
161
+ */
162
+ clientId?: string;
163
+ /** Bridgewise environment to talk to. Defaults to "prod". */
164
+ environment?: EmbedEnvironment;
134
165
  /**
135
166
  * App-relative path the hosted login page sends the user back to. Defaults
136
167
  * to the page `auth.login()` is called from.
@@ -311,16 +342,16 @@ declare class WidgetEvents {
311
342
  * Bridgewise embeds. Each feature lives on its own module.
312
343
  */
313
344
  declare class EmbedClient {
314
- /** SSO sign-in, token refresh, and handing the token to embeds. */
315
- readonly auth: SsoAuth;
345
+ /** The user's access token: supplying or obtaining it, and handing it to embeds. */
346
+ readonly auth: EmbedAuth;
316
347
  /** Events posted by embedded widgets, and iframe auto-resize. */
317
348
  readonly widgets: WidgetEvents;
318
349
  /** The origin embeds are served from — use it to build iframe URLs. */
319
350
  readonly embeddedOrigin: string;
320
351
  private readonly channel;
321
- constructor(config: EmbedConfig);
352
+ constructor(config?: EmbedConfig);
322
353
  /** Stops listening to embeds and stops token refresh. */
323
354
  destroy(): void;
324
355
  }
325
356
 
326
- export { type AssetType, type BridgetTeaserPayload, type BridgewiseMessage, EmbedClient, type EmbedConfig, type EmbedEnvironment, EmbedError, type EmbedErrorReason, type IdentifiersDataType, type RestrictedPayload, SSO_LOGOUT_MESSAGE_TYPE, SSO_READY_MESSAGE_TYPE, SSO_TOKEN_MESSAGE_TYPE, SsoAuth, type SsoLogoutMessage, type SsoTokenMessage, type TokenResult, type TradeNowPayload, type WidgetActionPayload, type WidgetCallback, type WidgetCallbacks, type WidgetEventContext, type WidgetEventPayloads, type WidgetEventType, WidgetEvents, getApiBaseUrl, getEmbeddedOrigin, isPositionsTradeNow };
357
+ export { type AccessTokenOptions, type AssetType, type BridgetTeaserPayload, type BridgewiseMessage, EmbedAuth, EmbedClient, type EmbedConfig, type EmbedEnvironment, EmbedError, type EmbedErrorReason, type IdentifiersDataType, type RestrictedPayload, SSO_LOGOUT_MESSAGE_TYPE, SSO_READY_MESSAGE_TYPE, SSO_TOKEN_MESSAGE_TYPE, type SsoLogoutMessage, type SsoTokenMessage, type TokenResult, type TradeNowPayload, type WidgetActionPayload, type WidgetCallback, type WidgetCallbacks, type WidgetEventContext, type WidgetEventPayloads, type WidgetEventType, WidgetEvents, getApiBaseUrl, getEmbeddedOrigin, isPositionsTradeNow };
package/dist/index.js CHANGED
@@ -40,6 +40,18 @@ function parseTokenResponse(json, previous) {
40
40
  expiresAtEpochSeconds: Math.floor(Date.now() / 1e3) + raw.expires_in
41
41
  };
42
42
  }
43
+ function readJwtExpiry(accessToken) {
44
+ try {
45
+ const payload = accessToken.split(".")[1];
46
+ const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
47
+ const exp = JSON.parse(json).exp;
48
+ if (typeof exp === "number") return exp;
49
+ } catch {
50
+ }
51
+ throw new Error(
52
+ "Could not read the access token's expiry. Pass `expiresAtEpochSeconds` with the token."
53
+ );
54
+ }
43
55
  function isExpired(tokens) {
44
56
  return Math.floor(Date.now() / 1e3) >= tokens.expiresAtEpochSeconds;
45
57
  }
@@ -126,8 +138,8 @@ function isReadyMessage(data) {
126
138
  return typeof data === "object" && data !== null && data.type === SSO_READY_MESSAGE_TYPE;
127
139
  }
128
140
 
129
- // src/auth/SsoAuth.ts
130
- var SsoAuth = class {
141
+ // src/auth/EmbedAuth.ts
142
+ var EmbedAuth = class {
131
143
  /** @internal Created by `EmbedClient`. */
132
144
  constructor(options, channel) {
133
145
  this.options = options;
@@ -138,7 +150,7 @@ var SsoAuth = class {
138
150
  this.successListeners = new Listeners();
139
151
  this.refreshListeners = new Listeners();
140
152
  this.errorListeners = new Listeners();
141
- this.api = new AuthApi(options.apiBaseUrl, options.clientId);
153
+ this.api = options.clientId ? new AuthApi(options.apiBaseUrl, options.clientId) : null;
142
154
  channel.subscribe((data, source) => {
143
155
  if (isReadyMessage(data)) void this.sendTokenTo(source);
144
156
  });
@@ -155,14 +167,29 @@ var SsoAuth = class {
155
167
  onError(listener) {
156
168
  return this.errorListeners.add(listener);
157
169
  }
170
+ /**
171
+ * Uses an access token you already hold for the user, and shares it with
172
+ * the embeds. Call it again whenever you have a newer token. Replaces any
173
+ * existing session; the SDK does not refresh a token supplied this way.
174
+ */
175
+ setAccessToken(accessToken, options = {}) {
176
+ this.setTokens({
177
+ accessToken,
178
+ userId: options.userId,
179
+ tenantId: options.tenantId,
180
+ expiresAtEpochSeconds: options.expiresAtEpochSeconds ?? readJwtExpiry(accessToken)
181
+ });
182
+ }
158
183
  /**
159
184
  * Call once when the app loads. If the URL carries `code`/`state` from the
160
185
  * hosted login page, exchanges them for tokens and removes them from the
161
186
  * URL. Otherwise, when `autoLogin` is true, redirects to the hosted login
162
187
  * page immediately; when false, resolves to null and leaves starting a
163
- * sign-in up to an explicit `login()` call.
188
+ * sign-in up to an explicit `login()` call. Does nothing without a
189
+ * `clientId`.
164
190
  */
165
191
  async init() {
192
+ if (!this.api) return null;
166
193
  const callback = readAuthCallback();
167
194
  if (!callback) {
168
195
  if (this.options.autoLogin) this.login();
@@ -193,9 +220,13 @@ var SsoAuth = class {
193
220
  }
194
221
  /**
195
222
  * Redirects the browser to the hosted login page. After sign-in the user
196
- * returns to `path`, else `redirectPath`, else the current page.
223
+ * returns to `path`, else `redirectPath`, else the current page. Requires
224
+ * a `clientId`.
197
225
  */
198
226
  login(path) {
227
+ if (!this.api) {
228
+ throw new Error("auth.login() needs `clientId` in the EmbedClient config");
229
+ }
199
230
  const returnPath = path ?? this.options.redirectPath ?? window.location.pathname + window.location.search;
200
231
  window.location.assign(this.api.loginUrl(returnPath));
201
232
  }
@@ -205,7 +236,10 @@ var SsoAuth = class {
205
236
  this.clearRefreshTimer();
206
237
  this.channel.broadcast({ type: SSO_LOGOUT_MESSAGE_TYPE });
207
238
  }
208
- /** Returns a valid access token, refreshing first if expired. Null if there is no session. */
239
+ /**
240
+ * Returns a valid access token, refreshing first if expired. Null if there
241
+ * is no session, or the token has expired and can't be refreshed.
242
+ */
209
243
  async getAccessToken() {
210
244
  if (!this.tokens) return null;
211
245
  if (isExpired(this.tokens)) await this.refresh();
@@ -245,7 +279,7 @@ var SsoAuth = class {
245
279
  }
246
280
  async performRefresh() {
247
281
  const session = this.tokens;
248
- if (!session?.refreshToken) {
282
+ if (!this.api || !session?.refreshToken) {
249
283
  this.tokens = null;
250
284
  return null;
251
285
  }
@@ -439,13 +473,14 @@ function setIframeHeight(source, height) {
439
473
 
440
474
  // src/EmbedClient.ts
441
475
  var EmbedClient = class {
442
- constructor(config) {
443
- this.embeddedOrigin = config.embeddedOrigin ?? getEmbeddedOrigin(config.environment);
476
+ constructor(config = {}) {
477
+ const environment = config.environment ?? "prod";
478
+ this.embeddedOrigin = config.embeddedOrigin ?? getEmbeddedOrigin(environment);
444
479
  this.channel = new FrameChannel(this.embeddedOrigin);
445
- this.auth = new SsoAuth(
480
+ this.auth = new EmbedAuth(
446
481
  {
447
482
  clientId: config.clientId,
448
- apiBaseUrl: getApiBaseUrl(config.environment),
483
+ apiBaseUrl: getApiBaseUrl(environment),
449
484
  redirectPath: config.redirectPath,
450
485
  autoLogin: config.autoLogin ?? false
451
486
  },
@@ -455,6 +490,7 @@ var EmbedClient = class {
455
490
  { autoResize: config.autoResize ?? true },
456
491
  this.channel
457
492
  );
493
+ if (config.accessToken) this.auth.setAccessToken(config.accessToken);
458
494
  }
459
495
  /** Stops listening to embeds and stops token refresh. */
460
496
  destroy() {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@bridgewise/embed-sdk-web",
3
- "version": "0.1.0-beta.0",
4
- "description": "Embed Bridgewise widgets in a web app: SSO sign-in, token hand-off to embed iframes, widget events and iframe auto-resize",
3
+ "version": "0.1.0-beta.1",
4
+ "description": "Embed Bridgewise widgets in a web app: authenticates the widget iframes, delivers widget events and auto-resizes them",
5
5
  "keywords": [
6
6
  "bridgewise",
7
7
  "embed",