@walkeros/web-core 4.1.0-next-1778668930820 → 4.1.0

package/CHANGELOG.md

@@ -0,0 +1,272 @@
+# @walkeros/web-core
+
+## 4.1.0
+
+### Patch Changes
+
+- Updated dependencies [e155ff8]
+- Updated dependencies [e800974]
+- Updated dependencies [e155ff8]
+- Updated dependencies [1a8f2d7]
+- Updated dependencies [1a8f2d7]
+- Updated dependencies [b276173]
+- Updated dependencies [dd9f5ad]
+- Updated dependencies [c60ef35]
+- Updated dependencies [adeebea]
+- Updated dependencies [13aaeaa]
+- Updated dependencies [e800974]
+- Updated dependencies [adeebea]
+- Updated dependencies [e800974]
+- Updated dependencies [e800974]
+- Updated dependencies [058f7ed]
+- Updated dependencies [28a8ac2]
+- Updated dependencies [fd6076e]
+  - @walkeros/core@4.1.0
+
+## 4.0.2
+
+### Patch Changes
+
+- Updated dependencies [a6a0ea7]
+  - @walkeros/core@4.0.2
+
+## 4.0.1
+
+### Patch Changes
+
+- Updated dependencies [381dfe7]
+- Updated dependencies [1524275]
+- Updated dependencies [03d7055]
+  - @walkeros/core@4.0.1
+
+## 4.0.0
+
+### Major Changes
+
+- 93ea9c4: Event model v4: breaking changes to the `Event`, `Source`, and
+  `Entity` shapes.
+  - `event.id` is now a W3C span_id (16 lowercase hex chars), generated by the
+    collector. Reference: W3C Trace Context (W3C Recommendation, January 2020).
+  - `event.version`, `event.group`, `event.count` are removed.
+  - `source.type` is now the source kind (e.g. `browser`, `gtag`, `mcp`, `cli`).
+    New `source.platform` holds the runtime (`web` | `server` | `app` | ...).
+  - `source.id` and `source.previous_id` are removed.
+  - Browser source now sets `source.url` and `source.referrer`.
+  - MCP source sets `source.tool` per emission. CLI source sets
+    `source.command`.
+  - `Entity.nested` and `Entity.context` are now optional. Root `event.nested`
+    and `event.context` remain required.
+  - Each source self-registers via TypeScript module augmentation of `SourceMap`
+    in `@walkeros/core`.
+  - App-side coordination (`/workspaces/developer/app`) is a follow-up plan, not
+    part of this release. Telemetry from v4 CLI/MCP will not validate against
+    the existing app schema until that follow-up ships.
+  - `Mapping.Rule.skip` is renamed to `Mapping.Rule.silent`. Customer flow.json
+    configs using `skip: true` in mapping rules must rename to `silent: true`.
+    Hard cut: no legacy alias, the field is gone.
+
+### Patch Changes
+
+- Updated dependencies [93ea9c4]
+- Updated dependencies [465775c]
+- Updated dependencies [942a7fe]
+- Updated dependencies [cfc7469]
+- Updated dependencies [8e06b1f]
+- Updated dependencies [3d50dd6]
+- Updated dependencies [1ef33d9]
+  - @walkeros/core@4.0.0
+
+## 3.4.2
+
+### Patch Changes
+
+- @walkeros/core@3.4.2
+
+## 3.4.1
+
+### Patch Changes
+
+- caea905: Wrap `localStorage`/`sessionStorage`/cookie operations in try/catch.
+  Storage access in private browsing (Safari), sandboxed iframes, or when quota
+  is exceeded throws `SecurityError`/`QuotaExceededError` — previously these
+  crashed the event pipeline at the call site. Reads now return empty, writes
+  return empty and do not persist, deletes are silently ignored.
+- Updated dependencies [12adf24]
+- Updated dependencies [75aa26b]
+  - @walkeros/core@3.4.1
+
+## 3.4.0
+
+### Patch Changes
+
+- Updated dependencies [74940cc]
+- Updated dependencies [525f5d9]
+  - @walkeros/core@3.4.0
+
+## 3.3.1
+
+### Patch Changes
+
+- @walkeros/core@3.3.1
+
+## 3.3.0
+
+### Patch Changes
+
+- Updated dependencies [2849acb]
+- Updated dependencies [08c365a]
+- Updated dependencies [08c365a]
+- Updated dependencies [08c365a]
+- Updated dependencies [08c365a]
+  - @walkeros/core@3.3.0
+
+## 3.2.0
+
+### Patch Changes
+
+- Updated dependencies [eb865e1]
+- Updated dependencies [c0a53f9]
+- Updated dependencies [f007c9f]
+- Updated dependencies [bf2dc5b]
+- Updated dependencies [da0b640]
+  - @walkeros/core@3.2.0
+
+## 3.1.1
+
+### Patch Changes
+
+- @walkeros/core@3.1.1
+
+## 3.1.0
+
+### Minor Changes
+
+- ff58828: Add optional StorageEnv parameter to storageRead, storageWrite, and
+  storageDelete. Enables dependency injection of window/document for testing and
+  simulation. Fully backwards-compatible — existing callers are unchanged.
+
+### Patch Changes
+
+- Updated dependencies [dfc6738]
+- Updated dependencies [966342b]
+- Updated dependencies [bee8ba7]
+- Updated dependencies [966342b]
+- Updated dependencies [df990d4]
+  - @walkeros/core@3.1.0
+
+## 3.0.2
+
+### Patch Changes
+
+- @walkeros/core@3.0.2
+
+## 3.0.1
+
+### Patch Changes
+
+- @walkeros/core@3.0.1
+
+## 3.0.0
+
+### Patch Changes
+
+- 499e27a: Add sideEffects declarations to all packages for bundler tree-shaking
+  support.
+- Updated dependencies [2b259b6]
+- Updated dependencies [2614014]
+- Updated dependencies [6ae0ee3]
+- Updated dependencies [37299a9]
+- Updated dependencies [499e27a]
+- Updated dependencies [0e5eede]
+- Updated dependencies [d11f574]
+- Updated dependencies [d11f574]
+- Updated dependencies [1fe337a]
+- Updated dependencies [5cb84c1]
+- Updated dependencies [23f218a]
+- Updated dependencies [499e27a]
+- Updated dependencies [c83d909]
+- Updated dependencies [b6c8fa8]
+  - @walkeros/core@3.0.0
+
+## 2.1.1
+
+### Patch Changes
+
+- Updated dependencies [fab477d]
+  - @walkeros/core@2.1.1
+
+## 2.1.0
+
+### Patch Changes
+
+- Updated dependencies [7fc4cee]
+- Updated dependencies [7fc4cee]
+- Updated dependencies [cb2da05]
+- Updated dependencies [2bbe8c8]
+- Updated dependencies [3eb6416]
+- Updated dependencies [02a7958]
+- Updated dependencies [97df0b2]
+- Updated dependencies [97df0b2]
+- Updated dependencies [026c412]
+- Updated dependencies [7d38d9d]
+  - @walkeros/core@2.1.0
+
+## 2.0.1
+
+## 2.0.0
+
+### Patch Changes
+
+- Updated dependencies [7b2d750]
+  - @walkeros/core@1.4.0
+
+## 1.0.5
+
+### Patch Changes
+
+- Updated dependencies [a4cc1ea]
+  - @walkeros/core@1.3.0
+
+## 1.0.4
+
+### Patch Changes
+
+- Updated dependencies [7ad6cfb]
+  - @walkeros/core@1.2.2
+
+## 1.0.3
+
+### Patch Changes
+
+- Updated dependencies [6256c12]
+  - @walkeros/core@1.2.1
+
+## 1.0.2
+
+### Patch Changes
+
+- Updated dependencies [f39d9fb]
+- Updated dependencies [888bbdf]
+  - @walkeros/core@1.2.0
+
+## 1.0.1
+
+### Patch Changes
+
+- Updated dependencies [b65b773]
+- Updated dependencies [20eca6e]
+  - @walkeros/core@1.1.0
+
+## 1.0.0
+
+### Major Changes
+
+- 67c9e1d: Hello World! walkerOS v1.0.0
+
+  Open-source event data collection. Collect event data for digital analytics in
+  a unified and privacy-centric way.
+
+### Patch Changes
+
+- Updated dependencies [67c9e1d]
+  - @walkeros/core@1.0.0

