@selwise/widget 1.0.0 → 1.0.2

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 (2) hide show
  1. package/README.md +93 -39
  2. package/package.json +6 -1
package/README.md CHANGED
@@ -1,13 +1,18 @@
1
1
  # @selwise/widget
2
2
 
3
- Selwise storefront widget runtime for e-commerce personalization and tracking.
3
+ Selwise storefront runtime for CDN and npm integrations.
4
4
 
5
- ## Installation
5
+ ## Install
6
6
 
7
7
  ```bash
8
8
  npm install @selwise/widget
9
9
  ```
10
10
 
11
+ ## Integration Models
12
+
13
+ - CDN script mode (auto-init, global runtime)
14
+ - npm instance mode (explicit lifecycle ownership)
15
+
11
16
  ## Quick Start (npm)
12
17
 
13
18
  ```ts
@@ -17,16 +22,11 @@ const widget = new Selwise();
17
22
  await widget.init({
18
23
  siteKey: 'YOUR_SITE_KEY',
19
24
  apiUrl: 'https://api.selwise.com/api/v1',
20
- exposeGlobal: true, // optional, default false
25
+ exposeGlobal: true,
21
26
  });
22
27
  ```
23
28
 
24
- Important:
25
-
26
- - Package import is side-effect free.
27
- - `window.Selwise` is exposed only when `exposeGlobal: true`.
28
-
29
- ## CDN Script Tag
29
+ ## Quick Start (CDN)
30
30
 
31
31
  ```html
32
32
  <script
@@ -36,36 +36,90 @@ Important:
36
36
  ></script>
37
37
  ```
38
38
 
