@compilacion/colleciones-clientos 1.0.0 → 1.0.4
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.
- package/README.md +112 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,3 +1,114 @@
|
|
|
1
1
|
npm run dev:testclient
|
|
2
2
|
|
|
3
|
-
zever gezever
|
|
3
|
+
zever gezever
|
|
4
|
+
# @compilacion/colleciones-clientos
|
|
5
|
+
|
|
6
|
+
A minimal, semantic-aware tracking client for compiling and emitting structured event data, designed for clean integration with web applications.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## ✨ Why this package?
|
|
11
|
+
|
|
12
|
+
This package provides a modular, semantically structured way to track events in a browser or Node.js context. It introduces an expressive abstraction over raw event logging, allowing you to:
|
|
13
|
+
|
|
14
|
+
- Build meaningful tracking data using domain and semantic context
|
|
15
|
+
- Manage event batching and network traffic efficiently
|
|
16
|
+
- Decouple semantic structure from transport
|
|
17
|
+
- Keep client-side tracking logic testable and declarative
|
|
18
|
+
|
|
19
|
+
### About "semantic" events
|
|
20
|
+
|
|
21
|
+
We use a consistent structure: `entity`, `action`, and `adjective`. This allows us to describe events like:
|
|
22
|
+
|
|
23
|
+
- `"session" "start" "engaged"`
|
|
24
|
+
- `"property" "display" "preview"`
|
|
25
|
+
|
|
26
|
+
This semantic approach gives us flexibility and consistency across tracking implementations.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 🚀 Usage
|
|
31
|
+
|
|
32
|
+
You can run the [manual runner](./test/manual-runner.js) to test locally:
|
|
33
|
+
```bash
|
|
34
|
+
npm run manual-runner
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Example
|
|
38
|
+
|
|
39
|
+
```js
|
|
40
|
+
import CollecionesEmitter from '../src/CollecionesEmitter.js';
|
|
41
|
+
import CollecionesTracker from '../src/CollecionesTracker.js';
|
|
42
|
+
import CollecionesSemanticCollectionEvent from '../src/CollecionesSemanticCollectionEvent.js';
|
|
43
|
+
|
|
44
|
+
// Setup
|
|
45
|
+
let emitter = new CollecionesEmitter('http://localhost:8080/collect', 3, 10);
|
|
46
|
+
let tracker = new CollecionesTracker([emitter], 'myTracker', 'theWebsiteApp');
|
|
47
|
+
tracker.addIdentifier('visitorId', '12');
|
|
48
|
+
|
|
49
|
+
// Create semantic collection event
|
|
50
|
+
let eC = new CollecionesSemanticCollectionEvent(
|
|
51
|
+
'property',
|
|
52
|
+
'display',
|
|
53
|
+
'preview'
|
|
54
|
+
);
|
|
55
|
+
|
|
56
|
+
eC.addEntityIdentifier('serpPage', 1234);
|
|
57
|
+
eC.addAttribute('pageUrl', 'https://');
|
|
58
|
+
eC.addEntityItemIdentifier('propertyId', 1);
|
|
59
|
+
eC.addEntityItemIdentifier('propertyId', 2);
|
|
60
|
+
eC.addEntityItemIdentifier('propertyId', 3);
|
|
61
|
+
eC.addEntityItemIdentifier('propertyId', [4, 5, 6]);
|
|
62
|
+
|
|
63
|
+
console.log(eC.getPayload());
|
|
64
|
+
tracker.track(eC);
|
|
65
|
+
|
|
66
|
+
// Send events
|
|
67
|
+
emitter.flush();
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## 🛠 Branching model
|
|
73
|
+
|
|
74
|
+
This project uses a dual-branch setup:
|
|
75
|
+
|
|
76
|
+
- `uat`: the **staging branch**. All feature work should merge into this first.
|
|
77
|
+
- `main`: the **release branch**, protected and only updated via pull requests from `uat`.
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## ⚙️ CI/CD Setup
|
|
82
|
+
|
|
83
|
+
We use GitHub Actions:
|
|
84
|
+
|
|
85
|
+
- PRs to `uat` and `main` trigger the `build-and-test` job.
|
|
86
|
+
- Version tags (e.g. `v1.2.0`) trigger the `release` job.
|
|
87
|
+
|
|
88
|
+
Only PRs to `main` from `uat` should be used to promote code to production.
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## 📦 Release process
|
|
93
|
+
|
|
94
|
+
To publish a new version:
|
|
95
|
+
|
|
96
|
+
1. Merge to `main` via PR from `uat`
|
|
97
|
+
2. Go to **GitHub → Releases → Draft a new release**
|
|
98
|
+
3. Create a tag (e.g. `v1.0.1`)
|
|
99
|
+
4. Target the `main` branch
|
|
100
|
+
5. Publish the release
|
|
101
|
+
|
|
102
|
+
GitHub Actions will:
|
|
103
|
+
- Build the package
|
|
104
|
+
- Publish to npm
|
|
105
|
+
|
|
106
|
+
The package is published as:
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
@compilacion/colleciones-clientos
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
If you encounter issues with scope or publishing, ensure your npm org is set up and the scope `@compilacion` is correctly authorized.
|
|
113
|
+
|
|
114
|
+
---
|