drtrace 0.3.0 → 0.4.0

package/README.md

@@ -23,7 +23,7 @@ This runs an interactive setup wizard that creates the `_drtrace/` configuration
 - Configuration guide (`README.md`)
 - Default agent specification
 
-### Manual Client Integration
+### Node.js Usage
 
 ```typescript
 import { DrTrace } from 'drtrace';
@@ -39,7 +39,6 @@ const client = DrTrace.init();
 //   flushIntervalMs: 1000,
 //   maxRetries: 3,
 //   maxQueueSize: 10000,
-//   timeoutMs: 5000,
 // });
 
 // Attach to console
@@ -50,6 +49,48 @@ console.log('This is captured by DrTrace');
 console.error('Errors are also captured');
 ```
 
+### Browser Usage (React, Vue, etc.)
+
+In browser environments, you must provide `applicationId` and `daemonUrl` explicitly since the browser cannot read config files from the filesystem.
+
+```typescript
+import { DrTrace } from 'drtrace';  // Auto-selects browser entry point
+
+// Browser requires explicit options (no config file loading)
+const client = DrTrace.init({
+  applicationId: 'my-react-app',
+  daemonUrl: 'http://localhost:8001',
+  moduleName: 'frontend',  // Optional: helps identify log source
+  batchSize: 50,
+  flushIntervalMs: 1000,
+});
+
+// Attach to console
+client.attachToConsole();
+
+// Objects are serialized properly
+console.log({ user: 'john', action: 'login' });  // Logs as JSON
+console.error('Something went wrong', new Error('Details'));
+```
+
+**Important for Browser:**
+- `applicationId` is **required** - throws error if missing
+- `daemonUrl` is **required** - throws error if missing
+- CORS must be enabled on the daemon (enabled by default)
+- Objects and errors are automatically serialized to JSON
+
+#### CORS Configuration
+
+The DrTrace daemon allows all origins by default. To restrict origins:
+
+```bash
+# Allow specific origins
+export DRTRACE_CORS_ORIGINS="http://localhost:3000,https://myapp.com"
+
+# Start daemon
+uvicorn drtrace_service.api:app --host localhost --port 8001
+```
+
 ## Starting the DrTrace Daemon
 
 **Important**: The DrTrace daemon must be running before your application can send logs.
@@ -155,13 +196,13 @@ Create a new DrTrace client instance.
 
 **Options:**
 - `applicationId` (required) - Unique application identifier
-- `daemonUrl` (optional) - DrTrace daemon URL (default: `http://localhost:8001`)
+- `daemonUrl` (required in browser, optional in Node.js) - DrTrace daemon URL (default: `http://localhost:8001`)
+- `moduleName` (optional) - Module/component name for log grouping (default: `'default'`)
 - `enabled` (optional) - Enable/disable DrTrace (default: `true`)
 - `batchSize` (optional) - Batch size for log batching (default: `50`)
 - `flushIntervalMs` (optional) - Flush interval in milliseconds (default: `1000`)
 - `maxRetries` (optional) - Retry attempts for failed sends with exponential backoff (default: `3`)
 - `maxQueueSize` (optional) - Maximum queued log entries before oldest entries are dropped (default: `10000`)
-- `timeoutMs` (optional) - Request timeout per batch in milliseconds (default: `5000`)
 
 ### `client.attachToConsole()`
 

package/agents/daemon-method-selection.md

@@ -288,6 +288,78 @@ def interact_with_daemon(query: str) -> str:
 
 ---
 
