@widgetic/embed-sdk 2.0.14 → 2.0.17

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.
Files changed (41) hide show
  1. package/README.md +31 -9
  2. package/dist/browser/chunks/ABTestManager.js +1 -1
  3. package/dist/browser/chunks/advanced.js +1 -1
  4. package/dist/browser/chunks/api.js +1 -1
  5. package/dist/browser/chunks/core.js +1 -1
  6. package/dist/browser/chunks/display.js +1 -1
  7. package/dist/browser/chunks/media.js +1 -1
  8. package/dist/browser/chunks/messaging.js +1 -1
  9. package/dist/browser/chunks/renderers.js +1 -1
  10. package/dist/browser/chunks/scanner.js +1 -1
  11. package/dist/browser/chunks/security.js +1 -1
  12. package/dist/browser/embed-bootstrap.js +1 -1
  13. package/dist/browser/embed-sdk.js +1 -1
  14. package/dist/esm/chunks/ABTestManager.js +1 -1
  15. package/dist/esm/chunks/advanced.js +1 -1
  16. package/dist/esm/chunks/api.js +1 -1
  17. package/dist/esm/chunks/core.js +1 -1
  18. package/dist/esm/chunks/display.js +1 -1
  19. package/dist/esm/chunks/media.js +1 -1
  20. package/dist/esm/chunks/messaging.js +1 -1
  21. package/dist/esm/chunks/renderers.js +1 -1
  22. package/dist/esm/chunks/scanner.js +1 -1
  23. package/dist/esm/chunks/security.js +1 -1
  24. package/dist/esm/embed-bootstrap.js +1 -1
  25. package/dist/esm/embed-sdk.js +1 -1
  26. package/dist/esm/types/abTesting/ABTestElement.d.ts +10 -0
  27. package/dist/esm/types/abTesting/ABTestManager.d.ts +54 -12
  28. package/dist/esm/types/abTesting/abVisitor.d.ts +31 -0
  29. package/dist/esm/types/core/advanced-security-manager.d.ts +3 -0
  30. package/dist/esm/types/core/widget-manager.d.ts +8 -43
  31. package/dist/esm/types/utils/declarative-embed-parser.d.ts +14 -0
  32. package/dist/esm/types/utils/hydrate-published-host.d.ts +7 -4
  33. package/dist/esm/types/utils/image-delivery.d.ts +54 -0
  34. package/dist/esm/types/utils/lookup-cache.d.ts +34 -0
  35. package/dist/esm/types/utils/preload-content-images.d.ts +21 -0
  36. package/dist/esm/types/utils/public-embed-lookup.d.ts +3 -0
  37. package/dist/esm/types/utils/published-host-bridge.d.ts +16 -0
  38. package/dist/umd/embed-bootstrap.js +1 -1
  39. package/dist/umd/embed-sdk.js +1 -1
  40. package/package.json +1 -1
  41. 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 with real-time capabilities
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 with real-time support
68
+ * Widget Manager - Core orchestrator for widget lifecycle
74
69
  *
75
- * Note: Real-time updates are based on Compositions, not individual widgets.
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 updates when that composition is modified.
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 with real-time support
103
+ * Register a widget instance
110
104
  */
111
105
  registerWidget(widgetId: string, config: WidgetConfig, element: HTMLElement): Promise<RenderedWidget>;
112
106
  /**
113
- * Set up real-time updates for a widget's composition
107
+ * Remember that a widget renders a composition
114
108
  */
115
- private setupRealtimeUpdates;
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;
@@ -57,7 +57,21 @@ export declare function installHostPropertyBridge(host: HTMLElement): void;
57
57
  * Returns the identifier used for state tracking (`composition-id` or `widget` / `widget-id`).
58
58
  */
59
59
  export declare function getHostInstanceId(host: HTMLElement): string | null;
60
+ export declare function isDeclarativeJsonScript(element: Element): boolean;
60
61
  export declare function isReservedHostAttribute(attrName: string): boolean;
