@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/dist/index.d.cts
ADDED
|
@@ -0,0 +1,357 @@
|
|
|
1
|
+
type EmbedErrorReason = "auth_callback_error" | "token_exchange_failed" | "token_refresh_failed";
|
|
2
|
+
declare class EmbedError extends Error {
|
|
3
|
+
readonly reason: EmbedErrorReason;
|
|
4
|
+
readonly cause?: unknown | undefined;
|
|
5
|
+
constructor(reason: EmbedErrorReason, message: string, cause?: unknown | undefined);
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
type FrameMessageHandler = (data: unknown, source: Window) => void;
|
|
9
|
+
/**
|
|
10
|
+
* The postMessage link between the host page and its embed iframes. It only
|
|
11
|
+
* accepts messages from child frames on the embed origin, and only ever
|
|
12
|
+
* posts to that origin.
|
|
13
|
+
*/
|
|
14
|
+
declare class FrameChannel {
|
|
15
|
+
readonly origin: string;
|
|
16
|
+
private readonly handlers;
|
|
17
|
+
constructor(origin: string);
|
|
18
|
+
/** Receives every message from an embed. Returns an unsubscribe function. */
|
|
19
|
+
subscribe(handler: FrameMessageHandler): () => void;
|
|
20
|
+
/**
|
|
21
|
+
* Posts a message to every frame on the page. `postMessage`'s
|
|
22
|
+
* `targetOrigin` is enforced by the browser at delivery time, so frames
|
|
23
|
+
* whose actual origin isn't the embed origin simply never receive it —
|
|
24
|
+
* no need to inspect the page to find which frames are embeds.
|
|
25
|
+
*/
|
|
26
|
+
broadcast(message: object): void;
|
|
27
|
+
send(frame: Window, message: object): void;
|
|
28
|
+
destroy(): void;
|
|
29
|
+
private readonly handleMessage;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
interface TokenResult {
|
|
33
|
+
accessToken: string;
|
|
34
|
+
refreshToken?: string;
|
|
35
|
+
userId?: string;
|
|
36
|
+
tenantId?: string;
|
|
37
|
+
expiresAtEpochSeconds: number;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
interface EmbedAuthOptions {
|
|
41
|
+
clientId?: string;
|
|
42
|
+
apiBaseUrl: string;
|
|
43
|
+
redirectPath?: string;
|
|
44
|
+
autoLogin: boolean;
|
|
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
|
+
}
|
|
53
|
+
/**
|
|
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
|
|
59
|
+
* persisted to storage.
|
|
60
|
+
*/
|
|
61
|
+
declare class EmbedAuth {
|
|
62
|
+
private readonly options;
|
|
63
|
+
private readonly channel;
|
|
64
|
+
/** Null when no `clientId` was configured: the hosted sign-in is unavailable. */
|
|
65
|
+
private readonly api;
|
|
66
|
+
private tokens;
|
|
67
|
+
private refreshTimer;
|
|
68
|
+
private refreshInFlight;
|
|
69
|
+
private readonly successListeners;
|
|
70
|
+
private readonly refreshListeners;
|
|
71
|
+
private readonly errorListeners;
|
|
72
|
+
/** @internal Created by `EmbedClient`. */
|
|
73
|
+
constructor(options: EmbedAuthOptions, channel: FrameChannel);
|
|
74
|
+
/** Fires after `init()` completes a sign-in. Returns an unsubscribe function. */
|
|
75
|
+
onSuccess(listener: (tokens: TokenResult) => void): () => void;
|
|
76
|
+
/** Fires after each successful token refresh. Returns an unsubscribe function. */
|
|
77
|
+
onTokenRefresh(listener: (tokens: TokenResult) => void): () => void;
|
|
78
|
+
/** Fires when sign-in or refresh fails. Returns an unsubscribe function. */
|
|
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;
|
|
86
|
+
/**
|
|
87
|
+
* Call once when the app loads. If the URL carries `code`/`state` from the
|
|
88
|
+
* hosted login page, exchanges them for tokens and removes them from the
|
|
89
|
+
* URL. Otherwise, when `autoLogin` is true, redirects to the hosted login
|
|
90
|
+
* page immediately; when false, resolves to null and leaves starting a
|
|
91
|
+
* sign-in up to an explicit `login()` call. Does nothing without a
|
|
92
|
+
* `clientId`.
|
|
93
|
+
*/
|
|
94
|
+
init(): Promise<TokenResult | null>;
|
|
95
|
+
/**
|
|
96
|
+
* Redirects the browser to the hosted login page. After sign-in the user
|
|
97
|
+
* returns to `path`, else `redirectPath`, else the current page. Requires
|
|
98
|
+
* a `clientId`.
|
|
99
|
+
*/
|
|
100
|
+
login(path?: string): void;
|
|
101
|
+
/** Drops the in-memory session and tells embedded iframes to drop theirs. */
|
|
102
|
+
logout(): void;
|
|
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
|
+
*/
|
|
107
|
+
getAccessToken(): Promise<string | null>;
|
|
108
|
+
/** Whether the SDK currently holds tokens (they don't survive a reload). */
|
|
109
|
+
hasSession(): boolean;
|
|
110
|
+
/**
|
|
111
|
+
* Re-sends the current access token to embedded iframes. Embeds normally
|
|
112
|
+
* ask for it themselves when they load, so this is only needed for an
|
|
113
|
+
* embed that doesn't.
|
|
114
|
+
*/
|
|
115
|
+
broadcastToken(): void;
|
|
116
|
+
/** @internal Stops token refresh. Called by `EmbedClient.destroy()`. */
|
|
117
|
+
destroy(): void;
|
|
118
|
+
private setTokens;
|
|
119
|
+
private sendTokenTo;
|
|
120
|
+
/** Concurrent callers share a single in-flight refresh. */
|
|
121
|
+
private refresh;
|
|
122
|
+
private performRefresh;
|
|
123
|
+
/** Refreshes at the moment the access token expires. */
|
|
124
|
+
private scheduleRefresh;
|
|
125
|
+
private clearRefreshTimer;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* SSO messages exchanged with embed iframes. They are plain objects (unlike
|
|
130
|
+
* widget events, which are JSON strings).
|
|
131
|
+
*/
|
|
132
|
+
/** Host → embed: the current access token. */
|
|
133
|
+
declare const SSO_TOKEN_MESSAGE_TYPE: "bridgewise:sso:token";
|
|
134
|
+
/** Embed → host: sent once its listener is attached, asking for the current token. */
|
|
135
|
+
declare const SSO_READY_MESSAGE_TYPE: "bridgewise:sso:ready";
|
|
136
|
+
/** Host → embed: the session ended, drop the token. */
|
|
137
|
+
declare const SSO_LOGOUT_MESSAGE_TYPE: "bridgewise:sso:logout";
|
|
138
|
+
interface SsoTokenMessage {
|
|
139
|
+
type: typeof SSO_TOKEN_MESSAGE_TYPE;
|
|
140
|
+
accessToken: string;
|
|
141
|
+
/** From the `/token` response; absent if it didn't include one. */
|
|
142
|
+
userId?: string;
|
|
143
|
+
/** From the `/token` response; absent if it didn't include one. */
|
|
144
|
+
tenantId?: string;
|
|
145
|
+
expiresAtEpochSeconds: number;
|
|
146
|
+
}
|
|
147
|
+
interface SsoLogoutMessage {
|
|
148
|
+
type: typeof SSO_LOGOUT_MESSAGE_TYPE;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
type EmbedEnvironment = "dev" | "stage" | "prod";
|
|
152
|
+
interface EmbedConfig {
|
|
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;
|
|
165
|
+
/**
|
|
166
|
+
* App-relative path the hosted login page sends the user back to. Defaults
|
|
167
|
+
* to the page `auth.login()` is called from.
|
|
168
|
+
*/
|
|
169
|
+
redirectPath?: string;
|
|
170
|
+
/**
|
|
171
|
+
* When true, `auth.init()` redirects to the hosted login page immediately
|
|
172
|
+
* if the URL carries no auth callback. When false (the default), `init()`
|
|
173
|
+
* only processes an in-progress callback (or resolves to null otherwise) —
|
|
174
|
+
* the app must call `auth.login()` itself to start a sign-in.
|
|
175
|
+
*/
|
|
176
|
+
autoLogin?: boolean;
|
|
177
|
+
/**
|
|
178
|
+
* When true (the default), the SDK sets each embed iframe's height from
|
|
179
|
+
* the `height` in its `load`, `resize` and `success` events.
|
|
180
|
+
*/
|
|
181
|
+
autoResize?: boolean;
|
|
182
|
+
/**
|
|
183
|
+
* Origin of the embedded widgets, overriding the environment's default
|
|
184
|
+
* (e.g. "http://localhost:3001" when running the widgets locally). Tokens
|
|
185
|
+
* are only ever posted to this origin.
|
|
186
|
+
*/
|
|
187
|
+
embeddedOrigin?: string;
|
|
188
|
+
}
|
|
189
|
+
/** Base URL of the Bridgewise REST API for an environment. */
|
|
190
|
+
declare function getApiBaseUrl(environment: EmbedEnvironment): string;
|
|
191
|
+
/** Default origin the embedded widgets are served from for an environment. */
|
|
192
|
+
declare function getEmbeddedOrigin(environment: EmbedEnvironment): string;
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* Events posted by embedded Bridgewise widgets to the host page. Widgets send
|
|
196
|
+
* them as JSON strings (unlike the SSO messages, which are plain objects).
|
|
197
|
+
*/
|
|
198
|
+
type AssetType = "fund" | "stock" | "alt" | "bond";
|
|
199
|
+
interface IdentifiersDataType {
|
|
200
|
+
exchange?: string;
|
|
201
|
+
ticker?: string;
|
|
202
|
+
tase?: string;
|
|
203
|
+
isin?: string;
|
|
204
|
+
type: AssetType;
|
|
205
|
+
tradingItemId?: number;
|
|
206
|
+
}
|
|
207
|
+
interface BridgetTeaserPayload {
|
|
208
|
+
companyId: number | null;
|
|
209
|
+
message: string;
|
|
210
|
+
query: string;
|
|
211
|
+
primaryTickerSymbol: string | null;
|
|
212
|
+
}
|
|
213
|
+
interface RestrictedPayload {
|
|
214
|
+
type: AssetType;
|
|
215
|
+
assetName?: string;
|
|
216
|
+
ticker?: string;
|
|
217
|
+
exchange?: string;
|
|
218
|
+
isin?: string;
|
|
219
|
+
tase?: string;
|
|
220
|
+
}
|
|
221
|
+
/**
|
|
222
|
+
* Payload of `click` / `hover` / `trigger` events: the widget's own data with
|
|
223
|
+
* `id` naming the action (e.g. "instrument", "trade_now", "info_action").
|
|
224
|
+
* Some widgets (Reasoning, StatisticalInsights, MarketSignals, altwise) use
|
|
225
|
+
* the widget name as `id` and nest their fields under `data`.
|
|
226
|
+
*/
|
|
227
|
+
type WidgetActionPayload = {
|
|
228
|
+
id: string;
|
|
229
|
+
} & Record<string, unknown>;
|
|
230
|
+
/** `click` from portfolio-positions when the user hits "Trade now" on an optimization suggestion. */
|
|
231
|
+
interface TradeNowPayload {
|
|
232
|
+
id: "trade_now";
|
|
233
|
+
currentAsset: {
|
|
234
|
+
identifier: string;
|
|
235
|
+
tid: number;
|
|
236
|
+
quantity: number;
|
|
237
|
+
assetType: AssetType;
|
|
238
|
+
};
|
|
239
|
+
targetAsset: {
|
|
240
|
+
identifier: string;
|
|
241
|
+
assetType: AssetType;
|
|
242
|
+
};
|
|
243
|
+
}
|
|
244
|
+
declare function isPositionsTradeNow(data: WidgetActionPayload, widget: string): data is WidgetActionPayload & TradeNowPayload;
|
|
245
|
+
interface WidgetEventPayloads {
|
|
246
|
+
load: {
|
|
247
|
+
height: number;
|
|
248
|
+
width: number;
|
|
249
|
+
};
|
|
250
|
+
resize: {
|
|
251
|
+
height: number | undefined;
|
|
252
|
+
};
|
|
253
|
+
success: {
|
|
254
|
+
height: number | undefined;
|
|
255
|
+
};
|
|
256
|
+
error: {
|
|
257
|
+
message: string;
|
|
258
|
+
status: number;
|
|
259
|
+
height: number;
|
|
260
|
+
};
|
|
261
|
+
"security-select": {
|
|
262
|
+
id: string;
|
|
263
|
+
} & Partial<IdentifiersDataType>;
|
|
264
|
+
"bridget-teaser-trigger": BridgetTeaserPayload;
|
|
265
|
+
navigate: {
|
|
266
|
+
href: string;
|
|
267
|
+
meta?: {
|
|
268
|
+
source: "security";
|
|
269
|
+
identifier: unknown;
|
|
270
|
+
} | {
|
|
271
|
+
source: "bridget-answer";
|
|
272
|
+
};
|
|
273
|
+
};
|
|
274
|
+
"trading-item-id-change": {
|
|
275
|
+
tradingItemId?: number;
|
|
276
|
+
};
|
|
277
|
+
"restricted-trigger": RestrictedPayload;
|
|
278
|
+
click: WidgetActionPayload;
|
|
279
|
+
hover: WidgetActionPayload;
|
|
280
|
+
trigger: WidgetActionPayload;
|
|
281
|
+
}
|
|
282
|
+
type WidgetEventType = keyof WidgetEventPayloads;
|
|
283
|
+
interface BridgewiseMessage<T extends WidgetEventType = WidgetEventType> {
|
|
284
|
+
/** Legacy name: `on-<type>-<widgetName>`. */
|
|
285
|
+
event: string;
|
|
286
|
+
type: T;
|
|
287
|
+
/** widgetName from the iframe URL. */
|
|
288
|
+
widget: string;
|
|
289
|
+
data: WidgetEventPayloads[T];
|
|
290
|
+
}
|
|
291
|
+
interface WidgetEventContext {
|
|
292
|
+
widget: string;
|
|
293
|
+
event: string;
|
|
294
|
+
/** The iframe window that sent the event. */
|
|
295
|
+
source: Window;
|
|
296
|
+
}
|
|
297
|
+
/** Maps each event type to the name of its callback in `WidgetCallbacks`. */
|
|
298
|
+
declare const WIDGET_CALLBACK_NAMES: {
|
|
299
|
+
readonly load: "onLoad";
|
|
300
|
+
readonly resize: "onResize";
|
|
301
|
+
readonly success: "onSuccess";
|
|
302
|
+
readonly error: "onError";
|
|
303
|
+
readonly "security-select": "onSecuritySelect";
|
|
304
|
+
readonly "bridget-teaser-trigger": "onBridgetTeaserTrigger";
|
|
305
|
+
readonly navigate: "onNavigate";
|
|
306
|
+
readonly "trading-item-id-change": "onTradingItemIdChange";
|
|
307
|
+
readonly "restricted-trigger": "onRestrictedTrigger";
|
|
308
|
+
readonly click: "onClick";
|
|
309
|
+
readonly hover: "onHover";
|
|
310
|
+
readonly trigger: "onTrigger";
|
|
311
|
+
};
|
|
312
|
+
type WidgetCallback<T extends WidgetEventType> = (data: WidgetEventPayloads[T], context: WidgetEventContext) => void;
|
|
313
|
+
/** One optional callback per event type: `onLoad`, `onResize`, `onClick`, ... */
|
|
314
|
+
type WidgetCallbacks = {
|
|
315
|
+
[T in WidgetEventType as (typeof WIDGET_CALLBACK_NAMES)[T]]?: WidgetCallback<T>;
|
|
316
|
+
};
|
|
317
|
+
|
|
318
|
+
interface WidgetEventsOptions {
|
|
319
|
+
autoResize: boolean;
|
|
320
|
+
}
|
|
321
|
+
/**
|
|
322
|
+
* Widget events module of the embed SDK, reached through
|
|
323
|
+
* `EmbedClient.widgets`. Delivers the events embedded widgets post to the
|
|
324
|
+
* host page, and keeps each iframe as tall as its content.
|
|
325
|
+
*/
|
|
326
|
+
declare class WidgetEvents {
|
|
327
|
+
private readonly options;
|
|
328
|
+
private readonly subscriptions;
|
|
329
|
+
/** @internal Created by `EmbedClient`. */
|
|
330
|
+
constructor(options: WidgetEventsOptions, channel: FrameChannel);
|
|
331
|
+
/**
|
|
332
|
+
* Registers callbacks for events posted by embedded widgets (onLoad,
|
|
333
|
+
* onResize, onClick, ...). Returns an unsubscribe function.
|
|
334
|
+
*/
|
|
335
|
+
on(callbacks: WidgetCallbacks): () => void;
|
|
336
|
+
private handle;
|
|
337
|
+
private emit;
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
/**
|
|
341
|
+
* Public entry point for the embed SDK: everything a host page needs to run
|
|
342
|
+
* Bridgewise embeds. Each feature lives on its own module.
|
|
343
|
+
*/
|
|
344
|
+
declare class EmbedClient {
|
|
345
|
+
/** The user's access token: supplying or obtaining it, and handing it to embeds. */
|
|
346
|
+
readonly auth: EmbedAuth;
|
|
347
|
+
/** Events posted by embedded widgets, and iframe auto-resize. */
|
|
348
|
+
readonly widgets: WidgetEvents;
|
|
349
|
+
/** The origin embeds are served from — use it to build iframe URLs. */
|
|
350
|
+
readonly embeddedOrigin: string;
|
|
351
|
+
private readonly channel;
|
|
352
|
+
constructor(config?: EmbedConfig);
|
|
353
|
+
/** Stops listening to embeds and stops token refresh. */
|
|
354
|
+
destroy(): void;
|
|
355
|
+
}
|
|
356
|
+
|
|
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 };
|