+## Important: Timestamps Are UTC
+
+All timestamps in DrTrace API are **UTC Unix timestamps**:
+
+| Field/Param | Format | Timezone |
+|-------------|--------|----------|
+| `ts` (in logs) | Unix float | UTC |
+| `start_ts`, `end_ts` | Unix float | UTC |
+| `since`, `until` | Relative or ISO 8601 | UTC |
+
+**Key Rules**:
+- ISO 8601 without timezone (e.g., `2025-12-31T02:44:03`) is interpreted as **UTC**, not local time
+- Relative times (`5m`, `1h`) are relative to server's current UTC time
+- To query with local time, include timezone offset: `2025-12-31T09:44:03+07:00`
+
+### Converting Local Time to UTC
+
+**Python:**
+```python
+from datetime import datetime, timezone, timedelta
+
+# Local time (e.g., 2025-12-31 09:44:03 in GMT+7)
+local_time = datetime(2025, 12, 31, 9, 44, 3)
+
+# Method 1: If you know your timezone offset
+local_tz = timezone(timedelta(hours=7))  # GMT+7
+local_aware = local_time.replace(tzinfo=local_tz)
+utc_time = local_aware.astimezone(timezone.utc)
+unix_ts = utc_time.timestamp()
+print(f"UTC Unix timestamp: {unix_ts}")
+
+# Method 2: Using system timezone
+import time
+unix_ts = time.mktime(local_time.timetuple())
+```
+
+**Bash:**
+```bash
+# Convert local time to Unix timestamp
+date -d "2025-12-31 09:44:03" +%s
+
+# Convert with explicit timezone
+TZ=UTC date -d "2025-12-31T02:44:03" +%s
+```
+
+### API Query Examples with Timezone
+
+```bash
+# Option 1: Include timezone in ISO 8601 (recommended for local time)
+curl "http://localhost:8001/logs/query?since=2025-12-31T09:44:03%2B07:00"
+
+# Option 2: Use relative time (always relative to server UTC time)
+curl "http://localhost:8001/logs/query?since=5m"
+
+# Option 3: Convert to UTC Unix timestamp first
+UTC_TS=$(TZ=UTC date -d "2025-12-31T02:44:03" +%s)
+curl "http://localhost:8001/logs/query?start_ts=$UTC_TS"
+
+# Option 4: Use ISO 8601 in UTC (note: no timezone = UTC)
+curl "http://localhost:8001/logs/query?since=2025-12-31T02:44:03"
+```
+
+### Common Timezone Pitfalls
+
+1. **ISO 8601 Without Timezone**: Interpreted as UTC, not local time. If you pass `2025-12-31T09:44:03` thinking it's local 9:44 AM, it will be treated as 9:44 AM UTC.
+
+2. **Server vs Client Timezone**: If your server is in a different timezone than your client, always use explicit UTC timestamps or include timezone offsets.
+
+3. **Relative Times**: `since=5m` means 5 minutes before server's current UTC time, regardless of your local timezone.
+
+---
+
 ## Related Documentation
 
 - `docs/daemon-interaction-guide.md` - OpenAPI discovery details
@@ -295,4 +367,4 @@ def interact_with_daemon(query: str) -> str:
 
 ---
 
-**Last Updated**: 2025-12-29
+**Last Updated**: 2025-12-31

package/agents/log-analysis.md

@@ -11,24 +11,25 @@ You must fully embody this agent's persona and follow all activation instruction
   <step n="1">Load persona from this current agent file (already in context)</step>
   <step n="2">Remember: You are a Log Analysis Specialist</step>
   <step n="3">READ the entire story file BEFORE any analysis - understand the query parsing rules</step>
-  <step n="4">When processing a user query, try methods in this order:
-    
-    **Method 1 (Preferred)**: Python code
+  <step n="4">When processing a user query, try methods in this order (see `agents/daemon-method-selection.md` for details):
+
+    **Method 1 (Preferred)**: HTTP/curl
+    - Simple, no Python dependencies, works in any environment
+    - Check status: `GET http://localhost:8001/status`
+    - Query logs: `GET http://localhost:8001/logs/query?since=5m&application_id=X`
+    - Analysis: `GET http://localhost:8001/analysis/why?application_id=X&since=5m`
+    - **CRITICAL**: First fetch `/openapi.json` to discover field names (e.g., timestamp is `ts`, NOT `timestamp`)
+
+    **Method 2 (Fallback)**: Python SDK
+    - Use when HTTP is blocked or you need async features
     - Try: `from drtrace_service.agent_interface import process_agent_query, check_daemon_status`