62
+ /**
63
+ * Parses `<script type="application/json">` (or `application/ld+json`, `application/widgetic+json`,
64
+ * `data-widgetic-json`, `data-widgetic-config`) child blocks inside `<widgetic>`.
65
+ *
66
+ * Supports both:
67
+ * 1. Clean runtime structure: `{ design: {...}, content: {...}, contentItems: [...] }`
68
+ * 2. Raw `src/lib/meta/design.json` (`componentGroups`) and `src/lib/meta/content.json` (`genericContent`, `contentItems[*].properties`) schemas.
69
+ */
70
+ export declare function parseDeclarativeJsonScripts(host: HTMLElement, baseOverlay?: PublicEmbedOverlay | null): {
71
+ design: Record<string, string>;
72
+ content: Record<string, unknown>;
73
+ contentItems: DeclarativeContentItem[];
74
+ };
61
75
  /**
62
76
  * Parses declarative child elements (`<img>`, `<item>`, `<audio>`, `<div>`, etc.) inside `<widgetic>`
63
77
  * into `contentItems`, hiding the raw declarative DOM nodes so they don't render visually alongside
@@ -11,18 +11,21 @@ import { REFUSED_HOST_ATTRIBUTE } from "./host-bridge-markers.js";
11
11
  export { REFUSED_HOST_ATTRIBUTE };
12
12
  export declare function hydratePublishedHost(host: HTMLElement): boolean;
13
13
  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
14
  /**
17
15
  * Reloads a published widget host in place while maintaining playback timestamp and selected item state.
16
+ *
17
+ * Nothing in the SDK calls this on its own. The SDK opens no socket and does no polling: a page (or a future
18
+ * channel from the gateway) that wants a reload calls it.
18
19
  */
19
20
  export declare function reloadPublishedHost(host: HTMLElement): Promise<boolean>;
20
21
  /**
21
- * Applies real-time content updates to a running widget without refreshing or reloading the iframe.
22
+ * Applies live content updates to a running widget without refreshing or reloading the iframe.
23
+ * Called by the page; the SDK does not push updates by itself.
22
24
  */
23
25
  export declare function applyLiveContentUpdate(host: HTMLElement, data: unknown): void;
24
26
  /**
25
- * Applies real-time style/design updates to a running widget without refreshing or reloading the iframe.
27
+ * Applies live style/design updates to a running widget without refreshing or reloading the iframe.
28
+ * Called by the page; the SDK does not push updates by itself.
26
29
  */
27
30
  export declare function applyLiveStyleUpdate(host: HTMLElement, styles: unknown): void;
