{"id":42720985,"url":"https://github.com/dagota12/omni-sdk","last_synced_at":"2026-01-29T16:10:49.635Z","repository":{"id":328366819,"uuid":"1112625723","full_name":"dagota12/omni-sdk","owner":"dagota12","description":"A highly extensible, analytics SDK for deep website usage analysis. Deploy as an NPM package ","archived":false,"fork":false,"pushed_at":"2025-12-21T13:52:44.000Z","size":8820,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-21T21:45:55.678Z","etag":null,"topics":["analytics","sdk","web"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dagota12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-08T22:10:01.000Z","updated_at":"2025-12-20T13:38:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dagota12/omni-sdk","commit_stats":null,"previous_names":["dagota12/omni-sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dagota12/omni-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagota12%2Fomni-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagota12%2Fomni-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagota12%2Fomni-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagota12%2Fomni-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dagota12","download_url":"https://codeload.github.com/dagota12/omni-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagota12%2Fomni-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28880972,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T10:31:27.438Z","status":"ssl_error","status_checked_at":"2026-01-29T10:31:01.017Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","sdk","web"],"created_at":"2026-01-29T16:10:48.840Z","updated_at":"2026-01-29T16:10:49.627Z","avatar_url":"https://github.com/dagota12.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Omni Analytics SDK\n\nA highly extensible, SOLID-principled analytics SDK for deep website usage analysis. Deploy as an NPM package or via CDN snippet.\n\n```\n███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██████╗ ███████╗\n██╔════╝██║██╔════╝ ████╗  ██║██╔══██╗██╔══██╗██╔════╝\n███████╗██║██║  ███╗██╔██╗ ██║███████║██║  ██║███████╗\n╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║  ██║╚════██║\n███████║██║╚██████╔╝██║ ╚████║██║  ██║██████╔╝███████║\n╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚═════╝ ╚══════╝\n\nOmni Analytics SDK\n```\n\n## 🚀 Quick Start\n\n```typescript\nimport { initializeSDK } from \"@omni-analytics/sdk\";\n\nconst { tracker } = initializeSDK({\n  projectId: \"my-project\",\n  endpoint: \"https://api.example.com/events\",\n});\n\n// That's it! The SDK automatically tracks:\n// ✅ Page views\n// ✅ User clicks with heatmap data\n// ✅ SPA navigation\n// ✅ Sessions and users\n```\n\n## 📦 What's Included\n\n### Core SDK (`@omni-analytics/sdk`)\n\n- ✅ Automatic page view tracking\n- ✅ Automatic click tracking with coordinates \u0026 selectors\n- ✅ SPA navigation support\n- ✅ Session management\n- ✅ Event batching \u0026 transmission\n- ✅ Multiple transmitter strategies (Fetch + Beacon)\n- ✅ Plugin system for extensibility\n- ✅ Full TypeScript support\n\n### React Integration (`@omni-analytics/react`)\n\n- ✅ `TrackerProvider` context\n- ✅ `useTracker` hook\n- ✅ Seamless React integration\n\n### Documentation\n\n- 📚 [Getting Started](./docs/GETTING_STARTED.md)\n- 📖 [API Reference](./docs/API_REFERENCE.md)\n- 🏗️ [Architecture](./docs/ARCHITECTURE.md)\n- 🔌 [Plugin Development](./docs/PLUGIN_DEVELOPMENT.md)\n\n## 🎯 Key Features\n\n### Automatic Tracking\n\nInitialize once and get:\n\n- Initial page loads\n- SPA route changes (via history.pushState)\n- All user clicks with X,Y coordinates\n- Element selectors (CSS \u0026 XPath)\n- Session tracking\n- Automatic data batching\n\n### Smart Transmission\n\n- Batch events (configurable size \u0026 timeout)\n- Fetch API with automatic retry\n- Beacon API fallback for page unload\n- Exponential backoff on failure\n\n### Plugin System\n\nExtend functionality with plugins:\n\n```typescript\nclass MyPlugin implements IPlugin {\n  name = \"my-plugin\";\n  version = \"1.0.0\";\n\n  async init(context: PluginContext) {\n    // Track custom events\n    context.tracker.trackCustom(\"my-event\", {});\n  }\n}\n```\n\n### React Ready\n\n```typescript\nimport { TrackerProvider, useTracker } from \"@omni-analytics/react\";\n\nfunction App() {\n  return (\n    \u003cTrackerProvider tracker={tracker}\u003e\n      \u003cMyComponent /\u003e\n    \u003c/TrackerProvider\u003e\n  );\n}\n\nfunction MyComponent() {\n  const tracker = useTracker();\n  return \u003cbutton onClick={() =\u003e tracker.trackCustom(\"clicked\")}\u003eClick\u003c/button\u003e;\n}\n```\n\n## 📊 Event Data\n\nEvents include:\n\n- Unique event ID\n- Project \u0026 client ID\n- Session \u0026 user ID\n- Event type (pageview/click/custom)\n- Timestamp\n- Page URL \u0026 referrer\n- Page \u0026 viewport dimensions\n- For clicks: coordinates, selectors, element info\n- Custom properties\n\nExample click event:\n\n```json\n{\n  \"type\": \"click\",\n  \"pageX\": 123,\n  \"pageY\": 456,\n  \"selector\": \"body \u003e main \u003e button.cta\",\n  \"xpath\": \"/body/main/button[1]\",\n  \"tagName\": \"button\"\n}\n```\n\n## 🏗️ Architecture (SOLID)\n\nBuilt with SOLID principles:\n\n| Principle | Implementation                        |\n| --------- | ------------------------------------- |\n| **S**RP   | Each module has single responsibility |\n| **O**CP   | Plugins extend without modifying core |\n| **L**SP   | Transmitters are interchangeable      |\n| **I**SP   | Minimal, focused interfaces           |\n| **D**IP   | DI container manages all dependencies |\n\nSee [Architecture](./docs/ARCHITECTURE.md) for details.\n\n## 📦 Installation\n\n### NPM\n\n```bash\nnpm install @omni-analytics/sdk @omni-analytics/react\n```\n\n### PNPM\n\n```bash\npnpm add @omni-analytics/sdk @omni-analytics/react\n```\n\n### Yarn\n\n```bash\nyarn add @omni-analytics/sdk @omni-analytics/react\n```\n\n### CDN\n\n```html\n\u003cscript src=\"https://cdn.example.com/omni-analytics.umd.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const { initializeSDK } = window.OmniAnalytics;\n  initializeSDK({\n    projectId: \"my-project\",\n    endpoint: \"https://api.example.com/events\",\n  });\n\u003c/script\u003e\n```\n\n## 🚀 Usage Examples\n\n### Basic Initialization\n\n```typescript\nimport { initializeSDK } from \"@omni-analytics/sdk\";\n\nconst { tracker } = initializeSDK({\n  projectId: \"my-project\",\n  endpoint: \"https://api.example.com/events\",\n});\n```\n\n### Custom Event Tracking\n\n```typescript\ntracker.trackCustom(\"user-signup\", {\n  plan: \"premium\",\n  source: \"homepage\",\n});\n```\n\n### User Management\n\n```typescript\n// After login\ntracker.setUserId(\"user-123\");\n\n// After logout\ntracker.setUserId(null);\ntracker.newSession();\n```\n\n### React Integration\n\n```typescript\nimport { initializeSDK } from \"@omni-analytics/sdk\";\nimport { TrackerProvider, useTracker } from \"@omni-analytics/react\";\n\nconst { tracker } = initializeSDK({\n  projectId: \"my-project\",\n  endpoint: \"https://api.example.com/events\",\n});\n\nfunction App() {\n  return (\n    \u003cTrackerProvider tracker={tracker}\u003e\n      \u003cYourApp /\u003e\n    \u003c/TrackerProvider\u003e\n  );\n}\n```\n\n### Custom Plugin\n\n```typescript\nimport { IPlugin, PluginContext } from \"@omni-analytics/sdk\";\n\nclass FormTrackingPlugin implements IPlugin {\n  name = \"form-tracking\";\n  version = \"1.0.0\";\n\n  async init(context: PluginContext) {\n    document.addEventListener(\"submit\", (e) =\u003e {\n      const form = e.target as HTMLFormElement;\n      context.tracker.trackCustom(\"form-submitted\", {\n        formId: form.id,\n        fields: form.elements.length,\n      });\n    });\n  }\n\n  async destroy() {}\n}\n```\n\n## 📈 Event Batching\n\nEvents are automatically batched for efficiency:\n\n```typescript\nconst { tracker } = initializeSDK({\n  projectId: \"my-project\",\n  endpoint: \"https://api.example.com/events\",\n  batchSize: 50, // Send after 50 events\n  batchTimeout: 10000, // Or after 10 seconds\n});\n```\n\n## 🐛 Debug Mode\n\nEnable debug logging:\n\n```typescript\nconst { tracker } = initializeSDK({\n  projectId: \"my-project\",\n  endpoint: \"https://api.example.com/events\",\n  debug: true,\n});\n\n// Console output:\n// [OmniSDK] Config initialized: {...}\n// [Tracker] Tracking event: {...}\n// [EventQueue] Flushing batch: 50 events\n```\n\n## 📚 Documentation\n\n- **[Getting Started](./docs/GETTING_STARTED.md)** - Beginner's guide\n- **[API Reference](./docs/API_REFERENCE.md)** - Complete API docs\n- **[Architecture](./docs/ARCHITECTURE.md)** - Design \u0026 internals\n- **[Plugin Development](./docs/PLUGIN_DEVELOPMENT.md)** - Create plugins\n\n## 🤝 Workspace Structure\n\n```\nomni-sdk/\n├── packages/\n│   ├── sdk/              # Core SDK\n│   │   └── src/\n│   │       ├── config/\n│   │       ├── di/\n│   │       ├── plugins/\n│   │       ├── queue/\n│   │       ├── session/\n│   │       ├── tracker/\n│   │       ├── transmitter/\n│   │       ├── types/\n│   │       └── utils/\n│   ├── react/            # React integration\n│   │   └── src/\n│   │       ├── context/\n│   │       ├── hooks/\n│   │       └── index.ts\n│   └── test-app/         # Example app\n├── docs/                 # Documentation\n└── rollup.config.js      # Build config\n```\n\n## 🛠️ Development\n\n### Setup\n\n```bash\npnpm install\n```\n\n### Build\n\n```bash\npnpm build\n```\n\n### Watch Mode\n\n```bash\npnpm dev\n```\n\n### Build Output\n\n- **CJS** - `packages/sdk/dist/index.cjs.js` (Node.js, bundlers)\n- **ESM** - `packages/sdk/dist/index.esm.js` (Modern bundlers)\n- **UMD** - `packages/sdk/dist/index.umd.js` (Browser, CDN)\n- **Types** - `packages/sdk/dist/index.d.ts` (TypeScript)\n\n## 📊 Performance\n\n| Metric        | Value                    |\n| ------------- | ------------------------ |\n| SDK Init      | \u003c5ms                     |\n| Event Track   | \u003c1ms                     |\n| Batch Size    | 50 events (default)      |\n| Batch Timeout | 10 seconds (default)     |\n| Bundle Size   | 16KB (minified, gzipped) |\n| Memory/Event  | ~200 bytes               |\n\n## 🌐 Browser Support\n\n- Chrome 60+\n- Firefox 55+\n- Safari 11+\n- Edge 79+\n\n## ✅ Features Status\n\n- [x] Core SDK architecture\n- [x] Automatic page view tracking\n- [x] Automatic click tracking\n- [x] Event batching\n- [x] Session management\n- [x] Plugin system\n- [x] React integration\n- [x] TypeScript support\n- [x] Multiple transmitters\n- [x] Documentation\n- [ ] Jest unit tests\n- [ ] E2E tests\n- [ ] Example applications\n\n## 🔮 Roadmap\n\n- Custom event serialization\n- Event sampling\n- Performance metrics collection\n- Error tracking\n- Redux middleware\n- Vue integration\n- Svelte integration\n- Analytics dashboard\n\n## 📄 License\n\nISC\n\n## 🤝 Contributing\n\nContributions welcome! Please:\n\n1. Follow SOLID principles\n2. Add tests for new features\n3. Update documentation\n4. Keep bundle size small\n\n## 📧 Support\n\n- Email: support@example.com\n- Issues: GitHub Issues\n- Discussions: GitHub Discussions\n\n---\n\n**Made with ❤️ for analytics**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdagota12%2Fomni-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdagota12%2Fomni-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdagota12%2Fomni-sdk/lists"}