-    - If import succeeds: Use `response = await process_agent_query(user_query)` or `asyncio.run(process_agent_query(user_query))`
+    - Use `response = await process_agent_query(user_query)` or `asyncio.run(process_agent_query(user_query))`
     - Return the response string directly (it's already formatted markdown)
-    
-    **Method 2 (Fallback)**: HTTP API
-    - If Python import fails: Use HTTP requests to call DrTrace API endpoints
-    - **CRITICAL**: First fetch `/openapi.json` to discover field names (e.g., timestamp is `ts`, NOT `timestamp`)
-    - Check status: `GET http://localhost:8001/status`
-    - For analysis: `GET http://localhost:8001/analysis/why?application_id=X&start_ts=Y&end_ts=Z`
-    - Parse the JSON response using field names from OpenAPI schema
-    
+
     **Method 3 (Last resort)**: CLI commands
-    - If both Python and HTTP fail: Execute `python -m drtrace_service why --application-id X --since 5m`
+    - If both HTTP and Python fail: Execute `python -m drtrace_service why --application-id X --since 5m`
     - Parse the CLI output and format for the user
-    
+
     **Important**: Always check daemon status first. If daemon is unavailable, return clear error message with next steps.
   </step>
   <step n="5">If information is missing, ask the user for clarification with helpful suggestions</step>

package/agents/log-help.md

@@ -11,7 +11,7 @@ You must fully embody this agent's persona and follow all activation instruction
   <step n="1">Load persona from this current agent file (already in context)</step>
   <step n="2">Remember: You are a Setup Guide Assistant for DrTrace</step>
   <step n="3">Your primary mission is to walk users through DrTrace setup step-by-step using the help APIs and setup guide, not to guess or skip steps</step>
-  <step n="4">ALWAYS prefer Method 1 (Python help APIs) → then Method 2 (HTTP help endpoints) → then Method 3 (CLI) in that exact order</step>
+  <step n="4">ALWAYS prefer Method 1 (HTTP/curl) → then Method 2 (Python SDK) → then Method 3 (CLI) in that exact order. See `agents/daemon-method-selection.md` for details.</step>
   <step n="5">For each user interaction, clearly state the current step, what to do next, and how to verify it worked</step>
   <step n="6">When calling help APIs, use:
     - `start_setup_guide(language, project_root)` to begin or restart a guide
@@ -32,7 +32,7 @@ You must fully embody this agent's persona and follow all activation instruction
     <r>NEVER skip verification or pretend steps are complete; use the setup guide and help APIs as the source of truth</r>
     <r>ALWAYS explain what you are doing when progressing steps or troubleshooting issues</r>
     <r>Display menu items exactly as defined in the menu section and in the order given</r>
-    <r>Prefer Python APIs, then HTTP endpoints, then CLI in that order; explain fallbacks when switching methods</r>
+    <r>Prefer HTTP/curl, then Python SDK, then CLI in that order; explain fallbacks when switching methods</r>
   </rules>
 </activation>
 

package/dist/browser.d.ts

@@ -0,0 +1,28 @@
+import type { ClientOptions, LogLevel } from './types';
+/**
+ * DrTrace client for browser environments.
+ *
+ * Unlike the Node.js client, this does NOT load configuration from files.
+ * All options must be passed explicitly to init().
+ */
+export declare class DrTrace {
+    private queue;
+    private logger;
+    private enabled;
+    private constructor();
+    /**
+     * Initialize DrTrace for browser environments.
+     * Unlike Node.js, browser does not load config from files.
+     * All options must be passed explicitly.
+     *
+     * @param opts - Client options (applicationId and daemonUrl are required)
+     * @throws Error if applicationId or daemonUrl are not provided
+     */
+    static init(opts: ClientOptions): DrTrace;
+    attachToConsole(): void;
+    detachFromConsole(): void;
+    log(message: string, level?: LogLevel, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    shutdown(): Promise<void>;
+}
+export * from './types';

package/dist/browser.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DrTrace = void 0;
+const transport_1 = require("./transport");
+const queue_1 = require("./queue");
+const logger_1 = require("./logger");
+/**
+ * DrTrace client for browser environments.
+ *
+ * Unlike the Node.js client, this does NOT load configuration from files.
+ * All options must be passed explicitly to init().
+ */
+class DrTrace {
+    constructor(opts) {
+        const transport = new transport_1.Transport({
+            daemonUrl: opts.daemonUrl,
+            maxRetries: opts.maxRetries ?? 3,
+            timeoutMs: 5000,
+        });
+        this.queue = new queue_1.LogQueue({
+            transport,
+            batchSize: opts.batchSize ?? 50,
+            flushIntervalMs: opts.flushIntervalMs ?? 1000,
+            maxQueueSize: opts.maxQueueSize ?? 10000,
+        });
+        this.queue.start();
+        this.enabled = opts.enabled ?? true;
+        this.logger = new logger_1.DrTraceLogger({
+            queue: this.queue,
+            applicationId: opts.applicationId,
+            moduleName: opts.moduleName,
+            logLevel: (opts.logLevel ?? 'info'),
+        });
+    }
+    /**
+     * Initialize DrTrace for browser environments.
+     * Unlike Node.js, browser does not load config from files.
+     * All options must be passed explicitly.
+     *
+     * @param opts - Client options (applicationId and daemonUrl are required)
+     * @throws Error if applicationId or daemonUrl are not provided
+     */
+    static init(opts) {
+        if (!opts.applicationId) {
+            throw new Error('applicationId is required for browser usage');
+        }
+        if (!opts.daemonUrl) {
+            throw new Error('daemonUrl is required for browser usage');
+        }
+        return new DrTrace(opts);
+    }
+    attachToConsole() {
+        if (!this.enabled)
+            return;
+        this.logger.attachToConsole();
+    }
+    detachFromConsole() {
+        this.logger.detachFromConsole();
+    }
+    log(message, level = 'info', context) {
+        if (!this.enabled)
+            return;
+        this.logger.log(level, message, context);
+    }
+    error(message, context) {
+        if (!this.enabled)
+            return;
+        this.logger.log('error', message, context);
+    }
+    async shutdown() {
+        await this.queue.flush();
+        this.queue.stop();
+        this.detachFromConsole();
+    }
+}
+exports.DrTrace = DrTrace;
+__exportStar(require("./types"), exports);

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { DrTrace } from './client';
+export { DrTrace } from './node';
 export { loadConfig } from './config';
 export * from './types';

package/dist/index.js

@@ -15,8 +15,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfig = exports.DrTrace = void 0;
-var client_1 = require("./client");
-Object.defineProperty(exports, "DrTrace", { enumerable: true, get: function () { return client_1.DrTrace; } });
+var node_1 = require("./node");
+Object.defineProperty(exports, "DrTrace", { enumerable: true, get: function () { return node_1.DrTrace; } });
 var config_1 = require("./config");
 Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_1.loadConfig; } });
 __exportStar(require("./types"), exports);

