@widgetic/embed-sdk 2.0.16 → 2.1.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 +36 -10
- package/dist/browser/chunks/ABTestManager.js +1 -1
- package/dist/browser/chunks/api.js +1 -1
- package/dist/browser/chunks/core.js +1 -1
- package/dist/browser/chunks/renderers.js +1 -1
- package/dist/browser/chunks/scanner.js +1 -1
- package/dist/browser/chunks/security.js +1 -1
- package/dist/browser/chunks/workflows.js +1 -0
- package/dist/browser/embed-bootstrap.js +1 -1
- package/dist/browser/embed-sdk.js +1 -1
- package/dist/esm/chunks/ABTestManager.js +1 -1
- package/dist/esm/chunks/api.js +1 -1
- package/dist/esm/chunks/core.js +1 -1
- package/dist/esm/chunks/renderers.js +1 -1
- package/dist/esm/chunks/scanner.js +1 -1
- package/dist/esm/chunks/security.js +1 -1
- package/dist/esm/chunks/workflows.js +1 -0
- package/dist/esm/embed-bootstrap.js +1 -1
- package/dist/esm/embed-sdk.js +1 -1
- package/dist/esm/types/abTesting/abVisitor.d.ts +2 -0
- package/dist/esm/types/core/advanced-security-manager.d.ts +3 -0
- package/dist/esm/types/core/autoscale-manager.d.ts +6 -0
- package/dist/esm/types/core/widget-manager.d.ts +8 -43
- package/dist/esm/types/embed-sdk.d.ts +1 -0
- package/dist/esm/types/sdk/embed-sdk.d.ts +1 -0
- package/dist/esm/types/utils/declarative-embed-parser.d.ts +5 -0
- package/dist/esm/types/utils/host-workflow-watch.d.ts +62 -0
- package/dist/esm/types/utils/hydrate-published-host.d.ts +8 -4
- package/dist/esm/types/utils/mount-direct-widget.d.ts +12 -0
- package/dist/esm/types/utils/public-embed-lookup.d.ts +5 -0
- package/dist/esm/types/utils/published-host-bridge.d.ts +10 -0
- package/dist/esm/types/utils/workflow-code-loader.d.ts +14 -0
- package/dist/esm/types/utils/workflow-code-loader.umd.d.ts +32 -0
- package/dist/esm/types/utils/workflow-embed-registry.d.ts +15 -0
- package/dist/esm/types/utils/workflow-page-events.d.ts +41 -0
- package/dist/esm/types/utils/workflow-shared-contract.d.ts +35 -0
- package/dist/esm/types/utils/workflow-shared-services.d.ts +84 -0
- package/dist/esm/types/workflows/umd-entry.d.ts +1 -0
- package/dist/esm/types/workflows/visitor-position.d.ts +32 -0
- package/dist/esm/types/workflows/workflow-autoscale.d.ts +41 -0
- package/dist/esm/types/workflows/workflow-counts.d.ts +65 -0
- package/dist/esm/types/workflows/workflow-host.d.ts +71 -0
- package/dist/esm/types/workflows/workflow-lookup.d.ts +53 -0
- package/dist/esm/types/workflows/workflow-signals.d.ts +34 -0
- package/dist/esm/types/workflows/workflow-stage.d.ts +154 -0
- package/dist/umd/embed-bootstrap.js +1 -1
- package/dist/umd/embed-sdk-workflows.js +1 -0
- package/dist/umd/embed-sdk.js +1 -1
- package/package.json +2 -1
- package/dist/esm/types/core/realtime-manager.d.ts +0 -286
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import { TriggerManager } from "./trigger-manager.js";
|
|
2
|
-
import { type RealtimeConfig, type RealtimeSubscription } from "./realtime-manager.js";
|
|
3
2
|
import type { WidgetConfig, WidgetInstance, CompositionData, ResponsiveState } from "./types.js";
|
|
4
3
|
/**
|
|
5
4
|
* Widget error types
|
|
@@ -24,8 +23,6 @@ export interface WidgetEvent {
|
|
|
24
23
|
* Embed configuration for the SDK
|
|
25
24
|
*/
|
|
26
25
|
export interface EmbedConfig {
|
|
27
|
-
/** Enable real-time updates */
|
|
28
|
-
realtime?: RealtimeConfig;
|
|
29
26
|
/** Security configuration */
|
|
30
27
|
security?: {
|
|
31
28
|
enableSanitization?: boolean;
|
|
@@ -50,11 +47,9 @@ export interface EmbedConfig {
|
|
|
50
47
|
accessToken?: string;
|
|
51
48
|
}
|
|
52
49
|
/**
|
|
53
|
-
* Rendered widget
|
|
50
|
+
* Rendered widget tracked by the widget manager
|
|
54
51
|
*/
|
|
55
52
|
export interface RenderedWidget extends WidgetInstance {
|
|
56
|
-
/** Real-time subscription for live updates */
|
|
57
|
-
realtimeSubscription?: RealtimeSubscription;
|
|
58
53
|
/** Last update timestamp */
|
|
59
54
|
lastUpdate?: number;
|
|
60
55
|
/** Update handlers */
|
|
@@ -70,18 +65,18 @@ export interface SecurityValidationResult {
|
|
|
70
65
|
sanitizedText?: string;
|
|
71
66
|
}
|
|
72
67
|
/**
|
|
73
|
-
* Widget Manager - Core orchestrator for widget lifecycle
|
|
68
|
+
* Widget Manager - Core orchestrator for widget lifecycle
|
|
74
69
|
*
|
|
75
|
-
* Note:
|
|
70
|
+
* Note: Content updates are based on Compositions, not individual widgets.
|
|
76
71
|
* Multiple widget instances can render the same composition and will all
|
|
77
|
-
* receive
|
|
72
|
+
* receive the content when `setContent` is called for that composition.
|
|
73
|
+
* The manager opens no socket and does no polling of its own.
|
|
78
74
|
*/
|
|
79
75
|
export declare class WidgetManager {
|
|
80
76
|
private static instance;
|
|
81
77
|
private config;
|
|
82
78
|
private securityManager;
|
|
83
79
|
private displayManager;
|
|
84
|
-
private realtimeManager;
|
|
85
80
|
private performanceMonitor;
|
|
86
81
|
private apiConfig;
|
|
87
82
|
private widgetsApi;
|
|
@@ -90,7 +85,6 @@ export declare class WidgetManager {
|
|
|
90
85
|
private widgetConfigs;
|
|
91
86
|
private compositionData;
|
|
92
87
|
private triggerManagers;
|
|
93
|
-
private compositionSubscriptions;
|
|
94
88
|
private compositionWidgets;
|
|
95
89
|
private eventListeners;
|
|
96
90
|
private errorHandlers;
|
|
@@ -106,45 +100,17 @@ export declare class WidgetManager {
|
|
|
106
100
|
*/
|
|
107
101
|
initialize(): Promise<void>;
|
|
108
102
|
/**
|
|
109
|
-
* Register a widget instance
|
|
103
|
+
* Register a widget instance
|
|
110
104
|
*/
|
|
111
105
|
registerWidget(widgetId: string, config: WidgetConfig, element: HTMLElement): Promise<RenderedWidget>;
|
|
112
106
|
/**
|
|
113
|
-
*
|
|
107
|
+
* Remember that a widget renders a composition
|
|
114
108
|
*/
|
|
115
|
-
private
|
|
116
|
-
/**
|
|
117
|
-
* Handle real-time update for a composition (affects all widgets rendering it)
|
|
118
|
-
*/
|
|
119
|
-
private handleCompositionUpdate;
|
|
120
|
-
/**
|
|
121
|
-
* Handle real-time update for a specific widget instance
|
|
122
|
-
*/
|
|
123
|
-
private handleWidgetUpdate;
|
|
124
|
-
/**
|
|
125
|
-
* Handle content updates
|
|
126
|
-
*/
|
|
127
|
-
private handleContentUpdate;
|
|
128
|
-
/**
|
|
129
|
-
* Handle style updates
|
|
130
|
-
*/
|
|
131
|
-
private handleStyleUpdate;
|
|
132
|
-
/**
|
|
133
|
-
* Handle configuration updates
|
|
134
|
-
*/
|
|
135
|
-
private handleConfigUpdate;
|
|
136
|
-
/**
|
|
137
|
-
* Handle data updates
|
|
138
|
-
*/
|
|
139
|
-
private handleDataUpdate;
|
|
109
|
+
private trackWidgetForComposition;
|
|
140
110
|
/**
|
|
141
111
|
* Apply content to widget element
|
|
142
112
|
*/
|
|
143
113
|
private applyContentToWidget;
|
|
144
|
-
/**
|
|
145
|
-
* Apply styles to widget element
|
|
146
|
-
*/
|
|
147
|
-
private applyStylesToWidget;
|
|
148
114
|
/**
|
|
149
115
|
* Sanitize content for security
|
|
150
116
|
*/
|
|
@@ -261,7 +227,6 @@ export declare class WidgetManager {
|
|
|
261
227
|
getStats(): {
|
|
262
228
|
widgets: number;
|
|
263
229
|
compositions: number;
|
|
264
|
-
compositionSubscriptions: number;
|
|
265
230
|
triggerManagers: number;
|
|
266
231
|
responsiveState: ResponsiveState | null;
|
|
267
232
|
isInitialized: boolean;
|
|
@@ -20,6 +20,7 @@ export { WidgeticMessenger, getMessenger, resetMessenger, type WidgeticMessage,
|
|
|
20
20
|
export { ABTestManager, type ABTestConfig, type ABTestAssignment, } from "./abTesting/ABTestManager.js";
|
|
21
21
|
export { ABTestElement, } from "./abTesting/ABTestElement.js";
|
|
22
22
|
export { TranslationElement, } from "./translations/TranslationElement.js";
|
|
23
|
+
export { sendWorkflowEvent } from "./utils/workflow-page-events.js";
|
|
23
24
|
export { log } from "./utils/logger.js";
|
|
24
25
|
export { detectBrowserCapabilities, determineBestRenderMode, } from "./utils/browser.js";
|
|
25
26
|
export { parseWidgetConfig, generateInstanceId, isValidWidgetElement, } from "./utils/parser.js";
|
|
@@ -20,6 +20,7 @@ export { WidgeticMessenger, getMessenger, resetMessenger, type WidgeticMessage,
|
|
|
20
20
|
export { ABTestManager, type ABTestConfig, type ABTestAssignment, } from "../abTesting/ABTestManager.js";
|
|
21
21
|
export { ABTestElement, } from "../abTesting/ABTestElement.js";
|
|
22
22
|
export { TranslationElement, } from "../translations/TranslationElement.js";
|
|
23
|
+
export { sendWorkflowEvent } from "../utils/workflow-page-events.js";
|
|
23
24
|
export { log } from "../utils/logger.js";
|
|
24
25
|
export { detectBrowserCapabilities, determineBestRenderMode, } from "../utils/browser.js";
|
|
25
26
|
export { parseWidgetConfig, generateInstanceId, isValidWidgetElement, } from "../utils/parser.js";
|
|
@@ -58,6 +58,11 @@ export declare function installHostPropertyBridge(host: HTMLElement): void;
|
|
|
58
58
|
*/
|
|
59
59
|
export declare function getHostInstanceId(host: HTMLElement): string | null;
|
|
60
60
|
export declare function isDeclarativeJsonScript(element: Element): boolean;
|
|
61
|
+
/**
|
|
62
|
+
* What a tag holds for its widget: its items and its JSON blocks, without what the SDK put there itself. A workflow
|
|
63
|
+
* hands these to the first widget it shows, so that what the page wrote in the tag is the content of that one.
|
|
64
|
+
*/
|
|
65
|
+
export declare function declarativeChildrenOf(host: HTMLElement): Element[];
|
|
61
66
|
export declare function isReservedHostAttribute(attrName: string): boolean;
|
|
62
67
|
/**
|
|
63
68
|
* Parses `<script type="application/json">` (or `application/ld+json`, `application/widgetic+json`,
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the page tells the widget on screen to watch, for a workflow (`widgetic:workflow-watch`, player version 6, and
|
|
3
|
+
* the `workflow` property of a widget mounted directly in the page). See the host bridge contract.
|
|
4
|
+
*
|
|
5
|
+
* Only what a published rule or trigger needs: the tables whose saved entries a trigger waits for, the columns a
|
|
6
|
+
* condition reads, and the actions a trigger waits for. Everything else a visitor does stays inside the widget.
|
|
7
|
+
*
|
|
8
|
+
* Like `workflow-page-events.ts` this file sits outside `src/workflows/` (the folder loaded only for a page with a
|
|
9
|
+
* `workflow-id` tag) because the host bridge uses it for every page; it therefore keeps its own small copy of how an
|
|
10
|
+
* action id is read, and a test pins that it agrees with the engine's.
|
|
11
|
+
*/
|
|
12
|
+
/** The most tables, columns and goals a widget is told to watch (the wrapper keeps no more than these). */
|
|
13
|
+
export declare const MAX_WATCHED_TABLES = 20;
|
|
14
|
+
export declare const MAX_WATCHED_COLUMNS = 50;
|
|
15
|
+
export declare const MAX_WATCHED_GOALS = 20;
|
|
16
|
+
export interface WatchedField {
|
|
17
|
+
table: string;
|
|
18
|
+
column: string;
|
|
19
|
+
}
|
|
20
|
+
/** What a shown composition has to report, in the shape both ways of telling a widget share. */
|
|
21
|
+
export interface WorkflowWatch {
|
|
22
|
+
tables: string[];
|
|
23
|
+
fields: WatchedField[];
|
|
24
|
+
/** Action ids: a goal's metric, or the metric and the element that counts joined by the first `@`. */
|
|
25
|
+
goals: string[];
|
|
26
|
+
}
|
|
27
|
+
/** What the engine's `describeWatch` says a composition needs (only the parts a widget is told about). */
|
|
28
|
+
export interface WatchSource {
|
|
29
|
+
inputTables: string[];
|
|
30
|
+
inputColumns: WatchedField[];
|
|
31
|
+
actionIds: string[];
|
|
32
|
+
}
|
|
33
|
+
export interface ActionIdParts {
|
|
34
|
+
metric: string;
|
|
35
|
+
selector: string | null;
|
|
36
|
+
}
|
|
37
|
+
/** What an action id counts: the goal and, when it is about one element, the element. Null for text that is not an id. */
|
|
38
|
+
export declare function splitActionId(actionId: string): ActionIdParts | null;
|
|
39
|
+
/** The watch of a composition: what a widget is told, with the same limits and filters the wrapper applies. */
|
|
40
|
+
export declare function buildWorkflowWatch(source: WatchSource): WorkflowWatch;
|
|
41
|
+
/** The `widgetic:workflow-watch` message a widget in a frame is sent (the wrapper hands the widget the goals in full). */
|
|
42
|
+
export declare function workflowWatchMessage(compositionId: string, watch: WorkflowWatch): {
|
|
43
|
+
type: "widgetic:workflow-watch";
|
|
44
|
+
version: 1;
|
|
45
|
+
compositionId: string;
|
|
46
|
+
tables: string[];
|
|
47
|
+
fields: WatchedField[];
|
|
48
|
+
goals: string[];
|
|
49
|
+
};
|
|
50
|
+
export interface DirectWorkflowGoal {
|
|
51
|
+
id: string;
|
|
52
|
+
metric: string;
|
|
53
|
+
goalTarget: string | null;
|
|
54
|
+
}
|
|
55
|
+
export interface DirectWorkflowProperty {
|
|
56
|
+
compositionId: string;
|
|
57
|
+
tables: string[];
|
|
58
|
+
fields: WatchedField[];
|
|
59
|
+
goals: DirectWorkflowGoal[];
|
|
60
|
+
}
|
|
61
|
+
/** The `workflow` property of `mount` and `update` for a widget mounted in the page: the goals as the wrapper hands them. */
|
|
62
|
+
export declare function workflowWatchProperty(compositionId: string, watch: WorkflowWatch): DirectWorkflowProperty;
|
|
@@ -9,20 +9,24 @@
|
|
|
9
9
|
*/
|
|
10
10
|
import { REFUSED_HOST_ATTRIBUTE } from "./host-bridge-markers.js";
|
|
11
11
|
export { REFUSED_HOST_ATTRIBUTE };
|
|
12
|
+
export { sendWorkflowEvent } from "./workflow-page-events.js";
|
|
12
13
|
export declare function hydratePublishedHost(host: HTMLElement): boolean;
|
|
13
14
|
export declare function hydratePublishedHosts(root?: ParentNode): number;
|
|
14
|
-
/** Enables WebSocket real-time subscription for a published host */
|
|
15
|
-
export declare function enableRealtimeForPublishedHost(host: HTMLElement): () => void;
|
|
16
15
|
/**
|
|
17
16
|
* Reloads a published widget host in place while maintaining playback timestamp and selected item state.
|
|
17
|
+
*
|
|
18
|
+
* Nothing in the SDK calls this on its own. The SDK opens no socket and does no polling: a page (or a future
|
|
19
|
+
* channel from the gateway) that wants a reload calls it.
|
|
18
20
|
*/
|
|
19
21
|
export declare function reloadPublishedHost(host: HTMLElement): Promise<boolean>;
|
|
20
22
|
/**
|
|
21
|
-
* Applies
|
|
23
|
+
* Applies live content updates to a running widget without refreshing or reloading the iframe.
|
|
24
|
+
* Called by the page; the SDK does not push updates by itself.
|
|
22
25
|
*/
|
|
23
26
|
export declare function applyLiveContentUpdate(host: HTMLElement, data: unknown): void;
|
|
24
27
|
/**
|
|
25
|
-
* Applies
|
|
28
|
+
* Applies live style/design updates to a running widget without refreshing or reloading the iframe.
|
|
29
|
+
* Called by the page; the SDK does not push updates by itself.
|
|
26
30
|
*/
|
|
27
31
|
export declare function applyLiveStyleUpdate(host: HTMLElement, styles: unknown): void;
|
|
28
32
|
/** Clears the bridge when a host is removed from the page. */
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* The tag has no hyphen, so the shadow root sits on a child.
|
|
4
4
|
*/
|
|
5
5
|
import type { PublicEmbedPayload } from "./public-embed-lookup.js";
|
|
6
|
+
import type { DirectWorkflowProperty } from "./host-workflow-watch.js";
|
|
6
7
|
export declare const DIRECT_CONTRACT_VERSION = 2;
|
|
7
8
|
export type DirectWidgetInstance = {
|
|
8
9
|
update: (next: Record<string, unknown>) => void;
|
|
@@ -14,8 +15,19 @@ export type DirectWidgetModule = {
|
|
|
14
15
|
mount: (target: HTMLElement, props: Record<string, unknown>) => DirectWidgetInstance;
|
|
15
16
|
};
|
|
16
17
|
type DirectModuleLoader = (url: string) => Promise<DirectWidgetModule>;
|
|
18
|
+
/**
|
|
19
|
+
* Loads a module ahead of time, so the module is already there when a workflow swaps it in. Resolves to whether it
|
|
20
|
+
* loaded, and never rejects: a module that does not load is found out by the swap that needs it.
|
|
21
|
+
*/
|
|
22
|
+
export declare function warmDirectModule(moduleUrl: string): Promise<boolean>;
|
|
17
23
|
/** Tests replace the network import. Pass null to restore it. */
|
|
18
24
|
export declare function setDirectModuleLoader(loader: DirectModuleLoader | null): void;
|
|
25
|
+
/**
|
|
26
|
+
* Tells a directly mounted widget what its workflow needs it to report: the tables whose saved entries a trigger waits
|
|
27
|
+
* for, the columns a condition reads, and the actions a trigger waits for. Pass null to take it back.
|
|
28
|
+
* It reaches the module as the `workflow` property, in `mount` when set before the mount and in `update` after.
|
|
29
|
+
*/
|
|
30
|
+
export declare function setDirectMountWorkflow(host: HTMLElement, property: DirectWorkflowProperty | null): void;
|
|
19
31
|
/**
|
|
20
32
|
* Updates a live direct-mounted widget in place (e.g. from a WebSocket content/style push)
|
|
21
33
|
* without destroying or reloading the widget.
|
|
@@ -79,6 +79,11 @@ export type PublishedEmbedLookup = {
|
|
|
79
79
|
} | {
|
|
80
80
|
status: "not-found";
|
|
81
81
|
};
|
|
82
|
+
/**
|
|
83
|
+
* The API hosts a public lookup may ask, in the order they are asked: the ones the page names itself
|
|
84
|
+
* (`data-api-url`, `WIDGETIC_EMBED_API`), then the SDK's own API, then production. Without repeats.
|
|
85
|
+
*/
|
|
86
|
+
export declare function publicEmbedApiOrigins(): string[];
|
|
82
87
|
export declare function publicCompositionLookupUrls(compositionId: string): string[];
|
|
83
88
|
export declare function resolvePublishedEmbed(compositionId: string): Promise<PublishedEmbedLookup>;
|
|
84
89
|
export declare function resolvePublishedEmbedUrl(compositionId: string): Promise<string | null>;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Relays `widgetic:host` into the gateway frame and wrapper events back to the page.
|
|
3
3
|
*/
|
|
4
|
+
import { type WorkflowWatch } from "./host-workflow-watch.js";
|
|
4
5
|
/** What the page tells a widget about the A/B test it is part of. */
|
|
5
6
|
export interface AbGoalAssignment {
|
|
6
7
|
/** The goal the test measures (a metric id such as `clicks`). */
|
|
@@ -17,6 +18,7 @@ declare class PublishedHostBridge {
|
|
|
17
18
|
private readonly compositionId;
|
|
18
19
|
private readyDispatched;
|
|
19
20
|
private latestAbGoal;
|
|
21
|
+
private latestWorkflowWatch;
|
|
20
22
|
private attributeFlushScheduled;
|
|
21
23
|
private attributeObserver;
|
|
22
24
|
private readonly onWindowMessage;
|
|
@@ -30,6 +32,14 @@ declare class PublishedHostBridge {
|
|
|
30
32
|
*/
|
|
31
33
|
sendAbGoal(assignment: AbGoalAssignment): void;
|
|
32
34
|
private postAbGoal;
|
|
35
|
+
/**
|
|
36
|
+
* Tells the widget what the workflow it is part of needs it to report: the tables whose saved entries a trigger
|
|
37
|
+
* waits for, the columns a condition reads, and the actions a trigger waits for (`widgetic:workflow-watch`, host
|
|
38
|
+
* bridge contract, player version 6). Kept, and sent again on every host snapshot. An empty watch is a valid one: it
|
|
39
|
+
* tells the widget to stop reporting.
|
|
40
|
+
*/
|
|
41
|
+
sendWorkflowWatch(watch: WorkflowWatch): void;
|
|
42
|
+
private postWorkflowWatch;
|
|
33
43
|
sendWidgetUpdate(payload: {
|
|
34
44
|
design?: Record<string, string>;
|
|
35
45
|
content?: Record<string, unknown>;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where the code of a `<widgetic workflow-id>` tag comes from.
|
|
3
|
+
*
|
|
4
|
+
* It is not part of what every page downloads: a page without such a tag never asks for it. Here, in the code-split
|
|
5
|
+
* builds (ESM, which bundlers and `<script type="module">` use), it is a chunk of the same build, loaded with a dynamic
|
|
6
|
+
* import. The single-file (UMD) build, which is what the CDN serves to every embed, cannot split like that, so
|
|
7
|
+
* scripts-sdk/workflow-bundle.js swaps this module for workflow-code-loader.umd.ts there, which loads the code from a
|
|
8
|
+
* second file instead. Whichever one is built in, the caller gets the same thing: a promise of the part of the workflow
|
|
9
|
+
* module that the SDK starts a workflow with.
|
|
10
|
+
*/
|
|
11
|
+
/** The part of the workflow module that the SDK uses. */
|
|
12
|
+
export type WorkflowHostModule = Pick<typeof import("../workflows/workflow-host.js"), "startWorkflowEmbed">;
|
|
13
|
+
/** Loads the workflow code. A rejected promise means it is not there, and the tag is then embedded as a plain one. */
|
|
14
|
+
export declare function importWorkflowHostModule(): Promise<WorkflowHostModule>;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { WorkflowHostModule } from "./workflow-code-loader";
|
|
2
|
+
/** Where the code is when nothing says otherwise: the CDN folder the SDK's own file is served from. */
|
|
3
|
+
export declare const DEFAULT_WORKFLOW_CODE_URL = "https://cdn.widgetic.com/sdks/browser/embed-sdk-workflows.js";
|
|
4
|
+
/**
|
|
5
|
+
* An attribute of the SDK's own script tag, for a page that serves the SDK itself under another name or from another
|
|
6
|
+
* place: `<script src="/vendor/widgetic.js" data-workflows-src="/vendor/widgetic-workflows.js">`.
|
|
7
|
+
*/
|
|
8
|
+
export declare const WORKFLOW_CODE_SOURCE_ATTRIBUTE = "data-workflows-src";
|
|
9
|
+
/** How long the file gets to arrive and run. A slower one leaves the tag as a plain embed. */
|
|
10
|
+
export declare const WORKFLOW_CODE_TIMEOUT_MILLISECONDS = 20000;
|
|
11
|
+
/** After a failure, how long the next tag is refused at once instead of asking the network again. */
|
|
12
|
+
export declare const WORKFLOW_CODE_RETRY_AFTER_MILLISECONDS = 60000;
|
|
13
|
+
/** What is needed of the SDK's own script tag to find the file next to it. */
|
|
14
|
+
export interface SdkScriptFacts {
|
|
15
|
+
/** The address of the script, as the browser resolved it. */
|
|
16
|
+
source: string;
|
|
17
|
+
/** What the script's `data-workflows-src` says, if anything. */
|
|
18
|
+
explicitSource: string | null;
|
|
19
|
+
/** The script's CSP nonce, handed on to the script that is added so that a nonce-based policy lets it run. */
|
|
20
|
+
nonce: string | null;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Says where the workflow code is: what the SDK's script tag names, or else the file next to the SDK's own (same
|
|
24
|
+
* folder, same query string, so that a page's cache-buster applies to both), or else the CDN's default.
|
|
25
|
+
*/
|
|
26
|
+
export declare function resolveWorkflowCodeUrl(sdkScript: Pick<SdkScriptFacts, "source" | "explicitSource"> | null, documentBaseUrl: string): string;
|
|
27
|
+
/**
|
|
28
|
+
* Loads the workflow code, once for the page: every tag that needs it gets the same promise. After a failure the next
|
|
29
|
+
* tags are refused at once for a minute rather than each asking a network that has just failed, and then it is tried
|
|
30
|
+
* again.
|
|
31
|
+
*/
|
|
32
|
+
export declare function importWorkflowHostModule(): Promise<WorkflowHostModule>;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which tags run a workflow, so that the page's own teardown of a tag (a reload, a removal) stops the workflow with it.
|
|
3
|
+
*
|
|
4
|
+
* The workflow code is loaded only for a page that has a `workflow-id` tag (see `src/workflows/`). This small file is
|
|
5
|
+
* what the rest of the SDK knows about it, and it is all a page without workflows ever loads.
|
|
6
|
+
*/
|
|
7
|
+
export interface WorkflowEmbedHandle {
|
|
8
|
+
/** Ends the workflow of the tag: timers, listeners and the stages it built. Must be safe to call twice. */
|
|
9
|
+
stop: () => void;
|
|
10
|
+
}
|
|
11
|
+
/** Remembers the workflow a tag runs. A workflow already running on the tag is stopped first. */
|
|
12
|
+
export declare function registerWorkflowEmbed(host: HTMLElement, handle: WorkflowEmbedHandle): void;
|
|
13
|
+
export declare function hasRegisteredWorkflowEmbed(host: HTMLElement): boolean;
|
|
14
|
+
/** Stops the workflow of a tag, if it runs one. Returns whether there was one. */
|
|
15
|
+
export declare function stopRegisteredWorkflowEmbed(host: HTMLElement): boolean;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a page can tell a workflow: `sendWorkflowEvent(host, name, values)`, or the DOM event it is made of.
|
|
3
|
+
*
|
|
4
|
+
* Lives outside `src/workflows/` on purpose: that folder is the part of the SDK that is only loaded for a page that
|
|
5
|
+
* has a `workflow-id` tag, and `sendWorkflowEvent` is exported for every page. So this file is small and depends on
|
|
6
|
+
* nothing; it keeps its own copy of the engine's limits, and a test pins that they are the same.
|
|
7
|
+
*
|
|
8
|
+
* A page is not trusted. A name or a value that does not fit is dropped here, before the workflow sees it, and what
|
|
9
|
+
* remains is only ever read by a published condition and then forgotten.
|
|
10
|
+
*/
|
|
11
|
+
/** The DOM event a page dispatches on the `<widgetic>` tag to tell its workflow something. */
|
|
12
|
+
export declare const WORKFLOW_EVENT_TYPE = "widgetic:workflow-event";
|
|
13
|
+
/** The DOM event the tag dispatches when a visitor moves to the next composition (`{ workflowId, from, to }`). */
|
|
14
|
+
export declare const WORKFLOW_STEP_EVENT_TYPE = "widgetic:workflow-step";
|
|
15
|
+
/** What a name of an event or of one of its values may look like. The engine's `EVENT_NAME_PATTERN`. */
|
|
16
|
+
export declare const PAGE_EVENT_NAME_PATTERN: RegExp;
|
|
17
|
+
/** How many events a page may send before the workflow is ready; the oldest are dropped past this. */
|
|
18
|
+
export declare const MAX_QUEUED_PAGE_EVENTS = 20;
|
|
19
|
+
export type PageEventValue = string | number | boolean;
|
|
20
|
+
export interface PageEvent {
|
|
21
|
+
name: string;
|
|
22
|
+
values: Record<string, PageEventValue>;
|
|
23
|
+
}
|
|
24
|
+
/** Reads what a page sent: a name that fits, and the values that fit. Null when there is no usable name. */
|
|
25
|
+
export declare function readPageEvent(detail: unknown): PageEvent | null;
|
|
26
|
+
/**
|
|
27
|
+
* Tells the workflow of a `<widgetic workflow-id>` tag that something happened on the page (an Event from your page
|
|
28
|
+
* trigger waits for it by name). Returns false, and does nothing, when the name does not fit.
|
|
29
|
+
*/
|
|
30
|
+
export declare function sendWorkflowEvent(host: HTMLElement, name: string, values?: Record<string, unknown>): boolean;
|
|
31
|
+
/**
|
|
32
|
+
* Events a page sends before its workflow is ready (the graph is still being read, or the next composition is still
|
|
33
|
+
* being shown). They are kept, up to a limit, and handed over in order once the workflow can use them.
|
|
34
|
+
*/
|
|
35
|
+
export declare class PageEventQueue {
|
|
36
|
+
private events;
|
|
37
|
+
add(event: PageEvent): void;
|
|
38
|
+
/** What was kept, oldest first; the queue is empty afterwards. */
|
|
39
|
+
take(): PageEvent[];
|
|
40
|
+
clear(): void;
|
|
41
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the two files of the single-file (UMD) build agree on: the SDK itself (`embed-sdk.js`, which every page that
|
|
3
|
+
* embeds a widget loads) and the code of a `<widgetic workflow-id>` tag (`embed-sdk-workflows.js`, which only a page
|
|
4
|
+
* with such a tag loads, and which the SDK asks for when it meets one).
|
|
5
|
+
*
|
|
6
|
+
* The code-split builds (ESM, for bundlers) need none of this: there the workflow code is a chunk of the same build and
|
|
7
|
+
* shares the SDK's modules the way every chunk does.
|
|
8
|
+
*
|
|
9
|
+
* The two files are built together and published together, but a visitor's browser can hold one of them from an
|
|
10
|
+
* earlier release for a while. So the pair checks that it is talking to its own kind:
|
|
11
|
+
*
|
|
12
|
+
* 1. The SDK puts the services the workflow code needs under WORKFLOW_SHARED_SERVICES_GLOBAL (see
|
|
13
|
+
* workflow-shared-services.ts) and adds the script of the workflow code to the page.
|
|
14
|
+
* 2. The workflow code (src/workflows/umd-entry.ts) leaves what it offers under WORKFLOW_EXPORTS_GLOBAL, together
|
|
15
|
+
* with the version of this contract it was built against.
|
|
16
|
+
* 3. The SDK takes it only if that version is its own. Otherwise the tag is embedded as a plain one, which is what
|
|
17
|
+
* happens when the code cannot be loaded at all.
|
|
18
|
+
*
|
|
19
|
+
* Both globals are there for the moment of the hand-over and removed straight after it.
|
|
20
|
+
*
|
|
21
|
+
* Raise WORKFLOW_SHARED_CONTRACT_VERSION whenever the shape of the services or of the exports changes.
|
|
22
|
+
*
|
|
23
|
+
* This file is the one module that both files contain a copy of (scripts-sdk/workflow-bundle.js lets it into the
|
|
24
|
+
* workflow code and tests/unit/scripts/umd-layout.test.ts holds the line on everything else), and it must stay free of
|
|
25
|
+
* state for that reason.
|
|
26
|
+
*/
|
|
27
|
+
/** The version of the hand-over described above. */
|
|
28
|
+
export declare const WORKFLOW_SHARED_CONTRACT_VERSION = 1;
|
|
29
|
+
/**
|
|
30
|
+
* Where the SDK leaves the services for the workflow code. scripts-sdk/workflow-shared-modules.js has the same name
|
|
31
|
+
* (the build reads the global from there), and the test next to the layout test holds the two together.
|
|
32
|
+
*/
|
|
33
|
+
export declare const WORKFLOW_SHARED_SERVICES_GLOBAL = "__widgeticEmbedSharedServices";
|
|
34
|
+
/** Where the workflow code leaves what it offers to the SDK. */
|
|
35
|
+
export declare const WORKFLOW_EXPORTS_GLOBAL = "__widgeticEmbedWorkflows";
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { elementMatchesGoalTarget, readStoredValue, removeStoredValue, writeStoredValue } from "../abTesting/abVisitor";
|
|
2
|
+
import { readStoredAutoscaleHeight, writeStoredAutoscaleHeight } from "../core/autoscale-manager";
|
|
3
|
+
import { declarativeChildrenOf, isReservedHostAttribute } from "./declarative-embed-parser";
|
|
4
|
+
import { buildWorkflowWatch, splitActionId, workflowWatchProperty } from "./host-workflow-watch";
|
|
5
|
+
import { setDirectMountWorkflow, warmDirectModule } from "./mount-direct-widget";
|
|
6
|
+
import { publicEmbedApiOrigins, resolvePublishedEmbed } from "./public-embed-lookup";
|
|
7
|
+
import { dispatchPublishedHostError, getPublishedHostBridge } from "./published-host-bridge";
|
|
8
|
+
import { registerWorkflowEmbed } from "./workflow-embed-registry";
|
|
9
|
+
import { PageEventQueue, readPageEvent } from "./workflow-page-events";
|
|
10
|
+
/**
|
|
11
|
+
* What the code of a `<widgetic workflow-id>` tag takes from the SDK, in the single-file (UMD) build, where that code
|
|
12
|
+
* is a file of its own (see workflow-shared-contract.ts for the hand-over).
|
|
13
|
+
*
|
|
14
|
+
* The workflow code is built without these modules and reads them from the object below instead, so that there is one
|
|
15
|
+
* of each on the page: the registry of embeds, the bridge to the published hosts, the visitor's stored values and the
|
|
16
|
+
* rest keep their state in these modules, and a second copy of any of them in the workflow code would have a state of
|
|
17
|
+
* its own that the SDK never sees.
|
|
18
|
+
*
|
|
19
|
+
* One entry for each module that src/workflows/ imports (the list is in scripts-sdk/workflow-shared-modules.js, which
|
|
20
|
+
* the build uses to leave them out of the workflow code), and in each entry the names that src/workflows/ takes from
|
|
21
|
+
* it. They are named one by one, not handed over as whole modules, so that the SDK keeps tree-shaking what the
|
|
22
|
+
* workflows do not use. tests/unit/utils/workflow-shared-services.test.ts reads the imports of src/workflows/ and fails
|
|
23
|
+
* the moment one is missing here.
|
|
24
|
+
*/
|
|
25
|
+
export declare function createWorkflowSharedServices(): {
|
|
26
|
+
contractVersion: number;
|
|
27
|
+
abVisitor: {
|
|
28
|
+
elementMatchesGoalTarget: typeof elementMatchesGoalTarget;
|
|
29
|
+
readStoredValue: typeof readStoredValue;
|
|
30
|
+
removeStoredValue: typeof removeStoredValue;
|
|
31
|
+
writeStoredValue: typeof writeStoredValue;
|
|
32
|
+
};
|
|
33
|
+
autoscaleManager: {
|
|
34
|
+
readStoredAutoscaleHeight: typeof readStoredAutoscaleHeight;
|
|
35
|
+
writeStoredAutoscaleHeight: typeof writeStoredAutoscaleHeight;
|
|
36
|
+
};
|
|
37
|
+
declarativeEmbedParser: {
|
|
38
|
+
declarativeChildrenOf: typeof declarativeChildrenOf;
|
|
39
|
+
isReservedHostAttribute: typeof isReservedHostAttribute;
|
|
40
|
+
};
|
|
41
|
+
hostBridgeMarkers: {
|
|
42
|
+
REFUSED_HOST_ATTRIBUTE: string;
|
|
43
|
+
};
|
|
44
|
+
hostWorkflowWatch: {
|
|
45
|
+
buildWorkflowWatch: typeof buildWorkflowWatch;
|
|
46
|
+
splitActionId: typeof splitActionId;
|
|
47
|
+
workflowWatchProperty: typeof workflowWatchProperty;
|
|
48
|
+
};
|
|
49
|
+
logger: {
|
|
50
|
+
log: {
|
|
51
|
+
debug: (message: string, ...args: any[]) => void;
|
|
52
|
+
info: (message: string, ...args: any[]) => void;
|
|
53
|
+
warn: (message: string, ...args: any[]) => void;
|
|
54
|
+
error: (message: string, ...args: any[]) => void;
|
|
55
|
+
setLevel: (level: "info" | "debug" | "warn" | "error") => void;
|
|
56
|
+
};
|
|
57
|
+
};
|
|
58
|
+
mountDirectWidget: {
|
|
59
|
+
setDirectMountWorkflow: typeof setDirectMountWorkflow;
|
|
60
|
+
warmDirectModule: typeof warmDirectModule;
|
|
61
|
+
};
|
|
62
|
+
publicEmbedLookup: {
|
|
63
|
+
publicEmbedApiOrigins: typeof publicEmbedApiOrigins;
|
|
64
|
+
resolvePublishedEmbed: typeof resolvePublishedEmbed;
|
|
65
|
+
};
|
|
66
|
+
publishedHostBridge: {
|
|
67
|
+
dispatchPublishedHostError: typeof dispatchPublishedHostError;
|
|
68
|
+
getPublishedHostBridge: typeof getPublishedHostBridge;
|
|
69
|
+
};
|
|
70
|
+
publishedHostDisplay: {
|
|
71
|
+
OVERLAY_HOST_ATTRIBUTE: string;
|
|
72
|
+
};
|
|
73
|
+
workflowEmbedRegistry: {
|
|
74
|
+
registerWorkflowEmbed: typeof registerWorkflowEmbed;
|
|
75
|
+
};
|
|
76
|
+
workflowPageEvents: {
|
|
77
|
+
PageEventQueue: typeof PageEventQueue;
|
|
78
|
+
readPageEvent: typeof readPageEvent;
|
|
79
|
+
WORKFLOW_EVENT_TYPE: string;
|
|
80
|
+
WORKFLOW_STEP_EVENT_TYPE: string;
|
|
81
|
+
};
|
|
82
|
+
};
|
|
83
|
+
/** The services as the workflow code finds them. */
|
|
84
|
+
export type WorkflowSharedServices = ReturnType<typeof createWorkflowSharedServices>;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where a visitor is in a workflow, kept in the visitor's own browser (localStorage, or memory for a page whose
|
|
3
|
+
* browser refuses storage).
|
|
4
|
+
*
|
|
5
|
+
* Only ids and times are kept: the block and composition the visitor is on, the version of the workflow they started
|
|
6
|
+
* on, when they started and when they reached the block. Never a value a visitor typed, never who they are.
|
|
7
|
+
*
|
|
8
|
+
* The version is what lets a visitor finish on the workflow they started on when a newer one is published in the
|
|
9
|
+
* meantime. After 30 days that no longer holds: the position is forgotten and the visitor is treated as a new one.
|
|
10
|
+
*/
|
|
11
|
+
/** How long a visitor finishes on the version they started on. */
|
|
12
|
+
export declare const POSITION_MAX_AGE_MILLISECONDS: number;
|
|
13
|
+
export interface StoredPosition {
|
|
14
|
+
/** The published version the visitor started on (and finishes on). */
|
|
15
|
+
versionId: string;
|
|
16
|
+
/** The composition block the visitor is on. */
|
|
17
|
+
nodeId: string;
|
|
18
|
+
/** The composition that block shows, so the first paint of a returning visitor needs no graph. */
|
|
19
|
+
compositionId: string;
|
|
20
|
+
/** When the visitor started on this version (milliseconds since the epoch). */
|
|
21
|
+
startedAt: number;
|
|
22
|
+
/** When the visitor reached this block, which is what a wait in a Scheduled trigger counts from. */
|
|
23
|
+
reachedAt: number;
|
|
24
|
+
}
|
|
25
|
+
/** The key one workflow's position is kept under. */
|
|
26
|
+
export declare function positionStorageKey(workflowId: string): string;
|
|
27
|
+
/** Reads what a visitor's browser kept for a workflow; null for none, for one that ran out, and for anything unreadable. */
|
|
28
|
+
export declare function readStoredPosition(workflowId: string, nowMilliseconds?: number): StoredPosition | null;
|
|
29
|
+
/** Keeps where a visitor is. A browser that refuses storage still remembers it for as long as the page lives. */
|
|
30
|
+
export declare function writeStoredPosition(workflowId: string, position: StoredPosition): void;
|
|
31
|
+
/** Forgets where a visitor is (they start again as a new visitor). */
|
|
32
|
+
export declare function clearStoredPosition(workflowId: string): void;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The rules of the autoscale a workflow embed always has.
|
|
3
|
+
*
|
|
4
|
+
* A workflow swaps one composition for the next in the same place, and the next one is usually a different height.
|
|
5
|
+
* So the embed follows the height of what is shown, whatever `autoscale` or a fixed height on the tag says. The
|
|
6
|
+
* numbers are the ones the other embeds' autoscale reads (`autoscale-min-height`, `-max-height`, `-debounce`,
|
|
7
|
+
* `-threshold`, `-animate`, `-animation-duration`) and have the same defaults.
|
|
8
|
+
*
|
|
9
|
+
* Only decisions live here (which numbers, what a height is held to, whether a change is worth following). Putting a
|
|
10
|
+
* height on the page is the viewport's job (workflow-stage.ts).
|
|
11
|
+
*/
|
|
12
|
+
export interface AutoscaleSettings {
|
|
13
|
+
/** The smallest the embed gets, in pixels. */
|
|
14
|
+
minHeight: number;
|
|
15
|
+
/** The largest the embed gets, in pixels. */
|
|
16
|
+
maxHeight: number;
|
|
17
|
+
/** How long a height has to hold still before the embed follows it, in milliseconds. */
|
|
18
|
+
debounceDelay: number;
|
|
19
|
+
/** The smallest change in height worth following, in pixels. */
|
|
20
|
+
threshold: number;
|
|
21
|
+
/** Whether a change in height is animated. */
|
|
22
|
+
animate: boolean;
|
|
23
|
+
/** How long the animation lasts, in milliseconds. */
|
|
24
|
+
animationDuration: number;
|
|
25
|
+
}
|
|
26
|
+
export declare const AUTOSCALE_DEFAULTS: Readonly<AutoscaleSettings>;
|
|
27
|
+
/**
|
|
28
|
+
* The autoscale settings of a workflow embed, read from its tag. `autoscale="false"` and a fixed height are not
|
|
29
|
+
* read: a workflow embed follows the content.
|
|
30
|
+
*/
|
|
31
|
+
export declare function readAutoscaleSettings(host: Element, options?: {
|
|
32
|
+
prefersReducedMotion?: boolean;
|
|
33
|
+
}): AutoscaleSettings;
|
|
34
|
+
/**
|
|
35
|
+
* A height held between the embed's minimum and maximum, and rounded up to a whole pixel (a half pixel less would cut
|
|
36
|
+
* the last line). `capHeight` is a limit that sits on top of the embed's own, such as the largest height an overlay
|
|
37
|
+
* has on the visitor's screen; when it is smaller than the minimum, the cap decides.
|
|
38
|
+
*/
|
|
39
|
+
export declare function clampHeight(rawHeight: number, settings: Pick<AutoscaleSettings, "minHeight" | "maxHeight">, capHeight?: number | null): number;
|
|
40
|
+
/** Is a new height different enough from the one shown to be worth following? The first height always is. */
|
|
41
|
+
export declare function shouldApplyHeight(currentHeight: number | null, nextHeight: number, threshold: number): boolean;
|