package/README.md

@@ -4,273 +4,39 @@
   </a>
 </p>
 
-# Web Core Utilities for walkerOS
+# @walkeros/web-core
 
-[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/core)
-&bull; [NPM Package](https://www.npmjs.com/package/@walkeros/web-core)
-
-Web core utilities are browser-specific functions designed for client-side
-walkerOS implementations. These utilities handle DOM interactions, browser
-information, storage, element visibility, and web-based communication.
+Browser-specific utilities for client-side walkerOS implementations, covering
+DOM interactions, browser information, storage, element visibility, web hashing,
+and web-based communication.
 
-> **Note**: Session management has been moved to `@walkeros/web-source-session`.
-> See the [session source package](../sources/session/README.md) for session
-> tracking.
+[Documentation](https://www.walkeros.io/docs) &bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/web-core) &bull;
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/core)
 
 ## Installation
 
-Import web utilities from the `@walkeros/web-core` package:
-
-```ts
-import { getAttribute, sendWeb, isVisible } from '@walkeros/web-core';
+```bash
+npm install @walkeros/web-core
 ```
 
-## Utilities
-
-### DOM Utilities
+## Quick start
 
-#### getAttribute
-
-`getAttribute(element: Element, name: string): string` retrieves attribute
-values from DOM elements with enhanced handling.
+```ts
+import { getAttribute, isVisible, sendWeb } from '@walkeros/web-core';
 
-```js
 const element = document.querySelector('[data-elb="product"]');
-const entityType = getAttribute(element, 'data-elb'); // Returns 'product'
-```
-
-#### Attribute Parsing
-
-##### splitAttribute
-
-`splitAttribute(str: string, separator?: string): string[]` splits attribute
-strings using specified separators.
-
-```js
-splitAttribute('id:123,name:shirt', ','); // Returns ['id:123', 'name:shirt']
-```
-
-##### splitKeyVal
-
-`splitKeyVal(str: string): [string, string]` splits key-value pairs from
-attribute strings.
-
-```js
-splitKeyVal('id:123'); // Returns ['id', '123']
-```
-
-##### parseInlineConfig
-
-`parseInlineConfig(str: string): Record<string, unknown>` parses inline
-configuration strings from HTML attributes.
-
-```js
-parseInlineConfig('{"tracking": true, "debug": false}');
-// Returns { tracking: true, debug: false }
-```
-
-### Browser Information
-
-#### getLanguage
-
-`getLanguage(navigatorRef: Navigator): string | undefined` extracts the user's
-preferred language.
-
-```js
-getLanguage(navigator); // Returns 'en-US' or user's language
-```
-
-#### getTimezone
-
-`getTimezone(): string | undefined` gets the user's timezone from the Intl API.
-
-```js
-getTimezone(); // Returns 'America/New_York' or user's timezone
-```
-
-#### getScreenSize
-
-`getScreenSize(windowRef: Window): string` returns the window's screen
-dimensions.
-
-```js
-getScreenSize(window); // Returns '1920x1080' or current screen size
-```
-
-### Element Visibility
-
-#### isVisible
-
-`isVisible(element: HTMLElement): boolean` checks if an element is visible to
-the user.
-
-```js
-const promoElement = document.getElementById('promotion');
-if (isVisible(promoElement)) {
-  // Element is visible on screen
-}
-```
-
-This function considers:
-
-- Element display and visibility styles
-- Element position within viewport
-- Parent element visibility
-- Intersection with the visible area
-
-### Storage Management
-
-#### Storage Operations
-
-##### storageRead
-
-`storageRead(key: string, storage?: StorageType): WalkerOS.PropertyType` reads
-data from browser storage with automatic type conversion.
-
-```js
-// Default uses sessionStorage
-const userId = storageRead('walker_user_id');
+const entity = getAttribute(element, 'data-elb');
 
-// Use localStorage
-const data = storageRead('data', 'local');
-```
-
-##### storageWrite
-
-`storageWrite(key: string, value: WalkerOS.PropertyType, maxAgeInMinutes?: number, storage?: StorageType, domain?: string): WalkerOS.PropertyType`
-writes data to storage with expiration and domain options.
-
-```js
-// Store with 30-minute expiration
-storageWrite('user_preference', 'dark-mode', 30);
-
-// Store in localStorage
-storageWrite('temp_data', { id: 123 }, undefined, 'local');
-
-// Store with custom domain for cookies
-storageWrite('tracking_id', 'abc123', 1440, 'cookie', '.example.com');
-```
-
-##### storageDelete
-
-`storageDelete(key: string, storage?: StorageType)` removes data from storage.
-
-```js
-storageDelete('expired_data');
-storageDelete('session_temp', 'local');
-```
-
-### Web Communication
-
-#### sendWeb
-
-`sendWeb<T>(url: string, data?: SendDataValue, options?: SendWebOptionsDynamic<T>): SendWebReturn<T>`
-sends data using various web transport methods.
-
-```js
-// Default fetch transport
-await sendWeb('https://api.example.com/events', eventData);
-
-// Use specific transport
-await sendWeb(url, data, { transport: 'beacon' });
-await sendWeb(url, data, { transport: 'xhr' });
-
-// With custom headers
-await sendWeb(url, data, {
-  headers: { Authorization: 'Bearer token' },
-  method: 'PUT',
-});
-```
-
-#### Transport-Specific Functions
-
-##### sendWebAsFetch
-
-`sendWebAsFetch(url: string, data?: SendDataValue, options?: SendWebOptionsFetch): Promise<SendResponse>`
-uses the modern Fetch API with advanced options.
-
-```js
-await sendWebAsFetch(url, data, {
-  credentials: 'include',
-  noCors: true,
-  headers: { 'Content-Type': 'application/json' },
-});
-```
-
-##### sendWebAsBeacon
-
-`sendWebAsBeacon(url: string, data?: SendDataValue): SendResponse` uses the
-Beacon API for reliable data transmission, especially during page unload.
-
-```js
-// Reliable sending during page unload
-window.addEventListener('beforeunload', () => {
-  sendWebAsBeacon('/analytics/pageview', { duration: Date.now() - startTime });
-});
-```
-
-##### sendWebAsXhr
-
-`sendWebAsXhr(url: string, data?: SendDataValue, options?: SendWebOptions): SendResponse`
-uses XMLHttpRequest for synchronous communication.
-
-```js
-// Synchronous request (blocks execution)
-const response = sendWebAsXhr(url, data, { method: 'POST' });
-```
-
-### Web Hashing
-
-#### getHashWeb
-
-`getHashWeb(str: string, length?: number): Promise<string>` generates SHA-256
-hashes using the Web Crypto API.
-
-```js
-// Generate hash for fingerprinting
-const userFingerprint = await getHashWeb(
-  navigator.userAgent + navigator.language + screen.width,
-  16,
-);
-// Returns shortened hash like '47e0bdd10f04ef13'
-```
-
-## Configuration Types
-
-### SendWebOptions
-
-```ts
-interface SendWebOptions {
-  headers?: Record<string, string>;
-  method?: string; // Default: 'POST'
-  transport?: 'fetch' | 'beacon' | 'xhr'; // Default: 'fetch'
-}
-
-interface SendWebOptionsFetch extends SendWebOptions {
-  credentials?: 'omit' | 'same-origin' | 'include';
-  noCors?: boolean;
+if (isVisible(element)) {
+  await sendWeb('https://api.example.com/events', { entity });
 }
 ```
 
-### StorageType
-
-```ts
-type StorageType = 'local' | 'session' | 'cookie';
-```
-
-## Usage Notes
-
-- **Consent Required**: Browser information functions may require user consent
-  depending on privacy regulations
-- **Transport Selection**: Choose transport based on use case:
-  - `fetch` - Modern, flexible, supports responses
-  - `beacon` - Reliable during page unload, small payloads
-  - `xhr` - Synchronous when needed, broader browser support
-
----
+## Documentation
 
-For platform-agnostic utilities, see
-[Core Utilities](https://www.walkeros.io/docs/core).
+Full configuration, mapping, and examples live in the docs:
+**https://www.walkeros.io/docs**
 
 ## Contribute
 
@@ -281,4 +47,4 @@ Feel free to contribute by submitting an
 
 ## License
 
-This project is licensed under the MIT License.
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@walkeros/web-core",
   "description": "Web-specific utilities for walkerOS",
-  "version": "4.1.0-next-1778668930820",
+  "version": "4.1.0",
   "license": "MIT",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -14,7 +14,8 @@
     }
   },
   "files": [
-    "dist/**"
+    "dist/**",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup --silent",
@@ -26,7 +27,7 @@
     "update": "npx npm-check-updates -u && npm update"
   },
   "devDependencies": {
-    "@walkeros/core": "4.1.0-next-1778668930820"
+    "@walkeros/core": "4.1.0"
   },
   "repository": {
     "url": "git+https://github.com/elbwalker/walkerOS.git",
@@ -50,6 +51,6 @@
     }
   ],
   "dependencies": {
-    "@walkeros/core": "4.1.0-next-1778668930820"
+    "@walkeros/core": "4.1.0"
   }
 }