@webticks/core 0.1.0 → 0.1.1

package/README.md

@@ -1,98 +1,62 @@
-# WebTicks Core - Usage Examples
+# @webticks/core
 
-## Browser Usage (No Changes Required!)
+Lightweight analytics library for modern web applications.
 
-Your existing React/Next.js packages continue to work exactly as before:
+## Installation
 
-```jsx
-import WebTicksAnalytics from '@webticks/react';
-
-function App() {
-  return (
-    <div>
-      <WebTicksAnalytics />
-      {/* Your app */}
-    </div>
-  );
-}
+```bash
+npm install @webticks/core
 ```
 
-## Server-Side Usage
-
-### Option 1: Express Middleware (Automatic)
+## Quick Start
 
 ```javascript
-import express from 'express';
-import { createServerMiddleware } from '@webticks/core/server';
-
-const app = express();
-
-// Automatically track all HTTP requests
-app.use(createServerMiddleware({
-  backendUrl: 'https://api.example.com/track'
-}));
+import inject from '@webticks/core';
 
-app.listen(3000);
+// Initialize analytics with explicit config
+inject({
+  backendUrl: 'https://your-api.com/track',
+  appId: 'your-app-id'
+});
 ```
 
-### Option 2: Manual Tracking
+## Best Practices: Environment Variables
 
-```javascript
-import { AnalyticsTracker } from '@webticks/core/tracker';
+For security and flexibility, it is **highly recommended** to source your configuration from environment variables rather than hardcoding them in your source code.
 
-const tracker = new AnalyticsTracker({
-  backendUrl: 'https://api.example.com/track'
+```javascript
+// Example using Vite or other modern bundlers
+inject({
+  backendUrl: import.meta.env.VITE_WEBTICKS_BACKEND_URL,
+  appId: import.meta.env.VITE_WEBTICKS_APP_ID
 });
 
-// Track server requests
-tracker.trackServerRequest({
-  method: 'GET',
-  path: '/api/users',
-  query: { page: 1 },
-  headers: { 'user-agent': 'Mozilla/5.0' }
+// Example using Node.js / Webpack
+inject({
+  backendUrl: process.env.WEBTICKS_BACKEND_URL,
+  appId: process.env.WEBTICKS_APP_ID
 });
+```
 
-// Track custom events
-tracker.trackEvent('database_query', {
-  table: 'users',
-  duration: 45
-});
+## Exports
 
-// Send immediately (useful for serverless)
-await tracker.sendQueue();
-```
+| Export | Description |
+|--------|-------------|
+| `@webticks/core` | Injector function (default) |
+| `@webticks/core/tracker` | `AnalyticsTracker` class for manual tracking |
 
-### Next.js Example
+## API
 
-```javascript
-// pages/api/users.js
-import { AnalyticsTracker } from '@webticks/core/tracker';
+### `inject(config)`
 
-const tracker = new AnalyticsTracker({
-  backendUrl: process.env.ANALYTICS_URL
-});
+| Option | Type | Description |
+|--------|------|-------------|
+| `backendUrl` | `string` | Recommended. URL to send analytics data to. Defaults to `/api/track`. |
+| `appId` | `string` | Required. Your application ID. |
 
-export default async function handler(req, res) {
-  tracker.trackServerRequest({
-    method: req.method,
-    path: req.url,
-    query: req.query,
-    headers: {
-      'user-agent': req.headers['user-agent']
-    }
-  });
-
-  // Your API logic here
-  const data = await getUsers();
-  
-  res.status(200).json(data);
-}
-```
+> [!NOTE]
+> `appId` and `backendUrl` are typically provided by the [webticks-api](https://github.com/Celerinc/webticks-api.git) project, which you can self-host. Alternatively, you can use any backend that implements the WebTicks ingestion API.
 
-## Key Benefits
+## License
 
-✅ **Centralized Logic**: All tracking logic lives in `@webticks/core`  
-✅ **Environment Agnostic**: Works in browser and Node.js  
-✅ **Zero Breaking Changes**: Existing packages work without modifications  
-✅ **Easy Updates**: Fix bugs once, all environments benefit  
-✅ **Flexible**: Works with any framework (Express, Koa, Fastify, serverless, etc.)
+[MPL-2.0](https://github.com/Celerinc/webticks/blob/main/LICENSE)

package/injector.js

@@ -1,6 +1,6 @@
 import { AnalyticsTracker } from "./tracker.js";
 
-export default function inject() {
+export default function inject(config = {}) {
   // Only auto-inject in browser environments
   if (typeof window === 'undefined') {
     console.warn("webticks auto-inject skipped: Not in a browser environment.");
@@ -12,10 +12,6 @@ export default function inject() {
     return;
   }
 
-  const config = {
-    backendUrl: "https://api.example.com/track"
-  };
-
   const tracker = new AnalyticsTracker(config);
   tracker.autoTrackPageViews();
   window.webticks = tracker;

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@webticks/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Lightweight analytics library for modern web applications with seamless event tracking and page view monitoring",
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "injector.js",
   "module": "injector.js",
   "exports": {

package/tracker.js

@@ -15,11 +15,10 @@ export class AnalyticsTracker {
    * @param {string} config.backendUrl - URL to send analytics data
    * @param {string} [config.appId] - Application ID for tracking (can also be set via WEBTICKS_APP_ID env variable)
    */
-  constructor(config) {
-    this.config = config || { backendUrl: "/api/track" };
-
-    // Get appId from config or environment variable
-    this.appId = this.config.appId || this.getAppIdFromEnv();
+  constructor(config = {}) {
+    this.config = config;
+    this.backendUrl = config.backendUrl || "/api/track";
+    this.appId = config.appId || null;
 
     /** @type {Event[]} */
     this.eventQueue = [];
@@ -44,22 +43,6 @@ export class AnalyticsTracker {
     console.log(`AnalyticsTracker initialized in ${isServer() ? 'Node.js' : 'Browser'} environment.`);
   }
 
-  /**
-   * Get app ID from environment variable
-   * Works in both browser (import.meta.env) and Node.js (process.env)
-   */
-  getAppIdFromEnv() {
-    // Browser environment (Vite, etc.)
-    if (typeof import.meta !== 'undefined' && import.meta.env) {
-      return import.meta.env.VITE_WEBTICKS_APP_ID || import.meta.env.WEBTICKS_APP_ID;
-    }
-    // Node.js environment
-    if (typeof process !== 'undefined' && process.env) {
-      return process.env.WEBTICKS_APP_ID;
-    }
-    return null;
-  }
-
   initializeUser() {
     // Skip if adapter is not available (will be initialized later in server environments)
     if (!this.adapter) {
@@ -226,7 +209,7 @@ export class AnalyticsTracker {
     const eventsToSend = [...this.eventQueue];
 
     try {
-      const response = await this.adapter.sendRequest(this.config.backendUrl, {
+      const response = await this.adapter.sendRequest(this.backendUrl, {
         uid: this.userId,
         sessionId: this.sessionId,
         events: eventsToSend,