@widgetic/embed-sdk 2.0.7 โ†’ 2.0.9

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 (38) hide show
  1. package/README.md +104 -498
  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/performance.js +1 -1
  10. package/dist/browser/chunks/renderers.js +1 -1
  11. package/dist/browser/chunks/scanner.js +1 -1
  12. package/dist/browser/chunks/security.js +1 -1
  13. package/dist/browser/embed-bootstrap.js +1 -1
  14. package/dist/browser/embed-sdk.js +1 -1
  15. package/dist/esm/chunks/ABTestManager.js +1 -1
  16. package/dist/esm/chunks/advanced.js +1 -1
  17. package/dist/esm/chunks/api.js +1 -1
  18. package/dist/esm/chunks/core.js +1 -1
  19. package/dist/esm/chunks/display.js +1 -1
  20. package/dist/esm/chunks/media.js +1 -1
  21. package/dist/esm/chunks/messaging.js +1 -1
  22. package/dist/esm/chunks/performance.js +1 -1
  23. package/dist/esm/chunks/renderers.js +1 -1
  24. package/dist/esm/chunks/scanner.js +1 -1
  25. package/dist/esm/chunks/security.js +1 -1
  26. package/dist/esm/embed-bootstrap.js +1 -1
  27. package/dist/esm/embed-sdk.js +1 -1
  28. package/dist/esm/types/utils/embed-gateway-codes.d.ts +9 -0
  29. package/dist/esm/types/utils/embed-telemetry.d.ts +13 -0
  30. package/dist/esm/types/utils/host-bridge-markers.d.ts +20 -0
  31. package/dist/esm/types/utils/host-bridge-snapshot.d.ts +18 -0
  32. package/dist/esm/types/utils/host-bridge-validation.d.ts +19 -0
  33. package/dist/esm/types/utils/hydrate-published-host.d.ts +4 -7
  34. package/dist/esm/types/utils/public-embed-lookup.d.ts +16 -6
  35. package/dist/esm/types/utils/published-host-bridge.d.ts +8 -0
  36. package/dist/umd/embed-bootstrap.js +1 -1
  37. package/dist/umd/embed-sdk.js +1 -1
  38. package/package.json +3 -3
