@walkeros/web-source-browser 0.0.0-next-20251219153324

package/README.md

@@ -0,0 +1,142 @@
+<p align="left">
+  <a href="https://www.walkeros.io">
+    <img title="elbwalker" src='https://www.walkeros.io/img/elbwalker_logo.png' width="256px"/>
+  </a>
+</p>
+
+# Browser DOM Source for walkerOS
+
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/sources/browser)
+&bull; [NPM Package](https://www.npmjs.com/package/@walkeros/web-source-browser)
+
+The Browser Source is walkerOS's primary web tracking solution that you can use
+to capture user interactions directly from the browsers DOM.
+
+## Quick Start
+
+```bash
+npm install @walkeros/web-source-browser
+```
+
+```typescript
+import { sourceBrowser } from '@walkeros/web-source-browser';
+await startFlow({ sources: { browser: { code: sourceBrowser } } });
+```
+
+## What It Does
+
+The Browser Source transforms your website into a comprehensive tracking
+environment by:
+
+- **Data attribute reading**: Extracts custom tracking data from HTML `data-elb`
+  attributes
+- **Session management**: Detects and handles user sessions automatically
+
+## Installation
+
+### With npm
+
+Install the source via npm:
+
+```bash
+npm install @walkeros/web-source-browser
+```
+
+Setup in your project:
+
+```javascript
+import { startFlow } from '@walkeros/collector';
+import { sourceBrowser } from '@walkeros/web-source-browser';
+
+const { collector } = await startFlow({
+  sources: {
+    browser: {
+      code: sourceBrowser,
+      config: {
+        settings: {
+          pageview: true,
+          session: true,
+          elb: 'elb', // Browser source will set window.elb automatically
+        },
+      },
+    },
+  },
+});
+```
+
+### With a script tag
+
+Load the source via dynamic import:
+
+```html
+<script>
+  // Load the collector and source
+  const { startFlow } = await import(
+    'https://cdn.jsdelivr.net/npm/@walkeros/collector/dist/index.mjs'
+  );
+  const { sourceBrowser } = await import(
+    'https://cdn.jsdelivr.net/npm/@walkeros/web-source-browser/dist/index.mjs'
+  );
+
+  const { collector, elb } = await startFlow({
+    sources: {
+      browser: {
+        code: sourceBrowser,
+        config: {
+          settings: {
+            prefix: 'data-elb',
+            pageview: true,
+            session: true,
+          },
+        },
+      },
+    },
+  });
+</script>
+```
+
+## Configuration reference
+
+| Name       | Type                             | Description                                      | Required | Example                          |
+| ---------- | -------------------------------- | ------------------------------------------------ | -------- | -------------------------------- |
+| `prefix`   | `string`                         | Prefix for data attributes used in DOM tracking  | No       | `'data-elb'`                     |
+| `scope`    | `Element \| Document`            | DOM scope for event tracking (default: document) | No       | `document.querySelector("#app")` |
+| `pageview` | `boolean`                        | Enable automatic pageview tracking               | No       | `true`                           |
+| `session`  | `boolean`                        | Enable session tracking and management           | No       | `true`                           |
+| `elb`      | `string`                         | Custom name for the global elb function          | No       | `'elb'`                          |
+| `name`     | `string`                         | Custom name for the browser source instance      | No       | `'mySource'`                     |
+| `elbLayer` | `boolean \| string \| Elb.Layer` | Enable elbLayer for async command queuing        | No       | `true`                           |
+
+### elb
+
+> **Two Different elb Functions**
+>
+> The collector provides **two different elb functions**:
+>
+> 1.  **Collector elb** (`elb` from `startFlow`): Basic event tracking that
+>     works with all sources and destinations
+> 2.  **Browser Source elb** (`collector.sources.browser.elb`): Enhanced
+>     function with browser-specific features
+>
+> **Browser Source elb adds:**
+>
+> - **DOM Commands**: `walker init` for asynchronous loading of DOM elements
+> - **Flexible Arguments**: Support for multiple argument patterns
+> - **elbLayer Integration**: Automatic processing of queued commands
+> - **Element parameters**: Support for element parameters in DOM commands
+>
+> Access the enhanced elb via `collector.sources.browser.elb`.
+>
+> See [Commands](https://www.walkeros.io/docs/sources/web/browser/commands) for
+> full browser source API documentation.
+
+## Contribute
+
+Feel free to contribute by submitting an
+[issue](https://github.com/elbwalker/walkerOS/issues), starting a
+[discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
+[contact](https://calendly.com/elb-alexander/30min).
+
+## License
+
+This project is licensed under the MIT License.

package/dist/dev.d.mts

@@ -0,0 +1,59 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+
+/**
+ * Data attribute prefix
+ * Used for DOM event tracking
+ */
+declare const DataAttributePrefix: z.ZodString;
+/**
+ * JavaScript variable name
+ * Used for global function names
+ */
+declare const JavaScriptVarName: z.ZodString;
+/**
+ * DOM scope selector
+ * Note: Runtime type is Element | Document (non-serializable)
+ */
+declare const ScopeSelector: z.ZodOptional<z.ZodString>;
+
+/**
+ * Browser source settings schema
+ */
+declare const SettingsSchema: z.ZodObject<{
+    prefix: z.ZodDefault<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    pageview: z.ZodDefault<z.ZodBoolean>;
+    session: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodAny]>>;
+    elb: z.ZodDefault<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    elbLayer: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString, z.ZodAny]>>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+/**
+ * Tagger configuration schema
+ * Used for automatic data attribute generation
+ */
+declare const TaggerSchema: z.ZodObject<{
+    prefix: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+type TaggerConfig = z.infer<typeof TaggerSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const tagger: _walkeros_core_dev.JSONSchema;
+
+declare const index_DataAttributePrefix: typeof DataAttributePrefix;
+declare const index_JavaScriptVarName: typeof JavaScriptVarName;
+declare const index_ScopeSelector: typeof ScopeSelector;
+type index_Settings = Settings;
+declare const index_SettingsSchema: typeof SettingsSchema;
+type index_TaggerConfig = TaggerConfig;
+declare const index_TaggerSchema: typeof TaggerSchema;
+declare const index_settings: typeof settings;
+declare const index_tagger: typeof tagger;
+declare namespace index {
+  export { index_DataAttributePrefix as DataAttributePrefix, index_JavaScriptVarName as JavaScriptVarName, index_ScopeSelector as ScopeSelector, type index_Settings as Settings, index_SettingsSchema as SettingsSchema, type index_TaggerConfig as TaggerConfig, index_TaggerSchema as TaggerSchema, index_settings as settings, index_tagger as tagger };
+}
+
+export { index as schemas };

package/dist/dev.d.ts

@@ -0,0 +1,59 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+
+/**
+ * Data attribute prefix
+ * Used for DOM event tracking
+ */
+declare const DataAttributePrefix: z.ZodString;
+/**
+ * JavaScript variable name
+ * Used for global function names
+ */
+declare const JavaScriptVarName: z.ZodString;
+/**
+ * DOM scope selector
+ * Note: Runtime type is Element | Document (non-serializable)
+ */
+declare const ScopeSelector: z.ZodOptional<z.ZodString>;
+
+/**
+ * Browser source settings schema
+ */
+declare const SettingsSchema: z.ZodObject<{
+    prefix: z.ZodDefault<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    pageview: z.ZodDefault<z.ZodBoolean>;
+    session: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodAny]>>;
+    elb: z.ZodDefault<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    elbLayer: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString, z.ZodAny]>>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+/**
+ * Tagger configuration schema
+ * Used for automatic data attribute generation
+ */
+declare const TaggerSchema: z.ZodObject<{
+    prefix: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+type TaggerConfig = z.infer<typeof TaggerSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const tagger: _walkeros_core_dev.JSONSchema;
+
+declare const index_DataAttributePrefix: typeof DataAttributePrefix;
+declare const index_JavaScriptVarName: typeof JavaScriptVarName;
+declare const index_ScopeSelector: typeof ScopeSelector;
+type index_Settings = Settings;
+declare const index_SettingsSchema: typeof SettingsSchema;
+type index_TaggerConfig = TaggerConfig;
+declare const index_TaggerSchema: typeof TaggerSchema;
+declare const index_settings: typeof settings;
+declare const index_tagger: typeof tagger;
+declare namespace index {
+  export { index_DataAttributePrefix as DataAttributePrefix, index_JavaScriptVarName as JavaScriptVarName, index_ScopeSelector as ScopeSelector, type index_Settings as Settings, index_SettingsSchema as SettingsSchema, type index_TaggerConfig as TaggerConfig, index_TaggerSchema as TaggerSchema, index_settings as settings, index_tagger as tagger };
+}
+
+export { index as schemas };