39
- ## Public API
40
-
41
- Instance and `window.Selwise` after initialization:
42
-
43
- - `init(config)`
44
- - `destroy()`
45
- - `track(name, args?)`
46
- - `trackOrder(order)`
47
- - `identify(userId, metadata?)`
48
- - `setTraits(traits)`
49
- - `getVisitorId()`
50
- - `getSessionId()`
51
- - `getJourneyId()`
52
- - `getJourneyState()`
53
- - `endJourney()`
54
- - `getVariant(experimentId)`
55
- - `getExperimentVariant(experimentId)`
56
- - `getActiveExperiments()`
57
- - `pushDataLayer(data)`
58
- - `getDataLayer()`
59
- - `getConsentState()`
60
- - `grantConsent(categories?)`
61
- - `revokeConsent(categories?)`
62
-
63
- ## Docs
64
-
65
- - https://docs.selwise.com/getting-started/npm-integration/
66
- - https://docs.selwise.com/client-api/public-api/
67
- - https://docs.selwise.com/client-api/data-layer/
68
- - https://docs.selwise.com/client-api/consent-management/
39
+ ## Lifecycle Ownership
40
+
41
+ Use one shared instance per app shell in npm mode.
42
+
43
+ ```ts
44
+ let widget: Selwise | null = null;
45
+
46
+ export async function ensureSelwise(siteKey: string, apiUrl: string) {
47
+ if (widget) return widget;
48
+
49
+ widget = new Selwise();
50
+ await widget.init({ siteKey, apiUrl, exposeGlobal: true });
51
+ return widget;
52
+ }
53
+
54
+ export function disposeSelwise() {
55
+ widget?.destroy();
56
+ widget = null;
57
+ }
58
+ ```
59
+
60
+ ## Public API Surface
61
+
62
+ | Method | Notes |
63
+ | --- | --- |
64
+ | `init(config)` | Initializes runtime config and identity state. |
65
+ | `destroy()` | Cleans up active runtime resources. |
66
+ | `track(name, args?)` | Sends canonical events through event queue. |
67
+ | `trackOrder(order)` | Sends order attribution payload. |
68
+ | `identify(userId, metadata?)` | Links visitor to known user identity. |
69
+ | `setTraits(traits)` | Updates profile traits without identity switch. |
70
+ | `getSiteUserId()` | Returns identified site user id if available. |
71
+ | `getVisitorId()` | Returns visitor id. |
72
+ | `getSessionId()` | Returns session id. |
73
+ | `getJourneyId()` | Returns active journey id or null. |
74
+ | `getJourneyState()` | Returns journey debug snapshot. |
75
+ | `endJourney()` | Rotates journey context. |
76
+ | `getVariant(experimentId)` | Returns assignment payload for experiment. |
77
+ | `getExperimentVariant(experimentId)` | Returns assigned variant id. |
78
+ | `getActiveExperiments()` | Returns active assignment list. |
79
+ | `pushDataLayer(data)` | Pushes structured data-layer payload. |
80
+ | `getDataLayer()` | Reads data-layer snapshot. |
81
+ | `getConsentState()` | Reads consent categories state. |
82
+ | `grantConsent(categories?)` | Grants selected consent categories. |
83
+ | `revokeConsent(categories?)` | Revokes selected consent categories. |
84
+
85
+ ## Event Example
86
+
87
+ ```ts
88
+ widget.track('product_view', {
89
+ entityType: 'product',
90
+ entityId: 'SKU-123',
91
+ metadata: { productItemCode: 'SKU-123', title: 'Runner Pro', price: 149.9 },
92
+ });
93
+
94
+ await widget.trackOrder({
95
+ orderId: 'ORDER-1001',
96
+ currency: 'USD',
97
+ total: 149.9,
98
+ items: [{ productItemCode: 'SKU-123', quantity: 1, unitPrice: 149.9 }],
99
+ });
100
+ ```
101
+
102
+ ## Common Errors
103
+
104
+ 1. `window.Selwise` missing in npm mode.
105
+ - Set `exposeGlobal: true` if global API compatibility is required.
106
+
107
+ 2. Duplicate events/widgets.
108
+ - Multiple instances are being initialized in app shell.
109
+
110
+ 3. `init()` appears no-op.
111
+ - Called in server runtime or with invalid/missing `siteKey`.
112
+
113
+ ## Documentation
114
+
115
+ - [Installation](https://docs.selwise.com/getting-started/installation/)
116
+ - [Platform Playbooks](https://docs.selwise.com/getting-started/platform-playbooks/)
117
+ - [npm Integration](https://docs.selwise.com/getting-started/npm-integration/)
118
+ - [CDN Integration](https://docs.selwise.com/getting-started/cdn-integration/)
119
+ - [Public API](https://docs.selwise.com/client-api/public-api/)
120
+ - [Event Cookbook](https://docs.selwise.com/client-api/event-cookbook/)
121
+ - [Verification](https://docs.selwise.com/getting-started/verification/)
122
+ - [Troubleshooting](https://docs.selwise.com/getting-started/integration-troubleshooting/)
69
123
 
70
124
  ## License
71
125
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@selwise/widget",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "Selwise storefront widget runtime for CDN and npm integrations.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -48,6 +48,7 @@
48
48
  "build:npm:types": "node ./scripts/write-npm-types.js",
49
49
  "build:npm": "rm -rf ./dist/npm && pnpm run build:npm:bundle && pnpm run build:npm:types",
50
50
  "build": "pnpm run clean && pnpm run build:npm && pnpm run build:cdn",
51
+ "prepack": "pnpm run build:npm",
51
52
  "analyze": "webpack --mode production --env analyze",
52
53
  "pack:check": "pnpm pack --pack-destination ./dist/pack",
53
54
  "test": "jest",
@@ -56,6 +57,10 @@
56
57
  "test:cov": "jest --coverage"
57
58
  },
58
59
  "devDependencies": {
60
+ "@selwise/recommendation-contract": "workspace:*",
61
+ "@selwise/search-contract": "workspace:*",
62
+ "@selwise/tracking-contract": "workspace:*",
63
+ "@selwise/widget-contract": "workspace:*",
59
64
  "@types/dompurify": "^3.2.0",
60
65
  "@types/jest": "^29.5.11",
61
66
  "dotenv": "^16.4.5",