@compilacion/colleciones-clientos 1.0.12 → 2.0.0

package/README.md

@@ -1,114 +1,76 @@
-npm run dev:testclient
+# Colleciones
 
-zever gezever
-# @compilacion/colleciones-clientos
-
-A minimal, semantic-aware tracking client for compiling and emitting structured event data, designed for clean integration with web applications.
+**Colleciones** is a structured, semantic tracking framework that lets you describe and dispatch events with clarity and precision. It introduces a fluent event model that is both developer-friendly and analytics-ready.
 
 ---
 
-## ✨ Why this package?
-
-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:
-
-- Build meaningful tracking data using domain and semantic context
-- Manage event batching and network traffic efficiently
-- Decouple semantic structure from transport
-- Keep client-side tracking logic testable and declarative
-
-### About "semantic" events
-
-We use a consistent structure: `entity`, `action`, and `adjective`. This allows us to describe events like:
+## Why Colleciones?
 
-- `"session" "start" "engaged"`
-- `"property" "display" "preview"`
+Most tracking systems suffer from inconsistent event naming and arbitrary structure. Colleciones solves this by building events around a shared semantic structure — entity, action, actor, context, and references — modeled as natural-language chains or structured code.
 
-This semantic approach gives us flexibility and consistency across tracking implementations.
+📖 See [docs/concept.md](./docs/concept.md) for the full background.
 
 ---
 
-## 🚀 Usage
+## How to Use It
 
-You can run the [manual runner](./test/manual-runner.js) to test locally:
-```bash
-npm run manual-runner
-```
+### 1. Create an Emitter
 
-### Example
+An emitter is responsible for collecting and sending events to a server.
 
 ```js
-import CollecionesEmitter from '../src/CollecionesEmitter.js';
-import CollecionesTracker from '../src/CollecionesTracker.js';
-import CollecionesSemanticCollectionEvent from '../src/CollecionesSemanticCollectionEvent.js';
-
-// Setup
-let emitter = new CollecionesEmitter('http://localhost:8080/collect', 3, 10);
-let tracker = new CollecionesTracker([emitter], 'myTracker', 'theWebsiteApp');
-tracker.addIdentifier('visitorId', '12');
-
-// Create semantic collection event
-let eC = new CollecionesSemanticCollectionEvent(
-  'property',
-  'display',
-  'preview'
-);
-
-eC.addEntityIdentifier('serpPage', 1234);
-eC.addAttribute('pageUrl', 'https://');
-eC.addEntityItemIdentifier('propertyId', 1);
-eC.addEntityItemIdentifier('propertyId', 2);
-eC.addEntityItemIdentifier('propertyId', 3);
-eC.addEntityItemIdentifier('propertyId', [4, 5, 6]);
-
-console.log(eC.getPayload());
-tracker.track(eC);
-
-// Send events
-emitter.flush();
-```
+import { CollecionesEmitter } from './index.js';
 
----
-
-## 🛠 Branching model
+const emitter = new CollecionesEmitter('/collect', 5, 10000);
+```
 
-This project uses a dual-branch setup:
+### 2. Create a Tracker
 
-- `uat`: the **staging branch**. All feature work should merge into this first.
-- `main`: the **release branch**, protected and only updated via pull requests from `uat`.
+A tracker enriches and routes events to one or more emitters.
 
----
+```js
+import { CollecionesTracker } from './index.js';
 
-## ⚙️ CI/CD Setup
+const tracker = new CollecionesTracker([emitter], 'myTracker', 'myApp');
+```
 
-We use GitHub Actions:
+### 3. Build Events with the DSL
 
-- PRs to `uat` and `main` trigger the `build-and-test` job.
-- Version tags (e.g. `v1.2.0`) trigger the `release` job.
+You can construct events declaratively using a natural language-like DSL:
 
-Only PRs to `main` from `uat` should be used to promote code to production.
+```js
+import collecionesDsl from './src/collecionesDsl.js';
 
----
+collecionesDsl
+  .the('red')
+  ._('button')
+  .has.been('clicked')
+  .then.track.with(emitter);
+```
 
-## 📦 Release process
+📘 See [docs/dsl.md](./docs/dsl.md) for full DSL documentation.
 
-To publish a new version:
+### 4. Manually Create Events (Optional)
 
-1. Merge to `main` via PR from `uat`
-2. Go to **GitHub → Releases → Draft a new release**
-3. Create a tag (e.g. `v1.0.1`)
-4. Target the `main` branch
-5. Publish the release
+You can also build structured events directly via the event class:
 
-GitHub Actions will:
-- Build the package
-- Publish to npm
+```js
+import { CollecionesEvent } from './index.js';
 
-The package is published as:
+const event = new CollecionesEvent();
+event.setEntity('form');
+event.setAction('submitted');
+event.setIdentifier('formId', 'abc123');
 
+tracker.track(event);
 ```
-@compilacion/colleciones-clientos
-```
 
-If you encounter issues with scope or publishing, ensure your npm org is set up and the scope `@compilacion` is correctly authorized.
+---
+
+## Learn More
 
----
+- 🧠 [Concept](./docs/concept.md)
+- 🏗️ [Architecture](./docs/architecture.md)
+- 🔄 [Emitters & Trackers](./docs/emitterAndTracker.md)
+- ✍️ [DSL Syntax](./docs/dsl.md)
+- 📦 [Event Structure](./docs/events.md)