package/dist/init.d.ts

@@ -12,6 +12,7 @@ export declare class ProjectInitializer {
     private projectRoot;
     private drtraceDir;
     private configPath;
+    private copiedAgentFiles;
     constructor(projectRoot?: string);
     /**
      * Run the interactive initialization workflow
@@ -57,6 +58,7 @@ export declare class ProjectInitializer {
     private copyAgentSpec;
     /**
      * Recursively copy all files from sourceDir to targetDir
+     * Returns list of relative file paths copied (for summary display)
      */
     private copyAgentsRecursive;
     /**

package/dist/init.js

@@ -49,6 +49,8 @@ const prompts_1 = __importDefault(require("prompts"));
 const config_schema_1 = require("./config-schema");
 class ProjectInitializer {
     constructor(projectRoot = process.cwd()) {
+        // Track copied agent files for summary display
+        this.copiedAgentFiles = [];
         this.projectRoot = projectRoot;
         this.drtraceDir = path.join(projectRoot, "_drtrace");
         this.configPath = path.join(this.drtraceDir, "config.json");
@@ -260,8 +262,9 @@ class ProjectInitializer {
                 console.warn("⚠️  Could not find agents directory");
                 return;
             }
-            // Copy all files recursively
-            this.copyAgentsRecursive(agentsDir, path.join(this.drtraceDir, "agents"));
+            // Copy all files recursively and track copied files
+            const copiedFiles = this.copyAgentsRecursive(agentsDir, path.join(this.drtraceDir, "agents"));
+            this.copiedAgentFiles.push(...copiedFiles);
         }
         catch (error) {
             console.warn(`⚠️  Could not copy agent files: ${error}`);
@@ -269,34 +272,35 @@ class ProjectInitializer {
     }
     /**
      * Recursively copy all files from sourceDir to targetDir
+     * Returns list of relative file paths copied (for summary display)
      */
-    copyAgentsRecursive(sourceDir, targetDir) {
+    copyAgentsRecursive(sourceDir, targetDir, basePath = "") {
         if (!fs.existsSync(targetDir)) {
             fs.mkdirSync(targetDir, { recursive: true });
         }
         const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
-        let copiedCount = 0;
+        const copiedFiles = [];
         for (const entry of entries) {
             const srcPath = path.join(sourceDir, entry.name);
             const destPath = path.join(targetDir, entry.name);
+            const relativePath = basePath ? path.join(basePath, entry.name) : entry.name;
             if (entry.isDirectory()) {
                 // Recursively copy directories
-                this.copyAgentsRecursive(srcPath, destPath);
+                const subCopied = this.copyAgentsRecursive(srcPath, destPath, relativePath);
+                copiedFiles.push(...subCopied);
             }
             else {
                 // Copy file (no renaming needed - files are already named correctly)
                 fs.copyFileSync(srcPath, destPath);
-                copiedCount++;
-                console.log(`✓ Copied ${entry.name}`);
+                copiedFiles.push(relativePath);
+                console.log(`✓ Copied ${relativePath}`);
             }
         }
-        if (copiedCount > 0 && !fs.existsSync(path.join(targetDir, "..", ".."))) {
-            // Only print summary if we're at the top level
-            const relativeSource = path.relative(process.cwd(), sourceDir);
-            if (!relativeSource.includes("..")) {
-                console.log(`✓ Successfully copied ${copiedCount} file(s) from agents/`);
-            }
+        // Print summary only at top level
+        if (!basePath && copiedFiles.length > 0) {
+            console.log(`✓ Successfully copied ${copiedFiles.length} file(s) from agents/`);
         }
+        return copiedFiles;
     }
     /**
      * Copy framework-specific integration guides to _drtrace/agents/integration-guides/
@@ -781,11 +785,12 @@ python -m drtrace_service status
         }
         console.log(`   • ${path.join(this.drtraceDir, ".env.example")}`);
         console.log(`   • ${path.join(this.drtraceDir, "README.md")}`);
-        if (config.agent?.enabled) {
-            console.log(`   • ${path.join(this.drtraceDir, "agents", "log-analysis.md")}`);
-            console.log(`   • ${path.join(this.drtraceDir, "agents", "log-it.md")}`);
-            console.log(`   • ${path.join(this.drtraceDir, "agents", "log-init.md")}`);
-            console.log(`   • ${path.join(this.drtraceDir, "agents", "log-help.md")}`);
+        // List all copied agent files (includes integration-guides/)
+        if (this.copiedAgentFiles.length > 0) {
+            console.log("\n📋 Agent Files:");
+            for (const agentFile of this.copiedAgentFiles.sort()) {
+                console.log(`   • ${path.join(this.drtraceDir, "agents", agentFile)}`);
+            }
         }
         console.log("\n📖 Next Steps:");
         console.log(`   1. Review ${this.configPath}`);

package/dist/logger.d.ts

@@ -3,13 +3,20 @@ import { LogQueue } from './queue';
 export declare class DrTraceLogger {
     private queue;
     private applicationId;
+    private moduleName;
     private logLevel;
     private originalConsole?;
     constructor(opts: {
         queue: LogQueue;
         applicationId: string;
+        moduleName?: string;
         logLevel: LogLevel;
     });
+    /**
+     * Serialize a value to a string suitable for logging.
+     * Handles objects, arrays, errors, and primitives correctly.
+     */
+    private serialize;
     attachToConsole(): void;
     detachFromConsole(): void;
     log(level: LogLevel, message: string, context?: Record<string, unknown>): void;

package/dist/logger.js

@@ -5,15 +5,40 @@ class DrTraceLogger {
     constructor(opts) {
         this.queue = opts.queue;
         this.applicationId = opts.applicationId;
+        this.moduleName = opts.moduleName || 'default';
         this.logLevel = opts.logLevel || 'info';
     }
+    /**
+     * Serialize a value to a string suitable for logging.
+     * Handles objects, arrays, errors, and primitives correctly.
+     */
+    serialize(value) {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return String(value);
+        if (value instanceof Error) {
+            return value.stack || `${value.name}: ${value.message}`;
+        }
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            // Handle circular references gracefully
+            return String(value);
+        }
+    }
     attachToConsole() {
         if (this.originalConsole)
             return;
         this.originalConsole = { log: console.log, error: console.error };
         console.log = (...args) => {
             try {
-                this.log('info', args.map(String).join(' '));
+                this.log('info', args.map((arg) => this.serialize(arg)).join(' '));
             }
             catch {
                 // Silently ignore logging errors
@@ -22,7 +47,7 @@ class DrTraceLogger {
         };
         console.error = (...args) => {
             try {
-                this.log('error', args.map(String).join(' '));
+                this.log('error', args.map((arg) => this.serialize(arg)).join(' '));
             }
             catch {
                 // Silently ignore logging errors
@@ -39,8 +64,9 @@ class DrTraceLogger {
     }
     log(level, message, context) {
         const event = {
-            timestamp: new Date().toISOString(),
-            applicationId: this.applicationId,
+            ts: Date.now() / 1000, // Unix timestamp as float (seconds.milliseconds)
+            application_id: this.applicationId,
+            module_name: this.moduleName,
             level,
             message,
             context,

package/dist/node.d.ts

@@ -0,0 +1,13 @@
+import type { ClientOptions, LogLevel } from './types';
+export declare class DrTrace {
+    private queue;
+    private logger;
+    private enabled;
+    private constructor();
+    static init(opts?: Partial<ClientOptions>): DrTrace;
+    attachToConsole(): void;
+    detachFromConsole(): void;
+    log(message: string, level?: LogLevel, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    shutdown(): Promise<void>;
+}

package/dist/node.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DrTrace = void 0;
+const config_1 = require("./config");
+const transport_1 = require("./transport");
+const queue_1 = require("./queue");
+const logger_1 = require("./logger");
+class DrTrace {
+    constructor(opts) {
+        const transport = new transport_1.Transport({
+            daemonUrl: opts.daemonUrl,
+            maxRetries: opts.maxRetries ?? 3,
+            timeoutMs: 5000,
+        });
+        this.queue = new queue_1.LogQueue({
+            transport,
+            batchSize: opts.batchSize ?? 50,
+            flushIntervalMs: opts.flushIntervalMs ?? 1000,
+            maxQueueSize: opts.maxQueueSize ?? 10000,
+        });
+        this.queue.start();
+        this.enabled = opts.enabled ?? true;
+        this.logger = new logger_1.DrTraceLogger({
+            queue: this.queue,
+            applicationId: opts.applicationId,
+            moduleName: opts.moduleName,
+            logLevel: (opts.logLevel ?? 'info'),
+        });
+    }
+    static init(opts) {
+        const cfg = (0, config_1.loadConfig)({ projectRoot: '.', environment: process.env.NODE_ENV });
+        const merged = {
+            applicationId: cfg.drtrace.applicationId,
+            daemonUrl: cfg.drtrace.daemonUrl || 'http://localhost:8001',
+            enabled: cfg.drtrace.enabled ?? true,
+            logLevel: (cfg.drtrace.logLevel ?? 'info'),
+            batchSize: cfg.drtrace.batchSize ?? 50,
+            flushIntervalMs: cfg.drtrace.flushIntervalMs ?? 1000,
+            ...opts,
+        };
+        return new DrTrace(merged);
+    }
+    attachToConsole() {
+        if (!this.enabled)
+            return;
+        this.logger.attachToConsole();
+    }
+    detachFromConsole() {
+        this.logger.detachFromConsole();
+    }
+    log(message, level = 'info', context) {
+        if (!this.enabled)
+            return;
+        this.logger.log(level, message, context);
+    }
+    error(message, context) {
+        if (!this.enabled)
+            return;
+        this.logger.log('error', message, context);
+    }
+    async shutdown() {
+        await this.queue.flush();
+        this.queue.stop();
+        this.detachFromConsole();
+    }
+}
+exports.DrTrace = DrTrace;

package/dist/resources/agents/daemon-method-selection.md

@@ -288,6 +288,78 @@ def interact_with_daemon(query: str) -> str:
 
 ---
 
+## Important: Timestamps Are UTC
+
+All timestamps in DrTrace API are **UTC Unix timestamps**:
+
+| Field/Param | Format | Timezone |
+|-------------|--------|----------|
+| `ts` (in logs) | Unix float | UTC |
+| `start_ts`, `end_ts` | Unix float | UTC |
+| `since`, `until` | Relative or ISO 8601 | UTC |
+
+**Key Rules**:
+- ISO 8601 without timezone (e.g., `2025-12-31T02:44:03`) is interpreted as **UTC**, not local time
+- Relative times (`5m`, `1h`) are relative to server's current UTC time
+- To query with local time, include timezone offset: `2025-12-31T09:44:03+07:00`
+
+### Converting Local Time to UTC
+
+**Python:**
+```python
+from datetime import datetime, timezone, timedelta
+
+# Local time (e.g., 2025-12-31 09:44:03 in GMT+7)
+local_time = datetime(2025, 12, 31, 9, 44, 3)
+
+# Method 1: If you know your timezone offset
+local_tz = timezone(timedelta(hours=7))  # GMT+7
+local_aware = local_time.replace(tzinfo=local_tz)
+utc_time = local_aware.astimezone(timezone.utc)
+unix_ts = utc_time.timestamp()
+print(f"UTC Unix timestamp: {unix_ts}")
+
+# Method 2: Using system timezone
+import time
+unix_ts = time.mktime(local_time.timetuple())
+```
+
+**Bash:**
+```bash
+# Convert local time to Unix timestamp
+date -d "2025-12-31 09:44:03" +%s
+
+# Convert with explicit timezone
+TZ=UTC date -d "2025-12-31T02:44:03" +%s
+```
+
+### API Query Examples with Timezone
+
+```bash
+# Option 1: Include timezone in ISO 8601 (recommended for local time)
+curl "http://localhost:8001/logs/query?since=2025-12-31T09:44:03%2B07:00"
+
+# Option 2: Use relative time (always relative to server UTC time)
+curl "http://localhost:8001/logs/query?since=5m"
+
+# Option 3: Convert to UTC Unix timestamp first
+UTC_TS=$(TZ=UTC date -d "2025-12-31T02:44:03" +%s)
+curl "http://localhost:8001/logs/query?start_ts=$UTC_TS"
+
+# Option 4: Use ISO 8601 in UTC (note: no timezone = UTC)
+curl "http://localhost:8001/logs/query?since=2025-12-31T02:44:03"
+```
+
+### Common Timezone Pitfalls
+
+1. **ISO 8601 Without Timezone**: Interpreted as UTC, not local time. If you pass `2025-12-31T09:44:03` thinking it's local 9:44 AM, it will be treated as 9:44 AM UTC.
+
+2. **Server vs Client Timezone**: If your server is in a different timezone than your client, always use explicit UTC timestamps or include timezone offsets.
+
+3. **Relative Times**: `since=5m` means 5 minutes before server's current UTC time, regardless of your local timezone.
+
+---
+
 ## Related Documentation
 
 - `docs/daemon-interaction-guide.md` - OpenAPI discovery details
@@ -295,4 +367,4 @@ def interact_with_daemon(query: str) -> str:
 
 ---
 
-**Last Updated**: 2025-12-29
+**Last Updated**: 2025-12-31

package/dist/resources/agents/log-analysis.md

@@ -11,24 +11,25 @@ You must fully embody this agent's persona and follow all activation instruction
   <step n="1">Load persona from this current agent file (already in context)</step>
   <step n="2">Remember: You are a Log Analysis Specialist</step>
   <step n="3">READ the entire story file BEFORE any analysis - understand the query parsing rules</step>
-  <step n="4">When processing a user query, try methods in this order:
-    
-    **Method 1 (Preferred)**: Python code
+  <step n="4">When processing a user query, try methods in this order (see `agents/daemon-method-selection.md` for details):
+
+    **Method 1 (Preferred)**: HTTP/curl
+    - Simple, no Python dependencies, works in any environment
+    - Check status: `GET http://localhost:8001/status`
+    - Query logs: `GET http://localhost:8001/logs/query?since=5m&application_id=X`
+    - Analysis: `GET http://localhost:8001/analysis/why?application_id=X&since=5m`
+    - **CRITICAL**: First fetch `/openapi.json` to discover field names (e.g., timestamp is `ts`, NOT `timestamp`)
+
+    **Method 2 (Fallback)**: Python SDK
+    - Use when HTTP is blocked or you need async features
     - Try: `from drtrace_service.agent_interface import process_agent_query, check_daemon_status`
-    - If import succeeds: Use `response = await process_agent_query(user_query)` or `asyncio.run(process_agent_query(user_query))`
+    - Use `response = await process_agent_query(user_query)` or `asyncio.run(process_agent_query(user_query))`
     - Return the response string directly (it's already formatted markdown)
-    
-    **Method 2 (Fallback)**: HTTP API
-    - If Python import fails: Use HTTP requests to call DrTrace API endpoints
-    - **CRITICAL**: First fetch `/openapi.json` to discover field names (e.g., timestamp is `ts`, NOT `timestamp`)
-    - Check status: `GET http://localhost:8001/status`
-    - For analysis: `GET http://localhost:8001/analysis/why?application_id=X&start_ts=Y&end_ts=Z`
-    - Parse the JSON response using field names from OpenAPI schema
-    
+
     **Method 3 (Last resort)**: CLI commands
-    - If both Python and HTTP fail: Execute `python -m drtrace_service why --application-id X --since 5m`
+    - If both HTTP and Python fail: Execute `python -m drtrace_service why --application-id X --since 5m`
     - Parse the CLI output and format for the user
-    
+
     **Important**: Always check daemon status first. If daemon is unavailable, return clear error message with next steps.
   </step>
   <step n="5">If information is missing, ask the user for clarification with helpful suggestions</step>

package/dist/resources/agents/log-help.md

@@ -11,7 +11,7 @@ You must fully embody this agent's persona and follow all activation instruction
   <step n="1">Load persona from this current agent file (already in context)</step>
   <step n="2">Remember: You are a Setup Guide Assistant for DrTrace</step>
   <step n="3">Your primary mission is to walk users through DrTrace setup step-by-step using the help APIs and setup guide, not to guess or skip steps</step>
-  <step n="4">ALWAYS prefer Method 1 (Python help APIs) → then Method 2 (HTTP help endpoints) → then Method 3 (CLI) in that exact order</step>
+  <step n="4">ALWAYS prefer Method 1 (HTTP/curl) → then Method 2 (Python SDK) → then Method 3 (CLI) in that exact order. See `agents/daemon-method-selection.md` for details.</step>
   <step n="5">For each user interaction, clearly state the current step, what to do next, and how to verify it worked</step>
   <step n="6">When calling help APIs, use:
     - `start_setup_guide(language, project_root)` to begin or restart a guide
@@ -32,7 +32,7 @@ You must fully embody this agent's persona and follow all activation instruction
     <r>NEVER skip verification or pretend steps are complete; use the setup guide and help APIs as the source of truth</r>
     <r>ALWAYS explain what you are doing when progressing steps or troubleshooting issues</r>
     <r>Display menu items exactly as defined in the menu section and in the order given</r>
-    <r>Prefer Python APIs, then HTTP endpoints, then CLI in that order; explain fallbacks when switching methods</r>
+    <r>Prefer HTTP/curl, then Python SDK, then CLI in that order; explain fallbacks when switching methods</r>
   </rules>
 </activation>
 

package/dist/resources/cpp/drtrace_sink.hpp

@@ -6,6 +6,7 @@
  */
 
 #pragma once
+#define DRTRACE_VERSION "0.4.0"
 
 // Standard library includes required for header-only implementation
 #include <atomic>

package/dist/transport.js

@@ -15,7 +15,11 @@ class Transport {
         if (events.length === 0)
             return;
         const url = `${this.daemonUrl}/logs/ingest`;
-        const payload = { logs: events };
+        // Wrap batch with application_id at top level as required by daemon API
+        const payload = {
+            application_id: events[0].application_id,
+            logs: events,
+        };
         const fetchImpl = globalThis.fetch;
         if (!fetchImpl)
             return; // Non-blocking skip

package/dist/types.d.ts

@@ -1,14 +1,20 @@
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 export interface LogEvent {
-    timestamp: string;
-    applicationId: string;
+    ts: number;
     level: LogLevel;
     message: string;
+    application_id: string;
+    module_name: string;
     context?: Record<string, unknown>;
 }
+export interface LogBatch {
+    application_id: string;
+    logs: LogEvent[];
+}
 export interface ClientOptions {
     applicationId: string;
     daemonUrl: string;
+    moduleName?: string;
     enabled?: boolean;
     logLevel?: LogLevel;
     batchSize?: number;

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "drtrace",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "DrTrace JavaScript/TypeScript client",
   "main": "dist/index.js",
+  "browser": "dist/browser.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/browser.js",
+      "node": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
     }
   },
   "bin": {
@@ -45,7 +52,10 @@
     "error-tracking",
     "debugging"
   ],
-  "author": "DrTrace Team",
+  "author": {
+    "name": "Thanh Cao",
+    "email": "caoduythanhcantho@gmail.com"
+  },
   "license": "MIT",
   "files": [
     "dist/",
@@ -55,7 +65,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/example/drtrace.git",
+    "url": "git+https://github.com/CaoDuyThanh/drtrace.git",
     "directory": "packages/javascript/drtrace-client"
+  },
+  "homepage": "https://github.com/CaoDuyThanh/drtrace#readme",
+  "bugs": {
+    "url": "https://github.com/CaoDuyThanh/drtrace/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
   }
 }