package/README.md CHANGED
@@ -1,568 +1,174 @@
1
- # Widgetic Embed SDK v1.0
1
+ # @widgetic/embed-sdk
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@widgetic/embed-sdk.svg)](https://www.npmjs.com/package/@widgetic/embed-sdk)
4
- [![Build Status](https://img.shields.io/github/workflow/status/widgetic/embed-sdk/CI)](https://github.com/widgetic/embed-sdk/actions)
5
4
  [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
6
5
 
7
- Framework-agnostic JavaScript SDK for embedding Widgetic widgets with support for custom elements, iframes, and batch API integration. Works with any framework or vanilla JavaScript.
8
-
9
- ## Features
10
-
11
- ### ๐Ÿš€ **Phase 1: Foundation & Core Architecture**
12
-
13
- - **Auto-initialization** on page load with intelligent DOM scanning
14
- - **Multiple render modes**: Custom Elements, iframes, with automatic fallback
15
- - **Browser compatibility** detection and graceful degradation
16
- - **Instance management** with singleton pattern and global coordination
17
- - **Comprehensive error handling** and recovery mechanisms
18
-
19
- ### ๐Ÿ”ฅ **Phase 2: Advanced API Integration**
20
-
21
- - **Batch API system** with intelligent request deduplication and caching
22
- - **Dynamic module loading** with HTTP/3 support and version management
23
- - **Performance optimization** via lazy loading and dependency resolution
24
- - **TTL-based caching** for compositions and widget metadata
25
-
26
- ## Framework Compatibility
27
-
28
- โœ… **Framework-Agnostic Core**: No framework dependencies in the core SDK
29
- โœ… **Vanilla JavaScript**: Works directly in any HTML page
30
- โœ… **React**: Compatible with all React versions
31
- โœ… **Vue**: Compatible with Vue 2 and Vue 3
32
- โœ… **Angular**: Compatible with all Angular versions
33
- โœ… **Svelte/SvelteKit**: Compatible with Svelte 3, 4, and 5
34
- โœ… **Next.js**: Works with both SSR and client-side rendering
35
- โœ… **Other Frameworks**: Works with any framework that can render HTML
36
-
37
- See `/demo/` directory for framework-specific integration examples.
38
-
39
- ## ๐Ÿงช Testing & Development
40
-
41
- ### External Developer Test Pages
42
-
43
- The SDK includes comprehensive test pages that simulate real-world usage:
44
-
45
- - **[API Key Test](examples/api-key-test.html)** - Simple test page for trying your API key with different CDN sources
46
- - **[External Developer Test](examples/external-dev-test.html)** - Comprehensive test suite covering all SDK features
47
- - **[UMD Build Test](examples/umd-test.html)** - Tests UMD bundle completeness and functionality
48
- - **[Token Provider Examples](examples/token-provider.html)** - Demonstrates different token provider implementations
49
-
50
- These test pages help you:
51
- - Verify your API key works correctly
52
- - Test different installation methods (npm, unpkg, jsDelivr)
53
- - Validate token provider configurations
54
- - Debug widget rendering issues
55
- - Test bundle completeness for UMD builds
56
-
57
- ## ๐Ÿ—๏ธ Layered API Architecture
58
-
59
- The Widgetic SDK provides three distinct API layers to match different use cases and complexity levels:
60
-
61
- ### ๐ŸŸข High-Level API - Declarative & Auto-magical
62
- **Perfect for:** Simple integrations, HTML-first approaches, minimal JavaScript
63
- **Characteristics:** Auto-initialization, convention over configuration, declarative HTML
6
+ Show a published Widgetic widget on your web page with one tag:
64
7
 
65
8
  ```html
66
- <!-- Just add the script and use custom elements -->
67
- <script src="https://unpkg.com/@widgetic/embed-sdk/dist/umd/embed-sdk.js"></script>
68
- <script>
69
- widgeticEmbedSdk.setApiKey('your-api-key');
70
- </script>
71
-
72
- <widgetic-widget composition-id="your-composition-id" width="400" height="300"></widgetic-widget>
73
- ```
74
-
75
- ### ๐Ÿ”ต Mid-Level API - Programmatic with Configuration
76
- **Perfect for:** Framework integrations, custom UIs, controlled rendering
77
- **Characteristics:** Programmatic control, flexible configuration, managed lifecycle
78
-
79
- ```typescript
80
- import { getWidgetRenderer, setTokenProvider, EndpointTokenProvider } from '@widgetic/embed-sdk';
81
-
82
- setTokenProvider(new EndpointTokenProvider({ tokenEndpoint: '/api/token' }));
83
-
84
- const renderer = getWidgetRenderer();
85
- const widget = await renderer.renderWidget({
86
- compositionId: 'your-composition-id',
87
- container: document.getElementById('widget-container'),
88
- width: 400,
89
- height: 300,
90
- onReady: (widget) => console.log('Widget ready:', widget)
91
- });
9
+ <widgetic composition-id="COMPOSITION_ID" width="800" height="450"></widgetic>
92
10
  ```
93
11
 
94
- ### ๐Ÿ”ด Low-Level API - Full Control & Manual Management
95
- **Perfect for:** Custom implementations, performance optimization, advanced use cases
96
- **Characteristics:** Manual lifecycle management, direct API access, maximum flexibility
12
+ The script that makes the tag work is called the embed script. This package is the same code for projects that bundle their own JavaScript.
97
13
 
98
- ```typescript
99
- import { getBatchClient, getModuleLoader, getAuthManager } from '@widgetic/embed-sdk';
14
+ ## Which way should I use it?
100
15
 
101
- const authManager = getAuthManager();
102
- authManager.setApiKey('your-api-key');
103
-
104
- const batchClient = getBatchClient();
105
- const compositions = await batchClient.getCompositions(['comp-1', 'comp-2']);
106
-
107
- const moduleLoader = getModuleLoader();
108
- const module = await moduleLoader.loadModule(widgetData, { version: 'latest' });
109
- ```
16
+ | You have | Use |
17
+ | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
18
+ | A web page, a CMS or a template where you can add a `<script>` tag | **The script from the Widgetic CDN.** It is the supported way, and it needs no npm. |
19
+ | A project with a bundler (Vite, webpack, Next.js and so on) that you want to keep free of third-party script tags | This package, `@widgetic/embed-sdk`. |
110
20
 
111
- ### ๐Ÿ“š Layer Examples and Documentation
21
+ ## The script from the CDN
112
22
 
113
- - **[Layered API Examples](examples/layered-api-examples.html)** - Interactive examples for all three layers
114
- - **[Layer Comparison Guide](examples/layered-api-examples.html#comparison)** - When to use each layer
115
- - **[Framework Integration Examples](examples/layered-api-examples.html#mid-level)** - React, Vue, Angular examples
116
-
117
- You can also import specific layers:
118
-
119
- ```typescript
120
- import { HighLevelAPI, MidLevelAPI, LowLevelAPI } from '@widgetic/embed-sdk';
121
-
122
- // Use only what you need
123
- const { setApiKey, WidgeticWidget } = HighLevelAPI;
124
- const { getWidgetRenderer } = MidLevelAPI;
125
- const { getBatchClient } = LowLevelAPI;
23
+ ```html
24
+ <script src="https://cdn.widgetic.com/sdks/browser/embed-sdk.js?v=6"></script>
25
+ <widgetic
26
+ composition-id="COMPOSITION_ID"
27
+ resize="fill-width"
28
+ width="800"
29
+ height="450"
30
+ autoscale="on"
31
+ adaptive="480"
32
+ embed-target="site"
33
+ ></widgetic>
126
34
  ```
127
35
 
128
- ## Sibling packages
129
-
130
- In this checkout, the SDK consumes the sibling `api-sdk` package through a
131
- link rather than the published registry copy.
132
-
133
- This package consumes sibling `@widgetic/*` checkouts through a link in `node_modules` that
134
- resolves the checkout itself โ€” its built output, not its source.
135
- The link is made by hand rather than through the `@widgetic/dev-tools` dev-alias setup the
136
- adopting apps use, so a sibling edit stays invisible here until that package rebuilds its
137
- `dist/`.
138
- Setup is the install script this package ships: it reinstalls and then links the sibling, so
139
- `node_modules` keeps resolving the checkout rather than the published package.
140
- The dev-alias workflow these packages have not adopted, and the reasons the adopting apps use
141
- it, are described in [the dev-tools README](../dev-tools/README.md).
36
+ The script finds every `<widgetic>` tag on the page, also the ones that are added later, asks Widgetic for the published composition and shows it inside the tag.
142
37
 
143
- `npm run i` is the whole setup here: it reinstalls `node_modules`, then
144
- re-links the `api-sdk` checkout.
38
+ The CDN copy is published by Widgetic. It comes from the same source as this package, but it is published separately, so it can be a different build from the version you installed.
145
39
 
146
- ```sh
147
- npm run i # install, then link the api-sdk checkout
148
- npm run lapisdk # re-link only, after a fresh node_modules
149
- ```
150
-
151
- ## Installation
152
-
153
- ### npm/yarn
40
+ ## This package, for bundlers
154
41
 
155
42
  ```bash
156
43
  npm install @widgetic/embed-sdk
157
- # or
158
- yarn add @widgetic/embed-sdk
159
- ```
160
-
161
- ### CDN
162
-
163
- ```html
164
- <!-- UMD build (recommended for CDN) -->
165
- <script src="https://unpkg.com/@widgetic/embed-sdk@2.0.0/dist/umd/embed-sdk.js"></script>
166
-
167
- <!-- or via jsDelivr -->
168
- <script src="https://cdn.jsdelivr.net/npm/@widgetic/embed-sdk@2.0.0/dist/umd/embed-sdk.js"></script>
169
-
170
- <!-- Latest version (unpkg) -->
171
- <script src="https://unpkg.com/@widgetic/embed-sdk/dist/umd/embed-sdk.js"></script>
172
- ```
173
-
174
- The UMD build includes all dependencies bundled, so no additional imports are needed.
175
-
176
- ## Quick Start
177
-
178
- ### HTML (Auto-initialization)
179
-
180
- The SDK automatically initializes when the DOM is ready and scans for `<widgetic-widget>` elements:
181
-
182
- #### UMD (Global Script)
183
-
184
- ```html
185
- <!DOCTYPE html>
186
- <html>
187
- <head>
188
- <title>Widgetic Widget</title>
189
- <!-- Load SDK from CDN -->
190
- <script src="https://unpkg.com/@widgetic/embed-sdk/dist/umd/embed-sdk.js"></script>
191
- </head>
192
- <body>
193
- <!-- Widget element -->
194
- <widgetic-widget
195
- composition-id="your-composition-id"
196
- render-mode="auto"
197
- width="350"
198
- height="200"
199
- resize="fill-width"
200
- ></widgetic-widget>
201
-
202
- <script>
203
- // Configure authentication (choose one method)
204
-
205
- // Method 1: Static API Key (development only)
206
- const provider = new widgeticEmbedSdk.StaticApiKeyProvider('your-api-key');
207
- widgeticEmbedSdk.setTokenProvider(provider);
208
-
209
- // Method 2: Token from your backend (recommended)
210
- const tokenProvider = new widgeticEmbedSdk.EndpointTokenProvider({
211
- tokenEndpoint: '/api/widgetic/token'
212
- });
213
- widgeticEmbedSdk.setTokenProvider(tokenProvider);
214
-
215
- // Method 3: AuthManager with API key (handles token lifecycle)
216
- widgeticEmbedSdk.setApiKey('your-api-key');
217
-
218
- // SDK will auto-initialize and render widgets
219
- </script>
220
- </body>
221
- </html>
222
44
  ```
223
45
 
224
- #### ES Modules
46
+ ```js
47
+ import { getSDK } from "@widgetic/embed-sdk";
225
48
 
226
- ```html
227
- <!DOCTYPE html>
228
- <html>
229
- <head>
230
- <title>Widgetic Widget</title>
231
- </head>
232
- <body>
233
- <!-- Widget element -->
234
- <widgetic-widget
235
- composition-id="62bldc5lecb2al3f458b4567"
236
- render-mode="auto"
237
- width="350"
238
- height="50"
239
- resize="fill-width"
240
- autoscale="on"
241
- adaptive="414"
242
- >
243
- </widgetic-widget>
244
-
245
- <!-- Import SDK as ES module -->
246
- <script type="module">
247
- import { setTokenProvider, StaticApiKeyProvider, setApiKey } from '@widgetic/embed-sdk';
248
-
249
- // Configure authentication (choose one method)
250
-
251
- // Method 1: Static API Key (development only)
252
- setTokenProvider(new StaticApiKeyProvider('your-api-key'));
253
-
254
- // Method 2: AuthManager with API key (handles token lifecycle)
255
- setApiKey('your-api-key');
256
-
257
- // SDK will auto-initialize and render widgets
258
- </script>
259
- </body>
260
- </html>
49
+ // Loading the package in a browser starts the embed script: it finds the <widgetic> tags and
50
+ // watches for new ones. Calling getSDK() keeps your bundler from dropping the import.
51
+ getSDK();
261
52
  ```
262
53
 
54
+ Load it in the browser only: it scans the page, and a server has no page.
263
55
 
264
- ### JavaScript/TypeScript
56
+ In a React or Next.js project, load it from an effect, so it runs in the browser:
265
57
 
266
- ```typescript
267
- import { getSDK, EmbedSDK } from "@widgetic/embed-sdk";
58
+ ```jsx
59
+ "use client";
60
+ import { useEffect } from "react";
268
61
 
269
- // Get the global SDK instance
270
- const sdk = getSDK();
62
+ export function WidgeticEmbed({ compositionId }) {
63
+ useEffect(() => {
64
+ import("@widgetic/embed-sdk").then(({ getSDK }) => getSDK());
65
+ }, []);
271
66
 
272
- // Or create a new instance
273
- const customSDK = new EmbedSDK();
274
-
275
- // Initialize and scan for widgets
276
- await sdk.init();
277
-
278
- // Manually refresh to detect new widgets
279
- await sdk.refresh();
280
-
281
- // Get widget instances
282
- const instances = sdk.getInstances();
283
- console.log(`Found ${instances.length} widgets`);
284
- ```
285
-
286
- ## Widget Attributes
287
-
288
- | Attribute | Type | Default | Description |
289
- | ---------------- | ------------------------------- | ------------ | -------------------------------------------- |
290
- | `composition-id` | string | **required** | Unique identifier for the widget composition |
291
- | `render-mode` | `auto\|custom-element\|iframe` | `auto` | Rendering method preference |
292
- | `width` | number\|string | `350` | Widget width in pixels |
293
- | `height` | number\|string | `50` | Widget height in pixels |
294
- | `resize` | `fill-width\|fixed\|responsive` | `fixed` | Resize behavior |
295
- | `autoscale` | `on\|off` | `off` | Enable automatic scaling |
296
- | `adaptive` | number | - | Adaptive breakpoint in pixels |
297
-
298
- ## Authentication & Security
299
-
300
- ### Token Provider (Recommended)
301
-
302
- For production applications, use a Token Provider instead of embedding API keys in client-side code:
303
-
304
- ```typescript
305
- import { setTokenProvider, EndpointTokenProvider } from "@widgetic/embed-sdk";
306
-
307
- // Recommended: Fetch tokens from your backend
308
- setTokenProvider(new EndpointTokenProvider({
309
- tokenEndpoint: '/api/widgetic/token',
310
- headers: {
311
- 'Authorization': 'Bearer ' + userJwtToken
312
- }
313
- }));
314
-
315
- // Custom token logic
316
- setTokenProvider(new FunctionTokenProvider(async () => {
317
- const response = await fetch('/api/auth/widgetic-token');
318
- const data = await response.json();
319
- return data.token;
320
- }));
321
- ```
322
-
323
- Your backend endpoint should return:
324
- ```json
325
- {
326
- "token": "your-widgetic-token",
327
- "expires_in": 3600
67
+ return <widgetic composition-id={compositionId} width="800" height="450" />;
328
68
  }
329
69
  ```
330
70
 
331
- ### Short-lived Tokens with AuthManager (Recommended)
71
+ ## The attributes you will use most
332
72
 
333
- For maximum security, use the AuthManager to automatically handle short-lived token lifecycle:
73
+ | Attribute | What it does |
74
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
+ | `composition-id` | **Required.** The id of the composition to show. |
76
+ | `width`, `height` | The size of the frame in pixels. When they are missing the frame is 400 by 300. |
77
+ | `resize` | How the frame follows its place on the page: `fixed` (the default), `fill-width`, `fill-height`, `fixed-width`, `fixed-height`, `fill` or `allow-scale-down`. |
78
+ | `autoscale` | `on` turns automatic scaling on. Without the attribute, or with `autoscale="false"`, it is off. |
79
+ | `adaptive` | An adaptive breakpoint in pixels. |
334
80
 
335
- ```typescript
336
- import { getAuthManager, setApiKey } from "@widgetic/embed-sdk";
81
+ The tag has more attributes: `embed-target`, and the ones for an overlay, a pop-up and for when a widget shows (`overlay-*`, `popup-*`, `trigger-*`). They are described in the Widgetic Partner integration guide, page 8, "Embed widgets on your pages".
337
82
 
338
- // Configure with your API key (server-side recommended)
339
- setApiKey('your-api-key');
83
+ ### Host context, theme, and partner media (host bridge)
340
84
 
341
- // The AuthManager will automatically:
342
- // - Exchange your API key for short-lived JWTs
343
- // - Cache tokens until they expire
344
- // - Refresh tokens automatically
345
- // - Handle token validation
85
+ Optional attributes on `<widgetic>` are sent to the published frame as a `widgetic:host` message and kept in sync while the widget is visible:
346
86
 
347
- const authManager = getAuthManager();
348
- // Token management is now handled automatically
349
- ```
350
-
351
- ### Backend Token Exchange Endpoint (Recommended)
352
-
353
- Implement a secure token exchange endpoint in your backend:
354
-
355
- ```javascript
356
- // Express.js example
357
- app.post('/api/widgetic/token', authenticate, async (req, res) => {
358
- try {
359
- const response = await fetch('https://api.widgetic.com/v1/tokens', {
360
- method: 'POST',
361
- headers: {
362
- 'Authorization': `Bearer ${process.env.WIDGETIC_API_KEY}`,
363
- 'Content-Type': 'application/json'
364
- },
365
- body: JSON.stringify({
366
- scope: ['widgets:read', 'compositions:read'],
367
- expiresIn: 3600 // 1 hour
368
- })
369
- });
370
-
371
- const data = await response.json();
372
- res.json({ token: data.token });
373
- } catch (error) {
374
- res.status(500).json({ error: 'Token generation failed' });
375
- }
376
- });
377
- ```
87
+ | Attribute | Purpose |
88
+ | --------------- | ------------------------------------------------------------------------------------ |
89
+ | `context` | JSON object (โ‰ค20 keys) stored on entries and returned on reads |
90
+ | `values` | JSON object that pre-fills fields by name |
91
+ | `lang` | BCP 47 language tag (for example `fr`, `pt-BR`) |
92
+ | `dir` | `ltr` or `rtl` |
93
+ | `mode` | `light` or `dark` |
94
+ | `colors` | JSON theme colours (`primary`, `background`, โ€ฆ) |
95
+ | `media-resolver` | HTTPS URL of a partner function that turns stored media addresses into playable URLs |
378
96
 
379
- ### Development with API Keys
97
+ The element fires DOM events (bubbling, composed) that match the frame protocol: `widgetic:ready`, `widgetic:error`, `widgetic:submitted`, `widgetic:resize`, `widgetic:data`, `widgetic:interaction`, `widgetic:form-submit`. Lookup failures use `widgetic:error` with `detail.code` in lower case (`not_found`, `domain_not_allowed`, `device_restricted`, โ€ฆ).
380
98
 
381
- For development only, you can use static API keys:
99
+ Markers the script writes: `data-widgetic-mounting`, `data-widgetic-mounted`, `data-device-restricted`, `data-widgetic-refused="CODE"`, `data-widgetic-context-invalid`. See `docs/host-contract.md` for the full contract.
382
100
 
383
- ```typescript
384
- import { StaticApiKeyProvider, setTokenProvider } from "@widgetic/embed-sdk";
101
+ ### Telemetry and hosts the script may contact
385
102
 
386
- // โš ๏ธ Development only - not for production!
387
- setTokenProvider(new StaticApiKeyProvider('your-api-key'));
388
- ```
103
+ For a typical published embed the script talks to:
389
104
 
390
- ### Security Best Practices
105
+ | Host | When | What is sent |
106
+ | ------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- |
107
+ | `api.widgetic.com` (or your `data-api-url`) | Composition lookup | Composition id, browser origin (CORS); no API key |
108
+ | `cdn.widgetic.com` | Fallback lookup script | Composition id |
109
+ | `api.axiom.co` | Optional performance batch (if keys are baked into a custom build) | Aggregated performance summary (no end-user id by default) |
110
+ | `events.statsigapi.net` | Optional performance batch (if keys are baked into a custom build) | Custom `widget_performance` event with summary payload |
391
111
 
392
- 1. **Never expose API keys in client-side code** - Use token providers or AuthManager
393
- 2. **Use short-lived tokens** - Tokens should expire within 1-24 hours
394
- 3. **Implement proper scopes** - Limit token permissions to what's needed
395
- 4. **Validate tokens server-side** - Verify tokens in your backend before issuing them
396
- 5. **Use HTTPS** - Always serve your application over HTTPS in production
397
- 6. **Monitor token usage** - Track token generation and usage patterns
112
+ Turn all telemetry calls off with `data-widgetic-telemetry="off"` on the embed script tag, or `window.WidgeticConfig = { telemetry: false }` before the script runs.
398
113
 
399
- ## API Reference
114
+ Local development: set `data-api-url="http://localhost:3000"` on the script tag (or `window.WIDGETIC_EMBED_API`); the script no longer hard-codes Render or localhost addresses.
400
115
 
401
- ### Core SDK
116
+ ## Which websites may show a widget
402
117
 
403
- ```typescript
404
- import { getSDK, EmbedSDK, config } from "@widgetic/embed-sdk";
118
+ The owner of a composition can limit it to a list of websites. A partner sets that list for its customers through the API, from a server (see the integration guide). On a website that is not on the list, the frame stays empty.
405
119
 
406
- // Global SDK instance
407
- const sdk = getSDK();
120
+ ## Never put an API key in a page
408
121
 
409
- // SDK configuration
410
- config.apiUrl = "https://api.widgetic.com";
411
- config.cdnUrl = "https://cdn.widgetic.com";
412
- config.debug = true;
413
- ```
122
+ A published widget needs no key and no token. Everything on a page can be read by anyone who opens it, so a key put there is a key given away.
414
123
 
415
- ### Batch API Client
124
+ This package also contains helpers that take an API key or a token (`setApiKey`, `setTokenProvider`). They are for the Widgetic editors that run for a signed-in Widgetic user, not for pages that only show widgets. Do not use them to show a widget.
416
125
 
417
- ```typescript
418
- import { getBatchClient } from "@widgetic/embed-sdk";
126
+ ## Where to read more
419
127
 
420
- const batchClient = getBatchClient();
128
+ - **The Widgetic Partner integration guide** (your Widgetic contact shares it with you): page 8 for everything about embedding, page 4 for the API and its keys.
129
+ - **`@widgetic/api-sdk`** is the package for calling the Widgetic API from your server. It is not part of this package.
421
130
 
422
- // Get multiple compositions efficiently
423
- const compositions = await batchClient.getCompositions(["id1", "id2", "id3"]);
131
+ ## For people who work on this package
424
132
 
425
- // Get widget metadata
426
- const widgets = await batchClient.getWidgets(["widget1", "widget2"]);
427
- ```
428
-
429
- ### Module Loader
430
-
431
- ```typescript
432
- import { getModuleLoader } from "@widgetic/embed-sdk";
433
-
434
- const moduleLoader = getModuleLoader();
435
-
436
- // Load widget module dynamically
437
- const loadedModule = await moduleLoader.loadModule(widgetData, {
438
- version: "latest",
439
- timeout: 10000,
440
- });
441
-
442
- // Preload modules for performance
443
- await moduleLoader.preloadModules(widgetDataList);
444
- ```
445
-
446
- ### Custom Rendering
447
-
448
- ```typescript
449
- import { getWidgetRenderer } from "@widgetic/embed-sdk";
450
-
451
- const renderer = getWidgetRenderer();
452
-
453
- // Render single widget
454
- const rendered = await renderer.renderWidget({
455
- compositionId: "your-composition-id",
456
- renderMode: "custom-element",
457
- container: document.getElementById("widget-container"),
458
- });
459
-
460
- // Batch render multiple widgets
461
- const results = await renderer.renderWidgets(renderOptions);
462
- ```
463
-
464
- ## Advanced Configuration
465
-
466
- ### Environment Configuration
467
-
468
- ```typescript
469
- import { config } from "@widgetic/embed-sdk";
470
-
471
- // API endpoints
472
- config.apiUrl = "https://your-api.domain.com";
473
- config.cdnUrl = "https://your-cdn.domain.com";
474
-
475
- // Performance tuning
476
- config.batchSize = 50;
477
- config.cacheTTL = 300000; // 5 minutes
478
-
479
- // Development
480
- config.debug = true;
481
- config.logLevel = "debug";
482
- ```
483
-
484
- ### Custom Error Handling
485
-
486
- ```typescript
487
- import { log } from "@widgetic/embed-sdk";
488
-
489
- // Listen for SDK events
490
- document.addEventListener("widgetic:error", (event) => {
491
- log.error("Widget error:", event.detail);
492
- });
493
-
494
- document.addEventListener("widgetic:initialized", (event) => {
495
- log.info("Widget initialized:", event.detail);
496
- });
133
+ ```bash
134
+ npm run i # install, then link the sibling api-sdk checkout (see below)
135
+ npm run dev # build and watch
136
+ npm run build # production build (dist/)
137
+ npm test # unit tests (vitest)
138
+ npm run test:e2e # browser tests (playwright)
139
+ npm run lint
497
140
  ```
498
141
 
499
- ## Browser Support
500
-
501
- - **Modern browsers**: Chrome 60+, Firefox 60+, Safari 12+, Edge 79+
502
- - **Custom Elements**: Supported natively or via polyfill
503
- - **HTTP/3**: Automatically detected with graceful fallback to HTTP/2
504
- - **ES Modules**: Native support with UMD fallback for older browsers
505
-
506
- ## Performance Features
142
+ In this checkout the SDK consumes the sibling `api-sdk` package through a link in `node_modules` that points at the checkout itself, so an edit in the sibling stays invisible here until that package rebuilds its `dist/`. `npm run i` reinstalls `node_modules` and links the sibling again; `npm run lapisdk` links it again after a fresh `node_modules`. The dev-alias workflow that the adopting apps use, and why, is described in [the dev-tools README](../dev-tools/README.md).
507
143
 
508
- - **Intelligent batching**: Groups API requests for optimal performance
509
- - **Request deduplication**: Prevents redundant network calls
510
- - **TTL caching**: Caches compositions and widget data
511
- - **Lazy loading**: Loads widget modules on demand
512
- - **HTTP/3 support**: Uses the latest protocol when available
513
- - **Tree shaking**: Only includes used functionality in bundles
144
+ ## Publishing
514
145
 
515
- ## TypeScript Support
516
-
517
- Full TypeScript support with comprehensive type definitions:
518
-
519
- ```typescript
520
- import type {
521
- WidgetConfig,
522
- WidgetInstance,
523
- RenderMode,
524
- CompositionData,
525
- WidgetData,
526
- } from "@widgetic/embed-sdk";
527
- ```
146
+ GitLab CI on `main` publishes this package and then replaces `https://cdn.widgetic.com/sdks/browser/embed-sdk.js`. The npm job is a Trusted Publisher (`NPM_ID_TOKEN`). It does not use a long-lived token.
528
147
 
529
- ## Contributing
148
+ 1. Bump `version` in `package.json`.
149
+ 2. Commit and push `main`.
150
+ 3. The `publish` job runs `npm publish` when that version is not already on npm, then uploads `dist/umd/embed-sdk.js` to the CDN and purges the cached copies.
530
151
 
531
- 1. Fork the repository
532
- 2. Create a feature branch: `git checkout -b feature/amazing-feature`
533
- 3. Make your changes and add tests
534
- 4. Run the test suite: `npm test`
535
- 5. Commit your changes: `git commit -m 'Add amazing feature'`
536
- 6. Push to the branch: `git push origin feature/amazing-feature`
537
- 7. Open a Pull Request
152
+ The CDN upload needs six CI/CD variables on this project, protected, environment scope `cdn`: `CLOUDFLARE_PUBLIC_ENDPOINT`, `R2_WIDGETS_NAME`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ZONE_ID`. The last two are what let the job purge the cached file.
538
153
 
539
- ## Development
154
+ When the GitLab job fails with `ci_quota_exceeded`, publish from a laptop. That does not use CI minutes. The group's remaining minutes are at [Usage quotas](https://gitlab.com/groups/widgeticai/-/usage_quotas), on the pipelines tab.
540
155
 
541
156
  ```bash
542
- # Install dependencies
543
- npm install
544
-
545
- # Start development server
546
- npm run dev
547
-
548
- # Build for production
157
+ npm ci
549
158
  npm run build
550
-
551
- # Run tests
552
- npm test
553
-
554
- # Lint and format
555
- npm run lint
556
- npm run format
159
+ npm publish --access public
160
+ npm run publish:cdn:dry-run
161
+ npm run publish:cdn -- --purge
557
162
  ```
558
163
 
164
+ `npm publish` needs the token in `~/.npmrc`. Do not commit that file. The dry run changes nothing. The last command asks you to type `publish`, uploads the file, and purges the cache. Check `npm view @widgetic/embed-sdk version` and the `last-modified` header of `https://cdn.widgetic.com/sdks/browser/embed-sdk.js`. What the upload checks, and how to roll back, is in `__docs/05-advanced/06-publishing-to-cdn.md`.
165
+
559
166
  ## License
560
167
 
561
168
  MIT ยฉ [Widgetic](https://widgetic.com)
562
169
 
563
170
  ## Support
564
171
 
565
- - ๐Ÿ“ง Email: support@widgetic.com
566
- - ๐Ÿ’ฌ Discord: [Join our community](https://discord.gg/widgetic)
567
- - ๐Ÿ“– Documentation: [docs.widgetic.com](https://docs.widgetic.com)
568
- - ๐Ÿ› Issues: [GitHub Issues](https://github.com/widgetic/embed-sdk/issues)
172
+ - Email: support@widgetic.com
173
+ - Documentation: [docs.widgetic.com](https://docs.widgetic.com)
174
+ - Issues: [GitHub Issues](https://github.com/widgetic/embed-sdk/issues)