28
31
  /** Clears the bridge when a host is removed from the page. */
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Right-sized delivery of an embed's content images.
3
+ *
4
+ * The lookup answer holds the content of a composition, and with it the URLs of the images the widget will show.
5
+ * Before the widget sees them, an image on Widgetic's own content host is pointed at Cloudflare Image
6
+ * Transformations (`/cdn-cgi/image/<options>/<source>`), which answers with a copy sized for the screen, in AVIF
7
+ * or WebP where the browser takes it, instead of the original (often several megapixels for a small widget).
8
+ *
9
+ * Bounded on purpose, because every unique transformation is billed:
10
+ * - three widths only (`IMAGE_WIDTH_LADDER`), chosen from the page's viewport, never from the image;
11
+ * - Widgetic's own hosts only (`IMAGE_DELIVERY_HOSTS`): a partner's bucket or a third-party image is never touched;
12
+ * - png, jpeg, webp and avif only: SVG is already small and a GIF may be animated;
13
+ * - `fit=scale-down`: a small original is never enlarged.
14
+ *
15
+ * Three independent switches, any of which serves the originals:
16
+ * - the owner's account setting, carried by the lookup answer (`media.optimize`; absent means off);
17
+ * - `window.WIDGETIC_IMAGE_OPTIMIZE = false`;
18
+ * - `data-image-optimize="off"` on the SDK's script tag.
19
+ */
20
+ /** The widths a copy can have. Few, so a visitor of any screen lands on one of a handful of cached variants. */
21
+ export declare const IMAGE_WIDTH_LADDER: readonly number[];
22
+ /** The hosts whose images Widgetic's Cloudflare zone may be asked to transform. */
23
+ export declare const IMAGE_DELIVERY_HOSTS: readonly string[];
24
+ /** What the lookup answer says about the owner's choice, as the SDK reads it. */
25
+ export type PublicEmbedMedia = {
26
+ optimize: boolean;
27
+ };
28
+ /**
29
+ * Whether this page may have its images rewritten: the owner opted in (the answer says so) and nothing on the page
30
+ * switched it off. An answer without `media` comes from a gateway that does not know the setting: originals.
31
+ */
32
+ export declare function imageDeliveryEnabled(media: PublicEmbedMedia | undefined): boolean;
33
+ /** The smallest width of the ladder that covers `neededPixels`; the largest when none does. */
34
+ export declare function widthFromLadder(neededPixels: number): number;
35
+ /**
36
+ * The width to ask for on this page: the viewport, in device pixels (capped at 2x). An embed is never wider than
37
+ * the page that holds it, so this is a safe ceiling that needs no knowledge of the image or of the widget.
38
+ */
39
+ export declare function viewportImageWidth(): number;
40
+ /** The transformed address of one image URL, or the URL itself when it is not one to transform. */
41
+ export declare function transformedImageUrl(url: string, width: number): string;
42
+ /**
43
+ * A copy of `value` with every transformable image URL rewritten. Strings, arrays and plain objects only, to a
44
+ * bounded depth and size; anything else is returned as it came.
45
+ */
46
+ export declare function rewriteImageUrls<T>(value: T, width: number): T;
47
+ /**
48
+ * The content and items of a lookup answer, with their images delivered right-sized when the owner and the page
49
+ * both allow it. Never throws: a failure here serves the originals.
50
+ */
51
+ export declare function deliverContentImages<C, I>(media: PublicEmbedMedia | undefined, content: C, contentItems: I): {
52
+ content: C;
53
+ contentItems: I;
54
+ };
@@ -0,0 +1,34 @@
1
+ /**
2
+ * A small persistent copy of the public embed lookup (`GET /embed/compositions/:id`), so a repeat view of a
3
+ * page paints from a local copy instead of waiting for the network, and refreshes it in the background
4
+ * (stale-while-revalidate).
5
+ *
6
+ * What it keeps, and what it never does:
7
+ * - Only a successful answer. A refusal (403 DOMAIN_NOT_ALLOWED), a failure (404, 410, 429...) and a payload the
8
+ * SDK could not read are never stored, so an embed whose owner just limited it to listed websites is refused
9
+ * on the next view, never "remembered" as served.
10
+ * - A copy is used for at most `LOOKUP_CACHE_MAX_AGE_MS` (30 s): the platform's promise is that an edit is
11
+ * visible within a few seconds, and this is the SDK's share of it. The gateway answers `private, max-age=5`
12
+ * and the browser's own HTTP cache does the `ETag` revalidation, so the SDK does not send `If-None-Match`
13
+ * itself (a cross-origin request with that header needs a preflight the lookup does not otherwise pay).
14
+ * - The signed entry write token is part of the copy; its 24 h lifetime is far beyond the copy's 30 s.
15
+ * - IndexedDB, not `localStorage`: a payload carries the whole content and its items. Where IndexedDB is not
16
+ * there (private modes, tests, an old browser), every function is a no-op and the lookup works as before.
17
+ *
18
+ * Off switch for a page: `window.WIDGETIC_EMBED_LOOKUP_CACHE = false`, or `data-lookup-cache="off"` on the SDK script.
19
+ */
20
+ export declare const LOOKUP_CACHE_MAX_AGE_MS = 30000;
21
+ export type CachedLookup = {
22
+ json: Record<string, unknown>;
23
+ storedAtMs: number;
24
+ };
25
+ /** Whether this page may use the cache: IndexedDB is there and nothing switched it off. */
26
+ export declare function lookupCacheEnabled(): boolean;
27
+ /** The stored copy of one lookup address, or null. Never throws. */
28
+ export declare function readLookupCache(url: string): Promise<CachedLookup | null>;
29
+ /** Stores the answer of one lookup address. Never throws, never waits for the disk. */
30
+ export declare function writeLookupCache(url: string, json: Record<string, unknown>): Promise<void>;
31
+ /** Whether a stored copy may still paint a page. */
32
+ export declare function lookupCacheIsFresh(entry: CachedLookup, nowMs?: number): boolean;
33
+ /** For tests: forgets the open database handle so the next call opens it again. */
34
+ export declare function resetLookupCacheForTests(): void;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Starts downloading the first images of an embed's content while its widget is still loading.
3
+ *
4
+ * The lookup answer already holds the content (and its items), so the first image URLs are known before
5
+ * `widget.html` has been fetched. A `<link rel="preload" as="image">` lets the browser fetch them in parallel
6
+ * with the widget, and the widget's own `<img>` later finds them in the HTTP cache.
7
+ *
8
+ * Deliberately small: at most `MAX_PRELOADED_IMAGES` per embed, https only, only a URL that ends in an image
9
+ * extension, once per URL per page. A guess that is wrong costs one image; a wide net would cost a page its
10
+ * bandwidth.
11
+ */
12
+ export declare const MAX_PRELOADED_IMAGES = 2;
13
+ /** The first image URLs of a content object and its items, in document order, without repeats. */
14
+ export declare function firstContentImageUrls(content: unknown, contentItems: unknown, limit?: number): string[];
15
+ /**
16
+ * Adds the preload hints. `mapUrl` lets the caller preload the address the widget will actually request
17
+ * (a resized copy, say), so the hint and the request are the same resource.
18
+ */
19
+ export declare function preloadFirstContentImages(content: unknown, contentItems: unknown, mapUrl?: (url: string) => string): void;
20
+ /** For tests. */
21
+ export declare function resetPreloadedImagesForTests(): void;
@@ -18,6 +18,7 @@
18
18
  * said no.
19
19
  */
20
20
  import { type GatewayRefusalCode } from "./embed-gateway-codes.js";
21
+ import { type PublicEmbedMedia } from "./image-delivery.js";
21
22
  /** The code the gateway puts on the 403 it sends to a website the embed's owner did not list. */
22
23
  export declare const EMBED_DOMAIN_REFUSAL_CODE = "DOMAIN_NOT_ALLOWED";
23
24
  /**
@@ -45,6 +46,8 @@ export type PublicEmbedPayload = PublicEmbedOverlay & {
45
46
  url: string;
46
47
  writeToken?: string;
47
48
  };
49
+ /** The owner's choice for image delivery, from the lookup answer (see `image-delivery.ts`). */
50
+ media?: PublicEmbedMedia;
48
51
  };
49
52
  /** The gateway's refusal: the owner limited this embed to listed websites and this page is not listed. */
50
53
  export type PublishedEmbedRefusal = {
@@ -1,12 +1,22 @@
1
1
  /**
2
2
  * Relays `widgetic:host` into the gateway frame and wrapper events back to the page.
3
3
  */
4
+ /** What the page tells a widget about the A/B test it is part of. */
5
+ export interface AbGoalAssignment {
6
+ /** The goal the test measures (a metric id such as `clicks`). */
7
+ metric: string;
8
+ /** The element inside the widget that counts (a CSS selector), or null for any use of the goal. */
9
+ goalTarget: string | null;
10
+ }
11
+ /** The capability a widget lists in `widgetic:ready` when it reports which element of a goal was used. */
12
+ export declare const GOAL_REPORTER_CAPABILITY = "goal-reporter";
4
13
  declare class PublishedHostBridge {
5
14
  private readonly host;
6
15
  private readonly iframe;
7
16
  private readonly gatewayOrigin;
8
17
  private readonly compositionId;
9
18
  private readyDispatched;
19
+ private latestAbGoal;
10
20
  private attributeFlushScheduled;
11
21
  private attributeObserver;
12
22
  private readonly onWindowMessage;
@@ -14,6 +24,12 @@ declare class PublishedHostBridge {
14
24
  private observeHostAttributes;
15
25
  private scheduleHostSnapshot;
16
26
  postHostSnapshot(): void;
27
+ /**
28
+ * Tells the widget which goal its A/B test measures and, when the version names one, the element that counts
29
+ * (`widgetic:ab-goal`, host bridge contract, player version 5). Kept, and sent again on every host snapshot.
30
+ */
31
+ sendAbGoal(assignment: AbGoalAssignment): void;
32
+ private postAbGoal;
17
33
  sendWidgetUpdate(payload: {
18
34
  design?: Record<string, string>;
19
35
  content?: Record<string, unknown>;